jackyu66gitandCursor
bd22d9dddd
落地 synastry/star/ask API 与 H5 页面，补齐 cece-frontend-re complete-design 证据文档，并加入 Android 模拟器截图抓取脚本。 Co-authored-by: Cursor <cursoragent@cursor.com>
119 lines
4.3 KiB
Markdown
119 lines
4.3 KiB
Markdown
# Feature Design Standard
|
||
|
||
**任何新功能或重大行为变更，开发前必须存在对应 Feature Specification。**
|
||
|
||
Feature Spec 是产品、设计、开发的**唯一功能输入**。
|
||
`feature-map.md` 只回答「做什么 / 在哪棵树上」——**不够**开始编码。
|
||
|
||
完整链路：
|
||
|
||
```
|
||
feature-map（能力树）
|
||
→ feature-spec（功能详细设计）
|
||
→ domain / OpenAPI / erd（技术契约）
|
||
→ implementation
|
||
→ test
|
||
→ review
|
||
```
|
||
|
||
规范位置：本文件。
|
||
Spec 目录：[`feature-spec/`](feature-spec/README.md)。
|
||
模板：[`feature-spec/_TEMPLATE.md`](feature-spec/_TEMPLATE.md)。
|
||
对标成熟 App：[`../design/reverse-engineering-spec.md`](../design/reverse-engineering-spec.md)（逆向 STEP 1–18 · Evidence First）。
|
||
|
||
---
|
||
|
||
## 禁止
|
||
|
||
- 根据一句需求直接编码
|
||
- 根据页面截图或竞品 UI **跳步猜测**业务规则（须走逆向规范并标注证据）
|
||
- 未定义 User Flow / 页面状态 / Business Rules 就开发
|
||
- 仅有页面或 API「能跑」就称 Feature Complete
|
||
- Spec 未更新就扩大已有功能行为（bugfix 除外）
|
||
- 在 Spec 中偷偷扩大 `feature-map` 分期范围（P2 写成 P1）
|
||
- 对标竞品时输出 Demo/MVP 式省略（「略」「TODO」「以后再做」）作为 Spec 终态
|
||
|
||
---
|
||
|
||
## 允许的例外
|
||
|
||
| 场景 | 要求 |
|
||
|---|---|
|
||
| 明确 bugfix（行为已在 Spec/OpenAPI 定义） | 可直接修；若暴露 Spec 错误则同步修正 Spec |
|
||
| 文案/lexicon 微调且不改规则 | 可改代码 + lexicon；不强制新 Spec |
|
||
| 纯重构（对外行为不变） | 不强制新 Spec；DoD 仍适用 |
|
||
| 存量功能尚无 Spec | **进入该功能开发前必须先 retrofit Spec**；否则只许修明确 bug，不得扩行为 |
|
||
|
||
---
|
||
|
||
## 冲突优先级
|
||
|
||
1. `lexicon.md`（用户可见中文）
|
||
2. `feature-map.md` 分期与边界标记
|
||
3. **本功能的 `feature-spec/<id>.md`**（流程、规则、验收）
|
||
4. `user-journey.md` / `page-tree.md`
|
||
5. `domain/` + OpenAPI（实现契约；必须与 Spec §8/§9 对齐）
|
||
6. 历史 PRD / `apps/docs/*` / 立项文档
|
||
|
||
Spec 文案不得违反 lexicon。Spec 不得把 `[P2]`/`[No]` 能力写成已交付。
|
||
|
||
---
|
||
|
||
## Feature Spec 强制章节
|
||
|
||
每份 Spec 必须包含（可用 N/A + 原因，不可省略标题）：
|
||
|
||
| # | 章节 | 要求 |
|
||
|---|---|---|
|
||
| 1 | 功能定义 | Name / Purpose / Business Goal |
|
||
| 2 | 用户价值 | 为何需要 / 完成后获得什么 / 为何付费 |
|
||
| 3 | 用户角色 | Guest / User / VIP（对齐实际 Identity 模型） |
|
||
| 4 | 用户流程 | ASCII 或 mermaid；含分支 |
|
||
| 5 | 页面设计 | 路由 + 页面列表；对照 page-tree |
|
||
| 6 | 页面状态 | Loading / Empty / Error / Normal / Locked（适用则写） |
|
||
| 7 | Business Rules | 编号 Rule N；**权益由 Server 判断** |
|
||
| 8 | 数据模型影响 | 表/字段；指向 erd，禁止臆造 |
|
||
| 9 | API 需求 | 路径级意图；细节以 OpenAPI 为准并须同步 |
|
||
| 10 | 权限设计 | 角色 × 能力矩阵 |
|
||
| 11 | 埋点 | 事件名；未接 SDK 也先定义 |
|
||
| 12 | 测试验收标准 | Given / When / Then |
|
||
| 13 | AI 开发前检查 | checkbox |
|
||
| 14 | Implementation Notes | 编码时填写：包、迁移、与现状 gap |
|
||
|
||
User Flow 与验收故事**写在 Spec 内**，不另建平行 `user-story/` 真相源。
|
||
|
||
---
|
||
|
||
## AI 开发前检查（强制）
|
||
|
||
Before implementation, AI MUST verify:
|
||
|
||
- [ ] Feature Spec 文件存在（`feature-spec/<id>.md`）
|
||
- [ ] 已在 `feature-map.md` 挂树且分期正确
|
||
- [ ] User Flow（§4）已定义
|
||
- [ ] Business Rules（§7）已定义
|
||
- [ ] API 需求（§9）已定义，并计划更新 OpenAPI
|
||
- [ ] 数据影响（§8）已核对 erd
|
||
- [ ] 页面状态（§6）已定义
|
||
- [ ] Acceptance（§12）已定义
|
||
- [ ] 文案符合 `lexicon.md`
|
||
|
||
任一项缺失 → **停止编码，先补 Spec 或 ASK**。
|
||
|
||
---
|
||
|
||
## 何时更新 Spec
|
||
|
||
- 新功能：先复制 `_TEMPLATE.md` → 填满 → 再编码
|
||
- 改规则 / 改权益 / 改主流程 / 改付费墙：先改 Spec，再改代码
|
||
- 仅修 bug：若 Spec 与现实不符，修完后回写 Spec
|
||
|
||
Playbook：[`../playbooks/feature-spec.md`](../playbooks/feature-spec.md)
|
||
|
||
---
|
||
|
||
## 与 DoD 的关系
|
||
|
||
无适用 Feature Spec → **不得**勾选 Feature Complete（见 `definition-of-done.md` §1）。
|
||
「OpenAPI 有了 / 页面打开了」而 Spec 缺失 = 伪完成。
|