tangweijie
3eccab2cf9
1. AGENTS.md 更新 - water-docs: 新增 specs/ 与 docs/design/ 生命周期规则章节 - water-backend: 更新协作引用（建设期/建成后、evidence 模块化） 2. specs/ 重复合并 - 006-reminder-event-design 合并入 003-rev006-reminder-event-design - 001-rev004-accounting 删除冗余 data-model.md + contracts/ - 002-rev005-invoice-flow 删除冗余 data-model.md + contracts/ 3. evidence 按模块归档 - 35 个 REV-004 文件归入 evidence/rev004-accounting/ - 7 个通用 bugfix 文件归入 evidence/bugfix/ 和 bugfix/frontend/ - 新建 rev005-invoice/、rev006-reminder/、rev007-statistics/ 目录 4. guides/ 清理 - 14 个 REV004_*.md 移入 evidence/rev004-accounting/ 5. 遗留文件处理 - docs/research/ 归档到 Archive/06_Migration_Plans/ - backend-check detached worktrees 清理 6. 交叉引用修复 - 006-reminder-event-design → 003-rev006-reminder-event-design - docs/guides/REV004_ → docs/evidence/rev004-accounting/REV004_ 7. DB 设计文档修正（01_Database_Design.md） - biz_invoice 明确为开票配置表，非发票记录表 - 新增 biz_invoice_record 为发票申请/结果主表 - 新增 biz_charge_invoice_rel 账单-发票关联说明 - REV-005 承接口径表名全部修正 8. 发票审计证据 - 新增 evidence/rev005-invoice/2026-06-16-invoice-document-audit.md
109 lines
5.2 KiB
Markdown
109 lines
5.2 KiB
Markdown
# Plan: REV-006 催缴与通知事件设计收口
|
||
|
||
**Branch**: `003-rev003-rev006-reminder-event-design` | **Date**: 2026-03-19 | **Spec**: [spec.md](./spec.md)
|
||
**Input**: Feature specification from `/specs/003-rev003-rev006-reminder-event-design/spec.md`（合并自 `003` 与 `006` 双会话）
|
||
|
||
## Summary
|
||
|
||
本计划将 `REV-006` 催缴与通知事件的正式设计收口拆分为 4 个可验证的阶段：详细设计主文档对齐、接口与协同边界文档化、治理同步和实现切入点评估。每个阶段完成后需通过独立的文档校验和台账回写。
|
||
|
||
## Technical Approach
|
||
|
||
- **Design-first, implementation-later**: 本轮仅收口正式设计文档，不在 backend 中新增业务代码。
|
||
- **Single source of truth**: 所有修订回写到 `docs/design/` 主文档，不创建平行版本。
|
||
- **Contract-driven**: 以 `contracts/if-rev-013.md` 和 `contracts/if-ext-008.md` 作为接口协同边界契约，驱动正式接口文档修订。
|
||
- **Gated by validation**: 每次文档修订后必须执行 `make validate-file`、`make check-links`、`make validate-mermaid` 中适用的校验命令。
|
||
|
||
## Constitution Check
|
||
|
||
- **Single source of truth**: ✅ 只编辑现有主文档（`12_REV_Detailed.md`、`03_Interface_Design.md`），不创建平行版本
|
||
- **Traceability**: ✅ 所有变更可追溯到本 spec 和 governance records
|
||
- **Validation required**: ✅ 每个阶段包含明确的验证任务
|
||
|
||
## Project Structure
|
||
|
||
### Documentation (this feature)
|
||
|
||
```text
|
||
specs/003-rev003-rev006-reminder-event-design/
|
||
├── spec.md # 功能规格（合并自 003 与 006）
|
||
├── plan.md # 本文件
|
||
├── research.md # 调研与现有基线评估
|
||
├── data-model.md # REV-006 涉及的实体与字段分析
|
||
├── quickstart.md # 快速开始指南
|
||
├── tasks.md # 任务拆解
|
||
├── contracts/
|
||
│ ├── rev006-interface-contract.md # REV-006 接口契约（来自原 003）
|
||
│ ├── if-rev-013.md # IF-REV-013 正式接口契约（来自原 006）
|
||
│ └── if-ext-008.md # IF-EXT-008 外部协同契约（来自原 006）
|
||
└── checklists/
|
||
└── requirements.md # 需求审查清单
|
||
```
|
||
|
||
### Source of Truth (upstream/downstream)
|
||
|
||
```text
|
||
docs/design/
|
||
├── 02_Detailed_Design/12_REV_Detailed.md # REV 模块详细设计（本 feature 的主要编辑目标）
|
||
├── 03_Technical_Design/03_Interface_Design.md # 接口设计（IF-REV-013、IF-EXT-008 的正式落点）
|
||
└── 00_Management/
|
||
├── 01_Project_Progress.md # 项目进度同步
|
||
├── 03_Task_Checklist.md # 任务清单同步
|
||
└── 15_SYS002_Requirement_Breakdown.md # 需求拆解同步
|
||
```
|
||
|
||
## Phase 1: Scope Confirmation
|
||
|
||
**Goal**: 确认本 feature 的确切编辑范围、主文档影响面和验证要求。
|
||
|
||
- 确认 `12_REV_Detailed.md` 的 `REV-006` 章节需要新增/修订的具体小节
|
||
- 确认 `03_Interface_Design.md` 的 `IF-REV-013` 和 `IF-EXT-008` 需要新增/修订的具体内容
|
||
- 确认治理类文档的同步范围（`01_Project_Progress.md`、`03_Task_Checklist.md`、`15_SYS002_Requirement_Breakdown.md`）
|
||
|
||
## Phase 2: Detailed Design Alignment
|
||
|
||
**Goal**: 将 `REV-006` 催缴事件设计的正式描述写入 `12_REV_Detailed.md`。
|
||
|
||
关键内容：
|
||
- 催缴对象生成规则（欠费条件、账龄、金额、客户类别、渠道偏好）
|
||
- 策略分组与任务生成维度
|
||
- 四态结果语义（`PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED`）
|
||
- 停复水/工单联动边界（只定义追溯接口，不展开内部流程）
|
||
- 历史查询与导出口径
|
||
|
||
## Phase 3: Interface & Contract Documentation
|
||
|
||
**Goal**: 将 `IF-REV-013` 和 `IF-EXT-008` 的正式定义写入 `03_Interface_Design.md`。
|
||
|
||
关键内容：
|
||
- `IF-REV-013`：任务生成、任务查询、人工核查、结果承接
|
||
- `IF-EXT-008`：外部消息触达协同（`SYS-010` 负责执行，`SYS-002` 保留业务控制）
|
||
- 四态回写字段定义
|
||
- 失败原因与处置引用字段
|
||
|
||
## Phase 4: Governance Sync
|
||
|
||
**Goal**: 同步治理台账，明确 `REV-006` 的当前结论、最小实现切入点和后续行动。
|
||
|
||
关键动作：
|
||
- 更新 `01_Project_Progress.md` 通报本轮收口结论
|
||
- 更新 `03_Task_Checklist.md` 登记本轮文档治理任务完成情况
|
||
- 更新 `15_SYS002_Requirement_Breakdown.md` 中 `SYS002-REQ-011` 的状态为"设计已收口"
|
||
|
||
## Phase 5: Implementation Entry-Point Assessment
|
||
|
||
**Goal**: 为后续研发立项提供最小实现切入点评估，不直接实现。
|
||
|
||
关键输出：
|
||
- 识别 backend 中是否存在 `Reminder/Message/Notice` 相关控制器或服务骨架
|
||
- 评估最小实现入口（如从简单查询端点开始逐步扩展）
|
||
- 输出结论建议（保留为"文档已收口、实现待立项"）
|
||
|
||
## Risks
|
||
|
||
| Risk | Mitigation |
|
||
|------|------------|
|
||
| 治理台账同步时遗漏条目 | 每阶段完成后立即检查 `01_Project_Progress.md` 和 `03_Task_Checklist.md` |
|
||
| 接口编号冲突（IF-REV-009 误关联） | 本 feature 明确 IF-REV-013 为 REV-006 专用编号 |
|
||
| 超出本 feature 范围展开实现 | 严守"设计收口、实现待立项"约束，不新增业务代码 |
|