fujian_water_biz_doc/specs/006-reminder-event-design/spec.md

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

Feature Branch: 006-reminder-event-design Created: 2026-03-18 Status: Ready for Planning Input: User description: "rev006-reminder-event-design"

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/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/00_Management/15_SYS002_Requirement_Breakdown.md
  • docs/design/01_Overview/03_Summary_Design.md
  • AGENTS.md
• Reference sources:
  • docs/guides/BACKEND_CURRENT_STATUS.md
  • docs/design/04_Appendix/Archive/02_Manuals/营收系统_用户操作手册.md
  • docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md
• Scope decision: In scope. 本 feature 聚焦 REV-006 催缴与通知的正式设计收口，补齐催缴对象生成、任务分组、IF-REV-013 / IF-EXT-008 协同边界、四态状态语义、历史查询口径、停复水/工单联动追溯和后续研发立项输入；不在本轮直接承诺 backend 已落地催缴业务实现。

User Scenarios & Testing (mandatory)

User Story 1 - 收口催缴任务生成规则 (Priority: P1)

作为文档维护者，我需要把 REV-006 的催缴触发时机、催缴对象筛选条件、策略分组规则和四态状态定义写清楚，使评审者能够明确欠费账单如何进入催缴任务，以及哪些场景属于自动催缴、人工补发或人工核查补记。

Why this priority: 当前 REV-006 已有第一轮场景描述，但后续研发立项仍依赖更清晰的触发规则、筛选条件和状态语义。

Independent Test: 单独评审 12_REV_Detailed.md 中 REV-006 章节，应能明确催缴对象来源、触发规则、四态状态和人工核查边界。

Acceptance Scenarios:

1. Given 当前文档只概括“按策略分组催缴任务”， When 评审者阅读补齐后的详细设计， Then 能明确欠费账单、账龄、金额、客户类别、渠道偏好和频控规则如何形成催缴对象与任务。
2. Given 后续需要据此拆解研发任务， When 维护者依据该规格评估实现切入点， Then 能区分自动催缴、人工补发、人工核查补记和停复水联动的边界。

---

User Story 2 - 统一 IF-REV-013 与消息协同边界 (Priority: P2)

作为接口设计评审者，我需要看到 IF-REV-013 和 IF-EXT-008 的职责分工、请求输出、回写字段和四态结果承接口径，使 SYS-002 与 SYS-010 的边界不再停留在抽象表述。

Why this priority: REV-006 的核心风险在于业务筛选、任务状态承接和外部通知执行边界不清，容易出现“任务生成”和“消息发送”职责混写。

Independent Test: 单独评审接口主文档和需求拆解台账，应能确认 IF-REV-013 的业务侧职责、IF-EXT-008 的外部协同职责以及四态回写字段。

Acceptance Scenarios:

1. Given 评审者查看接口设计， When 阅读 IF-REV-013 章节， Then 能明确任务生成、任务查询、人工核查和结果承接的请求路径、字段与状态语义。
2. Given 评审者查看需求拆解文档， When 阅读 SYS002-REQ-011 对应内容， Then 能明确当前属于“设计已收口、实现未见骨架”的状态，而不是误判为已实现。

---

User Story 3 - 形成治理与研发切入结论 (Priority: P3)

作为后续立项和治理跟踪人员，我需要在台账和进度记录中看到 REV-006 的当前结论、最小实现切入点和校验动作，避免文档收口后仍无法指导后续研发排期。

Why this priority: REV-006 当前在治理台账中属于未见实现，需要通过本轮 feature 明确“文档先行、实现待立项”的真实结论和后续切入点。

Independent Test: 单独检查治理文档，应能定位 REV-006 当前状态、最小研发切入点、台账同步动作和验证要求。

Acceptance Scenarios:

1. Given 项目需要安排后续研发排期， When 查看需求拆解和项目进度， Then 能明确 REV-006 当前是设计收口完成、backend 未见明确实现骨架、可继续立项推进的状态。
2. Given 本轮完成正式文档修订， When 查看进度与任务清单， Then 能定位本次 REV-006 文档治理动作及其最小校验结果。

---

Edge Cases

• 当欠费账单已被收费、作废或进入其他处置流程时，催缴对象是否仍可进入任务生成，文档必须如何表达排除条件？
• 当 SYS-010 只返回发送受理结果而未立即返回终态时，四态状态如何在 SYS-002 侧保持一致？
• 当旧系统存在催缴记录、停水记录和预存短信等历史查询场景，但当前 backend 未确认独立落表时，文档如何保持“历史只读承接”而不误写为现成在线表？
• 当人工核查补记场景发生时，哪些字段必须记录核查说明、关联任务号和后续处置引用？

