brunoandClaude Sonnet 4.5
332c032ef9
新增核心功能： - 健康画像生成系统（用户/部门/组织基线） - 风险评估框架（心血管/运动/呼吸/睡眠） - 行为画像分析（饮食/运动/睡眠/健康关注度） - 数据质量评分和告警 数据库迁移： - V1.3.0~V1.7.0 健康监测表结构 前端增强： - ljwx-admin: BigScreen集成、健康搜索优化 - ljwx-bigscreen: SSO认证、登录界面 文档体系： - 强制文档管理规范（kebab-case、分类、Git hooks） - 架构文档、开发指南、运维手册 - 工程蓝图 v2.1 CI/CD： - 文档验证工作流 - 生产就绪性检查脚本 - 完整测试覆盖 Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
6.3 KiB
Claude Code 驱动的生产级开发蓝图 v2.1（完整版）
项目定位：基于 OrbStack K8s 的 FastAPI 生产级模板项目 适用对象：个人 / 小团队 / AI-first 开发 核心原则： • Claude / qwen 不依赖记忆 • Git 是唯一事实源 • 应用 PR ≠ 上线 • GitOps PR 才是发布 • 所有“环境事实”必须可引用、可追溯、可回滚
⸻
🔥 v2.1 相对 v2.0 的本质升级
维度 v2.0 v2.1 上下文 说明性文档 协议化 + 强制引用 部署 CI 内隐式 GitOps PR 显式发布 AI 行为 依赖“听话” 依赖门禁 +结构 环境事实 分散在文档 GitOps Truth Ledger 单点 回滚 理论支持 PR / Argo / Git Revert 可审计性 有日志 PR + 历史 + Gate
⸻
0️⃣ 总体架构（先理解整体）
┌────────────┐ │ Issue │ ← 需求合同（不可模糊） └─────┬──────┘ │ ▼ ┌────────────┐ │ App Repo │ ← Claude / qwen 开发 │ 应用 PR │ （功能 + 测试 + 镜像） └─────┬──────┘ │ CI 产物：image:tag ▼ ┌────────────┐ │ GitOps PR │ ← 唯一“上线动作” │ 更新 tag │ └─────┬──────┘ │ ▼ ┌────────────┐ │ Argo CD │ ← Sync / Rollback └─────┬──────┘ │ ▼ ┌────────────┐ │ 验证闭环 │ ← health / metrics / logs / traces └────────────┘
一句话总结：
👉 应用仓解决“做没做对” 👉 GitOps 仓决定“有没有上线”
⸻
1️⃣ 仓库职责划分（v2.1 强制）
1.1 应用仓（App Repo）
职责： • 业务代码 • 测试 • Dockerfile • Helm Chart 模板（不含真实值） • 开发蓝图 / AI 协议
禁止： • ❌ 不得包含真实环境 DNS / 端口 / 密码 • ❌ 不得包含 prod 级 values
⸻
1.2 GitOps 仓（Deployment Repo）
职责： • 环境 values（dev / staging / prod） • ArgoCD Application • 唯一事实源（Truth Ledger）
一句铁律：
凡是“部署能否成功”的信息，只能存在于 GitOps 仓
⸻
2️⃣ Truth Ledger（v2.1 核心设计）
2.1 定义
Truth Ledger 是 唯一允许描述真实环境的地方：
gitops/ docs/ 40-truth.md ← 唯一事实源
包含但不限于： • Service DNS • Namespace • Registry / Harbor • 镜像命名规范 • ArgoCD 策略 • Runner 标签 • 环境差异
⸻
2.2 Claude / qwen 的硬规则 • ✅ 可以引用 gitops/docs/40-truth.md • ❌ 禁止凭空输出任何环境事实 • ❌ 禁止“根据经验猜”
若事实不存在，必须：
Assumption:
- 假设 Postgres service 名为 xxx
Verification:
- kubectl get svc -n infra
⸻
3️⃣ AI 执行协议（Execution Protocol）
本节是 Claude/qwen 的“宪法”
3.1 必读文件（强制）
Claude / qwen 在任何任务前，必须阅读： 1. docs/blueprint/PROMPT_BLUEPRINT_V2_1.md 2. docs/blueprint/AI_EXECUTION_PROTOCOL.md 3. gitops/docs/40-truth.md
⸻
3.2 输出结构（不允许缺项）
Claude 每一次输出必须按以下顺序：
Facts
（每条必须带 Source: path#section）
Assumptions
（<=3，每条含 Verification）
Plan
（<=8 步，可执行）
Diff Map
（将修改哪些文件）
Tests
（本地 / CI / Post-deploy）
Rollback
（如何回滚）
⸻
3.3 最重要的反瞎编机制 • Facts 必须可定位到文件 • 定位不到 → Assumption • 不允许混用
⸻
4️⃣ 开发流程（v2.1 两段 PR）
阶段 A：应用 PR（Build）
Issue ↓ Claude 规划（Plan） ↓ qwen / Claude 实现 ↓ 应用 PR ↓ CI Gate（必须全部通过）
CI Gate（必须） • pytest • mypy • lint • 安全扫描（bandit / safety） • build image • 上传测试报告
📌 此阶段结束：仅代表“可部署”
⸻
阶段 B：GitOps PR（Release）
CI 成功 ↓ 自动创建 GitOps PR ↓ 修改 dev values.yaml 中的 image.tag ↓ Merge ↓ ArgoCD Sync
GitOps PR 限制（强制） • 只能修改： • image.repository • image.tag • 环境 values • ❌ 禁止业务代码 • ❌ 禁止 Chart 结构变更（除非专门 PR）
⸻
5️⃣ 多环境晋级模型
dev → staging → prod
晋级方式 • dev：CI 自动 PR • staging：人工合并 PR • prod： • 必须 CODEOWNERS 审批 • selfHeal = false • 必须附带 rollback 说明
⸻
6️⃣ Post-deploy 验证（v2.1 强制闭环）
GitOps PR 合并后 必须验证：
6.1 功能 • /health/ready → 200 • 至少一个核心 API
6.2 可观测性 • /metrics 可抓 • Loki 有日志 • 日志包含 trace_id • Tempo 可看到 span
6.3 结果记录 • PR comment • 或 CI artifact • 或 Grafana dashboard 链接
⸻
7️⃣ 数据库迁移规则（保持 + 强化） • 只能通过 ArgoCD PreSync Hook • 必须 Expand / Contract • 禁止手工跑迁移作为常态
⸻
8️⃣ 回滚模型（v2.1）
层级 手段 应用 Git revert 发布 回滚 GitOps PR 部署 ArgoCD rollback 数据 前滚修复 / PITR
⸻
9️⃣ 禁止事项（v2.1 强化）
9.1 AI 行为 • ❌ 输出无法引用的事实 • ❌ 跳过测试 • ❌ 直接操作生产集群
9.2 部署 • ❌ CI 内 kubectl apply prod • ❌ 在 app repo 写 prod values • ❌ Secret 入 Git
⸻
🔟 新服务启动 Checklist（强烈建议）
[ ] 创建 app repo（模板） [ ] 创建 gitops app 目录 [ ] 填 docs/00-context.md [ ] 初始化 Helm chart [ ] 配 CI（build + test + image） [ ] 配 GitOps Application [ ] 验证 dev 部署
⸻
1️⃣1️⃣ 必备文件清单（v2.1 生效条件）
应用仓
docs/ blueprint/ PROMPT_BLUEPRINT_V2_1.md AI_EXECUTION_PROTOCOL.md
GitOps 仓
docs/ 40-truth.md 10-workflow.md envs/ dev/ staging/ prod/
⸻
1️⃣2️⃣ 版本历史 • v2.1（当前） • 引入 Truth Ledger • 引入两段 PR • AI 执行协议化 • Post-deploy 验证闭环
⸻
✅ 总结一句话
v2.1 的本质不是“写得更详细”，而是： 把 AI 从“聪明但不可靠”，变成“不聪明但不会乱来”。
⸻