127 lines
11 KiB
Markdown
127 lines
11 KiB
Markdown
# 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 项文档校验或一致性检查。
|