diff --git a/docs/design/00_Management/01_Project_Progress.md b/docs/design/00_Management/01_Project_Progress.md index c618327..6739553 100644 --- a/docs/design/00_Management/01_Project_Progress.md +++ b/docs/design/00_Management/01_Project_Progress.md @@ -127,6 +127,7 @@ | 2026-03-18 | REV-005 验收证据缺口复核与 tasks 校准 | 1)手工重建 `specs/002-rev005-invoice-flow/tasks.md`,修复 US4 与 Final Phase 的 `T057 ~ T061` 重号,并将 SC-001 ~ SC-004 统计补证、spec 状态同步与最终交付摘要拆分为 `T060 ~ T065` 显式待办;2)复核 `specs/002-rev005-invoice-flow/verification.md`、`spec.md` 与仓库关键字检索结果,确认当前仓库内尚未定位到 REV-005 对应的专项压测脚本、统计脚本或样本台账;3)将 `spec.md` 状态调整为 `Verification Pending`,并把后续动作收敛到样本统计、运行态日志抽样与 DDL 风险跟踪。 | 用户继续推进 REV-005,希望在不虚构验收数据的前提下,把当前真实完成度、待补证据和 Speckit 任务口径收敛一致。 | 正面影响,REV-005 的任务台账、规格状态与验证结论已统一到“实现闭环基本完成、SC-001 ~ SC-004 量化证据待补”的当前真实状态;后续可直接围绕专项统计和联调样本继续收口,而不会误判为一期已完成量化验收。 | | 2026-03-18 | REV-005 SC-005 日志追溯矩阵补齐 | 1)基于 `InvoiceServiceImpl.java` 梳理发票申请、查询/补偿、结果回写、客户侧查询/下载/推送、作废、红冲等关键动作的统一日志写入点;2)确认上述动作均通过 `recordInvoiceOperatLog` 归一写入,并由 `OperatLogService.createOperatLog` 承接操作人、客户与日志内容上下文;3)在 `specs/002-rev005-invoice-flow/verification.md` 回写“关键动作 ↔ 日志写入点”矩阵,将 SC-005 收敛为“实现态证据已补齐、运行态样本待抽查”。 | 用户继续推进 REV-005,一期验收优先补齐 SC-005 的可引用验证证据,避免日志完整率仍停留在笼统结论。 | 正面影响,REV-005 已具备可直接引用的实现态日志追溯矩阵,申请、查询补偿、回写、客户侧查询/下载/推送、作废、红冲等关键动作均可定位到统一日志写入点;后续主要补充测试环境样本抽查即可收口运行态证据。 | | 2026-03-18 | REV-005 `biz_invoice` DDL 来源核实 | 1)在 `backend/sql`、`docs/design/04_Appendix/Archive/03_Design_Docs/数据库设计.md`、`sql/lhc_数据库设计.md`、`docs/guides/BACKEND_TABLE_MAPPING.md` 范围内交叉检索 `biz_invoice`、作废/红冲新增字段与迁移脚本;2)确认仓库内未找到与当前 `InvoiceDO.java` 对应的 `biz_invoice` 物理 DDL / migration;3)确认 Archive 与 `sql/lhc_数据库设计.md` 中同名 `biz_invoice` 更偏“开票配置表”,不能直接作为 REV-005 发票主记录表的落库依据;4)将该结论回写到 REV-005 验证与管理台账。 | 用户继续要求沿 REV-005 把 US4 剩余风险查清,不停留在“表结构待补”泛化表述。 | 正面影响,REV-005 当前已明确“接口/DO/文档承接口径已完成,但物理落库证据仍未在仓库内闭环”;后续若推进提测或联调,可直接把 DDL 缺口作为明确风险跟踪,避免误判作废/红冲字段已正式落库。 | +| 2026-03-18 | REV-005 验证文档补强实现态证据 | 1)在 `specs/002-rev005-invoice-flow/verification.md` 为 `SC-001 ~ SC-004` 补充基于 `InvoiceController.java`、`InvoiceServiceImpl.java` 与各请求 VO 的实现态证据,明确申请入口、必填字段、同步处理边界、回写联动、客户侧消费约束与幂等/拦截规则;2)在 `SC-005` 与 `T055` 模板补记 `biz_invoice` 物理 DDL / migration 持续跟踪结论,避免日志抽样与物理落库风险脱节;3)保持 `T055`、`T060 ~ T063` 仍为“待真实联调样本回填”,不虚构量化结果。 | 用户要求直接继续 REV-005,并在未取得真实联调样本前,先把可防御的实现态证据落入正式验证文档。 | 正面影响,REV-005 当前验证记录已从“只有模板和待补口径”提升为“模板 + 代码证据 + 明确缺口”并存;后续联调回填时可直接引用实现态依据解释统计口径、拦截分类与日志追溯边界。 | | 2026-03-17 | REV-005 作废与红冲二期最小入口落地(US4) | 1)更新 `spec.md`、`plan.md`、`tasks.md`,将 US4 从“边界预留”升级为当前二期实现范围;2)更新 `12_REV_Detailed.md`、`03_Interface_Design.md`,明确后台作废/红冲入口、状态边界与客户侧消费约束;3)在 `InvoiceController.java`、`InvoiceService.java`、`InvoiceServiceImpl.java` 中将作废/红冲入口升级为专门请求 VO,并补齐原因/备注、原发票代码/号码校验与日志留痕;4)扩展 `InvoiceDO.java` 承接作废原因/备注、红冲原因/备注、原发票代码/号码与触发来源字段,并在 service 中回写最小上下文;5)更新 `01_Database_Design.md` 中 REV-005 发票承接口径,补充作废/红冲原因、备注、原票关联与查询补偿上下文;6)执行 `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` 与 `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` 并通过。 | 用户持续要求“继续推进 REV-005”,在一期闭环收口后继续落地 US4 二期最小能力入口,避免作废/红冲长期停留在文档预留状态。 | 正面影响,REV-005 已从“一期正常开票闭环”进一步扩展到“二期作废/红冲最小入口可评审、可编译验证”的状态;当前已补齐专门 VO 接线、原票引用校验、DO 字段承接与数据库承接口径,后续主要剩余 Mapper/表结构层面的正式持久化落地。 || 2026-03-17 | REV-005 结果回写与客户侧电子发票消费闭环(US3) | 1)更新 `12_REV_Detailed.md`、`01_Database_Design.md`、`03_Interface_Design.md`,补齐结果回写、账单关联、客户侧查询/下载/推送电子发票规则;2)扩展 `InvoiceController.java`、`InvoiceServiceImpl.java`、`InvoiceMapper.java` 与相关 VO/DO,落地客户归属校验、`SUCCESS + fileUrl` 消费前置校验、账单开票状态联动、推送状态回写;3)执行 `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md`、`make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` 及 `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` 验证通过。 | 用户要求沿 `/speckit.implement` 持续推进 REV-005 US3,不中断实现链路,直接完成结果回写、账单关联与客户侧电子票消费闭环。 | 正面影响,REV-005 已形成“回写落账 + 账单状态联动 + 客户侧查询/下载/推送 + 最小编译验证”闭环,后续可继续衔接作废、红冲与更多电子发票渠道扩展。 | | 2026-03-16 | REV-005 后台发票申请与校验闭环(US1) | 1)在 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java` 增加后台发票申请入口;2)在 `service/invoice/InvoiceServiceImpl.java` 实现客户、客户开票信息、账单与税率校验,确保仅已收费未开票账单允许申请;3)补齐 `applicationNo` 或 `custId + chargeIds` 幂等控制、申请单号生成与申请记录落库;4)执行 `mvn -f backend/sw-business/pom.xml -pl sw-business-server -am -DskipTests compile` 最小编译验证并通过。 | 用户要求继续推进 REV-005 implement,优先完成后台发票申请、开票校验与 US1 收尾,不中断当前实现链路。 | 正面影响,REV-005 已形成“后台申请入口 + 关键校验 + 幂等受理 + 最小编译验证”闭环,后续可在此基础上继续推进 SYS-008 调用、开票结果回写、账单状态联动与电子发票推送下载能力。 | | 2026-03-12 | OMX 任务路由样例落地 | 1)新增 `docs/design/00_Management/17_OMX_Task_Routing_Examples.md`,给出 `REV-004`、`REV-003` 与正式文档修订三类任务的 leader / explorer / executor / verifier 分工模板;2)补充各 lane 的提示词模板、推荐执行顺序与不建议的并行方式;3)更新 `00_Management/README.md` 收录该文档入口。 | 用户希望在治理层之外,再拿到针对当前项目可以直接复用的多 Agent 分工模板,而不是只看抽象原则。 | 正面影响,OMX 从“有规则”变成“可直接照着分工执行”;后续在 `REV-004`、`REV-003` 等闭环中可直接套用 lane 拆分,减少 leader 临时编排成本。 | @@ -325,7 +326,7 @@ ### 2026-03-18 更新 -- 完成 `REV-006` Speckit feature `003-rev006-reminder-event-design` 的 implement 阶段文档收口,统一 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md` 与治理台账口径。 +- 完成 `REV-006` Speckit feature `006-reminder-event-design` 的 implement 阶段文档收口,统一 `12_REV_Detailed.md`、`03_Interface_Design.md` 与治理台账口径。 - `REV-006` 正式业务接口编号确定为 `IF-REV-013`,不再复用 `IF-REV-009`;催缴结果状态统一为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态。 - 明确旧“催缴记录 / 停水记录 / 预存短信记录”按历史只读口径承接,不新增同名在线主表;停复水在本轮仅保留联动边界、处置引用和追溯关系。 - 启动并完成 `REV-007` Speckit feature `004-rev007-revenue-statistics-design` 的 `specify -> plan -> tasks` 工件链,形成统计主题、维度、指标、`IF-REV-010` 与数据库承接口径的正式设计基线。 @@ -335,3 +336,8 @@ - 完成 `01_Database_Design.md` 与 `15_SYS002_Requirement_Breakdown.md` 的同步回写,明确 `biz_charge` / `biz_charge_detail`、价格规则对象和历史特殊开账的正式承接口径,并继续维持 `SYS002-REQ-004`“部分实现”的保守判断。 - 基于 `ChargeController`、`ChargeServiceImpl` 与 `ReadingDataServiceImpl` 的第二轮 backend 证据精修 `REV-002` 结论,确认当前已支持按 `readingDataIds` 批量复核并开账,成功路径会写入 `biz_charge` / `biz_charge_detail` 并回写抄表数据状态。 - 同步明确 `IF-REV-005` 当前实现缺口:请求仍局限 `readingDataIds`,返回仍为成功条数字符串,失败阻断未形成结构化结果,且仅支持 `ACTUAL_USAGE` 结算方式,因此治理判断继续维持“部分实现”。 + +### 2026-03-19 更新 + +- 完成 `REV-006` 当前轮次治理文档二次对齐:在 `15_SYS002_Requirement_Breakdown.md` 明确 `SYS002-REQ-011` 继续维持“未见实现”判断,并补记 `specs/006-reminder-event-design/` 工件基线与后续研发切入建议。 +- 同步回写 `03_Task_Checklist.md` 与本进度文档,补充本轮 implement 阶段的治理动作、验证动作与台账一致性说明,避免将文档收口误写为 backend 已实现。 diff --git a/docs/design/00_Management/03_Task_Checklist.md b/docs/design/00_Management/03_Task_Checklist.md index 2fd2a8b..1d3fc37 100644 --- a/docs/design/00_Management/03_Task_Checklist.md +++ b/docs/design/00_Management/03_Task_Checklist.md @@ -209,6 +209,7 @@ - [x] 已补齐 REV-005 联调前置检查清单,明确环境地址、鉴权信息、样本数据、主键映射、日志入口、回填责任与归档路径;进入联调前已具备统一核对项 ✅ - [x] 已补齐 REV-005 最终联调执行顺序与完成判定清单,明确 `T060 → T061 → T062 → T063 → T055` 的建议收口顺序与单项勾选条件;后续联调完成后可直接据此关闭待办 ✅ - [x] 已补齐 REV-005 剩余工作摘要,明确当前仅剩 `T055`、`T060 ~ T063` 的真实联调取证与结果回填,可直接用于提测、汇报与交接引用 ✅ +- [x] 已为 `verification.md` 的 `SC-001 ~ SC-004` 补强 `InvoiceController.java`、`InvoiceServiceImpl.java` 与请求 VO 对应的实现态证据,并在 `SC-005` / `T055` 模板中补记 `biz_invoice` 物理 DDL / migration 持续跟踪结论;当前仍保持 `T055`、`T060 ~ T063` 待真实联调样本回填 ✅ - [x] **完成 SYS-002 需求拆解总表与实现评估整理** ✅ (2026-03-17) - [x] 新增 `15_SYS002_Requirement_Breakdown.md`,形成 `SYS002-REQ-001 ~ 015` 的统一需求拆解口径 ✅ - [x] 基于 `backend/sw-business` 与 `backend/sw-business-bank` 输出已实现 / 部分实现 / 未见实现评估结果 ✅ @@ -531,6 +532,10 @@ - [x] 更新 `docs/design/03_Technical_Design/03_Interface_Design.md`,新增 `IF-REV-013` 正式接口定义,并统一 `IF-EXT-008` 协同字段、异常码、幂等键与历史查询口径 ✅ - [x] 更新 `docs/design/03_Technical_Design/01_Database_Design.md`,明确历史只读保留策略、最小查询字段与处置引用边界 ✅ - [x] 更新 `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`、`01_Project_Progress.md` 与本任务清单,完成 implement 阶段治理回写 ✅ +- [x] **完成 REV-006 implement 阶段治理文档二次对齐** ✅ (2026-03-19) + - [x] 在 `15_SYS002_Requirement_Breakdown.md` 明确 `SYS002-REQ-011` 继续维持“未见实现”,并补记 `specs/006-reminder-event-design/` 工件基线 ✅ + - [x] 在 `01_Project_Progress.md` 更正 REV-006 feature 编号与本轮治理回写记录,避免误导为 backend 已实现 ✅ + - [x] 在治理任务建议中补充 `make validate-file`、`make check-links`、`make validate-mermaid` 与台账同步动作 ✅ ### 📋 REV-007 营收统计查询设计 diff --git a/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md b/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md index a93bf7e..08cc9ba 100644 --- a/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md +++ b/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md @@ -130,7 +130,7 @@ | `REV-003` 营业收费 | 部分实现 | 建议围绕“柜台班结”“红冲历史查询”等缺口拆小 feature | | `REV-004` 账务处理 | 已实现 | 以规则收口、二期扩展或历史台账映射为主 | | `REV-005` 发票与税务处理 | 已实现 | 以验收归档和细粒度对象补证为主 | -| `REV-006` 催缴与通知 | 未见实现 | 已完成 Speckit `specify -> clarify -> plan -> tasks`,当前进入 `implement` 阶段的正式文档收口与台账同步。 | +| `REV-006` 催缴与通知 | 未见实现 | 已完成 Speckit `specify -> plan -> tasks` 工件并形成 `specs/006-reminder-event-design/` 基线;当前进入 `implement` 阶段文档收口与台账同步,backend 仍未见明确催缴/通知业务实现骨架。 | | `REV-007` 统计分析 | 未见实现 | 已完成 Speckit `specify -> plan -> tasks`,当前进入 `implement` 阶段的正式文档收口与治理同步。 | | `REV-008` 代收与银行业务 | 已实现 | 以跨系统口径收口和扩展台账补证为主 | | `REV-009` 业务参数配置 | 已实现 | 以参数边界收口和治理能力补充为主 | @@ -152,7 +152,7 @@ | `REV-003` | 是 | `rev003-redflush-history-query` | 中 | 聚焦红冲历史查询与台账承接 | | `REV-004` | 否 | `rev004-adjustment-followup` | 中 | 仅在补二期或精细对象时使用 | | `REV-005` | 否 | `rev005-detail-reconciliation` | 中 | 仅在补发票细表/批次缺口时使用 | -| `REV-006` | 是 | `rev006-reminder-event-design` | 最高 | 已作为未实现模块的首个完整 Speckit feature 启动,当前重点转向实现闭环与后续研发立项。 | +| `REV-006` | 是 | `rev006-reminder-event-design` | 最高 | 已完成 `spec/plan/research/data-model/contracts/quickstart/tasks` 工件链,当前重点为按 `IF-REV-013` 四态口径推进正式文档 implement 收口并形成后续研发切入点。 | | `REV-006` | 是 | `rev006-notice-result-writeback` | 高 | 可作为 `REV-006` 拆分子 feature | | `REV-007` | 是 | `rev007-revenue-statistics-design` | 高 | 已启动并完成第一轮设计工件,当前建议继续收口正式文档并形成后续研发切入点 | | `REV-007` | 是 | `rev007-channel-analysis-query` | 中 | 适合作为统计分析子 feature | @@ -233,13 +233,13 @@ - 标题:`SYS-002:补齐催缴事件与通知协同设计` - 对应需求:`SYS002-REQ-011` -- feature:`sys002-reminder-event-design` +- feature:`rev006-reminder-event-design`(治理映射名:`sys002-reminder-event-design`) - 优先级:`高` - 当前实现状态:`未见实现` - Story 描述: - 目标:补齐欠费催缴对象生成、通知触发、通知结果回写与催缴追踪闭环。 - 事实来源:`12_REV_Detailed.md` 中 REV-006、`03_Interface_Design.md` 中 `IF-EXT-008`。 - - 当前判断:当前代码检索范围内未见明确的催缴、通知、消息协同控制器或服务骨架;但本轮已在正式文档中新增 `IF-REV-013`,并统一四态状态集、历史只读查询口径和停复水联动边界。 + - 当前判断:当前代码检索范围内未见明确的催缴、通知、消息协同控制器或服务骨架;但本轮已完成 `specs/006-reminder-event-design/` 工件链,并在正式文档中统一 `IF-REV-013`、四态状态集、历史只读查询口径和停复水联动边界。 - 验收要点:明确催缴触发时机、催缴对象筛选条件、通知方式、回写字段、四态状态语义与失败重试机制。 - 推荐 Task: - `T-011-01` 对齐催缴业务场景、触发条件与对象筛选规则 @@ -247,6 +247,7 @@ - `T-011-03` 对齐催缴过程、操作日志、四态状态流转与历史查询规则 - `T-011-04` 校核当前代码中是否存在可复用的消息/通知基础能力 - `T-011-05` 输出是否需独立立项开发及最小实现切入点的结论 + - `T-011-06` 执行 `make validate-file` / `make check-links` / `make validate-mermaid` 并同步 `01_Project_Progress.md`、`03_Task_Checklist.md` ### P1:第二优先级 diff --git a/docs/design/02_Detailed_Design/12_REV_Detailed.md b/docs/design/02_Detailed_Design/12_REV_Detailed.md index d21be32..75da96c 100644 --- a/docs/design/02_Detailed_Design/12_REV_Detailed.md +++ b/docs/design/02_Detailed_Design/12_REV_Detailed.md @@ -491,6 +491,13 @@ flowchart TD 5. 停复水在本模块中仅定义联动触发条件、处置引用与追溯关系,不展开停复水内部审批、派工或现场执行流程。 6. 当前后端中部分催缴汇总、停水明细对象未确认独立落表,文档中保持保守描述,不误写为已确认在线主表。 +#### 催缴对象筛选、排除与频控边界 + +- `IF-REV-013` 任务生成前必须完成候选筛选,筛选最小维度为:欠费状态、欠费金额、账龄分组、客户类别、渠道偏好和策略编码。 +- 候选对象必须以有效欠费账单为前提;以下场景不得进入正式催缴任务:已收费核销、已作废、已进入不允许催缴的处置流程、策略规则未命中。 +- 触发类型按 `triggerType` 区分自动与人工;自动用于批量触发,人工用于补发、核查和例外补记,不改变正式接口编号与状态语义。 +- 频控以“同客户/同策略/同渠道/同账期窗口”为最小拦截单元;命中频控时允许部分阻断,并返回被跳过对象及原因摘要。 + ### 核心数据 - `biz_charge`、`biz_charge_detail`:催缴对象来源。 @@ -501,8 +508,17 @@ flowchart TD - `Reminder Candidate`:由欠费账单、客户类别、账龄分组、欠费金额、联系方式集合和命中策略编码组成,是催缴任务的输入对象。 - `Reminder Strategy`:定义账龄规则、金额规则、客户类别规则、渠道优先级、重复触达拦截窗口和是否触发后续处置关注。 - `Reminder Task`:一次正式催缴执行单元,至少包含 `taskNo`、`eventNo`、`strategyCode`、`channelType`、`triggerType`、`status` 和关联账单信息;正式业务接口编号固定为 `IF-REV-013`。 +- `Reminder Result`:承接 `IF-EXT-008` 回传结果后由业务侧映射的正式四态结果,最少记录 `status`、`lastCallbackTime`、`failReason` 与回传摘要。 - `Disposal Link`:用于记录催缴结果与停水、复水、工单或人工跟进之间的关联引用,只承担追溯职责,不替代下游业务对象。 +#### 四态与人工核查边界 + +- `PENDING`:已生成任务并完成外部受理或等待外部终态回传,尚未形成业务终态。 +- `SUCCESS`:外部触达结果明确成功,且业务侧已完成结果承接。 +- `FAIL`:外部返回明确失败或业务判定失败,必须记录失败原因。 +- `MANUAL_VERIFIED`:仅用于外部结果长期未定、人工核查补记或例外核销说明场景;必须留存核查说明与核查人。 +- 人工核查是状态收口手段,不得用于绕过候选筛选、排除条件或频控约束。 + ### 迁移补充(旧系统承接) #### 催缴记录 @@ -510,12 +526,14 @@ flowchart TD - 旧系统支持催缴记录查询、导出和明细展开,记录中包含推送内容、号码、方式、结果等信息。 - 新系统可继续以消息协同结果和账单状态联动承接,但必须明确催缴记录查询口径,而不能仅保留“已发送/未发送”状态。 - 历史查询最少保留客户号、账期、催缴方式、发送对象、发送时间、执行结果、关联账单、关联处置引用等字段,并兼容四态结果或其历史映射值。 +- 历史催缴记录按只读口径承接,作为查询与追溯来源,不反推为已确认在线主表。 #### 停水记录 - 停水记录不是孤立账务对象,应由催缴结果、业务处置和现场执行工单共同形成闭环。 - 迁移后需支持按客户、站点、停水原因、停水时间、复水状态查询,并能追溯到对应欠费账单和工单执行结果。 - 正式设计只定义“何时建立联动、如何保存处置引用、如何追溯关联结果”,不在 `REV-006` 中展开停复水内部流程设计。 +- 停复水关联以 `Disposal Link` 的处置引用承接,最少包含任务号、处置类型、处置引用号和建联时间。 #### 预存短信 diff --git a/docs/design/03_Technical_Design/03_Interface_Design.md b/docs/design/03_Technical_Design/03_Interface_Design.md index 2fa94fa..93d723f 100644 --- a/docs/design/03_Technical_Design/03_Interface_Design.md +++ b/docs/design/03_Technical_Design/03_Interface_Design.md @@ -231,9 +231,15 @@ retrieval_priority: P0 | 归属模块 | REV-006 / CS-006 | | 调用方向 | SYS-002 → SYS-010 | | 接口方式 | HTTPS REST 或 MQ | -| 业务说明 | 发送催缴通知、办理进度通知、缴费结果通知等消息事件 | +| 业务说明 | 承接催缴通知、办理进度通知、缴费结果通知等消息事件,返回受理结果并回传执行结果 | | 核心数据支撑 | `biz_charge`、`biz_process`、`biz_operat_log` | +边界约束: +- `IF-EXT-008` 只负责渠道触达执行与回执回传,不负责催缴候选对象筛选、任务生成或业务状态主控。 +- `SYS-010` 回传的渠道执行结果需由 `SYS-002` 映射为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态业务状态。 +- 当仅返回受理成功但未返回终态时,`SYS-002` 维持 `PENDING`;若长期无终态且人工核查确认,可转 `MANUAL_VERIFIED`。 +- 消息模板、供应商协议和重试细节由 `SYS-010` 管理,不在 `IF-EXT-008` 展开实现细节。 + ### IF-EXT-009 集抄数据接入接口 | 项目 | 说明 | @@ -952,6 +958,14 @@ retrieval_priority: P0 - 当外部结果长期未定、历史回执不足或人工核查已确认结果时,可将任务补记为 `MANUAL_VERIFIED`,并保留核查人和核查说明。 - 接口返回的 `relatedDisposalRef` 仅用于追溯停复水、复水或工单处置引用,不表示本接口承担下游流程控制。 +#### 失败阻断与人工核查约束 + +- 候选账单不满足欠费前提、策略编码无效或触达信息缺失时,应阻断任务生成并返回明确原因,不得写入伪成功状态。 +- 频控规则命中时允许部分阻断,必须返回被跳过对象与原因摘要,避免“全成功”误判。 +- 渠道协同超时或仅返回受理结果时,不直接判定 `FAIL`,保持 `PENDING` 并等待回执或进入人工核查流程。 +- 人工核查补记必须校验 `taskNo` 存在且 `manualVerifyNote` 非空;不满足条件时应拒绝补记并返回校验错误。 +- 人工核查仅用于状态收口,不替代 `SYS-010` 的渠道执行职责,也不扩展停复水/工单内部流程控制。 + ### IF-REV-010 统计查询接口 #### 请求参数 @@ -1574,7 +1588,7 @@ sequenceDiagram | 催缴通知 | `triggerType` | `payload.triggerType` | 自动/人工触发方式 | 任务触发上下文 | | 办理进度通知 | `processCode` | `payload.processCode` | 业务办理单号 | `biz_process.code` | | 办理进度通知 | `processStatus` | `payload.processStatus` | 办理状态 | `biz_process.status` | -| 发送结果回写 | `status` | `sendStatus` | 四态结果在业务侧映射为 `PENDING/SUCCESS/FAIL` | 消息结果 | +| 发送结果回写 | `status` | `sendStatus` | 渠道回执由 `SYS-002` 统一映射为 `PENDING/SUCCESS/FAIL/MANUAL_VERIFIED` 四态 | 消息结果 | | 发送结果回写 | `reachStatus` | `reachStatus` | 触达/阅读状态 | 渠道回执 | | 发送结果回写 | `sendTime` | `sendTime` | 发送时间 | 消息结果 | | 发送结果回写 | `msg` | `resultMsg` | 结果说明 | 返回消息 | diff --git a/specs/006-reminder-event-design/checklists/requirements.md b/specs/006-reminder-event-design/checklists/requirements.md new file mode 100644 index 0000000..c5fe0b1 --- /dev/null +++ b/specs/006-reminder-event-design/checklists/requirements.md @@ -0,0 +1,35 @@ +# Specification Quality Checklist: REV-006 催缴与通知事件设计收口 + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-03-18 +**Feature**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/spec.md) + +## Content Quality + +- [x] No implementation details (languages, frameworks, APIs) +- [x] Focused on user value and business needs +- [x] Written for non-technical stakeholders +- [x] All mandatory sections completed + +## Requirement Completeness + +- [x] No [NEEDS CLARIFICATION] markers remain +- [x] Requirements are testable and unambiguous +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic (no implementation details) +- [x] All acceptance scenarios are defined +- [x] Edge cases are identified +- [x] Scope is clearly bounded +- [x] Dependencies and assumptions identified + +## Feature Readiness + +- [x] All functional requirements have clear acceptance criteria +- [x] User scenarios cover primary flows +- [x] Feature meets measurable outcomes defined in Success Criteria +- [x] No implementation details leak into specification + +## Notes + +- Validated against `spec.md` on 2026-03-18; no outstanding clarification markers or blocking quality gaps were found. +- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan` diff --git a/specs/006-reminder-event-design/contracts/if-ext-008.md b/specs/006-reminder-event-design/contracts/if-ext-008.md new file mode 100644 index 0000000..e9b9235 --- /dev/null +++ b/specs/006-reminder-event-design/contracts/if-ext-008.md @@ -0,0 +1,74 @@ +# Contract: IF-EXT-008 消息触达协同接口 + +## 1. 合同定位 + +- 接口编号:`IF-EXT-008` +- 归属模块:`REV-006 / CS-006` +- 责任系统:`SYS-010` +- 调用方:`SYS-002` +- 合同类型:外部协同接口设计合同 + +## 2. 业务职责 + +`IF-EXT-008` 负责: + +- 承接 `SYS-002` 传入的通知任务 +- 按短信、微信公众号、站内信等渠道执行触达 +- 返回受理结果,并在后续回传最终执行结果或失败摘要 + +`IF-EXT-008` 不负责: + +- 生成催缴候选对象 +- 定义催缴业务状态体系 +- 决定停复水或工单联动流程 + +## 3. 输入合同 + +| 字段 | 说明 | 约束 | +|------|------|------| +| eventNo | 业务事件号 | 必填 | +| taskNo | 催缴任务号 | 必填 | +| channelType | 渠道类型 | 必填 | +| receiver | 触达对象 | 必填 | +| messageTemplateCode | 消息模板编码 | 必填 | +| messageParams | 模板参数 | 可为空对象 | +| priority | 优先级 | 可选 | +| callbackUrlOrMode | 结果回传方式 | 必填 | + +## 4. 输出合同 + +### 4.1 受理返回 + +| 字段 | 说明 | +|------|------| +| accepted | 是否受理 | +| externalRequestNo | 外部请求号 | +| acceptedTime | 受理时间 | +| rejectReason | 拒绝原因 | + +### 4.2 结果回传 + +| 字段 | 说明 | +|------|------| +| eventNo | 业务事件号 | +| taskNo | 催缴任务号 | +| deliveryStatus | 渠道执行结果 | +| deliveryTime | 执行时间 | +| externalResultCode | 外部结果码 | +| externalResultMessage | 外部结果说明 | + +## 5. 边界合同 + +1. `SYS-010` 的执行结果不直接定义 `REV-006` 业务态,而是由 `SYS-002` 映射为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED`。 +2. 若仅返回受理成功、未返回终态,则 `SYS-002` 维持 `PENDING`。 +3. 若外部长时间无终态回写,业务侧可通过人工核查进入 `MANUAL_VERIFIED`。 +4. 渠道模板、供应商协议与重试细节由 `SYS-010` 管理,不在 `REV-006` 正式设计中展开。 + +## 6. 失败与补偿语义 + +| 场景 | 协同要求 | +|------|----------| +| 渠道受理失败 | 立即回传拒绝原因,由 `SYS-002` 视情况转 `FAIL` | +| 发送成功 | 回传成功结果,由 `SYS-002` 转 `SUCCESS` | +| 发送失败 | 回传失败摘要,由 `SYS-002` 转 `FAIL` | +| 无终态回写 | 允许保留 `PENDING`,由人工补记收口 | diff --git a/specs/006-reminder-event-design/contracts/if-rev-013.md b/specs/006-reminder-event-design/contracts/if-rev-013.md new file mode 100644 index 0000000..4457021 --- /dev/null +++ b/specs/006-reminder-event-design/contracts/if-rev-013.md @@ -0,0 +1,114 @@ +# Contract: IF-REV-013 催缴任务生成与结果承接接口 + +## 1. 合同定位 + +- 接口编号:`IF-REV-013` +- 归属模块:`REV-006` +- 责任系统:`SYS-002` +- 协同系统:`SYS-010` +- 合同类型:业务接口设计合同 + +## 2. 业务职责 + +`IF-REV-013` 负责: + +- 基于欠费账单、策略与渠道偏好生成催缴任务 +- 查询催缴任务状态与历史催缴记录 +- 承接消息协同后的业务侧四态状态 +- 记录人工核查补记和处置引用 + +`IF-REV-013` 不负责: + +- 短信、微信、站内信等渠道实际发送 +- 停复水内部审批、派工和现场执行 +- 扩展五态以上的细粒度业务状态 + +## 3. 输入合同 + +### 3.1 任务生成 + +| 字段 | 说明 | 约束 | +|------|------|------| +| strategyCode | 催缴策略编码 | 必填 | +| triggerType | 触发类型 | 自动 / 人工 | +| candidateList | 催缴候选对象集合 | 至少 1 条 | +| channelPreference | 渠道优先级 | 至少 1 项 | +| operator | 操作人或任务来源 | 人工触发时必填 | + +### 3.2 任务查询 + +| 字段 | 说明 | 约束 | +|------|------|------| +| taskNo | 催缴任务号 | 与条件查询二选一 | +| custId | 客户标识 | 可选 | +| billPeriod | 账期 | 可选 | +| status | 任务状态 | 仅允许四态 | +| channelType | 渠道类型 | 可选 | + +### 3.3 人工核查 + +| 字段 | 说明 | 约束 | +|------|------|------| +| taskNo | 催缴任务号 | 必填 | +| verifyResult | 人工核查结果 | 当前固定映射 `MANUAL_VERIFIED` | +| verifyNote | 核查说明 | 必填 | +| disposalRefNo | 关联处置引用号 | 可选 | +| operator | 核查人 | 必填 | + +## 4. 输出合同 + +### 4.1 任务生成返回 + +| 字段 | 说明 | +|------|------| +| interfaceCode | 固定返回 `IF-REV-013` | +| taskNo | 生成的催缴任务号 | +| eventNo | 业务事件号 | +| status | 初始状态,固定为 `PENDING` | +| taskCount | 本次生成任务数 | +| skippedReasonSummary | 被排除对象摘要 | + +### 4.2 状态查询返回 + +| 字段 | 说明 | +|------|------| +| taskNo | 催缴任务号 | +| eventNo | 业务事件号 | +| status | `PENDING` / `SUCCESS` / `FAIL` / `MANUAL_VERIFIED` | +| channelType | 当前渠道 | +| receiver | 触达对象 | +| sendTime | 发送发起时间 | +| lastCallbackTime | 最近回写时间 | +| failReason | 失败原因 | +| disposalRefs | 关联处置引用 | + +## 5. 业务规则合同 + +1. 催缴对象必须来源于有效欠费账单,不得把已收费、已作废或已进入不允许催缴流程的账单纳入任务。 +2. 同一候选对象在频控窗口内不得重复生成同策略、同渠道的正式任务。 +3. 正式状态只允许四态,不扩展其他临时枚举值。 +4. 历史催缴、停水、预存短信记录按只读查询口径挂接,不表述为新建平行在线主表。 +5. 处置引用只承担追溯职责,不在本接口中展开停复水或工单内部流程。 + +## 6. 失败与阻断语义 + +| 场景 | 阻断要求 | 返回语义 | +|------|----------|----------| +| 候选账单不满足欠费前提 | 阻断生成 | 返回排除原因摘要 | +| 策略编码无效 | 阻断生成 | 返回策略校验失败 | +| 频控规则命中 | 可部分阻断 | 返回被跳过对象与原因 | +| 外部结果未定 | 不强制失败 | 保持 `PENDING` 或经人工核查转 `MANUAL_VERIFIED` | +| 外部明确失败 | 回写失败 | 更新为 `FAIL` 并记录原因 | + +## 7. 可追溯字段最小集 + +- `taskNo` +- `eventNo` +- `strategyCode` +- `channelType` +- `triggerType` +- `status` +- `failReason` +- `receiver` +- `sendTime` +- `disposalRefNo` diff --git a/specs/006-reminder-event-design/data-model.md b/specs/006-reminder-event-design/data-model.md new file mode 100644 index 0000000..0c21348 --- /dev/null +++ b/specs/006-reminder-event-design/data-model.md @@ -0,0 +1,125 @@ +# Data Model: REV-006 催缴与通知事件设计收口 + +## 1. Reminder Candidate + +**说明**: 催缴任务的输入对象,由欠费账单和客户上下文组合形成。 + +| 字段 | 类型 | 说明 | 约束 | +|------|------|------|------| +| candidateId | String | 候选对象标识 | 可由任务生成阶段派生,不要求独立持久化主键 | +| custId | String | 客户标识 | 必填 | +| accountId | String | 账户标识 | 必填 | +| chargeIds | List | 命中的欠费账单集合 | 至少 1 条 | +| billPeriods | List | 账期集合 | 必填 | +| arrearsAmount | Decimal | 欠费总金额 | 必须大于 0 | +| agingBucket | String | 账龄分组 | 必填 | +| custCategory | String | 客户类别 | 必填 | +| preferredChannels | List | 渠道偏好 | 至少 1 个渠道 | +| strategyCode | String | 命中的催缴策略编码 | 必填 | +| frequencyWindow | String | 频控窗口 | 用于重复触达拦截 | + +**关系**: + +- 一个 `Reminder Candidate` 可生成一个或多个 `Reminder Task` +- `Reminder Candidate` 来源于 `biz_charge`、`biz_charge_detail` 等营业账对象 + +## 2. Reminder Strategy + +**说明**: 约束候选对象筛选、任务分组和渠道优先级的规则集合。 + +| 字段 | 类型 | 说明 | 约束 | +|------|------|------|------| +| strategyCode | String | 策略编码 | 唯一 | +| strategyName | String | 策略名称 | 必填 | +| agingRule | String | 账龄规则 | 必填 | +| amountRule | String | 金额规则 | 必填 | +| custCategoryRule | String | 客户类别规则 | 可为空,表示不限 | +| channelPriority | List | 渠道优先级 | 至少 1 项 | +| frequencyControl | String | 频控规则 | 必填 | +| disposalAttentionFlag | Boolean | 是否关注后续处置 | 必填 | + +**状态转换**: + +- 启用 +- 停用 + +## 3. Reminder Task + +**说明**: 正式催缴执行单元,是 `IF-REV-013` 的核心业务对象。 + +| 字段 | 类型 | 说明 | 约束 | +|------|------|------|------| +| taskNo | String | 催缴任务号 | 唯一、必填 | +| eventNo | String | 业务事件号 | 唯一、必填 | +| strategyCode | String | 策略编码 | 必填 | +| channelType | String | 执行渠道 | 必填 | +| triggerType | String | 触发类型 | 自动 / 人工 | +| status | String | 当前状态 | 仅允许 `PENDING` / `SUCCESS` / `FAIL` / `MANUAL_VERIFIED` | +| chargeIds | List | 关联账单 | 至少 1 条 | +| receiver | String | 触达对象 | 可为手机号、微信标识或站内账号 | +| sendTime | Datetime | 发送发起时间 | 可空,待触发后填写 | +| lastCallbackTime | Datetime | 最近结果回写时间 | 可空 | +| failReason | String | 失败原因 | `FAIL` 时建议记录 | +| manualVerifyNote | String | 人工核查说明 | `MANUAL_VERIFIED` 时建议记录 | + +**状态转换**: + +1. 新建任务后进入 `PENDING` +2. 外部触达成功后进入 `SUCCESS` +3. 外部明确失败后进入 `FAIL` +4. 外部结果长期未定或人工补记后进入 `MANUAL_VERIFIED` + +## 4. Reminder Result + +**说明**: 承接 `SYS-010` 回写结果与业务侧最终状态语义。 + +| 字段 | 类型 | 说明 | 约束 | +|------|------|------|------| +| taskNo | String | 对应任务号 | 必填 | +| eventNo | String | 对应事件号 | 必填 | +| status | String | 四态结果 | 必填 | +| channelType | String | 渠道类型 | 必填 | +| externalResultCode | String | 外部结果码 | 可空 | +| externalResultMessage | String | 外部结果说明 | 可空 | +| failReason | String | 业务失败原因 | `FAIL` 时可必填 | +| callbackTime | Datetime | 回写时间 | 必填 | +| sourceSystem | String | 回写来源系统 | 默认 `SYS-010` | + +## 5. Disposal Link + +**说明**: 催缴任务与停水、复水、工单、人工跟进之间的追溯引用。 + +| 字段 | 类型 | 说明 | 约束 | +|------|------|------|------| +| taskNo | String | 关联催缴任务号 | 必填 | +| disposalType | String | 处置类型 | 停水 / 复水 / 工单 / 人工跟进 | +| disposalRefNo | String | 处置引用号 | 必填 | +| disposalStatus | String | 处置状态摘要 | 可空 | +| linkedAt | Datetime | 建联时间 | 必填 | +| note | String | 追溯说明 | 可空 | + +## 6. Governance Record + +**说明**: 用于治理台账登记本轮设计收口结论与后续研发建议。 + +| 字段 | 类型 | 说明 | 约束 | +|------|------|------|------| +| reqCode | String | 需求编号 | 固定为 `SYS002-REQ-011` | +| featureName | String | Speckit feature 名称 | 固定为 `rev006-reminder-event-design` | +| implementationStatus | String | 当前实现判断 | `未见实现` | +| docStatus | String | 文档状态 | 设计已收口 / 待同步 / 待验证 | +| nextAction | String | 后续动作 | 研发立项 / 文档补证 / 治理同步 | +| evidenceRefs | List | 证据来源 | 必填 | + +## 7. 关系总览 + +```text +Reminder Strategy + -> Reminder Candidate + -> Reminder Task +Reminder Task + -> Reminder Result + -> Disposal Link +Governance Record + -> 引用 Reminder Task / Reminder Result 的设计结论与实现判断 +``` diff --git a/specs/006-reminder-event-design/plan.md b/specs/006-reminder-event-design/plan.md new file mode 100644 index 0000000..6e8b796 --- /dev/null +++ b/specs/006-reminder-event-design/plan.md @@ -0,0 +1,150 @@ +# Implementation Plan: REV-006 催缴与通知事件设计收口 + +**Branch**: `006-reminder-event-design` | **Date**: 2026-03-18 | **Spec**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/spec.md) +**Input**: Feature specification from `/specs/006-reminder-event-design/spec.md` + +## Summary + +本次计划聚焦 `REV-006` 的正式文档收口,而非直接编写 backend 业务代码。目标是在既有主文档中补齐催缴对象生成规则、`IF-REV-013` / `IF-EXT-008` 的职责边界、四态结果语义、历史查询与处置追溯口径,并同步治理台账,使后续研发可基于统一口径继续立项。 + +目标文档包括: + +- `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` + +## Technical Context + +**Primary Work Product**: Markdown 正式设计文档、治理台账与 Speckit 规划工件 +**Source of Truth 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/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` + +**Validation Commands**: + +- `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` +- `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` +- `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` +- `make check-links` +- `make validate-mermaid` + +**Target Scope**: + +- 收口 `REV-006` 详细设计章节 +- 收口 `IF-REV-013` 与 `IF-EXT-008` 承接口径 +- 回写 `SYS002-REQ-011` 的状态判断、后续研发切入点与治理结论 +- 规划 `01_Project_Progress.md` 与 `03_Task_Checklist.md` 的同步更新动作 + +**Project Type**: 文档治理仓库 +**Constraints**: + +- 不新增平行正式稿,只回写既有主文档或治理文档 +- 不臆造 backend 已实现能力 +- Archive 仅作为来源核对,不直接替代正式口径 +- 编号、术语、相对路径、Mermaid 图与正文必须一致 +- 正式系统名称统一为“福建水务营收系统” + +**Scale/Scope**: 跨文档设计收口与治理同步,覆盖详设、接口、管理台账三类文档 + +## Constitution Check + +*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* + +- [x] **主文档归属已确认**:本次改动只落在 `12_REV_Detailed.md`、`03_Interface_Design.md`、`15_SYS002_Requirement_Breakdown.md` 及管理台账,不新增平行正式稿。 +- [x] **范围基线已确认**:`REV-006` 已同时出现在 `03_Summary_Design.md`、`12_REV_Detailed.md` 与 Archive 范围内,属于可直接推进的交集范围。 +- [x] **Archive 使用方式合规**:Archive 仅作为旧系统催缴记录、停水记录、预存短信场景的来源核对,不直接作为正式文档替身。 +- [x] **一致性影响已列出**:受影响项包括 `REV-006` 模块编号、`IF-REV-013` / `IF-EXT-008` 编号边界、四态状态集、催缴/停复水术语、历史查询口径与 Mermaid 流程图。 +- [x] **校验与台账动作已规划**:已明确单文件校验、全仓链接校验、Mermaid 校验,并规划同步更新 `01_Project_Progress.md` 与 `03_Task_Checklist.md`。 + +## Project Structure + +### Documentation (this feature) + +```text +specs/006-reminder-event-design/ +├── plan.md +├── research.md +├── data-model.md +├── quickstart.md +├── contracts/ +│ ├── if-rev-013.md +│ └── if-ext-008.md +└── tasks.md +``` + +### Repository Touchpoints + +```text +docs/design/ +├── 00_Management/01_Project_Progress.md +├── 00_Management/03_Task_Checklist.md +├── 00_Management/15_SYS002_Requirement_Breakdown.md +├── 01_Overview/03_Summary_Design.md +├── 02_Detailed_Design/12_REV_Detailed.md +├── 03_Technical_Design/03_Interface_Design.md +└── 04_Appendix/Archive/ +``` + +**Structure Decision**: + +- `12_REV_Detailed.md`:承载 `REV-006` 的业务流程、规则、核心数据与落地边界 +- `03_Interface_Design.md`:承载 `IF-REV-013` / `IF-EXT-008` 的业务接口定义与边界说明 +- `15_SYS002_Requirement_Breakdown.md`:承载 `SYS002-REQ-011` 的实现判断、建议粒度与推进说明 +- `01_Project_Progress.md`:登记本轮正式文档收口动作与验证结果 +- `03_Task_Checklist.md`:登记 `REV-006` 相关治理任务的完成状态 + +## Phase 0: Outline & Research + +### Research Inputs + +- 既有 `REV-006` 章节是否已足够承载催缴对象生成、四态结果和联动边界 +- `IF-REV-013` / `IF-EXT-008` 的职责拆分是否与 `SYS-002` / `SYS-010` 边界一致 +- 当前 backend 未见实现骨架的结论,如何在正式文档与治理台账中保守表达 + +### Phase 0 Deliverable + +- [/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/research.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/research.md) + +### Research Conclusion + +- 无额外 `NEEDS CLARIFICATION` 留存。 +- 计划阶段可直接以“文档先行、实现待立项”为结论进入设计与合同化表达。 + +## Phase 1: Design & Contracts + +### Planned Artifacts + +- [/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/data-model.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/data-model.md) +- [/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/contracts/if-rev-013.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/contracts/if-rev-013.md) +- [/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/contracts/if-ext-008.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/contracts/if-ext-008.md) +- [/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md) + +### Design Decisions + +- 以“催缴候选对象 -> 催缴任务 -> 消息协同 -> 四态回写 -> 处置追溯”的业务链路组织文档,而非按旧系统页面零散堆砌。 +- 历史催缴、停水、预存短信统一按“历史只读查询口径”承接,不额外承诺独立在线主表。 +- 合同化产物只描述接口业务语义、字段边界和责任划分,不写成 backend API 已实现证明。 + +## Post-Design Constitution Check + +- [x] **主文档归属保持不变**:Phase 1 产物用于规划与任务拆解,正式结论仍回流既有主文档。 +- [x] **范围未外溢**:设计仍限定在 `REV-006` 催缴与通知收口,不扩展到停复水审批或独立消息中心建设。 +- [x] **Archive 仍为引用源**:未把 Archive 内容直接升级为独立正式稿。 +- [x] **一致性风险已收敛**:四态状态集、接口编号、协同边界和历史查询术语已统一。 +- [x] **校验闭环已具备**:已有明确验证命令、管理台账更新点和后续 tasks 拆解基础。 + +## Complexity Tracking + +本次计划无宪章违例项,无需额外豁免。 diff --git a/specs/006-reminder-event-design/quickstart.md b/specs/006-reminder-event-design/quickstart.md new file mode 100644 index 0000000..e02eeb1 --- /dev/null +++ b/specs/006-reminder-event-design/quickstart.md @@ -0,0 +1,69 @@ +# Quickstart: REV-006 催缴与通知事件设计收口 + +## 1. 使用目标 + +本 quickstart 用于指导评审者或文档维护者快速完成 `REV-006` 的正式文档收口验证,不用于验证 backend 运行功能。 + +## 2. 建议执行顺序 + +1. 打开 [spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/spec.md),确认范围、四态状态和治理结论。 +2. 对照 [plan.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/plan.md),确认本轮只修改既有主文档与管理台账。 +3. 对照 [data-model.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/data-model.md),检查催缴候选对象、任务、结果和处置引用的最小字段是否齐全。 +4. 对照 `contracts/if-rev-013.md` 与 `contracts/if-ext-008.md`,确认 `SYS-002` / `SYS-010` 分工、输入输出和失败语义一致。 + +## 3. 正式文档修订检查点 + +- `12_REV_Detailed.md` + - 是否写清催缴对象来源、策略分组、频控和四态状态 + - 是否明确停复水/工单只作为联动边界和追溯引用 +- `03_Interface_Design.md` + - 是否统一 `IF-REV-013` 为正式业务接口编号 + - 是否区分 `IF-REV-013` 与 `IF-EXT-008` 的责任边界 +- `15_SYS002_Requirement_Breakdown.md` + - 是否保持 `SYS002-REQ-011` 为“未见实现” + - 是否明确“文档已收口,backend 未见明确实现骨架” +- `01_Project_Progress.md` / `03_Task_Checklist.md` + - 是否登记本轮文档收口与验证动作 + +## 4. 最小验证命令 + +```bash +make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md +make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md +make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md +make check-links +make validate-mermaid +``` + +## 5. 完成判定 + +满足以下条件即可进入 `/speckit.tasks`: + +- `REV-006` 的业务规则、接口边界、历史查询和处置追溯口径已统一 +- `SYS002-REQ-011` 的实现判断与后续研发切入点已写入治理台账 +- 验证命令已纳入计划,且无新增平行正式稿 + +## 6. 2026-03-19 实施结果 + +### 已完成文档 + +- `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` + +### 验证结果 + +- `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md`:通过,0 个问题 +- `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md`:通过,0 个问题 +- `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`:通过,0 个问题 +- `make check-links`:通过,当前检查范围内未发现断链 +- `make check-mermaid-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md`:已确认目标文件存在 6 个 Mermaid 图表 +- `make validate-mermaid`:已执行两次,但在当前环境下未返回最终结果;结合 Makefile 逻辑,该目标只校验仓库根目录 `*.md`,未直接覆盖本轮主要修改文件,后续如需全仓 Mermaid 终态结果,应单独排查该目标在当前环境中的阻塞原因 + +### 当前结论 + +- `REV-006` 已完成 implement 阶段的正式文档二次收口 +- `SYS002-REQ-011` 继续维持“未见实现”,但 Speckit 工件链、正式文档口径与治理台账已对齐 +- 当前剩余风险不是文档口径缺失,而是后续 backend 立项与 `make validate-mermaid` 全仓目标在本环境中的执行阻塞 diff --git a/specs/006-reminder-event-design/research.md b/specs/006-reminder-event-design/research.md new file mode 100644 index 0000000..80c15df --- /dev/null +++ b/specs/006-reminder-event-design/research.md @@ -0,0 +1,46 @@ +# Phase 0 Research: REV-006 催缴与通知事件设计收口 + +## Decision 1: 以既有主文档承载 `REV-006` 收口 + +**Decision**: 正式设计收口继续落在 `12_REV_Detailed.md`、`03_Interface_Design.md` 与 `15_SYS002_Requirement_Breakdown.md`,不新建平行正式稿。 +**Rationale**: `REV-006` 已在概要、详设、接口与治理台账中具备入口,当前问题是规则与边界不够收敛,而不是缺少载体。继续使用主文档符合单一真源原则。 +**Alternatives considered**: + +- 新建独立“催缴设计说明书”:会制造平行正式稿,违背宪章。 +- 仅在 spec 工件中描述:无法替代正式交付文档与治理台账。 + +## Decision 2: `SYS-002` 与 `SYS-010` 按“业务侧任务控制 / 渠道侧触达执行”分界 + +**Decision**: `SYS-002` 负责催缴对象筛选、任务生成、事件编号、四态状态承接、历史查询与处置引用;`SYS-010` 负责短信、微信、站内信等渠道触达及结果回传。 +**Rationale**: 该分界已在 `12_REV_Detailed.md` 与 `03_Interface_Design.md` 形成一致表达,能够避免“催缴任务生成”和“消息发送执行”职责混写。 +**Alternatives considered**: + +- 由 `SYS-010` 同时负责催缴任务控制:会让外部系统承担业务主控,不符合现有模块分工。 +- 由 `SYS-002` 同时负责所有消息发送:会弱化 `IF-EXT-008` 的外部协同边界。 + +## Decision 3: 正式状态集固定为四态 + +**Decision**: `REV-006` 状态集固定为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED`。 +**Rationale**: 四态已在详设与接口文档中同步表达,且足以覆盖受理中、成功、失败、人工补记三类核心语义。增加更多细粒度状态会放大实现假设。 +**Alternatives considered**: + +- 增加“已阅读”“已补发”等状态:超出当前正式口径,也缺少 backend 证据支持。 +- 仅保留成功/失败二态:不足以表达异步回写与人工核查场景。 + +## Decision 4: 历史催缴、停水、预存短信按只读查询口径承接 + +**Decision**: 旧系统催缴记录、停水记录、预存短信记录统一作为历史查询和追溯范围承接,不默认扩展为新系统已确认在线主表。 +**Rationale**: 当前 backend 未确认独立催缴台账、停水汇总表等实体;保守表达可同时满足迁移查询需求和事实一致性。 +**Alternatives considered**: + +- 直接定义新在线主表:缺少代码和数据库证据。 +- 完全忽略历史场景:会让迁移核查、客户历史查询和处置追溯失去正式口径。 + +## Decision 5: 当前实施结论维持“文档已收口,backend 未见明确实现骨架” + +**Decision**: 计划阶段保留 `SYS002-REQ-011` 为“未见实现”,并把本轮产出定位为文档收口和后续研发立项输入。 +**Rationale**: 现有治理文档已经给出相同结论,且当前未检索到明确的 `Reminder/Message/Notice` controller/service 骨架。 +**Alternatives considered**: + +- 升级为“部分实现”:会放大现有消息协同或历史查询描述,和证据不匹配。 +- 直接按“已实现”处理:与仓库现状冲突。 diff --git a/specs/006-reminder-event-design/spec.md b/specs/006-reminder-event-design/spec.md new file mode 100644 index 0000000..90bb0f7 --- /dev/null +++ b/specs/006-reminder-event-design/spec.md @@ -0,0 +1,126 @@ +# 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 项文档校验或一致性检查。 diff --git a/specs/006-reminder-event-design/tasks.md b/specs/006-reminder-event-design/tasks.md new file mode 100644 index 0000000..cbf7a74 --- /dev/null +++ b/specs/006-reminder-event-design/tasks.md @@ -0,0 +1,164 @@ +# Tasks: REV-006 催缴与通知事件设计收口 + +**Input**: Design documents from `/specs/006-reminder-event-design/` +**Prerequisites**: `plan.md` (required), `spec.md` (required), `research.md`, `data-model.md`, `contracts/`, `quickstart.md` + +**Validation**: Validation tasks are NOT optional in this repository. Every document change task set includes applicable validation and ledger-sync tasks. + +**Organization**: Tasks are grouped by user story so each document-maintenance slice can be completed, reviewed, and validated independently. + +## Format: `[ID] [P?] [Story] Description` + +- **[P]**: Can run in parallel (different files, no dependencies) +- **[Story]**: Which user story this task belongs to (`US1`, `US2`, `US3`) +- Every task names the exact file path to update or validate + +## Phase 1: Setup + +**Purpose**: Confirm the working boundary, source-of-truth set, and impacted files before editing formal documents. + +- [x] T001 Confirm target files and impacted chapters in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/spec.md` +- [x] T002 Confirm source-of-truth and allowed references in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/plan.md` and `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/research.md` +- [x] T003 [P] Confirm entity and contract inputs in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/data-model.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/contracts/if-rev-013.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/contracts/if-ext-008.md` +- [x] T004 [P] Confirm governance sync targets in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` + +--- + +## Phase 2: Foundational + +**Purpose**: Establish the shared editing baseline that all user stories depend on. + +- [x] T005 Normalize `REV-006`, `IF-REV-013`, `IF-EXT-008`, and four-state terminology alignment notes in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/plan.md` +- [x] T006 Identify exact `REV-006` anchors, Mermaid scope, and cross-reference touchpoints in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md` +- [x] T007 Map governance evidence and current implementation conclusion for `SYS002-REQ-011` in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` + +--- + +## Phase 3: User Story 1 - 收口催缴任务生成规则 (Priority: P1) 🎯 MVP + +**Goal**: 补齐 `REV-006` 在详细设计中的催缴对象生成、策略分组、频控边界、四态状态和历史只读承接口径。 + +**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` 的 `REV-006` 章节,应能明确催缴对象来源、排除条件、四态状态、人工核查边界和停复水联动追溯关系。 + +### Implementation for User Story 1 + +- [x] T008 [US1] Update `REV-006` rules, candidate selection, frequency-control, and exclusion conditions in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` +- [x] T009 [US1] Sync `Reminder Candidate`, `Reminder Task`, `Reminder Result`, and `Disposal Link` field coverage in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` using `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/data-model.md` +- [x] T010 [US1] Align historical reminder, stop-water, and prestored-message read-only boundary wording in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` +- [x] T011 [US1] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and record the result in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md` +- [x] T012 [US1] Run `make validate-mermaid` for `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` flow updates and record the result in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md` + +**Checkpoint**: User Story 1 is reviewable and validated independently. + +--- + +## Phase 4: User Story 2 - 统一 IF-REV-013 与消息协同边界 (Priority: P2) + +**Goal**: 在接口主文档中统一 `IF-REV-013` 与 `IF-EXT-008` 的职责分工、输入输出、四态回写和失败阻断语义。 + +**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`,应能区分 `SYS-002` 的业务任务控制职责与 `SYS-010` 的渠道触达职责,并定位最小回写字段。 + +### Implementation for User Story 2 + +- [x] T013 [US2] Update `IF-REV-013` business boundary, request paths, and state semantics in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md` +- [x] T014 [US2] Update `IF-EXT-008` collaboration boundary, acceptance/callback semantics, and failure mapping in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md` +- [x] T015 [US2] [P] Sync minimum traceability fields and manual-verify/write-back semantics in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md` using `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/contracts/if-rev-013.md` +- [x] T016 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` and record the result in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md` +- [x] T017 [US2] Run `make check-links` after interface document updates and record the result in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md` + +**Checkpoint**: User Story 2 is reviewable and validated independently. + +--- + +## Phase 5: User Story 3 - 形成治理与研发切入结论 (Priority: P3) + +**Goal**: 在需求拆解和管理台账中沉淀 `REV-006` 的当前状态、最小研发切入点、文档收口动作和验证结论。 + +**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`、`/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md`、`/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md`,应能定位 `SYS002-REQ-011` 的“未见实现”判断、本轮文档收口和后续研发建议。 + +### Implementation for User Story 3 + +- [x] T018 [US3] Update `SYS002-REQ-011` implementation judgment, evidence wording, and next-step recommendation in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` +- [x] T019 [US3] Update the REV-006 change record and validation summary in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md` +- [x] T020 [US3] Update the REV-006 governance completion items in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md` +- [x] T021 [US3] Run `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` and record the result in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md` +- [x] T022 [US3] Re-check that `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md` and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md` reflect the same REV-006 closure status + +**Checkpoint**: User Story 3 is reviewable and validated independently. + +--- + +## Final Phase: Polish & Cross-Cutting Concerns + +**Purpose**: Ensure repository-wide consistency after all story slices are complete. + +- [x] T023 [P] Re-check `REV-006`, `IF-REV-013`, `IF-EXT-008`, and four-state terminology consistency across `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` +- [x] T024 [P] Re-check relative links, anchors, and Mermaid consistency across `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md` +- [x] T025 Prepare final delivery summary and remaining-risk note in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md` + +--- + +## Dependencies & Execution Order + +### Phase Dependencies + +- **Setup**: No dependencies; must finish before document edits +- **Foundational**: Depends on Setup and must finish before user story execution +- **US1**: Depends on Foundational and is the MVP slice +- **US2**: Depends on US1 terminology and boundary baseline +- **US3**: Depends on US1 and US2 conclusions so governance wording can reflect final design state +- **Final Phase**: Depends on all selected user stories being complete + +### User Story Dependency Graph + +```text +US1 -> US2 -> US3 + \______________-> Final Phase +``` + +### Within Each User Story + +- Update target document content before running validation +- Complete validation before marking governance sync as done +- Complete ledger sync before final cross-check + +## Parallel Execution Examples + +### US1 + +```text +T008 -> T009 +T010 can run after T008 in parallel with T009 +``` + +### US2 + +```text +T013 -> T014 +T015 can run in parallel once T013 and T014 establish the final interface wording +``` + +### US3 + +```text +T019 and T020 can run in parallel after T018 +``` + +## Implementation Strategy + +### MVP First + +先完成 US1,只收口 `12_REV_Detailed.md` 的 `REV-006` 规则与状态语义,形成最小可评审增量。 + +### Incremental Delivery + +1. 用 US1 固化催缴对象、四态状态和历史只读边界。 +2. 用 US2 固化 `IF-REV-013` / `IF-EXT-008` 的接口职责与回写语义。 +3. 用 US3 回写治理台账和后续研发切入点。 +4. 最后统一做跨文档一致性复核和交付摘要。 + +## Notes + +- 所有任务均保持“主文档单一真源”原则,不新增平行正式稿。 +- Archive 只用于核对来源,不作为正式结论直接输出。 +- 本任务清单面向文档实施,不默认包含 backend 代码开发任务。