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

Feature Specification: REV-006 催缴事件与通知协同设计

Feature Branch: 003-rev006-reminder-event-design Created: 2026-03-18 Status: Draft Input: User description: "为 REV-006 催缴与通知补齐 spec-kit 规格，明确催缴任务生成、消息协同结果回写、停复水联动和历史查询边界"

Document Scope & Sources (mandatory)

• Target documents:
  • docs/design/02_Detailed_Design/12_REV_Detailed.md
  • docs/design/03_Technical_Design/03_Interface_Design.md
  • docs/design/03_Technical_Design/01_Database_Design.md
  • docs/design/00_Management/15_SYS002_Requirement_Breakdown.md
  • docs/design/00_Management/01_Project_Progress.md
  • docs/design/00_Management/03_Task_Checklist.md
• Primary source of truth:
  • docs/design/02_Detailed_Design/12_REV_Detailed.md
  • docs/design/03_Technical_Design/03_Interface_Design.md
  • docs/design/03_Technical_Design/01_Database_Design.md
  • docs/design/00_Management/04_Writing_Guide.md
  • AGENTS.md
• Reference sources:
  • docs/design/00_Management/15_SYS002_Requirement_Breakdown.md
  • docs/guides/BACKEND_CURRENT_STATUS.md
  • docs/guides/BACKEND_TABLE_MAPPING.md
  • docs/design/04_Appendix/Archive/01_Requirements/
  • docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md
• Scope decision: In scope. This feature is limited to补齐 REV-006 的正式设计口径、接口边界、数据承接边界和后续任务拆解依据；不扩展到 SYS-010 的内部实现，不重写其他 REV-* 模块，不新建平行正式主稿。

Clarifications

Session 2026-03-18

• Q: 停水/复水联动在本 feature 中应细化到什么程度？ → A: 只定义催缴与停复水的联动边界、触发条件、追溯关系，不展开停复水内部流程。
• Q: REV-006 是否应继续复用 IF-REV-009？ → A: 为 REV-006 新增独立正式接口编号，发票查询继续保留 IF-REV-009。
• Q: REV-006 的催缴结果应采用哪组正式状态？ → A: 采用 4 个正式状态：PENDING、SUCCESS、FAIL、MANUAL_VERIFIED。

User Scenarios & Testing (mandatory)

User Story 1 - 定义催缴闭环范围 (Priority: P1)

作为文档维护者，我需要把 REV-006 的催缴生成、消息触达、结果回写和后续处置边界写清楚，使评审者能明确该模块到底负责什么、不负责什么，并据此开展后续设计与研发；其中停复水仅定义联动边界，不展开内部处置流程。

Why this priority: REV-006 当前在仓库内被判定为“未见实现”，如果范围和边界不先收敛，后续 plan/tasks 会直接失焦。

Independent Test: 单独评审 12_REV_Detailed.md 中 REV-006 章节，应能独立回答“催缴任务如何产生、结果如何回写、停复水与工单如何衔接、哪些内容不在本轮范围内”。

Acceptance Scenarios:

1. Given 当前 REV-006 只有概要级描述， When 评审者阅读更新后的详细设计， Then 能明确催缴对象来源、任务生成维度、自动与人工催缴边界以及停复水联动触发入口。
2. Given 后续需要把 REV-006 拆成开发任务， When 维护者依据该规格开展计划拆解， Then 不需要再回到 Archive 才能判断本轮范围和排除项。

---

User Story 2 - 统一消息协同与结果回写口径 (Priority: P2)

作为接口与系统集成评审者，我需要看到 SYS-002 与 SYS-010 之间关于催缴事件、触达结果、失败重试和状态回写的统一口径，并为 REV-006 使用独立正式接口编号和明确的 4 态结果集，以便避免与发票查询接口混淆。

Why this priority: REV-006 的业务价值高度依赖消息协同结果，若回写与状态语义不清，会直接影响催缴结果查询、后续催办和停复水判断。

Independent Test: 单独评审接口设计相关章节，应能独立确认触发方、回写方、关键状态、失败语义和查询/补偿责任分界。

Acceptance Scenarios:

1. Given SYS-002 需要向 SYS-010 发送催缴事件， When 评审者查看规格， Then 能明确独立接口编号、事件生成条件、发送前置校验和最小回写字段集。
2. Given 消息发送失败或结果迟迟未回写， When 评审者查看规格， Then 能明确 PENDING、SUCCESS、FAIL、MANUAL_VERIFIED 的适用边界，以及重试/补偿归属和人工核查入口。

---

User Story 3 - 明确历史查询与停复水联动边界 (Priority: P3)

作为后续实施和验收人员，我需要知道催缴记录、预存短信、停水记录等历史口径如何在当前体系中承接，避免为了追求“完整”而无依据地新增平行模型。

Why this priority: 旧系统相关对象较多，如果不先定义“最小保留集”和联动边界，后续很容易把历史菜单直接平移成新模块。

Independent Test: 单独检查规格中的迁移/历史查询要求，应能判断哪些历史信息必须可查、哪些仅保留映射说明、哪些应转交工单或外部协同模块承接。

Acceptance Scenarios:

1. Given 需要追查某次催缴或停水处置历史， When 评审者阅读规格， Then 能明确最少需要保留的查询字段与关联对象。
2. Given Archive 中存在旧“停水记录”“预存短信”等入口， When 评审者执行范围判断， Then 能明确这些内容在新体系中属于催缴协同能力还是外部协同能力，而不是新增独立正式模块。

---

Edge Cases