Requirements (mandatory)

Functional Requirements

• FR-001: Specification MUST identify the exact target documents for REV-006 reminder-event alignment and governance sync.
• FR-002: Specification MUST identify 12_REV_Detailed.md、03_Interface_Design.md、15_SYS002_Requirement_Breakdown.md as the main source-of-truth set for this feature.
• FR-003: Specification MUST record that this feature is in scope only for reminder-candidate generation, task rules, IF-REV-013 / IF-EXT-008 interface boundary, four-state result semantics, historical query boundary, and governance sync.
• FR-004: Specification MUST preserve the single-source-of-truth model and MUST NOT create a parallel formal design document for REV-006.
• FR-005: Specification MUST define reminder-candidate selection conditions, including arrears status, aging, amount, customer category, channel preference, strategy grouping, and frequency-control boundary.
• FR-006: Specification MUST define the formal four-state reminder result set as PENDING、SUCCESS、FAIL、MANUAL_VERIFIED, including the intended meaning of each state.
• FR-007: Specification MUST define the exact business boundary of IF-REV-013, including task generation, task query, manual verification, result acceptance, and historical query support.
• FR-008: Specification MUST define the external collaboration boundary of IF-EXT-008, clarifying that SYS-010 is responsible for channel delivery while SYS-002 retains business-side task and state control.
• FR-009: Specification MUST define the minimum write-back and traceability fields for reminder results, including task number, event number, strategy code, channel type, trigger type, status, failure reason, and disposal reference.
• FR-010: Specification MUST define how reminder results link to stop-water, restore-water, work-order, or manual follow-up references without expanding those downstream internal workflows.
• FR-011: Specification MUST define historical query and export expectations for reminder records, including customer, bill period, reminder channel, target receiver, send time, execution result, related bills, and disposal references.
• FR-012: Specification MUST explicitly capture the current implementation judgment as “文档已收口，backend 未见明确催缴/通知业务实现骨架” unless stronger evidence is found later.
• FR-013: Specification MUST identify the minimum validation actions after document updates, including affected file validation, link checks, and Mermaid checks where flows are updated.
• FR-014: Specification MUST state that important formal document changes under this feature require synchronized updates to 01_Project_Progress.md and 03_Task_Checklist.md.

Assumptions

• 本 feature 以正式文档收口和后续研发立项准备为目标，默认不在本轮直接承诺 backend 业务代码实现。
• IF-REV-013 继续作为 REV-006 的正式业务接口编号，不复用其他 IF-REV-* 编号。
• SYS-010 负责短信、微信公众号、站内信等触达执行；SYS-002 保留催缴对象筛选、任务生成、四态状态承接和历史查询职责。
• 当前 backend 中未见明确的 Reminder/Message/Notice 业务控制器或服务骨架，因此实现状态保持“未见实现”。
• 催缴记录、停复水记录和预存短信等历史场景在本轮按“历史只读查询口径”承接，不默认要求新建平行在线主表。

Key Entities (include if feature involves data)

• Reminder Candidate: 由欠费账单、账龄、欠费金额、客户类别、联系方式和命中策略组成的催缴输入对象。
• Reminder Strategy: 定义账龄规则、金额规则、客户类别规则、渠道优先级、频控策略和后续联动关注条件的策略对象。
• Reminder Task: 一次正式催缴执行单元，至少包含 taskNo、eventNo、strategyCode、channelType、triggerType、status 和关联账单集合。
• Reminder Result: 催缴任务的四态结果及其失败原因、执行时间、外部回写摘要和业务侧处置引用。
• Disposal Link: 催缴结果与停复水、工单、人工核查等后续处置之间的追溯引用对象。
• Governance Record: 用于在需求拆解、项目进度和任务清单中登记本轮 REV-006 收口结论和后续研发建议的治理记录。

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 评审者可在 5 分钟内从规格中定位 REV-006 的目标文档、催缴对象生成规则、接口边界和排除项。
• SC-002: 规格中至少覆盖 3 类独立可评审内容：催缴任务生成规则、IF-REV-013 / IF-EXT-008 边界、治理与研发切入结论。
• SC-003: 规格明确区分至少 6 项关键任务或结果要素，如 taskNo、eventNo、strategyCode、channelType、triggerType、status、失败原因、处置引用。
• SC-004: 后续执行 /speckit.plan 时，规划者无需再补充范围澄清即可将工作拆分为详细设计收口、接口收口、治理同步和实现切入点评估四类任务。
• SC-005: 规格明确列出全部必要验证动作，审阅者可直接据此执行至少 4 项文档校验或一致性检查。