tanzk
ea9f936df5
- AGENTS.md 新增铁律14「文件入库分类纪律」，显式引用《仓库入库规范》，
补齐 META 三层强制链（R-P1-6「标而不管」闭环）
- docs/README.md §六（升 v2.2）：
- §6.1 13 份 → standards 14 份 + 根 AGENTS = 15 约束源；补登仓库入库规范；
4 处 ⚠️待挂核实已挂 → ✅（铁律 8-11），另校正 alembic=铁律6、文档性质=文末段
- §6.2 arch 48 → 50 份锁定（_pending 4 份待审）
- §6.3 API ~374 → 449 路径 / 547 操作（app.openapi 实盘）
- §6.4 删除已解决的「4 份 META 无强制入口」并重编号
- arch/README.md：_pending「20 份」改为「初始 20 / 当前实盘 4」（R-P2-2）
- API接口文档.md 升 v1.2：头部计数按 openapi 校正 + 附可复算命令（R-P2-8）
- 台账 R-P1-6/R-P2-1/R-P2-2/R-P2-8 回填已完成及实盘证据
实盘 2026-10-07：standards META14/REQ3/REF5=22；arch 锁定 50、_pending 草案 4；
FastAPI 449 路径、547 操作（448 /api/v1 + /health）。
2.8 KiB
2.8 KiB
架构文档（Arch）— 锁定目录
生效日期：2026-09-01 用途：存放已锁定的架构设计文档（对应"AI 协作治理规范" 4.2 / 4.3） 关联文档：AGENTS.md（全局约束，其中"禁止擅自修改已锁定架构文档"）
⚠️ 本目录下的文件默认视为 LOCKED（锁定）。AI 助手不得擅自修改； 修改必须先经人工审核，更新后重新标记版本并打 tag。
目录规范
| 项 | 约定 |
|---|---|
| 命名 | A-YYYYMMDD-序号-简述.md（如 A-20260901-001-退款查询接口.md） |
| 锁定标记 | 文件头部标注 状态: LOCKED + 版本号 |
| git tag | 锁定后打 arch/A-YYYYMMDD-序号 标签 |
| 修改 | 人工审核 → 更新文件 → 版本号 +1 → 重新打 tag |
子目录：_pending/（待审核设计文档）
docs/arch/_pending/ 存放已迁移但未经架构锁定流程的历史设计文档（原 .trae/documents/，初始迁入 20 份；经多轮审核锁定 / 归位后，截至 2026-10-07 实盘仅剩 4 份待审草案，以目录实际文件为准）。
- 状态：
PENDING（待人工审核），不是 LOCKED - 规则：AI 可阅读参考，但不得视为已锁定架构；开发前若引用其中设计，须先经人工审核确认
- 迁移：审核通过后按
A-YYYYMMDD-序号-简述.md重命名、标注状态: LOCKED并移到docs/arch/根目录、打arch/tag
文档模板
# A-YYYYMMDD-序号-简述
**状态**：LOCKED（v1.0）
**日期**：YYYY-MM-DD
**架构师阶段产出**：<是谁 / 哪个 Agent 产出>
**审查结论**：<人工终审结果>
## 一、模块边界图
```mermaid
graph LR
A[模块A] --> B[模块B]
B --> C[模块C]
二、接口契约
- 路径：
/api/v1/xxx - 方法：GET/POST/PUT/DELETE
- 请求 / 响应字段（含单位，金额为分）
- 错误码（对照 docs/standards/error-code.md）
三、数据库变更（ER 增量）
| 字段 | 类型 | 索引 | 外键 | 说明 |
|---|---|---|---|---|
| id | bigint PK | PK | - | - |
四、风险清单（至少 3 个）
- <风险 1>
- <风险 2>
- <风险 3>
---
## 阶段切换 SOP（对应 4.3）
1. 需求确认 → **Architect** 阶段 → 产出架构文档（放本目录）
2. 人工审核架构文档 → **锁定**（标记 LOCKED + 打 `arch/` tag）
3. 切 **Developer** 阶段 → 基于本目录已锁定文档开发（禁止自行改架构）
4. 开发完成 → commit → 切 **Reviewer** 阶段 → 审查报告（见 docs/standards/review-checklist.md）
5. 报告无 CRITICAL → 人工终审 → 合并
6. 有 CRITICAL → 切回 Developer 修复 → 重新审查
> 关键：阶段切换时必须清空上一轮上下文（新建会话），防止 AI 把架构阶段假设带到开发阶段。