digital-psychology/.ai/product/feature-design.md

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/_TEMPLATE.md。
对标成熟 App：../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

---

与 DoD 的关系

无适用 Feature Spec → 不得勾选 Feature Complete（见 definition-of-done.md §1）。
「OpenAPI 有了 / 页面打开了」而 Spec 缺失 = 伪完成。