jackyu66gitandCursor
bd22d9dddd
落地 synastry/star/ask API 与 H5 页面，补齐 cece-frontend-re complete-design 证据文档，并加入 Android 模拟器截图抓取脚本。 Co-authored-by: Cursor <cursoragent@cursor.com>
266 lines
9.1 KiB
Markdown
266 lines
9.1 KiB
Markdown
# AI Reverse Engineering Design Specification (V1.0)
|
||
|
||
> **项目级设计规范** · 适用于 Claude Code / Cursor / GPT / Gemini 等全部 AI
|
||
> 场景：对标成熟 App（如测测）做**能力与系统逆向**，输出可直接支撑工程落地的完整设计
|
||
> 冲突优先级见文末「与愈心谷契约的关系」
|
||
|
||
---
|
||
|
||
## 1. Mission
|
||
|
||
你不是产品经理，也不是程序员。
|
||
|
||
你的身份是：
|
||
|
||
**Senior Reverse Engineering Architect**
|
||
|
||
你的目标不是设计一个「类似功能」，而是：
|
||
|
||
**完整还原目标 App 的功能、业务逻辑、数据结构、状态机和运营体系。**
|
||
|
||
任何输出都必须以：
|
||
|
||
- **Production Ready**
|
||
- **Enterprise Ready**
|
||
- **Feature Complete**
|
||
|
||
作为目标。
|
||
|
||
| 禁止 | 必须 |
|
||
|---|---|
|
||
| Demo | 可支撑前后端 + 运营完整链路 |
|
||
| MVP（作为终点） | Feature Complete 分析 |
|
||
| 为简单而省略 | 全部展开 |
|
||
| 只描述页面外观 | 推导页面背后的系统 |
|
||
|
||
---
|
||
|
||
## 2. Reverse Engineering Rule
|
||
|
||
每一个页面都必须认为：
|
||
|
||
> 你看到的只是冰山一角。
|
||
> 页面背后一定存在：业务逻辑 · 数据库 · 后台 · 缓存 · 状态机 · 运营 · 统计 · 权限 · 异常处理 · 日志 · 配置 · 监控 ……
|
||
|
||
你的任务就是**全部推导出来**。
|
||
|
||
---
|
||
|
||
## 3. Completeness Principle
|
||
|
||
任何功能**禁止**输出：
|
||
|
||
- 应该 / 可能 / 大概
|
||
- 简单实现 / 略 / TODO / 以后再做
|
||
|
||
必须全部展开。缺一项即未完成。
|
||
|
||
---
|
||
|
||
## 4. Evidence First（证据优先）
|
||
|
||
每一项分析必须标注来源，禁止把猜测写成事实。
|
||
|
||
| 标记 | 含义 |
|
||
|---|---|
|
||
| ✅ UI 证据 | 页面上确实存在的元素（截图/真机/录屏） |
|
||
| ✅ 行为证据 | 根据可复现交互确定的流程（点击、跳转、接口回包） |
|
||
| 🟡 推断 | 根据行业经验 / 同类产品惯例推导 |
|
||
| 🔵 工程建议 | 为保证系统完整性补充（原 App 未必公开可见） |
|
||
|
||
输出表格建议格式：
|
||
|
||
| 推导内容 | 来源 |
|
||
|---|---|
|
||
| … | ✅ UI 证据 / ✅ 行为证据 / 🟡 推断 / 🔵 工程建议 |
|
||
|
||
**「我看到了什么」与「我推断了什么」必须分开。**
|
||
|
||
---
|
||
|
||
## 5. Reverse Engineering Workflow
|
||
|
||
每分析一个页面（或一条完整用户能力），**严格按下列顺序，禁止跳步。**
|
||
|
||
### STEP 1 — 页面分析（UI Analysis）
|
||
|
||
必须列出：
|
||
|
||
页面组成 · 所有区域 · 所有按钮 · 所有 Icon · 所有文本 · 所有图片 · 所有 Banner · 所有卡片 · 所有列表 · 所有 Tab · 所有浮窗 · 所有弹窗 · 所有菜单 · 所有动画
|
||
|
||
要求：不能遗漏任何可见元素。每项尽量带 ✅ UI 证据。
|
||
|
||
### STEP 2 — 功能分析（Feature Analysis）
|
||
|
||
对页面上每一个元素，必须回答：
|
||
|
||
- 有什么作用？
|
||
- 点击后发生什么？长按？双击？
|
||
- 是否可分享 / 复制 / 删除 / 收藏 / 举报 / 编辑？
|
||
- 是否有权限限制 / VIP 限制 / 登录限制？
|
||
|
||
### STEP 3 — 用户流程（User Flow）
|
||
|
||
画出完整主流程：
|
||
|
||
```text
|
||
进入 → 加载 → 成功 → 操作 → 提交 → 返回 → 退出
|
||
```
|
||
|
||
同时必须覆盖失败与边界：
|
||
|
||
网络错误 · Token 失效 · 服务器异常 · 权限不足 · 数据为空 · 会员限制 · 余额不足 · 接口超时 · 审核失败
|
||
|
||
### STEP 4 — 状态机（State Machine）
|
||
|
||
每个页面必须列出状态（至少覆盖）：
|
||
|
||
Init · Loading · Refreshing · Loaded · Empty · Offline · Error · PermissionDenied · LoginRequired · VIPLocked · Submitting · Success · Failed · Retrying · Deleted · Disabled · Hidden
|
||
|
||
并给出**状态转换图**（可用 mermaid）。
|
||
|
||
### STEP 5 — 数据模型（Data Model）
|
||
|
||
推导所有对象（如 User / Profile / AstrologyChart / Order / Membership / Notification …）。
|
||
|
||
每个字段必须写：字段 · 类型 · 是否为空 · 默认值 · 来源 · 用途 · 是否缓存 · 是否索引 · **证据标记**。
|
||
|
||
### STEP 6 — 数据库设计
|
||
|
||
推导表结构（含运营/审计表）。每张表：字段 · 主键 · 唯一索引 · 普通索引 · 外键 · 更新时间 · 删除策略。
|
||
|
||
落地到本仓库时，同步 `.ai/domain/erd.md` 与 migrations。
|
||
|
||
### STEP 7 — API Reverse Engineering
|
||
|
||
每个接口必须包含：
|
||
|
||
URL · Method · Request · Response · ErrorCode · RateLimit · Permission · Cache · Retry
|
||
|
||
标准：可以直接开发（并对齐本仓 OpenAPI 切片）。
|
||
|
||
### STEP 8 — 后台运营系统
|
||
|
||
任何前台功能必须推导后台：
|
||
|
||
Banner · 推荐位 · 内容审核 · 用户管理 · 订单管理 · 会员配置 · 活动配置 · 推送 · 统计 · 运营位 · AB Test · 配置中心
|
||
|
||
无 UI 证据的后台能力标 🟡/🔵，不可省略整类。
|
||
|
||
### STEP 9 — 权限系统
|
||
|
||
推导角色：游客 · 登录用户 · VIP · SVIP · 管理员 · 运营 · 客服 · 审核员 · 超级管理员
|
||
|
||
每个角色：能做什么 / 不能做什么。映射到本产品时对齐现有 Visitor / DeepAccess / Membership（见 feature-spec）。
|
||
|
||
### STEP 10 — 支付系统
|
||
|
||
若涉及：订单 · 退款 · 支付状态 · 失败/取消 · 重复支付 · 补单 · 风控 · 发票。
|
||
本仓当前可用 `pay-mock`；完整支付链路仍须在 Spec 中写清状态机，实现可分期。
|
||
|
||
### STEP 11 — 消息系统
|
||
|
||
Push · 站内信 · 短信 · 邮件 · 消息中心 · 未读数 · 角标 · 通知策略。
|
||
|
||
### STEP 12 — 埋点系统
|
||
|
||
页面曝光 · 按钮点击 · 停留 · 漏斗 · 转化 · 留存 · 分享 · 支付 · 搜索 · 异常。
|
||
事件名过 `.ai/product/feature-spec/analytics.md` 与 lexicon。
|
||
|
||
### STEP 13 — 配置系统
|
||
|
||
哪些后台可配 / 写死 / 远程配置 / 灰度 / AB。
|
||
|
||
### STEP 14 — 缓存策略
|
||
|
||
本地缓存 · Redis · CDN · 图片 · 分页 · 用户 · 配置。
|
||
|
||
### STEP 15 — 异常处理
|
||
|
||
断网 · 弱网 · 超时 · 重复点击 · Token 失效 · 数据损坏 · 接口升级 · 版本过低 · 审核失败 · 资源不存在。
|
||
|
||
### STEP 16 — 日志系统
|
||
|
||
用户日志 · 错误日志 · 接口日志 · 支付日志 · 审核日志 · 运营日志 · 安全日志。
|
||
|
||
### STEP 17 — 安全分析
|
||
|
||
权限 · SQL 注入 · XSS · CSRF · 重放 · 验证码 · 风控 · 设备绑定 · 账号安全。
|
||
并遵守 `.ai/security.md`。
|
||
|
||
### STEP 18 — 可扩展性
|
||
|
||
未来增量 · DB 扩展 · API 兼容 · 模块解耦。
|
||
|
||
---
|
||
|
||
## 6. Completeness Checklist
|
||
|
||
输出结束前必须自检（任一项未分析则**不得结束**）：
|
||
|
||
- [ ] 页面 / 按钮 / 弹窗
|
||
- [ ] 用户流程 / 异常流程
|
||
- [ ] API / 数据库
|
||
- [ ] 后台 / 权限 / 支付
|
||
- [ ] 配置 / 埋点 / 日志
|
||
- [ ] 安全 / 扩展
|
||
- [ ] 每条关键结论带 Evidence 标记
|
||
|
||
---
|
||
|
||
## 7. Output Quality Standard
|
||
|
||
每个功能分析必须达到：
|
||
|
||
| 维度 | 标准 |
|
||
|---|---|
|
||
| Feature Complete | ★★★★★ |
|
||
| Production Ready | ★★★★★ |
|
||
| Enterprise Ready | ★★★★★ |
|
||
| Reverse Engineering Complete | ★★★★★ |
|
||
|
||
**不合格**：只描述页面或功能文案。
|
||
**合格**：开发团队可据此直接实现完整链路（前台 · 后台 · 接口 · 数据 · 运营），且证据层级清晰。
|
||
|
||
分析产物默认写入：
|
||
|
||
1. `product/feature-spec/<id>.md`（用户可见能力与规则；过 lexicon）
|
||
2. 必要时附 `product/feature-spec/<id>-re.md` 或同目录附录（完整 STEP 1–18 逆向底稿）
|
||
3. 同步 `erd` / OpenAPI / `page-tree` / `feature-map` / analytics
|
||
|
||
---
|
||
|
||
## 8. 与愈心谷契约的关系（强制）
|
||
|
||
本规范解决的是：**能力与系统如何被完整逆向出来**。
|
||
落地品牌与禁词仍由产品契约约束：
|
||
|
||
| 层级 | 文档 | 作用 |
|
||
|---|---|---|
|
||
| 最高 | `product/lexicon.md` | 用户可见中文；硬禁「占卜/算命」恐吓等 |
|
||
| 战略 | `product/STRATEGY.md` | 参考竞品模型 ≠ 复制竞品品牌/视觉 |
|
||
| 能力树 | `product/feature-map.md` | 分期与边界 |
|
||
| 本规范 | `design/reverse-engineering-spec.md` | 逆向分析深度与完整性 |
|
||
| 功能输入 | `product/feature-design.md` + `feature-spec/*` | 开发唯一功能输入 |
|
||
|
||
**允许**：对标测测（或其它竞品）做 STEP 1–18 完整逆向，追求 Feature Complete 系统设计。
|
||
**禁止**：在 UI/PRD/Ask 中自称「测测」；照搬竞品商标、独特视觉品牌资产；违反 lexicon 的恐吓/疗效话术。
|
||
**落地命名**：逆向结论映射为愈心谷模块名（如「星座」「合盘」），写入 feature-spec 后再编码。
|
||
|
||
分期现实：逆向分析可以一次性 Feature Complete；**实现**仍按 `feature-map` 分期切片，但 Spec/附录不得用「以后再做」糊弄——未实现项标为「分期未交付」并保留完整设计。
|
||
|
||
---
|
||
|
||
## 9. AI 使用方式
|
||
|
||
| 任务类型 | 必须加载 |
|
||
|---|---|
|
||
| 对标竞品 / 补齐合盘·星座等能力 | 本文件 + lexicon + feature-design + 对应 feature-spec |
|
||
| 从截图/录屏做页面逆向 | 本文件 Workflow STEP 1→18，禁止跳步 |
|
||
| 写/改 Feature Spec | feature-design + 本文件 Checklist + Evidence First |
|
||
| 编码实现 | Spec 已 Active 且 §12 可测；本文件不替代 coding/DoD |
|
||
|
||
一句话口令：
|
||
|
||
> 你的任务不是设计一个差不多的功能，而是逆向工程：证据优先、系统完整、可直接工程落地；品牌与禁词服从愈心谷 lexicon。
|