# 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

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

```markdown
## 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/p1-status.md) · [product/p2-status.md](product/p2-status.md)。

---

## 10. 宣称 Done 前的最短自问

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