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

凡原型或页面实现**复杂判断逻辑、跨模块校验、状态/公式推导、导入导出规则**时，除代码外**必须**同步写入 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`