ljwx-health/CLAUDE.md

CLAUDE.md — LJWX Health

⚡ 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)

---

🚨 Hard Rules (violation = task failure)

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

---

Quick Start

# Frontend (Vue3)
cd ljwx-admin && pnpm install && pnpm dev  # http://localhost:3333

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

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

DO NOT restart ljwx-boot — user handles restarts manually.

---

Architecture

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

DB: MySQL 127.0.0.1:3306/test (root/123456) · Redis 127.0.0.1:6379 (123456, DB:1)

---

Key Files

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

Frontend

• src/service/request/index.ts — request interceptor (auto-injects customerId)
• src/hooks/common/table.ts — useTable hook
• src/service/api/ — typed API calls

CI/CD

• .github/workflows/gitops-deploy.yml — GitHub Actions
• deploy/helm/ljwx-health/ — Helm chart

---

Environment Profiles

	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)

---

Gates (Quality Checks)

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

Hooks auto-run on every Edit/Write — violations are blocked immediately.

---

Health Metrics

heart_rate · blood_oxygen · temperature · pressure_high/low · stress · step/distance/calorie · sleep

Scheduled tasks: 01:00 weight config · 02:00-02:10 baselines · 04:00 scores · 05:00 cleanup

---

Docs

• 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

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

OTel agent at /opt/opentelemetry-javaagent.jar — required for distributed tracing.

---

Today: 2026-02-24