Organize the research plan / Cursor Plan into acheckable, acceptance-ready, phase-by-phase implementabledevelopment plan Markdown.
The format is derived from DApp-X's docs/*_DEVELOPMENT_PLAN.md;format rules are universal, and project-specific closing items are rewritten according to the current repository's conventions.
- Empty skeleton:references/TEMPLATE.md
- When writing a plan in the dappx repository, additionally required reading:references/dappx-checklist.md
I. Scope of Application and Naming
| Scenario | File |
|---|---|
| Whole-repo / APP master plan | docs/DEVELOPMENT_PLAN.md |
| Admin backend master plan | docs/ADMIN_DEVELOPMENT_PLAN.md(if there is an independent backend) |
| Single module expansion | docs/{MODULE}_DEVELOPMENT_PLAN.md, e.g. GAME_DEVELOPMENT_PLAN.md |
- One document per module: prioritize covering the full chain of backend + frontend + admin backend involved in that module; if a certain end does not exist, delete the section and shift the numbering accordingly, leaving no empty sections.
- When a module document expands a certain phase of the master plan: for the corresponding phase in the master plan, only add a sentence pointing to the new document,conflicting descriptions between the two plans are prohibited。
- A new project may first write a single
docs/DEVELOPMENT_PLAN.md; split it later when the module becomes more complex.
II. Section Skeleton (fixed order)
# {产品或模块}开发计划[· 一期]
> 引用块:技术栈 / 需求来源 / 文档范围 / 落地形态 / 核心原则
## 目录
## 一、范围与关键决策 1.1 已定决策表 1.2 交付内容树 1.3 不在本期范围
## 二、风险与待确认事项 R1~Rn + Q1~Qn
## 三、数据库设计 SQL 原文 + 设计说明(无库可改为「数据与规则设计」)
## 四、业务流程与状态机 text 流程图 + 状态约束表
## 五、后端开发阶段 阶段 X1~Xn(checkbox)
## 六、前端开发阶段 阶段 Xn(checkbox)
## 七、管理后台开发阶段 可选;无则删除并顺移
## 八、工程配套与收口 不可省略
## 九、阶段总览与里程碑 Phase 代码块
## 十、验收清单 可观测结果 checkbox
## 十一、参考与索引 后续分期 + 文档索引 + 修订记录
Separate sections with --- . If customer acquisition / SEO / operations are part of the delivery, they may be merged after the frontend and a separate "Content and Customer Acquisition Phase" may be opened, or merged before Chapter 8,as long as the numbering is continuous。
III. Phase Writing (core)
3.1 Numbering
- Single-letter prefix + sequence number: the master plan commonly uses
B(backend) /F(frontend); modules use the module's first letter (GG for game,VC for card...). - Numbering increases continuously throughout the document(backend 15, frontend 67, admin backend 8, closing 9), for ease of reference.
- Writing person-days, durations, schedules, or time estimates is prohibited; sequence and parallelism are expressed only in the Phase section of Chapter 9.
3.2 Phase Structure
### 阶段 G4:下注、结算与查询接口
**目标**:打通「用户下注 → 扣款 → 开奖 → 派彩」。此阶段完成后可用接口调试工具完整走通一局。
- [ ] **接口**:`POST /api/games/bet` — 下注
- [ ] **新建**:`app/service/game/GameBetService.php` — 下注主流程
- [ ] **逻辑**:单事务内扣款 + 写流水 + 更新期数汇总
- 子项写清调用顺序与幂等点
- [ ] **约定**:响应禁止返回用户数字主键(按项目安全规范改写)
**目标**: state in one sentencewhat can be verified once done。- Each checkbox starts with abold type label(see 3.3).
- Use indented sub-items for details; within a phase,
####may be used for grouping. - Not started
- [ ]; when completed, change to- [x], and at the end of sub-items you may add "(completed)" and implementation points—do not delete details after completion。
3.3 Item Type Labels
| Label | Used for |
|---|---|
**接口** |
API:`METHOD /path` — 说明; the admin backend may additionally append |权限码 |
**新建** / **扩展** |
specific file path + one-sentence responsibility |
**逻辑** |
business rules, transactions, idempotency, validation |
**数据库** / **种子** / **迁移** |
schema / seed / migrations |
**模型** / **配置** / **路由** |
models, configuration, route registration |
**前端** / **交互** / **组件** |
pages and interactions |
**约定** |
security / API / engineering hard constraints |
**单测** / **验证** |
testing or "confirm that existing capabilities are already in effect" |
Labels may be added according to the stack (e.g. **队列**、**邮件**), but the set of labels within the same document should remain stable.
IV. Chapter 9 Phase Milestones
Phase G-1 (存储与引擎,可并行):
├── G1 数据库、模型与配置
├── G2 判定引擎 + 单测
└── 里程碑:给定固定输入,引擎输出与金样本完全一致
Phase G-2 (主链路):
├── G3 …
├── G4 …
└── 里程碑:用接口调试工具完整走通关键路径
After the code block, two fixed sentences:
- Recommended implementation order(arrows string together phases, marking parallelizable branches).
- Which phase can start independently first / which is the focus, and write the reason.
Phase naming:Phase {前缀}-{序号}, write the theme and parallelism hints in parentheses.
V. How to write the first four chapters
5.1 Decisions up front
1.1 List in a tabledecisions already made(decision item → conclusion). Anything that differs from the original requirements must be stated here, not scattered throughout the body.
5.2 Risks must have consequences
### 2.x R{n}(高/中/低){标题}: problem description (specific example calculation or failure manifestation) → mitigation measures (numbered, marked "already incorporated into the design") → use a blockquote when confirmation is needed.
- Counterexample: "Exchange rate fluctuations may cause losses."
- Good example: calculate that "with an order of 500 and the exchange rate going from 0.05 to 0.04, the platform incurs a net loss of about 88."
R{n} / Q{n} must be referenceable in subsequent chapters.
5.3 Database: give the original SQL
Give the complete CREATE / ALTERdirectly (Chinese COMMENT on fields), then explain in prosewhy(unique index, JSON trade-offs, order number generation, etc.).
At the beginning, use a blockquote to state the conventions of this repository clearly, for example: schema source-of-truth path, idempotent migrations, prohibition on directly modifying the production database, amount type (forbid FLOAT). When there is no traditional DB, switch to "Data and rule design" (versioned rules, snapshot fields, file TTL, etc.), which must still be implementable and testable.
5.4 Use text diagrams for flows
Use text code blocks to draw state machines / fund or data flows; use tables to constrain "which operations are allowed in each state." For fund-related flows, mark action names such as freeze / settle / adjust (according to the project's actual API).
VI. Required items for the closing phase (Chapter 8)
Cannot be omitted. Write as item-by-item checkboxes; do not gloss over it with a single sentence like "pay attention to security."
According tothe current project, map the following categories (delete if absent; if present, write down the specific file/configuration names):
| Category | What to write |
|---|---|
| Identifiers and privacy | External ID strategy, primary key fields that must not be leaked |
| Rate limiting and anti-abuse | How write endpoints / payment-type endpoints are registered |
| Fund or billing types | The complete change surface for new transaction types / subscription states |
| i18n | Source-of-truth files and import/validation commands |
| Route and configuration registration | Route tables, tasks, queues, processes |
| Permissions and auditing | Backend permission codes, operation logs |
| Integration testing | Point to the acceptance checklist in Chapter 10 |
In dappx , when writing the plan, use references/dappx-checklist.md to replace the above table with the repository's specific paths and a seven-step checklist.
VII. Chapter 10 acceptance checklist
Group by topic; each item is anobservable result, not "did something."
- Good example:
申请失败后:余额全额退回、产生「开卡费退回」流水、可重新申请 - Counterexample:
实现了幂等处理
Suggested grouping order: fund/billing security (highest priority) → business correctness → permissions and auditing (when there is a backend) → performance and stability → frontend-backend consistency and compliance.
VIII. Chapter 11 references and index
- Subsequent phases: not done in this phase / to be done in the next phase; note commitments such as "if fields were reserved in phase one, the next phase will only add and not modify."
- Documentation and specification index: Table "Content → Authoritative Source" (rules, schema, skills, related docs).
- Revision History:
日期 | 说明; append a row for structural changes.
IX. Writing Guidelines
- Verify before citing existing implementations, give accurate paths; do not write non-existent class names/configurations into the plan.
- Explain why, do not just list what.
- Key finding up front: key facts that change the workload assessment (e.g., "downstream is ready, only the write source is missing") go early in Chapter 2, as a separate section.
- Terminology consistent throughout; user-visible copy in the plan uses i18n keys or copy responsibility descriptions, do not pretend multilingual translations are finalized.
- Output language: if the user requests Simplified Chinese, the plan body uses Simplified Chinese.
X. Execution Flow (Agent)
- Confirm product/module name, phase-one boundary, output path (default
docs/…_DEVELOPMENT_PLAN.md)。 - If the repository already has a master plan or module plan, read it before writing to avoid conflicts.
- Copy references/TEMPLATE.md, trim sections by stack and platform.
- First fill in the decisions and risks of Chapters 1 and 2, then write the database tables/flows, then break down the phase checkboxes.
- After writing, complete Chapter 9 Phase and Chapter 10 observable acceptance; attach this repository's authoritative documents in Chapter 11.
- If in dappx: cross-check with references/dappx-checklist.md to complete the closure and acceptance items.