docs: simplify CLAUDE.md files - remove verbose context rules and use concise format

Co-authored-by: Qwen-Coder <[email protected]>
2026-02-24 15:50:38 +08:00
parent 201105b43f
commit 5162b9c42a
2 changed files with 87 additions and 774 deletions
@@ -1,236 +1,16 @@
-# CLAUDE.md
+# .claude/CLAUDE.md

-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+**Primary docs**: `/CLAUDE.md` — all rules, architecture, key files.

---
-
-## 🛑 CRITICAL: Context Optimization - Read This FIRST
-
-**⚠️ BEFORE using Read/Grep tools, you MUST check if this is exploratory work.**
-
-**Exploratory work = Use `Task(subagent_type=Explore)` ONLY**
-
-Examples of exploratory work:
- "继续改进 ljwx-phone" → Task(Explore)
- "分析 UI 结构" → Task(Explore)
- "了解数据处理流程" → Task(Explore)
-
-**DO NOT read multiple files directly. This causes context exhaustion.**
-
-### 🤖 Automatic Protection Enabled
-
-This repository has automatic context protection:
-
-📋 **Quick Reference**: `.claude/QUICK_REFERENCE.md` - Decision flowchart and patterns
-🛡️ **Context Guard**: `.claude/hooks/context-guard.md` - Automatic keyword detection
-🔍 **Task Detector**: `.claude/skills/task-type-detector.md` - Pattern matching rules
-
-**Before EVERY operation, consult QUICK_REFERENCE.md for the decision flowchart.**
-
-See `/CLAUDE.md` for complete rules.
-
---
-
-## 📍 Primary Documentation
-
-**The main project documentation is located at the repository root:**
-
-👉 **[/CLAUDE.md](/CLAUDE.md)** - Comprehensive development guide for LJWX Health
-
-This file contains:
- Quick start commands for all components (ljwx-admin, ljwx-boot, ljwx-bigscreen)
- GitOps CI/CD workflows and deployment procedures
- Architecture overview and project structure
- Development workflow and best practices
- OpenAPI contract maintenance requirements
- Environment isolation strategies
- Health system architecture and scheduled tasks
- Observability stack configuration
- Known issues and fixes
-
-## 🚨 Critical: Engineering Blueprint
-
-Before starting any work, read the mandatory engineering standards:
-
-📘 **[/PROMPT_BLUEPRINT.md](/PROMPT_BLUEPRINT.md)** - AI-controlled development blueprint
-
-All deliverables must include:
-1. OpenAPI contract updates (if applicable)
-2. Backend implementation
-3. Database migration scripts (Flyway)
-4. Minimum viable tests
-5. Observability instrumentation (logs, traces, metrics)
-6. GitOps deployment configuration
-
-## 🎯 Quick Reference
-
-### Start Development
+## Context Rule (MANDATORY)
+Exploratory work → `Task(subagent_type=Explore)`. Never read multiple files directly.

+## Gates
 ```bash
-# Frontend (Vue3 + TypeScript)
-cd ljwx-admin && pnpm install && pnpm dev  # http://localhost:3333
-
-# Backend (Spring Boot + Java 21)
-cd ljwx-boot && ./run-local.sh  # http://localhost:9998
-
-# BigScreen (Flask + Python)
-cd ljwx-bigscreen/bigscreen && python run.py  # http://localhost:5225
+bash scripts/gates/gate-all.sh
 ```
+Hooks auto-enforce rules on every Edit/Write. See `scripts/hooks/`.

