zjkal 开发计划文档格式
把调研方案 / Cursor Plan 整理成可勾选、可验收、可分期落地的开发计划 Markdown。
体例源自 DApp-X 的 docs/*_DEVELOPMENT_PLAN.md；格式规则通用，项目特有收口项按当前仓库约定改写。
- 空骨架：references/TEMPLATE.md
- 在 dappx 仓库内写计划时，额外必读：references/dappx-checklist.md
一、适用范围与命名
| 场景 | 文件 |
|---|---|
| 整仓 / APP 主计划 | docs/DEVELOPMENT_PLAN.md |
| 管理后台主计划 | docs/ADMIN_DEVELOPMENT_PLAN.md（若有独立后台） |
| 单模块展开 | docs/{MODULE}_DEVELOPMENT_PLAN.md，如 GAME_DEVELOPMENT_PLAN.md |
- 一个模块一份文档：优先覆盖该模块涉及的后端 + 前端 + 后台全链路；无某端则删章节并顺移编号，不留空章。
- 模块文档展开主计划某阶段时：主计划对应阶段只加一句指向新文档的说明，禁止两份计划描述冲突。
- 新项目可先写单份
docs/DEVELOPMENT_PLAN.md；模块变复杂后再拆。
二、章节骨架（顺序固定）
# {产品或模块}开发计划[· 一期]
> 引用块：技术栈 / 需求来源 / 文档范围 / 落地形态 / 核心原则
## 目录
## 一、范围与关键决策 1.1 已定决策表 1.2 交付内容树 1.3 不在本期范围
## 二、风险与待确认事项 R1~Rn + Q1~Qn
## 三、数据库设计 SQL 原文 + 设计说明（无库可改为「数据与规则设计」）
## 四、业务流程与状态机 text 流程图 + 状态约束表
## 五、后端开发阶段 阶段 X1~Xn（checkbox）
## 六、前端开发阶段 阶段 Xn（checkbox）
## 七、管理后台开发阶段 可选；无则删除并顺移
## 八、工程配套与收口 不可省略
## 九、阶段总览与里程碑 Phase 代码块
## 十、验收清单 可观测结果 checkbox
## 十一、参考与索引 后续分期 + 文档索引 + 修订记录
章节之间用 --- 分隔。获客 / SEO / 运营若属于交付一部分，可并入前端后另开「内容与获客阶段」，或并入第八章前，编号连续即可。
三、阶段写法（核心）
3.1 编号
- 单字母前缀 + 序号：主计划常用
B（后端）/F（前端）；模块用模块首字母（G游戏、V卡……）。 - 整份文档内编号连续递增（后端 1
5、前端 67、后台 8、收口 9），便于引用。 - 禁止写人日、工期、排期、估时；顺序与并行只在第九章 Phase 表达。
3.2 阶段结构
### 阶段 G4：下注、结算与查询接口
**目标**：打通「用户下注 → 扣款 → 开奖 → 派彩」。此阶段完成后可用接口调试工具完整走通一局。
- [ ] **接口**：`POST /api/games/bet` — 下注
- [ ] **新建**：`app/service/game/GameBetService.php` — 下注主流程
- [ ] **逻辑**：单事务内扣款 + 写流水 + 更新期数汇总
- 子项写清调用顺序与幂等点
- [ ] **约定**：响应禁止返回用户数字主键（按项目安全规范改写）
**目标**：一句话说清做完能验证什么。- 每条 checkbox 以粗体类型标签开头（见 3.3）。
- 细节用缩进子项；阶段内可用
####分组。 - 未开工
- [ ]；完成改- [x]，子项末尾可补「（已完成）」与实现要点——完成后不要删细节。
3.3 条目类型标签
| 标签 | 用于 |
|---|---|
**接口** |
API：`METHOD /path` — 说明；后台可追加 ｜权限码 |
**新建** / **扩展** |
具体文件路径 + 一句职责 |
**逻辑** |
业务规则、事务、幂等、校验 |
**数据库** / **种子** / **迁移** |
schema / seed / migrations |
**模型** / **配置** / **路由** |
模型、配置、路由登记 |
**前端** / **交互** / **组件** |
页面与交互 |
**约定** |
安全 / API / 工程硬约束 |
**单测** / **验证** |
测试或「确认既有能力已生效」 |
可按栈增补标签（如 **队列**、**邮件**），但同一文档内标签集合保持稳定。
四、第九章 Phase 里程碑
Phase G-1 (存储与引擎，可并行):
├── G1 数据库、模型与配置
├── G2 判定引擎 + 单测
└── 里程碑：给定固定输入，引擎输出与金样本完全一致
Phase G-2 (主链路):
├── G3 …
├── G4 …
└── 里程碑：用接口调试工具完整走通关键路径
代码块后固定两句：
- 建议实施顺序（箭头串阶段，标出可并行分支）。
- 哪个阶段可最先独立开工 / 哪个是重心，并写原因。
Phase 命名：Phase {前缀}-{序号}，括号写主题与并行提示。
五、前四章写法
5.1 决策前置
1.1 用表列出已拍板决策（决策项 → 结论）。与原始需求有差异的必须在此写明，勿散落正文。
5.2 风险要有后果
### 2.x R{n}（高/中/低）{标题}：问题描述（具体算例或故障表现）→ 缓解手段（编号，标明「已纳入设计」）→ 需要确认时用引用块。
- 反例：「汇率波动可能造成损失」。
- 正例：算出「订单 500、汇率 0.05→0.04 时平台净亏约 88」。
R{n} / Q{n} 须能在后续章节被引用。
5.3 数据库给 SQL 原文
直接给完整 CREATE / ALTER（字段中文 COMMENT），再用散文解释为什么（唯一索引、JSON 取舍、单号生成等）。
开头引用块写清本仓库约定，例如：schema 真相源路径、幂等迁移、禁止直接改现网库、金额类型（禁用 FLOAT）。无传统 DB 时改为「数据与规则设计」（版本化规则、快照字段、文件 TTL 等），仍要可实施、可测试。
5.4 流程用 text 图
用 text 代码块画状态机 / 资金或数据流转；表格约束「每状态允许哪些操作」。资金类标出 freeze / settle / adjust 等动作名（按项目实际 API）。
六、收口阶段（第八章）必写项
不可省略。 写成逐条 checkbox，禁止一句「注意安全」带过。
按当前项目映射下列类别（无则删，有则写到具体文件/配置名）：
| 类别 | 写什么 |
|---|---|
| 标识与隐私 | 对外 ID 策略、禁止泄露的主键字段 |
| 限流与防刷 | 写接口 / 支付类接口登记方式 |
| 资金或计费类型 | 新增流水类型 / 订阅状态的完整改动面 |
| i18n | 真相源文件与导入/校验命令 |
| 路由与配置登记 | 路由表、任务、队列、进程 |
| 权限与审计 | 后台权限码、操作日志 |
| 联调 | 指向第十章验收清单 |
在 dappx 中写计划时，用 references/dappx-checklist.md 替换上表为该仓具体路径与七步清单。
七、第十章验收清单
按主题分组；每条是可观测结果，不是「做了某事」。
- 正例：
申请失败后：余额全额退回、产生「开卡费退回」流水、可重新申请 - 反例：
实现了幂等处理
建议分组顺序：资金/计费安全（最高优先级）→ 业务正确性 → 权限与审计（有后台时）→ 性能与稳定性 → 前后端一致性与合规。
八、第十一章参考与索引
- 后续分期：本期不做 / 下期做；注明「一期已预留字段则下期只增不改」类承诺。
- 文档与规范索引：表格「内容 → 权威来源」（rules、schema、技能、相关 docs）。
- 修订记录：
日期 | 说明；结构性改动追加一行。
九、写作准则
- 引用既有实现前先核实，给出准确路径；不存在的类名/配置不要写进计划。
- 解释为什么，不只罗列是什么。
- 一号发现前置：改变工作量判断的关键事实（如「下游已就绪只缺写入源」）放在第二章靠前，单独成节。
- 术语全文一致；用户可见文案在计划中用 i18n key 或文案职责描述，不假装已定稿多语言译文。
- 输出语言：若用户要求简体中文，计划正文用简体中文。
十、执行流程（Agent）
- 确认产品/模块名、一期边界、输出路径（默认
docs/…_DEVELOPMENT_PLAN.md）。 - 若仓库已有主计划或模块计划，先读再写，避免冲突。
- 复制 references/TEMPLATE.md，按栈与端裁剪章节。
- 先填第一、二章决策与风险，再写库表/流程，再拆阶段 checkbox。
- 写完第九章 Phase 与第十章可观测验收；第十一章挂上本仓权威文档。
- 若在 dappx：对照 references/dappx-checklist.md 补全收口与验收条目。