jackyu66gitandCursor
bd22d9dddd
落地 synastry/star/ask API 与 H5 页面，补齐 cece-frontend-re complete-design 证据文档，并加入 Android 模拟器截图抓取脚本。 Co-authored-by: Cursor <cursoragent@cursor.com>
204 lines
3.9 KiB
Markdown
204 lines
3.9 KiB
Markdown
# 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 解释 · 统计 · 验收。
|