• 当欠费账单满足多条催缴策略时，如何确定任务分组、优先级和避免重复触达？
• 当 SYS-010 返回失败、超时或迟迟不回写时，如何稳定映射到 PENDING、SUCCESS、FAIL、MANUAL_VERIFIED，而不再扩展更多细分状态？
• 当同一客户既存在催缴事件又进入停水/复水处置时，如何保证催缴记录与工单处置链路可追溯但不互相覆盖状态，且本 feature 不承担停复水内部流程定义？
• 当旧系统存在催缴记录、停水记录、预存短信历史数据，但当前后端未见独立表族时，如何定义最小保留查询口径而不臆造新模型？
• 当 REV-006 改用独立正式接口编号后，如何保证 12_REV_Detailed.md、03_Interface_Design.md、01_Database_Design.md 和管理台账同步更新且不保留旧冲突口径？

Requirements (mandatory)

Functional Requirements

• FR-001: Specification MUST identify REV-006 的精确目标文档，并说明每份文档承担的职责。
• FR-002: Specification MUST identify 12_REV_Detailed.md、03_Interface_Design.md、01_Database_Design.md 作为本 feature 的主约束来源。
• FR-003: Specification MUST record that the feature is in scope only for REV-006 的设计与任务拆解准备，不扩展到 SYS-010 内部实现或其他 REV-* 模块重写。
• FR-004: Specification MUST preserve the single-source-of-truth model and MUST NOT introduce a new parallel formal design document for reminder/notice capability.
• FR-005: Specification MUST define reminder object sources based on overdue billing data and customer attributes, including at minimum arrears status, amount, aging, customer category, and applicable reminder strategy dimensions.
• FR-006: Specification MUST define the business flow for reminder generation, task grouping, message dispatch request, result writeback, and follow-up handling.
• FR-007: Specification MUST distinguish automatic reminder, manual reminder, and subsequent disposal linkage, including what belongs to SYS-002, what is coordinated by SYS-010, and what is handled through downstream disposal processes.
• FR-008: Specification MUST define exactly four formal result states for reminder collaboration: PENDING, SUCCESS, FAIL, and MANUAL_VERIFIED, with unambiguous transition intent and usage boundaries.
• FR-008a: Specification MUST require a dedicated formal interface identifier for REV-006 reminder task generation and result handling, and MUST prohibit continued reuse of IF-REV-009 for this feature because IF-REV-009 remains reserved for invoice result query.
• FR-009: Specification MUST define the minimum historical query retention scope for reminder records, stop-water related records, and prepaid-balance reminder events, including the fields needed to trace content, channel, target, time, result, operator/source, and related billing object.
• FR-010: Specification MUST define how stop-water and recovery handling relate to reminder outcomes without collapsing them into the same business object, and MUST limit this feature to linkage conditions and traceability rather than internal disposal workflow details.
• FR-011: Specification MUST state the exclusions for this feature, including that historical menu names and Archive structures are reference material only and not direct targets for formal document reconstruction.
• FR-012: Specification MUST capture cross-document consistency impacts for interfaces, data retention, terminology, result states, and downstream ledger updates.
• FR-013: Specification MUST list the validation actions required after document updates, including single-file validation for impacted docs and link consistency checks.
• FR-014: Specification MUST state that formal document changes under this feature require synchronized updates to 01_Project_Progress.md and 03_Task_Checklist.md.

Assumptions

• 本 feature 以正式文档补齐和后续立项准备为目标，默认不在本轮直接修改 backend 代码。
• SYS-010 继续作为消息发送能力提供方，SYS-002 负责业务事件生成、状态承接和历史查询口径。
• REV-006 将在正式文档中使用新的独立接口编号；现有 IF-REV-009 继续保留给发票结果查询，不再混用。
• 催缴结果状态默认收敛为 PENDING、SUCCESS、FAIL、MANUAL_VERIFIED 四态，本轮不再细分为“已送达”“已阅读”“已补发”等更细粒度状态。
• 旧系统“催缴记录”“预存短信”“停水记录”等历史入口默认先按查询能力和映射口径承接，不默认要求新建同名独立主表。
• 停水/复水属于后续业务处置链的一部分，本 feature 只要求定义与催缴结果的联动边界、触发条件和追溯关系，不展开其内部节点、审批或执行流程。

Key Entities (include if feature involves data)

• Reminder Candidate: 满足欠费、账龄、客户类别等条件、可进入催缴流程的账单或客户对象集合。
• Reminder Strategy: 决定催缴触发条件、分组规则、触达渠道和优先级的业务规则集。
• Reminder Task: 一次可追溯的催缴执行单元，包含催缴对象、触达渠道、生成来源、执行状态和后续处置指向。
• Reminder Result: 由消息协同或人工核查产生的结果记录，反映发送状态、失败原因、回写时间和后续动作建议。
• Reminder History Record: 支撑历史查询的最小记录集合，至少覆盖触达内容、目标对象、渠道、发送时间、结果状态、关联账单和操作来源。
• Disposal Link: 催缴结果与停水、复水、工单或人工处置之间的关联关系，用于追溯后续业务动作，但不替代下游业务对象。
• Ledger Update: 当 REV-006 正式文档完成补齐后，需要同步回写到项目进度和任务清单的治理记录。

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 评审者可在 5 分钟内从规格中定位 REV-006 的目标文档、主约束来源、范围边界和排除项。
• SC-002: 规格中覆盖至少 3 类独立可评审场景：催缴任务生成、消息结果回写、历史查询/停复水联动。
• SC-003: REV-006 的状态语义、协同边界和历史查询最小保留集在规格中均有明确表述，且不存在未解析的 [NEEDS CLARIFICATION] 标记。
• SC-004: 后续执行 /speckit.plan 时，规划者无需新增范围澄清即可把工作拆分为文档对齐、接口补齐、数据口径补齐和台账更新四类任务。
• SC-005: 规格明确列出全部必要验证动作，审阅者可直接据此执行至少 4 项文档校验或一致性检查而无需二次猜测。