fujian_water_biz_doc/specs/003-rev006-reminder-event-design/plan.md

Plan: REV-006 催缴与通知事件设计收口

Branch: 003-rev003-rev006-reminder-event-design | Date: 2026-03-19 | Spec: 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)

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)

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 范围展开实现	严守"设计收口、实现待立项"约束，不新增业务代码