# 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 缺失 = 伪完成。