digital-psychology/.ai/definition-of-done.md

Definition of Done — AI Quality Gate（强制）

Done ≠ Code Complete.
Done = Feature Complete + Verified + Documented.

任何功能在未满足下列适用标准前，禁止对用户说「完成 / Done / P1 Complete」。
若某项 N/A，必须写明原因；静默跳过 = Not Done。

加载：每个任务结束前必须对照本文件；见 AGENTS.md。

---

0. 禁止的「伪完成」信号

仅有下列项 不足以 称 Done：

• API 路由存在
• 页面能打开
• go test ./... 或 npm run build:h5 通过
• 没有 product/feature-spec/<id>.md 却声称功能完整

还缺：Feature Spec、测试分层、异常/空/加载态、权限、完整用户路径、文档与 Review。

---

1. Feature 完成（产品层）

必须：

项	要求
Feature Spec	存在 product/feature-spec/<id>.md；§4 Flow / §7 Rules / §9 API / §12 Acceptance 非空（见 feature-design.md）
Feature Map	已在 product/feature-map.md 定义且范围清晰
用户路径	Spec §4 + user-journey.md 对应 Step；入口可达
页面入口	Spec §5 + page-tree.md 路由存在
Loading	网络请求有加载态（Spec §6）
Empty	无数据有引导（非空白死页）
Error	失败可感知 + 可恢复（重试/返回）

示例 — 个人画像完整路径（缺一不可称该 Feature Done）：

进入 → 无档案 → 创建档案 → 生成画像
  → 查看基础版 → 深度版入口 → 支付/mock → 完整分析可见

仅有「/portrait 显示一段文案」= Demo / Incomplete。

---

2. Backend Done

2.1 API

• OpenAPI（proto/openapi.yaml）已更新
• Request / Response 字段明确
• 错误走统一信封 {code,message,data}；业务失败用数字 code + 可读 message
• 禁止裸 { "error": "..." } 作为对外约定

2.2 分层

handler → service → repository → database

• 业务逻辑不在 handler
• 权益 / 归属校验在 service（或明确 domain 层），不在前端

2.3 测试（见 §4）

• 核心 service / engine 有单元测试（Level 1）
• P1 关键流有集成测试或可重复的自动化冒烟（Level 2）

---

3. Frontend Done

3.1 页面四态

每个网络页面必须具备：

状态	要求
Normal	成功数据正确展示
Loading	请求中
Empty	无档案 / 无列表等引导
Error	失败文案 + 重试或返回

示例 — 问答不能只有聊天壳；至少覆盖：无档案、发送中、失败重试、历史为空（登录态按当前 Visitor 模型裁剪）。

3.2 组件

抽公共组件时：可复用、props 明确、状态完整；遵守 design/component-catalog.md + lexicon。

3.3 文案

用户可见文本符合 product/lexicon.md。

---

4. Test Done（分级）

Level	名称	最低要求	P1 Feature
0	Build	go test ./...；触及 H5 则 npm run build:h5	必须
1	Unit	Domain / Service / 算法（如 portrait、relation、scale 计分）	必须
2	Integration	至少一条端到端 API 流可自动跑	P1 关键流必须
3	E2E	浏览器关键路径（Playwright 等）	P1 收口前至少 1 条主路径

P1 必须覆盖的 Integration 流（Level 2）

1. Portrait： create profile → generate portrait → deep_access mock → detail 可见
2. Relation： two profiles → relation insight → deep_access → tips 可见
3. Membership（有实现后）： subscribe mock → 权益生效 → 报告完整字段

Level 0 alone ≠ Backend/Frontend Done。

---

5. Database Done

• apps/api/migrations/ 有对应变更
• 新环境：deps:up → API 启动 migrate → 可服务
• 破坏性变更有 rollback / forward 策略（见 database.md）
• Seed 可选但须幂等或可重复说明

禁止手改共享/生产库代替 migration。

---

6. Security Done

• 权益（深度版 / 成长会员）只在服务端裁剪字段
• 用户只能访问自己的 Profile / Report（归属校验）
• 入参校验；参数化 SQL（无拼接）
• Secret 不入库、不进镜像、不进提交

禁止：前端 if (vip) showFullReport() 作为唯一闸门。

---

7. AI Review Done

功能声称完成前，必须输出：

## Review Report
- Feature: <name>
- Scope label: Demo | Feature Complete | P1 Complete | N/A
- Architecture: PASS | FAIL — <note>
- API: PASS | FAIL | N/A — <note>
- Security: PASS | FAIL | N/A — <note>
- Test (L0/L1/L2/L3): PASS | FAIL — <note>
- Frontend states (L/E/E/N): PASS | FAIL | N/A — <note>
- Documentation: PASS | FAIL | N/A — <note>
- Environment: PASS | FAIL | N/A — <note>
- Known Issues: <list or none>

任一关键 FAIL → 不得标 Done。

另保留 .ai/review.md 细项可一并勾选。

---

8. Release Done（版本发布时）

• CHANGELOG
• Migration 说明
• Environment / 配置说明
• Test Result（含 Level）
• Rollback Plan

---

9. 阶段标签（强制用词）

标签	含义
Vertical Slice Demo	主路径可演示；缺测/缺态/缺功能仍可存在
Feature Complete	单功能满足本文件 §1–7
P1 Complete	feature-map P1 必做项全部 Feature Complete + L2 三流 + 至少 1 条 L3（或书面豁免经用户同意）
P2 Complete	feature-map P2 范围全部 Feature Complete + P2 L2 流 + 至少 1 条 P2 L3（真支付除外，见 feature-map）

当前仓库默认状态见：product/p1-status.md · product/p2-status.md。

---

10. 宣称 Done 前的最短自问

1. 用户能否走完 journey，不只是打开页？
2. 无数据 / 失败时页面是否可用？
3. 不付费能否靠改前端看到深度字段？（不应）
4. 新机器按 commands.md 能否复现？
5. Review Report 是否已贴出且无 FAIL？