-### OpenAPI Contract Workflow
-
-```bash
-# Export OpenAPI specification
-cd ljwx-boot && ./scripts/export-openapi.sh
-
-# Check for breaking changes
-cd ljwx-boot && ./scripts/check-api-breaking-changes.sh
-```
-
-### GitOps Deployment
-
-```bash
-# Auto-deploy via git push
-git push origin main     # Production deployment to K3s
-git push origin develop  # Development environment
-
-# Manual GitHub Actions trigger
-# Actions → GitOps Deploy to K3s → Run workflow
-```
-
-### Observability
-
-```bash
-# Deploy monitoring stack to K8s
-./scripts/deploy-observability.sh
-
-# Local monitoring (Docker Compose)
-docker-compose -f ljwx-boot/docker-compose-p0-monitoring.yml up -d
-
-# Access Grafana
-kubectl port-forward -n infra svc/grafana 3000:3000  # admin/admin123
-```
-
-## 📐 Architecture at a Glance
-
-This is a **multi-component health monitoring platform**:
-
-1. **ljwx-admin** - Vue3 admin dashboard (port 3333)
-   - Multi-tenant with auto customerId injection
-   - NaiveUI component library
-   - Pinia state management
-
-2. **ljwx-boot** - Spring Boot backend API (port 9998)
-   - Java 21, Maven multi-module
-   - MySQL + Redis
-   - Scheduled health data processing tasks
-   - Flyway migrations (production only)
-
-3. **ljwx-bigscreen** - Flask monitoring dashboard (port 5225/5001)
-   - Real-time health metrics visualization
-   - Celery async tasks
-   - WeChat enterprise integration
-
-## ⚙️ Environment Profiles
-
-**Local Development:**
- Profile: `local`
- Paths: Relative (`logs/`, `uploads/`)
- Database: `127.0.0.1:3306/test`
- Flyway: **Disabled**
- Log format: Plain text
-
-**Production (K8s):**
- Profile: `prod`
- Paths: Absolute (`/app/logs/`, `/app/data/`)
- Database: `mysql.infra.svc.cluster.local`
- Flyway: **Enabled**
- Log format: JSON (Loki-compatible)
-
-## 🔍 Key Files Reference
-
-### Backend (ljwx-boot)
- `ljwx-boot-modules/src/main/java/com/ljwx/modules/health/task/HealthBaselineScoreTasks.java` - Scheduled tasks
- `ljwx-boot-modules/src/main/java/com/ljwx/modules/health/service/WeightCalculationService.java` - Health scoring
- `ljwx-boot-admin/src/main/resources/logback-spring.xml` - Logging configuration
- `ljwx-boot-admin/src/main/resources/application-local.yml` - Local config
- `ljwx-boot/api/openapi.json` - OpenAPI contract baseline
-
-### Frontend (ljwx-admin)
- `src/service/request/index.ts` - Request interceptor (customerId injection)
- `src/hooks/common/table.ts` - Table data management hook
- `src/views/monitor/scheduler/index.vue` - Task scheduler UI
-
-### BigScreen (ljwx-bigscreen)
- `bigscreen/bigScreen/bigScreen.py` - Flask application
- `bigscreen/config.py` - Environment configuration
- `bigscreen/bigScreen/models.py` - Database models
-
-### CI/CD & Deployment
- `.github/workflows/gitops-deploy.yml` - GitHub Actions GitOps workflow
- `.gitea/workflows/gitops-deploy.yml` - Gitea Actions workflow (ARM64)
- `scripts/deploy-k3s-with-ingress.sh` - K8s deployment script
- `scripts/deploy-observability.sh` - Monitoring stack deployment
-
-## ⚠️ Important Constraints
-
-1. **DO NOT restart ljwx-boot during debugging** - User handles restarts manually
-2. **OpenAPI contract is mandatory** - All controller changes must pass contract validation
-3. **Use DTOs only** - Controllers must not expose Entity/Map directly
-4. **Follow Flyway migrations** - Use Expand/Contract pattern for schema changes
-5. **Multi-tenant isolation** - All APIs must respect customerId (except auth/system)
-6. **Observability required** - All features must emit logs, traces, and metrics
-7. **Documentation rules** - All .md files must follow strict naming and location rules
-
-## 📁 Documentation Rules (MANDATORY)
-
-**⚠️ CRITICAL: When creating any .md document, you MUST:**
-
-1. **Never create in root or subproject root**
-   - ❌ `/new-doc.md` - Prohibited
-   - ❌ `/ljwx-boot/guide.md` - Prohibited (except README.md, CHANGELOG.md)
-   - ✅ `/docs/05-features/new-feature.md` - Correct
-
-2. **Use kebab-case naming only**
-   - ❌ `NewFeature.md`, `new_feature.md`, `FEATURE_DOC.md`
-   - ✅ `new-feature.md`, `api-integration-guide.md`
-
-3. **Select correct category**
-   - Features → `docs/05-features/`
-   - Dev guides → `docs/06-development/{backend|frontend|api}/`
-   - Deployment → `docs/03-deployment/`
-   - Fix reports → `archive/{year}/fixes/`
-   - Implementation → `archive/{year}/implementations/`
-
-4. **Use creation tools** (recommended)
-   ```bash
-   ./scripts/create-doc.sh  # Interactive wizard
-   ```
-
-**See `/CLAUDE.md` Section "📁 文档管理规范" for complete rules.**
-
-**Violation consequences:**
- Git pre-commit hook will block commits
- GitHub Actions will fail PR checks
- Manual fixes required before merge
-
-## 🛠️ Claude Code Skills & Hooks
-
-This repository includes custom skills and hooks in `.claude/`:
-
- **skills/** - Custom automation scripts
- **hooks/** - Development lifecycle hooks
- **templates/** - Code generation templates
-
-Refer to individual files in these directories for usage instructions.
-
-## 📚 Additional Resources
-
-For subsystem-specific details:
- **ljwx-admin**: `ljwx-admin/CLAUDE.md` - Frontend architecture
- **ljwx-bigscreen**: `ljwx-bigscreen/CLAUDE.md` - Monitoring system
- **Infrastructure**: `docs/` - CI/CD and deployment guides
-
---
-
-**Remember:** Always consult the main [/CLAUDE.md](/CLAUDE.md) for comprehensive information. This file serves as a quick reference and pointer to the primary documentation.
+## Non-stop Execution
+`settings.json` sets `defaultMode: dontAsk` — Claude proceeds without approval prompts.
+Hooks block violations automatically instead of asking.
@@ -1,598 +1,131 @@
-# CLAUDE.md
+# CLAUDE.md — LJWX Health

-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+## ⚡ Context Rules (MANDATORY)
+
+**Exploratory work → ALWAYS use `Task(subagent_type=Explore)`**
+- "继续/分析/了解/查看/探索/研究/梳理" → Task(Explore)
+- Files >500 lines → Read with offset/limit only
+- Never read the same file twice
+
+**Before ANY Read/Grep: Is this exploratory? If yes → Task(Explore)**

 ---

-## 🛑 STOP: Read This FIRST - Context Optimization (必读)
+## 🚨 Hard Rules (violation = task failure)

-**BEFORE reading ANY file or using Grep, ask yourself:**
-
-### Is this exploratory work?
- ❓ "继续改进 ljwx-phone" → **YES** → Use `Task(subagent_type=Explore)`
- ❓ "分析当前 UI 结构" → **YES** → Use `Task(subagent_type=Explore)`
- ❓ "了解健康数据处理流程" → **YES** → Use `Task(subagent_type=Explore)`
- ✅ "读取 config.yaml 的第 50 行" → NO → Can use Read directly
-
-### ❌ PROHIBITED Pattern (禁止模式)
-```
-User: "继续改进 ljwx-phone 的 UI"
-
-❌ WRONG:
-  Read(home_tab_screen.dart)        # 382 lines
-  Read(user_details_screen.dart)    # 229 lines
-  Read(health_data_card.dart)       # 1367 lines ⚠️
-  Read(profile_screen.dart)         # 87 lines
-  → Result: Context exhaustion, repeated compaction
-
-✅ CORRECT:
-  Task(
-    subagent_type=Explore,
-    prompt="探索 ljwx-phone 的 UI 结构，重点关注首页、用户信息和健康数据展示"
-  )
-  → Result: Efficient exploration, minimal context usage
-```
-
-### Enforcement
-**If you violate this rule, the conversation WILL fail due to context exhaustion.**
-
-**This is NOT optional. This is MANDATORY.**
-
-### 🤖 Automatic Protection
-
-**This repository has automatic task type detection and context protection:**
-
-📋 **Context Guard Hook**: `.claude/hooks/context-guard.md`
- Automatically detects exploratory task keywords
- Enforces Task(Explore) usage
- Monitors context thresholds
- Blocks violations before they happen
-
-🔍 **Task Type Detector**: `.claude/skills/task-type-detector.md`
- Analyzes user input patterns
- Recommends correct tool usage
- Provides decision explanations
- Defaults to safe choices when ambiguous
-
-**Before ANY Read/Grep operation, you MUST:**
-1. Check if task matches exploratory patterns (see context-guard.md)
-2. Verify file size (<1000 lines for direct read)
-3. Confirm context remaining (>30%)
-4. Explain your tool choice decision
-
-**Trigger Keywords (Auto-enforce Task(Explore)):**
- 继续 + [改进|优化|开发|实现]
- 分析 + [代码|结构|实现|流程]
- 了解 + [如何|怎么|什么]
- 查看 + [所有|全部|整个]
- 探索 / 研究 / 调研 / 梳理 / 整理
- 对比 + [多个|不同]
+| Rule | Constraint |
+|------|-----------|
+| No `^` versions | `package.json` must use `~` only |
+| No `any` | TypeScript `any` type forbidden |
+| `@PreAuthorize` | All controller endpoints (except login/refresh) |
+| No tenantId in DTO | DTOs must not expose customerId/tenantId |
+| Flyway path | SQL migrations → `ljwx-boot-admin/src/main/resources/db/migration/` |
+| No `IF NOT EXISTS` | Flyway SQL forbidden |
+| Multi-tenant | All APIs must respect customerId (except auth/system) |
+| No entity in API | Controllers use DTOs only, never Entity/Map |
+| Observability | All features must emit logs + traces + metrics |

 ---

-## 🚨 IMPORTANT: Engineering Blueprint
-
-**BEFORE working on any task in this repository, you MUST read and strictly follow the engineering standards defined in:**
-
-📘 [`PROMPT_BLUEPRINT.md`](./PROMPT_BLUEPRINT.md) - AI 受控开发蓝图 v1.0
-
-This blueprint defines:
- Mandatory delivery standards (OpenAPI-first, database migrations, observability, GitOps)
- Technical stack constraints (GitHub Actions, Argo CD, Prometheus, Loki, Tempo)
- Database versioning rules (Flyway, Expand/Contract pattern)
- Output format requirements
- Prohibited practices
-
-**All work must comply with PROMPT_BLUEPRINT.md requirements. Non-compliance is considered task failure.**
-
---
-
-## ⚡ Context Optimization Rules (上下文优化规则)
-
-**CRITICAL: Follow these rules to prevent context exhaustion and repeated compaction.**
-
-### Mandatory Practices
-
-1. **Use Task Tool for Exploration** - NEVER use direct Grep/Read for open-ended codebase exploration
-   ```
-   ❌ BAD:  Grep("health") → Read multiple files → Grep again → ...
-   ✅ GOOD: Task(subagent_type=Explore, prompt="探索健康数据处理流程")
-   ```
-
-2. **Read Large Files Strategically** - Files >500 lines MUST use offset/limit
-   ```
-   ❌ BAD:  Read("DataManager.java")  # 4546 lines
-   ✅ GOOD: Grep("class DataManager", -n=True) → Read with offset/limit
-   ```
-
-3. **Avoid Redundant Reads** - Never read the same file twice in one conversation
-   - Remember what you've already read
-   - Reference previous reads instead of re-reading
-
-4. **Precise Search Before Read** - Always narrow down before reading
-   ```
-   Step 1: Glob("**/*Health*.java")           # Find candidates
-   Step 2: Grep("class.*Service", -n=True)    # Locate exact lines
-   Step 3: Read with offset/limit             # Read only relevant sections
-   ```
-
-5. **Prefer Specialized Tools Over Bash**
-   - ✅ Glob for file search (NOT `find` or `ls`)
-   - ✅ Grep for content search (NOT `grep` or `rg`)
-   - ✅ Read for file content (NOT `cat` or `head`)
-
-### Response Efficiency
-
- Keep responses concise and structured
- Use tables/lists instead of paragraphs
- Avoid repeating information already in context
- Don't explain obvious steps
-
-### When Context is Low (<20%)
-
-1. **Stop exploratory work** - Use Task tool exclusively
-2. **Avoid reading any files** - Work with existing context
-3. **Suggest new conversation** - For complex tasks
-
-### Verification
-
-Before each tool call, ask yourself:
- ✅ Is this the most context-efficient approach?
- ✅ Can I use Task tool instead?
- ✅ Do I really need to read this entire file?
- ✅ Have I already read this before?
-
-**Failure to follow these rules will result in context exhaustion and degraded performance.**
-
---
-
-## 📁 文档管理规范
-
-**⚠️ 强制规则**: 所有新创建的文档必须遵循以下分类规则，**禁止直接在根目录创建文档**。
-
-### 根目录 - 仅保留核心文档（≤10个）
-
-**允许保留**:
-1. `README.md` - 项目主文档
-2. `CLAUDE.md` - AI开发指导
-3. `CONTRIBUTING.md` - 贡献指南
-4. `CHANGELOG.md` - 版本历史
-5. `PROMPT_BLUEPRINT.md` - 工程蓝图
-
-**禁止**: 任何其他 `.md` 文档
-
-### 文档分类规则
-
-#### 📂 docs/ - 活跃文档（按功能分类）
-
-| 目录 | 用途 | 示例 |
-|------|------|------|
-| **01-getting-started/** | 快速开始、环境配置 | `quick-start-docker.md` |
-| **02-architecture/** | 系统架构、设计文档 | `system-overview.md` |
-| **03-deployment/** | 部署指南（docker/kubernetes/gitops） | `helm-deployment.md` |
-| **04-operations/** | 运维手册（database/monitoring/troubleshooting） | `grafana-dashboards.md` |
-| **05-features/** | 功能说明（health-monitoring/geofence/multi-tenant） | `alert-system.md` |
-| **06-development/** | 开发指南（backend/frontend/api） | `openapi-codegen-guide.md` |
-| **07-compliance/** | 工程规范 | `code-review-checklist.md` |
-| **08-reference/** | 参考资料 | `api-reference.md` |
-
-#### 🗄️ archive/ - 历史文档（按时间分类）
-
-| 目录 | 用途 | 示例 |
-|------|------|------|
-| **archive/2025/fixes/** | 故障修复报告 | `login-timeout-fix.md` |
-| **archive/2025/implementations/** | 实施完成报告 | `OPENAPI_CODEGEN_IMPLEMENTATION.md` |
-| **archive/2025/experiments/** | 实验性方案 | `performance-test-plan.md` |
-| **archive/deprecated/** | 已废弃文档 | `old-deployment-guide.md` |
-
-### 🤖 Claude Code 强制规则
-
-**当创建任何 .md 文档时，必须：**
-1. ❌ 禁止在根目录或子项目根目录创建（除 README.md, CHANGELOG.md）
-2. ✅ 使用 kebab-case 命名：`my-doc.md`
-3. ✅ 放在正确的分类目录
-4. ✅ 使用 `./scripts/create-doc.sh` 创建（推荐）
-
-**详细规范**: 📄 [Documentation Management Guide](docs/07-compliance/documentation-management-guide.md)
-
---
-
-## Repository Overview
-
-LJWX Health (灵境万象健康监测系统) is a comprehensive enterprise-level health monitoring platform for wearable devices. It consists of three main components:
-
-1. **ljwx-admin** - Vue3 frontend admin dashboard (TypeScript + Naive UI)
-2. **ljwx-boot** - Spring Boot backend API (Java 21 + MySQL + Redis)
-3. **ljwx-bigscreen** - Flask real-time monitoring dashboard (Python + ECharts)
-
-The repository uses GitHub Actions and Gitea Actions for CI/CD automation, supporting multi-architecture Docker image builds and K8s deployments.
-
---
-
-## Quick Start Commands
-
-### Application Development
+## Quick Start

 ```bash
