ljwx-health/docs/engineering/decision-records/0001-template-adoption.md

ADR-0001: 接入模板治理体系

状态

已接受 (Accepted) - 2025-12-18

上下文

ljwx-health（灵境万象健康监测系统）当前处于快速迭代阶段，存在以下工程挑战：

现状问题

1. API 契约缺失:

   • Swagger/Knife4j 仅在运行时生成，无基线契约
   • 前后端联调依赖"口头约定"或临时文档
   • 无法进行破坏性变更检测

2. 数据库版本化混乱:

   • 迁移脚本散落在 sql/migration/, database/migrations/, migration_*.sql
   • 无统一迁移工具（Flyway/Liquibase）
   • 新环境搭建依赖手动执行 SQL

3. 可观测性薄弱:

   • 日志格式不统一（文本 vs JSON）
   • 缺少分布式追踪（Trace）
   • 指标暴露不规范（无 Golden Signals）

4. 部署流程缺失:

   • 无标准化 Compose/Helm 配置
   • 环境搭建依赖"老手带新手"
   • 无 GitOps 流程

业务影响

• 研发效率低: 新人上手时间 > 3 天
• 线上故障定位慢: 缺少 Trace，依赖日志搜索
• 发布风险高: 无自动化迁移，手动执行易出错
• 技术债累积: 临时方案越来越多，无统一规范

---

决策

引入 模板治理体系，分 6 个阶段实施：

阶段 1: 治理骨架（PR-1）

新增:

• PROMPT_BLUEPRINT.md - AI 受控开发蓝图 v1.0
• PROMPT_TASK.md - 任务清单与分阶段规划
• openapi/openapi.yaml - OpenAPI 3.0 契约基线
• observability/{logging,tracing,metrics}.md - 可观测性规范
• deploy/README.md - 部署演进路线图
• docs/engineering/decision-records/0001-template-adoption.md - 本文件

验收: 文档齐全，不影响现有服务运行

阶段 2: OpenAPI 契约（PR-2）

目标: 建立 API 契约基线，覆盖核心 20% 接口

关键接口:

• 健康数据查询（Spring Boot）
• 设备管理（Spring Boot）
• 告警配置（Spring Boot）
• 大屏数据 API（FastAPI）

统一模型:

• ErrorResponse（错误响应）
• PageResponse<T>（分页响应）
• 认证方式（Bearer Token）

验收: OpenAPI 可被 Swagger UI/Redoc 渲染

阶段 3: Flyway 集成（PR-3）

策略: 使用 Flyway baseline，从 data.sql 当前状态起步

迁移文件:

• V20251218_001__baseline.sql（从 data.sql 提取 schema-only）
• V20251218_002__create_message_config_table.sql（补充缺失的表）

配置:

spring.flyway:
  enabled: true
  baseline-on-migrate: true  # 关键：已有库不重放历史脚本
  locations: classpath:db/migration

验收: 新库/已有库均能正常执行迁移

阶段 4: Compose 开发环境（PR-4）

新增:

• deploy/compose/docker-compose.dev.yml（MySQL + Redis）
• scripts/db_migrate.sh（执行 Flyway 迁移）
• scripts/dev_up.sh（启动基础设施）
• scripts/dev_down.sh（停止服务）

验收: 新人执行 ./scripts/dev_up.sh && ./scripts/db_migrate.sh 即可完成环境搭建

阶段 5: 可观测性改造（PR-5）

Spring Boot:

• Metrics: 启用 /actuator/prometheus
• Tracing: 增加 OTel Java Agent 启动配置
• Logging: Logback JSON 格式 + trace_id 注入

FastAPI:

• Metrics: 增加 /metrics 端点（prometheus_client）
• Tracing: OTel instrumentation（自动埋点）
• Logging: structlog + trace_id

验收: Loki ↔ Tempo ↔ Prometheus 三支柱可联动查询

阶段 6: Helm 部署骨架（PR-6）

新增:

• deploy/helm/ljwx-health/Chart.yaml
• deploy/helm/ljwx-health/values.yaml
• deploy/helm/ljwx-health/templates/（deployment, service, ingress, migration-job）
• deploy/environments/{dev-eu,dev-mac}.yaml

