迭代 ONE-OS 多原型：加氢记录/订单同源对账、租赁明细校验与月度损益、车辆与台账增强；新增客户回款与加氢站统计；补齐业务逻辑与对象存储发布规范，同步原型导航。
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
王冕
135
rules/business-logic-documentation-guide.md
Normal file
135
rules/business-logic-documentation-guide.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# 业务逻辑文档化指南（全局）
|
||||
|
||||
凡原型或页面实现**复杂判断逻辑、跨模块校验、状态/公式推导、导入导出规则**时，除代码外**必须**同步写入 Markdown 与 PRD，供评审、标注目录与后续 Agent 读取。
|
||||
|
||||
参考范例：`src/prototypes/lease-business-detail/.spec/field-checks.md` + `requirements-prd.md` §5 单元格系统校验。
|
||||
|
||||
---
|
||||
|
||||
## 何时必须文档化
|
||||
|
||||
满足以下**任一**条件，即视为「复杂业务逻辑」，不得只留在代码或口头说明：
|
||||
|
||||
| 类型 | 示例 |
|
||||
|------|------|
|
||||
| 多步判定 / 优先级链 | 客户名称 5 步校验、收款状态三态 |
|
||||
| 跨模块对照 | 对照客户管理、车辆管理、合同台账 |
|
||||
| 公式 / 聚合口径 | KPI、表尾 SUBTOTAL、应收租金 = 租金 × 月数 |
|
||||
| 状态机 | 未收款 → 部分收款 → 已结清 |
|
||||
| 导入 / 保存拦截 | 重复键策略、实收 ≤ 应收 |
|
||||
| 权限 / 角色分支 | 主管可改、数据范围（若实现） |
|
||||
| 一键修复 / 建议值 | 校验警告 + 替换动作 |
|
||||
|
||||
纯样式、文案、布局微调**不**触发本指南；但若改动会改变上述判定结果，必须更新文档。
|
||||
|
||||
---
|
||||
|
||||
## 文档落点（三层）
|
||||
|
||||
```text
|
||||
src/prototypes/<name>/
|
||||
├── .spec/requirements-prd.md # ① PRD：摘要 + 验收项（产品可读）
|
||||
├── .spec/<logic-topic>.md # ② 规格：完整判定顺序、数据源、边界（开发/评审）
|
||||
├── annotation-source.json # ③ 标注：目录节点 + 页面/字段标注（经同步脚本）
|
||||
└── columnHeaderTips.ts 等 # 可选：表头/字段级一句话提示
|
||||
```
|
||||
|
||||
### ① PRD（`requirements-prd.md`）
|
||||
|
||||
在对应功能章节增加**摘要**，至少包含：
|
||||
|
||||
- 业务目的（一句话）
|
||||
- 判定顺序或状态表（表格优先）
|
||||
- 数据源 / 对照模块
|
||||
- 用户可见结果（图标、文案、是否可一键修复）
|
||||
- 链接到 `.spec/<logic-topic>.md` 全文
|
||||
|
||||
在 **§验收重点** 增加可勾选项。
|
||||
|
||||
### ② 规格 Markdown（`.spec/<logic-topic>.md`）
|
||||
|
||||
完整规则文档，建议结构：
|
||||
|
||||
```markdown
|
||||
# <模块> · <逻辑名称>
|
||||
|
||||
> 实现：`utils/xxx.ts`；UI：`components/xxx.tsx`
|
||||
|
||||
## 对照数据源
|
||||
## 交互与状态（ok / warn / none）
|
||||
## <字段或场景 A> 判定顺序（表格）
|
||||
## <字段或场景 B> …
|
||||
## 启用范围 / 与代码映射
|
||||
```
|
||||
|
||||
要求：
|
||||
|
||||
- **判定顺序**写清优先级（命中即返回）
|
||||
- **前置条件**写清何时不校验
|
||||
- **弱校验 / 强校验**区分标注
|
||||
- 标明原型种子 vs 真实 API（若未接后端）
|
||||
|
||||
### ③ 标注目录（`annotation-source.json`）
|
||||
|
||||
通过 `scripts/sync-annotation-directory.mjs`（或等价脚本）同步：
|
||||
|
||||
| 同步目标 | 内容 |
|
||||
|----------|------|
|
||||
| `directory` → 规格说明 | 全文或 `markdownPath` 指向 `.spec/*.md` |
|
||||
| 页面标注节点 | 功能区摘要（如列表工具栏、明细表） |
|
||||
| 字段标注节点 | 单字段判定摘要（如客户名称） |
|
||||
| `markdownMap` | 与节点 `annotationText` 一致 |
|
||||
|
||||
**禁止**：代码已改、PRD/标注仍写旧逻辑。
|
||||
|
||||
---
|
||||
|
||||
## 实施顺序（与开发绑定）
|
||||
|
||||
```text
|
||||
实现 / 修改业务逻辑代码
|
||||
↓
|
||||
编写或更新 .spec/<logic-topic>.md
|
||||
↓
|
||||
更新 requirements-prd.md 摘要 + 验收项
|
||||
↓
|
||||
更新表头提示 / 字段标注文案（如有）
|
||||
↓
|
||||
运行 sync-annotation-directory.mjs
|
||||
↓
|
||||
验收：目录与 PRD 可读、与页面行为一致
|
||||
```
|
||||
|
||||
逻辑变更与文档变更**同一轮交付**；不得「先合代码、后补文档」作为默认流程。
|
||||
|
||||
---
|
||||
|
||||
## 最小检查清单
|
||||
|
||||
- [ ] 复杂逻辑有独立 `.spec/*.md` 或 PRD 内等价完整章节
|
||||
- [ ] PRD 摘要含判定顺序表 / 状态表
|
||||
- [ ] PRD §验收 含可验证条目
|
||||
- [ ] `annotation-source.json` 目录已同步
|
||||
- [ ] 关键字段在「字段标注」或表头提示有一句业务说明
|
||||
- [ ] 文档标明数据来源（种子 / API / 手工列）
|
||||
- [ ] 代码路径在 PRD §源码入口 或规格文首注明
|
||||
|
||||
---
|
||||
|
||||
## 反例
|
||||
|
||||
| ❌ 不做 | ✅ 应做 |
|
||||
|--------|--------|
|
||||
| 只在 `utils/field-checks.ts` 里写 5 层 if | 同步 `field-checks.md` + PRD §5 摘要 |
|
||||
| 评审时口头解释客户名校验 | 目录「单元格系统校验」可点开全文 |
|
||||
| 改判定顺序不更新 PRD | 同 PR 更新 `.spec` + 跑 sync 脚本 |
|
||||
| 表头提示与真实逻辑矛盾 | 以 `.spec` 为单一真相，提示引用摘要 |
|
||||
|
||||
---
|
||||
|
||||
## 关联规则
|
||||
|
||||
- 产品需求对齐：`rules/requirements-alignment-guide.md`
|
||||
- 原型开发验收：`rules/prototype-development-guide.md`
|
||||
- 标注布局：`rules/prototype-annotation-layout-guide.md`
|
||||
- Agent 门禁：根目录 `AGENTS.md`
|
||||
Reference in New Issue
Block a user