-# Frontend (ljwx-admin) - Vue3 Admin Dashboard
+# Frontend (Vue3)
 cd ljwx-admin && pnpm install && pnpm dev  # http://localhost:3333

-# Backend (ljwx-boot) - Spring Boot API
+# Backend (Spring Boot)
 cd ljwx-boot && ./run-local.sh  # http://localhost:9998

-# BigScreen (ljwx-bigscreen) - Python Dashboard
+# BigScreen (Flask)
 cd ljwx-bigscreen/bigscreen && python run.py  # http://localhost:5225
 ```

-### CI/CD Deployment
-
-```bash
-# Auto-deploy via git push
-git push origin main     # Production → K3s
-git push origin develop  # Development
-
-# Manual GitHub Actions trigger
-# Actions → GitOps Deploy to K3s → Run workflow
-```
-
-### OpenAPI Contract
-
-```bash
-cd ljwx-boot
-./scripts/export-openapi.sh                    # Export contract
-./scripts/check-api-breaking-changes.sh        # Check breaking changes
-```
-
-📖 **Detailed guide**: [OpenAPI Contract Guide](docs/06-development/backend/openapi-contract-guide.md)
-
---
-
-## Service Access Points
-
-### Application Services
-
-| Service | URL | Purpose |
-|---------|-----|---------|
-| **ljwx-admin** | http://localhost:3333 | Admin dashboard |
-| **ljwx-boot** | http://localhost:9998 | Backend API |
-| **ljwx-bigscreen** | http://localhost:5225 | Monitoring dashboard |
-| **API Docs** | http://localhost:9998/doc.html | Swagger/Knife4j |
-
-### Database Services
-
-| Service | Connection | Credentials |
-|---------|------------|-------------|
-| **MySQL** | 127.0.0.1:3306 | root / 123456<br>Database: test |
-| **Redis** | 127.0.0.1:6379 | Password: 123456<br>DB: 1 |
+**DO NOT restart ljwx-boot** — user handles restarts manually.

 ---

 ## Architecture

-### Application Stack
+| Component | Stack | Port |
+|-----------|-------|------|
+| ljwx-admin | Vue3 + TypeScript + Naive UI + Pinia | 3333 |
+| ljwx-boot | Spring Boot 3 + Java 21 + MySQL + Redis | 9998 |
+| ljwx-bigscreen | Flask + Python + ECharts | 5225 |

-**ljwx-admin (Frontend)**
- Vue 3.5 + TypeScript 5.7 + Vite 6.0 + Naive UI 2.40
- Pinia 2.3 + Vue Router 4.5
- Multi-tenant support with auto customerId injection
-
-**ljwx-boot (Backend)**
- Spring Boot 3.x + Java 21 + Maven
- MySQL 8.0 with MyBatis-Plus
- Redis with connection pooling
- Health data scheduled tasks
-
-**ljwx-bigscreen (Monitoring Dashboard)**
- Flask 2.0+ + Python 3.8+
- ECharts.js + WebSocket real-time updates
- Celery with Redis backend
-
-### Project Structure
-```
-ljwx-health/
-├── ljwx-admin/                     # Vue3 frontend
-│   ├── src/views/                 # Page components
-│   ├── service/api/               # API calls
-│   └── hooks/common/table.ts      # useTable hook
-│
-├── ljwx-boot/                      # Spring Boot backend
-│   ├── ljwx-boot-admin/           # Main application
-│   ├── ljwx-boot-modules/         # Business modules
-│   ├── run-local.sh               # ⭐ Local startup
-│   └── scripts/                   # Build and deploy scripts
-│
-├── ljwx-bigscreen/                 # Python monitoring
-│   └── bigscreen/
-│       ├── bigScreen/             # Flask application
-│       └── run.py                 # ⭐ Application entry
-│
-└── docs/                          # Documentation
-    ├── 01-getting-started/        # Quick start guides
-    ├── 03-deployment/             # Deployment guides
-    ├── 04-operations/             # Operations manuals
-    └── 06-development/            # Development guides
-```
+**DB**: MySQL `127.0.0.1:3306/test` (root/123456) · Redis `127.0.0.1:6379` (123456, DB:1)

 ---

-## Development Workflow
+## Key Files

-### Frontend Development (ljwx-admin)
+**Backend**
+- `ljwx-boot-modules/.../health/task/HealthBaselineScoreTasks.java` — scheduled tasks
+- `ljwx-boot-modules/.../health/service/WeightCalculationService.java` — health scoring
+- `ljwx-boot-admin/src/main/resources/application-local.yml` — local config
+- `ljwx-boot-admin/src/main/resources/db/migration/` — Flyway migrations

-**Key patterns:**
- Use `useTable` hook for table data management
- NaiveUI components: avoid `remote` property unless needed
- API calls auto-inject customerId via request interceptor
+**Frontend**
+- `src/service/request/index.ts` — request interceptor (auto-injects customerId)
+- `src/hooks/common/table.ts` — useTable hook
+- `src/service/api/` — typed API calls

-📖 **Detailed guide**: ljwx-admin/CLAUDE.md
+**CI/CD**
+- `.github/workflows/gitops-deploy.yml` — GitHub Actions
+- `deploy/helm/ljwx-health/` — Helm chart

-### Backend Development (ljwx-boot)
+---

-**Important notes:**
- **DO NOT restart ljwx-boot during debugging** - User handles restarts
- Check status: `./run-local.sh status`
- Logs are in `logs/` directory
- Configuration: Uses `local` profile
+## Environment Profiles

-📖 **Detailed guides**:
- [Environment Isolation](docs/06-development/backend/environment-isolation.md)
- [OpenAPI Contract Maintenance](docs/06-development/backend/openapi-contract-guide.md)
+| | local | prod/k8s |
+|---|-------|---------|
+| DB | `127.0.0.1:3306/test` | K8s Service DNS |
+| Flyway | Disabled | Enabled |
+| Paths | Relative (`logs/`) | Absolute (`/app/logs/`) |
+| Log format | Plain text | JSON (Loki) |

-### BigScreen Development (ljwx-bigscreen)
+---
+
+## Gates (Quality Checks)

-**Performance testing:**
 ```bash
