jackyu66gitandCursor
5ceb3ce749
落地管理员 RBAC/封禁/推送任务 stub，logout 解绑 device 并统一各页 ensureAccount，同时收口 P2 生日生成与状态文档。 Co-authored-by: Cursor <cursoragent@cursor.com>
196 lines
5.9 KiB
Markdown
196 lines
5.9 KiB
Markdown
# 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？
|