验收: Helm 模板语法正确（暂不要求可部署）

---

技术栈约束（不可更改）

组件	技术选型	说明
后端	Spring Boot 3.x + FastAPI	已有技术栈
数据库	MySQL 8.0（当前），Postgres（未来）	迁移到 infra namespace 复用
缓存	Redis	独立前缀/库隔离
CI	GitHub Actions（hosted runner）	除非明确要求使用 self-host/ARC
CD	Argo CD（GitOps）	部署目标为 k3s 集群（EU 节点/Mac Studio）
可观测性	Grafana + Loki + Tempo + Prometheus（原生）	K8s 部署，ConfigMap 挂载配置

---

替代方案

方案 A: 仅引入 Flyway，不做全面治理 ❌

优点: 快速解决数据库版本化问题

缺点:

• API 契约、可观测性问题依然存在
• 无法形成系统性工程规范
• 后续补课成本更高

决策: 拒绝。局部优化无法解决系统性问题。

方案 B: 一次性重构全部代码 ❌

优点: 彻底解决所有问题

缺点:

• 风险巨大（可能引入新 Bug）
• 周期长（影响业务迭代）
• 需要停止所有功能开发

决策: 拒绝。采用 渐进式改造（6 个 PR 分阶段）更稳健。

方案 C: 采用模板治理体系（本方案）✅

优点:

• 分阶段实施，风险可控
• 每个 PR 独立可验收
• 不阻塞业务功能开发
• 建立长期工程规范

缺点:

• 需要 6 个 PR 逐步完成
• 需要团队学习新工具（Flyway, OTel）

决策: 接受。风险与收益平衡最优。

---

实施计划

时间线（建议）

PR	内容	预计工作量	依赖
PR-1	治理骨架	0.5 天	无
PR-2	OpenAPI 契约	1 天	PR-1
PR-3	Flyway 集成	1.5 天	PR-1
PR-4	Compose 环境	0.5 天	PR-3
PR-5	可观测性改造	2 天	PR-1
PR-6	Helm 骨架	1 天	PR-4

总计: 约 6.5 个工作日

验收总体标准

• 所有 6 个 PR 文件清单完整
• 新人可通过 ./scripts/dev_up.sh 一键启动开发环境
• OpenAPI 契约可被工具验证（openapi-diff, spectral）
• Flyway 迁移在新库/已有库均能正常执行
• 可观测性三支柱（Logs/Traces/Metrics）均可查询
• Helm 模板可被 helm template 渲染

---

后果

正面影响

1. 研发效率提升:

   • 新人上手时间从 3 天缩短至 1 小时
   • 前后端联调不再依赖"口头约定"

2. 线上故障定位时间缩短:

   • 从日志搜索（30 分钟）→ Trace 定位（1 分钟）

3. 发布成功率提升:

   • 数据库迁移自动化，避免手动执行错误

4. 技术债可控:

   • 建立长期工程规范，避免临时方案累积

负面影响（可控）

1. 学习成本:

   • 团队需学习 Flyway, OTel, Helm
   • 缓解措施: 提供详细文档（observability/*.md, deploy/README.md）

2. 短期开发效率下降:

   • 前 2 周需要适应新规范
   • 缓解措施: 逐步实施（6 个 PR），每个 PR 独立可验收

3. 基础设施依赖:

   • 需要 Tempo, Prometheus, Loki 已部署
   • 缓解措施: 开发环境可先用 Compose 部署（PR-4）

---

相关决策

• ADR-0002: 数据库迁移从 MySQL 到 Postgres（待规划）
• ADR-0003: 前端 Vue3 组件规范（待规划）

---

参考资料

• PROMPT_BLUEPRINT.md - AI 受控开发蓝图 v1.0
• PROMPT_TASK.md - 任务清单与分阶段规划
• OpenAPI Specification 3.0
• Flyway Documentation
• OpenTelemetry Documentation
• Argo CD Documentation

---

决策日期: 2025-12-18 决策人: LJWX Health Engineering Team 审核人: AI-Assisted Development Team 状态: ✅ 已接受，进入实施阶段（PR-1 完成）