-./performance_test.sh              # Load testing
-python test_health_fix.py          # Health data tests
+bash scripts/gates/gate-all.sh    # Run all gates
+bash scripts/gates/gate-rules.sh  # Static rules scan only
+bash scripts/gates/gate-compile.sh # Compile check only
 ```

-📖 **Detailed guide**: ljwx-bigscreen/CLAUDE.md
+Hooks auto-run on every Edit/Write — violations are blocked immediately.

 ---

-## CI/CD & Deployment
+## Health Metrics

-### GitHub Actions - GitOps Workflow
+`heart_rate` · `blood_oxygen` · `temperature` · `pressure_high/low` · `stress` · `step/distance/calorie` · `sleep`

-**Auto-deploy triggers:**
- Push to `main` or `develop` branches
- Create `v*` tags (e.g., `v1.2.3`)
+**Scheduled tasks**: 01:00 weight config · 02:00-02:10 baselines · 04:00 scores · 05:00 cleanup

-**Manual trigger:** Actions → GitOps Deploy to K3s → Run workflow
+---

-**Required Secrets:**
- `HARBOR_USERNAME` / `HARBOR_PASSWORD`
- `REDIS_PASSWORD` (optional)
- `MYSQL_USERNAME` / `MYSQL_PASSWORD` (optional)
- `JWT_SECRET` (optional)
+## Docs

-### Gitea Actions - ARM64 Workflow
-
-**Features:**
- ARM64 架构专用构建
- 适合树莓派、Apple Silicon 服务器
- Self-hosted runner 要求: `[self-hosted, linux, ARM64]`
-
-📖 **Detailed guides**:
- [CI/CD Detailed Configuration](docs/03-deployment/gitops/ci-cd-detailed-guide.md)
- [Quick Start (GitHub Hosted)](docs/QUICK_START_GITHUB_HOSTED.md)
- [Quick Start (Self-Hosted)](docs/QUICK_START_GITOPS.md)
+- Architecture: `docs/02-architecture/`
+- Deployment: `docs/03-deployment/`
+- Operations: `docs/04-operations/`
+- Dev guides: `docs/06-development/`
+- **New docs**: Never in root. Use `docs/` subdirs with kebab-case names.

 ---

 ## Custom Base Images

-**⚠️ MANDATORY**: All Dockerfiles must use correct custom base images.
+| Component | Image |
+|-----------|-------|
+| ljwx-boot | `harbor.omniverseai.net/ljwx-base-images/java-maven-otel:21-alpine` |
+| ljwx-admin | `harbor.omniverseai.net/ljwx-base-images/node20-pnpm:latest` |
+| ljwx-bigscreen | `harbor.omniverseai.net/ljwx-base-images/python3.12-pip:latest` |

-### Available Images
-
-| Component | Base Image | Contains |
-|-----------|------------|----------|
-| **ljwx-boot** | `harbor.omniverseai.net/ljwx-base-images/java-maven-otel:21-alpine` | JDK 21 + Maven + **OpenTelemetry Agent 2.11.0** |
-| **ljwx-admin** | `harbor.omniverseai.net/ljwx-base-images/node20-pnpm:latest` | Node 20 + pnpm 10.8.0 |
-| **ljwx-bigscreen** | `harbor.omniverseai.net/ljwx-base-images/python3.12-pip:latest` | Python 3.12 + pip |
-
-### Critical: OpenTelemetry Integration
-
-**Without OpenTelemetry Java Agent, distributed tracing to Tempo won't work.**
-
-**Correct Dockerfile pattern:**
-```dockerfile
-# Build stage
-FROM harbor.omniverseai.net/ljwx-base-images/java-maven-otel:21-alpine AS builder
-# OpenTelemetry agent is at /opt/opentelemetry-javaagent.jar
-
-# Runtime stage
-FROM eclipse-temurin:21-jre-alpine
-COPY --from=builder /opt/opentelemetry-javaagent.jar /opt/opentelemetry-javaagent.jar
-ENTRYPOINT ["sh", "-c", "java -javaagent:/opt/opentelemetry-javaagent.jar $JAVA_OPTS -jar app.jar"]
-```
-
-📖 **Detailed guide**: [Custom Base Images](docs/03-deployment/docker/custom-base-images.md)
+OTel agent at `/opt/opentelemetry-javaagent.jar` — required for distributed tracing.

 ---

-## Environment Isolation
-
-The project implements strict isolation between development and production:
-
-| | Development (local) | Production (prod/k8s) |
-|---|---------------------|----------------------|
-| **Paths** | Relative (`logs/`) | Absolute (`/app/logs/`) |
-| **Database** | `127.0.0.1:3306/test` | K8s Service DNS |
-| **Flyway** | Disabled | Enabled |
-| **Log format** | Plain text | JSON (Loki-compatible) |
-
-📖 **Detailed guide**: [Environment Isolation](docs/06-development/backend/environment-isolation.md)
-
---
-
-## Observability (可观测性)
-
-### Monitoring Stack
-
-LJWX Health 集成三大支柱可观测性：
- **Logs**: Logback/Python JSON → Loki → Grafana
- **Traces**: OpenTelemetry → Tempo → Grafana
- **Metrics**: Micrometer/prometheus_client → Prometheus → Grafana
-
-### Quick Deployment
-
-```bash
-# Deploy monitoring stack to K8s
-./scripts/deploy-observability.sh
-
-# Access Grafana
-kubectl port-forward -n infra svc/grafana 3000:3000  # admin/admin123
-```
-
-### Local Development
-
-```bash
-# Docker Compose
-docker-compose -f ljwx-boot/docker-compose-p0-monitoring.yml up -d
-
-# Access services
-# Grafana: http://localhost:3000
-# Prometheus: http://localhost:9090
-```
-
-📖 **Detailed guide**: [Observability Configuration](docs/04-operations/monitoring/observability-guide.md)
-
---
-
-## Health System Architecture
-
-### Scheduled Tasks
-
-```
-01:00 - Weight configuration validation
-02:00 - User health baseline generation
-02:05 - Department health baseline
-02:10 - Organization health baseline
-04:00 - User health score generation
-05:00 - Data cleanup
-Monthly - Table partitioning
-```
-
-**Location:** `ljwx-boot-modules/src/main/java/com/ljwx/modules/health/task/HealthBaselineScoreTasks.java`
-
-**Management UI:** http://localhost:3000/#/monitor/scheduler
-
-### Supported Health Metrics
-
- **heart_rate** (心率) - Core vital sign
- **blood_oxygen** (血氧) - Respiratory health
- **temperature** (体温) - Body temperature
- **pressure_high/pressure_low** (血压) - Cardiovascular health
- **stress** (压力) - Mental health
- **step/distance/calorie** - Activity metrics
- **sleep** (睡眠) - Sleep quality
-
---
-
-## Important Files and Locations
-
-### Frontend (ljwx-admin)
- **Request interceptor**: `src/service/request/index.ts` - Auto-injects customerId
- **useTable hook**: `src/hooks/common/table.ts` - Table data management
- **API definitions**: `src/service/api/` - Typed API calls
- **Scheduler UI**: `src/views/monitor/scheduler/index.vue`
-
-### Backend (ljwx-boot)
- **Scheduled tasks**: `ljwx-boot-modules/.../health/task/HealthBaselineScoreTasks.java`
- **Weight service**: `ljwx-boot-modules/.../health/service/WeightCalculationService.java`
- **Health service**: `ljwx-boot-modules/.../health/service/UnifiedHealthDataQueryService.java`
- **Environment config**: `ljwx-boot-admin/src/main/resources/application-local.yml`
- **Logging config**: `ljwx-boot-admin/src/main/resources/logback-spring.xml`
-
-### BigScreen (ljwx-bigscreen)
- **Main app**: `bigscreen/bigScreen/bigScreen.py`
- **Configuration**: `bigscreen/config.py`
- **Models**: `bigscreen/bigScreen/models.py`
-
-### CI/CD & Deployment
- **GitHub workflow**: `.github/workflows/gitops-deploy.yml`
- **Gitea workflow**: `.gitea/workflows/gitops-deploy.yml`
- **Deployment script**: `scripts/deploy-k3s-with-ingress.sh`
- **Helm chart**: `deploy/helm/ljwx-health/`
-
---
-
-## Known Issues and Fixes
-
-### IPv6 Address Resolution (Fixed)
- **Issue**: IPv6 localhost "0:0:0:0:0:0:0:1" not recognized by ip2region
- **Fix**: Added detection in `IPUtil.java:171-185`
- **Handles**: Local addresses, IPv6, internal IPs with proper fallbacks
-
-### Weight Cache Table (Fixed)
- **Issue**: `t_weight_cache` table missing caused health score failures
- **Fix**: Auto-creates table structure in `WeightCalculationService.java`
-
-### Health Recommendation NullPointerException (Fixed)
- **Issue**: Null keys in data grouping caused crashes
- **Fix**: Added null filtering in `HealthRecommendationService.java`
-
-### Health Data Query Performance (Optimized)
- **Issue**: N+1 query problem, repeated config parsing
- **Fix**: Batch conversion with caching in `UnifiedHealthDataQueryService.java`
- **Performance**: 13x faster (~200ms → ~15ms for 20 records)
-
---
-
-## Development Best Practices
-
-### Multi-Tenant Architecture
- **customerId auto-injection**: Request interceptor automatically adds customerId
- **Exclusion list**: Login, auth, dictionary, and system APIs excluded
- **Override support**: Explicitly passed customerId values are preserved
-
-### Performance Optimization
- **Avoid N+1 queries**: Use batch queries with caching
- **Batch processing**: Process data in batches of 200 records
- **Connection pooling**: 30 base + 50 overflow connections
- **Redis caching**: 3-5 minute TTL for frequently accessed data
-
-### Code Quality
- **Null safety**: Always filter null values before stream operations
- **Error handling**: Comprehensive try-catch with graceful degradation
- **Logging levels**: DEBUG for details, INFO for performance metrics
- **Type safety**: Proper BigDecimal to Double conversions
-
---
-
-## Additional Documentation
-
-For detailed information about specific subsystems:
- **ljwx-admin**: `ljwx-admin/CLAUDE.md` - Frontend architecture
- **ljwx-bigscreen**: `ljwx-bigscreen/CLAUDE.md` - Monitoring system
- **Infrastructure**: `docs/` directory for detailed guides
-
-### Key Documentation Links
-
-**Development:**
- [Environment Isolation Guide](docs/06-development/backend/environment-isolation.md)
- [OpenAPI Contract Guide](docs/06-development/backend/openapi-contract-guide.md)
- [Backend Development Guide](docs/06-development/backend/)
- [Frontend Development Guide](docs/06-development/frontend/)
-
-**Deployment:**
- [CI/CD Detailed Guide](docs/03-deployment/gitops/ci-cd-detailed-guide.md)
- [Custom Base Images](docs/03-deployment/docker/custom-base-images.md)
- [GitOps Deployment](docs/GITOPS_DEPLOYMENT.md)
- [Quick Start (GitHub Hosted)](docs/QUICK_START_GITHUB_HOSTED.md)
-
-**Operations:**
- [Observability Guide](docs/04-operations/monitoring/observability-guide.md)
- [Database Operations](docs/04-operations/database/)
- [Troubleshooting](docs/04-operations/troubleshooting/)
-
-**Compliance:**
- [Documentation Management Guide](docs/07-compliance/documentation-management-guide.md)
- [Code Review Checklist](docs/07-compliance/)
-
---
-
-*Last updated: 2026-01-19*
-*Optimized for Claude Code context efficiency*
+*Today: 2026-02-24*