BLSFlow docs

Appearance

开发规范 ​

1. 目标 ​

统一 blsflow 项目的文档、设计、实现与回写方式，使 AI 与开发者在长期协作中保持稳定输出。

2. 文档规范 ​

  • 需求边界文档只回答“做什么、做到哪里为止”，不写实现。
  • 架构文档只回答“如何分层、如何分工、状态归谁”。
  • 任务文档只回答“这次要做什么、范围是什么、如何验收”。
  • 模块文档用于沉淀稳定知识，不记录流水账。
  • 决策记录用于记录“为什么选这个，不选那个”。

3. 任务执行规范 ​

  • 每个新任务必须在 tasks/ 下新建任务文档。
  • 任务文档必须遵循统一模板。
  • 未在任务中授权的范围，不应擅自扩展。
  • 大任务优先拆成多个可验收的小任务。

4. 设计与实现规范 ​

  • PHP API 服务（services/api）的分层、路由顺序、鉴权与 Request 注入约定见：docs/standards/php后端基础规范.md。
  • 优先复用既有边界，不随意新增服务。
  • 优先在既有模块中扩展，不擅自调整模块职责。
  • 当前阶段未显式进入实现时，不输出表结构和字段级 API 设计。
  • 涉及状态流转时，必须明确状态归属与冻结语义。
  • 涉及跨服务协作时，必须区分同步、异步、定时三类交互。

5. 命名规范 ​

  • 文档标题应体现职责，不使用模糊标题。
  • 任务文件建议使用：T编号-任务名称.md
  • 决策文件建议使用：编号-决策名称.md
  • 模块文件名称与模块职责保持一致。

6. 可审查性规范 ​

每次任务输出建议包含：

  1. 本次目标
  2. 涉及范围
  3. 改动点
  4. 风险点
  5. 验收方式
  6. 文档回写点

7. 文档回写规范 ​

任务完成后，视情况更新：

  • docs/项目概览.md
  • 相关模块文档
  • 决策记录
  • changelog
  • 当前任务状态与实施记录

8. 禁止事项 ​

  • 禁止把需求文档扩展成实现细节文档
  • 禁止绕过任务范围做额外架构改造
  • 禁止为“看起来完整”而补充未确认的业务规则
  • 禁止把临时想法写成正式决策