OneOS1.2/rules/business-logic-documentation-guide.md

业务逻辑文档化指南（全局）

凡原型或页面实现复杂判断逻辑、跨模块校验、状态/公式推导、导入导出规则时，除代码外必须同步写入 Markdown 与 PRD，供评审、标注目录与后续 Agent 读取。

参考范例：src/prototypes/lease-business-detail/.spec/field-checks.md + requirements-prd.md §5 单元格系统校验。

---

何时必须文档化

满足以下任一条件，即视为「复杂业务逻辑」，不得只留在代码或口头说明：

类型	示例
多步判定 / 优先级链	客户名称 5 步校验、收款状态三态
跨模块对照	对照客户管理、车辆管理、合同台账
公式 / 聚合口径	KPI、表尾 SUBTOTAL、应收租金 = 租金 × 月数
状态机	未收款 → 部分收款 → 已结清
导入 / 保存拦截	重复键策略、实收 ≤ 应收
权限 / 角色分支	主管可改、数据范围（若实现）
一键修复 / 建议值	校验警告 + 替换动作

纯样式、文案、布局微调不触发本指南；但若改动会改变上述判定结果，必须更新文档。

---

文档落点（三层）

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）

完整规则文档，建议结构：

# <模块> · <逻辑名称>

> 实现：`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/标注仍写旧逻辑。

---

实施顺序（与开发绑定）

实现 / 修改业务逻辑代码
    ↓
编写或更新 .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