136 lines
4.5 KiB
Markdown
136 lines
4.5 KiB
Markdown
# 业务逻辑文档化指南（全局）
|
||
|
||
凡原型或页面实现**复杂判断逻辑、跨模块校验、状态/公式推导、导入导出规则**时，除代码外**必须**同步写入 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`
|