# Feature Spec: \<Name\>

> 复制本文件为 `<id>.md`。规范：[../feature-design.md](../feature-design.md)  
> 语言：[../lexicon.md](../lexicon.md) · 能力树：[../feature-map.md](../feature-map.md)  
> Status: `Draft` | `Active` | `Deprecated`  
> Map node: （如 `2.3 个人画像 [P1]`）  
> Phase: `P1` | `P2` | `P3`

---

## 1. 功能定义

| 字段 | 内容 |
|---|---|
| Name | |
| Purpose | |
| Business Goal | |

**In Scope / Out of Scope**（防止偷偷扩 scope）

| In | Out |
|---|---|
| | |

---

## 2. 用户价值

必须回答：

1. 用户为什么需要它？  
2. 用户完成后获得什么？  
3. 为什么愿意付费？（若无付费面，写 N/A）

---

## 3. 用户角色

对齐当前 Identity（Visitor 设备身份 + 可选升级）。写清**实际能做什么**，勿照搬竞品。

| Actor | 说明 | 本功能能力 |
|---|---|---|
| Guest / Visitor | 未登录设备身份 | |
| User | 已有持久用户/档案 | |
| VIP | 成长会员 active | |
| DeepAccess | 单份报告深度版已购 | |

---

## 4. 用户流程

```text
进入
 ↓
…
```

或 mermaid。必须含：无数据分支、权益分支、失败分支（可简写并在 §6 展开）。

---

## 5. 页面设计

对照 [../page-tree.md](../page-tree.md)。

| 路由 | 页面 | 说明 |
|---|---|---|
| | | |

页面结构示例：

```text
/path
├── Empty State
├── Loading State
├── Result / Normal State
└── Locked State
```

---

## 6. 页面状态规范

| 状态 | 说明 | UI 行为 |
|---|---|---|
| Loading | 请求中 | |
| Empty | 无数据 | 引导去哪 |
| Error | 失败 | 重试/返回 |
| Normal | 成功 | |
| Locked | 付费/权益限制 | CTA |

---

## 7. Business Rules

编号规则；**权益与归属必须在 Server 判定**。

| ID | Rule |
|---|---|
| R1 | |
| R2 | |

---

## 8. 数据模型影响

指向 [../../domain/erd.md](../../domain/erd.md)。新增/变更表字段列表；无则写「无 schema 变更」。

| 表 | 变更 | 备注 |
|---|---|---|
| | | |

---

## 9. API 需求

路径级意图即可；字段细节以 `proto/openapi.yaml` 为准，**实现时必须同步 OpenAPI**。

| Method | Path | 意图 |
|---|---|---|
| | | |

Response 权益意图示例：`summary` 始终按规则返回；`detail` 无权益时剥离或 null。

---

## 10. 权限设计

| 能力 | Visitor | User | DeepAccess | VIP |
|---|---|---|---|---|
| 查看基础 | | | | |
| 查看完整 | | | | |
| 写入/生成 | | | | |

---

## 11. 埋点

未接分析 SDK 也先定义事件名。

| Event | 触发 |
|---|---|
| `<feature>_started` | |
| `<feature>_completed` | |
| `deep_access_clicked` | |
| `purchase_completed` | |

---

## 12. 测试验收标准

### 主路径

**Given** …  
**When** …  
**Then** …

### 权益 / 异常

**Given** …  
**When** …  
**Then** …

---

## 13. AI 开发前检查

- [ ] Spec 本章齐全（无空关键节）  
- [ ] feature-map 已挂树  
- [ ] lexicon 文案已核对  
- [ ] OpenAPI / erd 更新计划已明确  
- [ ] §12 可转化为 L1/L2/E2E 用例  

---

## 14. Implementation Notes

编码时填写（首次实现或重大变更）：

| 项 | 内容 |
|---|---|
| Packages | `apps/api/internal/...` · `apps/user-h5/src/...` |
| Migrations | |
| Gaps vs Spec | （`Gap:` 未实现项） |
| Tests | L1 / L2 / e2e 路径 |

---

## 附录：子能力展开检查（复杂功能必填）

防止只写「入口 → 结果 → 分享」。按需勾选/展开：

- [ ] 入口与列表  
- [ ] 主操作流程（逐步）  
- [ ] 中断 / 恢复 / 草稿  
- [ ] 结果生成（免费层）  
- [ ] 深度层 / 付费墙  
- [ ] 分享  
- [ ] AI 解释 / 追问入口  
- [ ] 数据统计 / 埋点  
- [ ] 验收标准覆盖上述每一项  

示例（探索测试）：测试入口 · 列表 · 题目流程 · 答题保存 · 中断恢复 · 结果生成 · 免费层 · 深度层 · 分享 · AI 解释 · 统计 · 验收。