diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..229a42c --- /dev/null +++ b/.dockerignore @@ -0,0 +1,11 @@ +node_modules/ +.git/ +.dockerignore +Dockerfile* +dist/ +build/ +coverage/ +*.log* +.env* +.DS_Store +Thumbs.db diff --git a/.gitignore b/.gitignore index 2e262b8..1f74b29 100644 --- a/.gitignore +++ b/.gitignore @@ -36,4 +36,9 @@ pdf_output/福建水务业务系统设计方案.pdf pdf_output/福建水务业务系统数据库设计.pdf pdf_output.tar.gz node_modules +dist/ +build/ +*.log +.env* temp_mermaid_* +.codex diff --git a/docs/design/00_Management/01_Project_Progress.md b/docs/design/00_Management/01_Project_Progress.md index 7b7eed1..dfade5e 100644 --- a/docs/design/00_Management/01_Project_Progress.md +++ b/docs/design/00_Management/01_Project_Progress.md @@ -322,3 +322,9 @@ - 新增 `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`,完成 `SYS-002` 需求总览、Story/feature 映射、代码实现评估与 TAPD 转换建议整理。 - 形成 `SYS002-REQ-001 ~ 015` 的统一拆解口径,可直接用于 Speckit 立项、TAPD Story/Task 建模与后续文档/实现对齐跟踪。 + +### 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` 正式业务接口编号确定为 `IF-REV-013`,不再复用 `IF-REV-009`;催缴结果状态统一为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态。 +- 明确旧“催缴记录 / 停水记录 / 预存短信记录”按历史只读口径承接,不新增同名在线主表;停复水在本轮仅保留联动边界、处置引用和追溯关系。 diff --git a/docs/design/00_Management/03_Task_Checklist.md b/docs/design/00_Management/03_Task_Checklist.md index 0de4e12..ea9d95d 100644 --- a/docs/design/00_Management/03_Task_Checklist.md +++ b/docs/design/00_Management/03_Task_Checklist.md @@ -518,6 +518,14 @@ ### 📋 4 周计划一次性执行完成 - [x] **第 1 周:检索入口标准化** ✅ (2026-03-11) + +### 📋 REV-006 催缴事件与通知协同设计 + +- [x] **完成 REV-006 正式文档口径收口与台账同步** ✅ (2026-03-18) + - [x] 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md`,明确催缴对象、策略摘要、`IF-REV-013`、四态状态集与停复水联动边界 ✅ + - [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] 补齐一级目录 `README.md` 索引(7/7) ✅ - [x] 新增 AI 检索优先白名单:`docs/design/00_Management/10_AI_Retrieval_Whitelist.md` ✅ - [x] **第 2 周:主文档元数据统一** ✅ (2026-03-11) diff --git a/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md b/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md index 997df1e..28d2bea 100644 --- a/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md +++ b/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md @@ -33,7 +33,7 @@ | SYS002-REQ-008 | REV-005 | 发票申请受理 | 对已收费未开票账单发起单笔/批量开票申请 | SYS-008 | IF-REV-008 / IF-EXT-006 | biz_invoice、biz_invoice_taxrate、biz_cust_invoice | Story | | SYS002-REQ-009 | REV-005 | 发票结果查询与补偿 | 按申请单号/受理号查询开票结果并补偿 | SYS-008 | IF-REV-009 | biz_invoice、biz_operat_log | Story | | SYS002-REQ-010 | REV-005 | 发票结果回写 | 回写开票状态、票号、下载地址、作废/红冲结果 | SYS-008 | IF-EXT-007 | biz_invoice、biz_process_invoice_modifys | Story | -| SYS002-REQ-011 | REV-006 | 催缴与通知协同 | 生成催缴对象、触发通知事件、回写通知结果 | SYS-010 | IF-EXT-008 | biz_charge、biz_process、biz_operat_log | Story | +| SYS002-REQ-011 | REV-006 | 催缴与通知协同 | 生成催缴对象、触发通知事件、回写通知结果 | SYS-010 | IF-REV-013 / IF-EXT-008 | biz_charge、biz_process、biz_operat_log | Story | | SYS002-REQ-012 | REV-007 | 营收统计查询 | 查询营收、收费、欠费、渠道、客户统计 | 统计分析端 | IF-REV-010 | 聚合视图 / 统计结果集 | Story | | SYS002-REQ-013 | REV-008 | 银行代扣与回盘 | 下发代扣批次、接收回盘并回写状态 | SYS-009 / 银行 | IF-REV-011 / IF-EXT-001 / IF-EXT-002 | biz_withholding、bk_withholding_batch、bk_withholding_item | Story | | SYS002-REQ-014 | REV-008 | 对账与结算处理 | 处理对账、差异追踪、结算协同 | SYS-009 / 银行 | IF-REV-011 | bk_reconcile_batch、bk_settlement_batch | Story | @@ -79,7 +79,7 @@ | SYS002-REQ-008 | 发票申请受理 | 已实现 | `controller/admin/invoice/InvoiceController.java`、`service/invoice/InvoiceServiceImpl.java`、`dal/dataobject/invoice/InvoiceDO.java`、`dal/mysql/invoice/InvoiceMapper.java` | 已有后台申请、幂等键、申请单号、受理号与落库逻辑。 | | SYS002-REQ-009 | 发票结果查询与补偿 | 已实现 | `InvoiceServiceImpl.java` 中 `applicationNo`、`sysRequestNo`、`lastTryTime`、`nextTryTime`、`tryCount`、`latestResult`、`latestError` 等字段与补偿逻辑 | 与文档中“查询补偿、回写优先、主动查询兜底”口径高度一致。 | | SYS002-REQ-010 | 发票结果回写 | 已实现 | `controller/admin/invoice/vo/InvoiceWriteBackReqVO.java`、`InvoiceServiceImpl.java`、`InvoiceMapper.java` | 已见回写入参与主键查询、回写及状态保护相关实现痕迹。 | -| SYS002-REQ-011 | 催缴与通知协同 | 未见实现 | 当前在 `backend/sw-business` 中未检索到明确的 `Reminder/Message/Notice` 业务控制器 | 当前更接近文档口径,未见明确催缴/通知业务实现骨架。 | +| SYS002-REQ-011 | 催缴与通知协同 | 未见实现 | 当前在 `backend/sw-business` 中未检索到明确的 `Reminder/Message/Notice` 业务控制器 | 本轮已完成 `IF-REV-013`、四态状态集、历史只读边界和停复水联动边界的正式文档收口,但 backend 仍未见明确催缴/通知业务实现骨架。 | | SYS002-REQ-012 | 营收统计查询 | 未见实现 | 当前在 `backend/sw-business` 中未检索到明确的 `Statistic/Report/Analysis` 控制器 | 文档已有统计口径,但代码层未见明显统计查询实现入口。 | | SYS002-REQ-013 | 银行代扣与回盘 | 已实现 | `backend/sw-business-bank/.../withholdingbatch/WithholdingBatchController.java`、`withholdingitem/WithholdingItemController.java`、`withholdingagreement/WithholdingAgreementController.java`、`app/bankwithholding/BankWithholdingController.java` | 代扣批次、明细、协议、应用侧代扣入口均已存在。 | | SYS002-REQ-014 | 对账与结算处理 | 已实现 | `backend/sw-business-bank/.../reconcilebatch/ReconcileBatchController.java`、`reconcilediff/ReconcileDiffController.java`、`settlementbatch/SettlementBatchController.java`、`ReconcileStatusEnum.java`、`SettlementBatchDO.java` | 对账批次、差异、结算批次与状态枚举均已具备。 | @@ -101,7 +101,7 @@ | SYS-002:补齐发票申请设计闭环 | SYS002-REQ-008 | `sys002-invoice-apply-design` | 已实现 | 高 | 已进入完成态,适合转为验收/归档类 Story。 | | SYS-002:补齐发票结果查询与补偿规则 | SYS002-REQ-009 | `sys002-invoice-result-query-rules` | 已实现 | 高 | 已进入完成态,适合转为验收/归档类 Story。 | | SYS-002:统一发票结果回写口径 | SYS002-REQ-010 | `sys002-invoice-writeback-sync` | 已实现 | 高 | 已进入完成态,适合转为验收/归档类 Story。 | -| SYS-002:补齐催缴事件与通知协同设计 | SYS002-REQ-011 | `sys002-reminder-event-design` | 未见实现 | 高 | 建议优先作为后续设计/实现立项。 | +| SYS-002:补齐催缴事件与通知协同设计 | SYS002-REQ-011 | `sys002-reminder-event-design` | 未见实现 | 高 | 设计口径已完成第一轮收口,可继续按 `IF-REV-013` 和四态状态集推进后续实现立项。 | | SYS-002:补齐营收统计查询设计 | SYS002-REQ-012 | `sys002-revenue-statistics-design` | 未见实现 | 中 | 建议先确认范围,再决定是否立项。 | | SYS-002:统一银行代扣与回盘协同口径 | SYS002-REQ-013 | `sys002-bank-withholding-sync` | 已实现 | 中 | 已有银行子系统实现,建议做跨文档口径收口。 | | SYS-002:补齐对账与结算处理规则 | SYS002-REQ-014 | `sys002-reconcile-settlement-rules` | 已实现 | 中 | 重点收口对账差异分类与结算边界。 | @@ -119,6 +119,52 @@ | 校核代码实现状态 | 检查 Controller/Service/DO/VO/Mapper 是否已形成完整闭环 | | 输出验收结论 | 形成“已实现 / 部分实现 / 未见实现”与后续动作建议 | +## Spec-Kit 立项建议 + +### REV-001 ~ REV-009 三色清单 + +| 模块 | 当前判断 | 建议 | +|---|---|---| +| `REV-001` 客户资料管理 | 已实现 | 以文档收口、验收归档为主,不建议单独发起大范围 Speckit feature | +| `REV-002` 抄表开账 | 部分实现 | 建议围绕“开账计费与账单生成缺口”拆小 feature | +| `REV-003` 营业收费 | 部分实现 | 建议围绕“柜台班结”“红冲历史查询”等缺口拆小 feature | +| `REV-004` 账务处理 | 已实现 | 以规则收口、二期扩展或历史台账映射为主 | +| `REV-005` 发票与税务处理 | 已实现 | 以验收归档和细粒度对象补证为主 | +| `REV-006` 催缴与通知 | 未见实现 | 已完成 Speckit `specify -> clarify -> plan -> tasks`,当前进入 `implement` 阶段的正式文档收口与台账同步。 | +| `REV-007` 统计分析 | 未见实现 | 建议完整走 Speckit:`specify -> clarify -> plan -> tasks` | +| `REV-008` 代收与银行业务 | 已实现 | 以跨系统口径收口和扩展台账补证为主 | +| `REV-009` 业务参数配置 | 已实现 | 以参数边界收口和治理能力补充为主 | + +### Speckit 使用原则 + +1. 红色项(未见实现)优先完整走 Speckit,全流程沉淀范围、边界、成功标准与任务拆解。 +2. 黄色项(部分实现)不要按整个模块立项,应只围绕一个明确缺口建立小范围 feature。 +3. 绿色项(已实现)默认不再新开大 feature,仅在发现明确 gap 时才补充小型 feature。 +4. Feature 粒度以“一个可交付能力闭环”为准,避免把整个 `REV-*` 模块打包成单个 feature。 + +### 推荐 Speckit Feature 清单 + +| 模块 | 是否建议走 Speckit | 推荐 feature 名 | 建议优先级 | 说明 | +|---|---|---|---|---| +| `REV-001` | 否 | `rev001-master-data-alignment` | 低 | 仅在发现主数据口径缺口时使用 | +| `REV-002` | 是 | `rev002-billing-generation-gap` | 高 | 聚焦 `IF-REV-005`、开账生成与结果表达缺口 | +| `REV-003` | 是 | `rev003-counter-shift-close` | 高 | 聚焦柜台班结闭环 | +| `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-notice-result-writeback` | 高 | 可作为 `REV-006` 拆分子 feature | +| `REV-007` | 是 | `rev007-revenue-statistics-design` | 高 | 建议先补经营统计主查询能力 | +| `REV-007` | 是 | `rev007-channel-analysis-query` | 中 | 适合作为统计分析子 feature | +| `REV-008` | 否 | `rev008-reconcile-closure` | 中 | 仅在对账闭环出现明确 gap 时使用 | +| `REV-009` | 否 | `rev009-parameter-governance` | 低 | 仅在参数治理能力需补齐时使用 | + +### 推荐推进顺序 + +1. 先启动红色项:`REV-006`、`REV-007`。 +2. 再处理黄色项中最关键的缺口:`REV-002` 的开账生成、`REV-003` 的柜台班结。 +3. 绿色项默认走文档/实现对齐与验收归档,不单独进入完整 Speckit 生命周期。 + ## 当前建议优先推进项 ### P0 @@ -193,14 +239,14 @@ - Story 描述: - 目标:补齐欠费催缴对象生成、通知触发、通知结果回写与催缴追踪闭环。 - 事实来源:`12_REV_Detailed.md` 中 REV-006、`03_Interface_Design.md` 中 `IF-EXT-008`。 - - 当前判断:当前代码检索范围内未见明确的催缴、通知、消息协同控制器或服务骨架。 - - 验收要点:明确催缴触发时机、催缴对象筛选条件、通知方式、回写字段与失败重试机制。 + - 当前判断:当前代码检索范围内未见明确的催缴、通知、消息协同控制器或服务骨架;但本轮已在正式文档中新增 `IF-REV-013`,并统一四态状态集、历史只读查询口径和停复水联动边界。 + - 验收要点:明确催缴触发时机、催缴对象筛选条件、通知方式、回写字段、四态状态语义与失败重试机制。 - 推荐 Task: - `T-011-01` 对齐催缴业务场景、触发条件与对象筛选规则 - - `T-011-02` 对齐通知协同接口与通知结果回写字段 - - `T-011-03` 对齐催缴过程表、操作日志与状态流转规则 + - `T-011-02` 对齐 `IF-REV-013` / `IF-EXT-008` 协同接口与通知结果回写字段 + - `T-011-03` 对齐催缴过程、操作日志、四态状态流转与历史查询规则 - `T-011-04` 校核当前代码中是否存在可复用的消息/通知基础能力 - - `T-011-05` 输出是否需独立立项开发的结论 + - `T-011-05` 输出是否需独立立项开发及最小实现切入点的结论 ### P1:第二优先级 diff --git a/docs/design/02_Detailed_Design/12_REV_Detailed.md b/docs/design/02_Detailed_Design/12_REV_Detailed.md index 2ca6c07..3985073 100644 --- a/docs/design/02_Detailed_Design/12_REV_Detailed.md +++ b/docs/design/02_Detailed_Design/12_REV_Detailed.md @@ -59,7 +59,7 @@ retrieval_priority: P1 | REV-003 营业收费 | `IF-REV-006` | `biz_charge*`、`biz_collection`、`bk_transaction*` | `SYS-009` | | REV-004 账务处理 | `IF-REV-007` | `biz_charge*`、`biz_operat_log*` | 财务与营业人员 | | REV-005 发票与税务处理 | `IF-REV-008` | `biz_invoice*`、`biz_cust_invoice` | `SYS-008` | -| REV-006 催缴与通知 | `IF-REV-009` | `biz_charge*`、催缴结果留痕 | `SYS-010` | +| REV-006 催缴与通知 | `IF-REV-013` | `biz_charge*`、催缴结果留痕 | `SYS-010` | | REV-007 统计分析 | `IF-REV-010` | 客户、抄表、收费、渠道聚合对象 | 统计分析端 | | REV-008 代收与银行业务 | `IF-REV-011` | `bk_withholding_*`、`bk_reconcile_*`、`bk_settlement_*` | `SYS-009`、银行 | | REV-009 业务参数配置 | `IF-REV-012` | `biz_parameter_settings`、`biz_page_settings*`、`biz_price_*` | 统一平台、营收模块 | @@ -456,58 +456,71 @@ flowchart TD ### 功能说明 -针对欠费账单按账龄、金额、客户类别等规则生成催缴任务,通过短信、微信、站内通知等方式触达客户,并回写催缴结果。 +针对欠费账单按账龄、金额、客户类别等规则生成催缴任务,通过短信、微信、站内通知等方式触达客户,并回写催缴结果;本模块同时定义催缴与停复水/工单处置之间的联动边界与追溯关系,但不展开停复水内部处置流程。 ### 业务流程 ```mermaid flowchart TD A[生成欠费客户清单] --> B[按策略分组催缴任务] - B --> C[触发催缴接口] - C --> D[调用SYS-010消息服务] + B --> C[触发IF-REV-013生成催缴任务] + C --> D[调用IF-EXT-008协同SYS-010] D --> E[接收发送结果回写] E --> F[更新催缴状态与后续策略] + F --> G[按联动边界挂接停复水/工单处置] ``` ### 关键规则 -1. 催缴策略以营业账状态、欠费金额、账龄分布和客户类别为基础。 -2. 自动催缴与人工催缴可并行,支持停复水等后续处置联动。 -3. 触达能力由 `SYS-010` 提供,SYS-002 负责生成待发送业务事件、催缴名单与结果回写。 -4. 当前后端中部分催缴汇总、停水明细对象未确认独立落表,文档中保持保守描述。 +1. 催缴策略以营业账状态、欠费金额、账龄分布、客户类别和渠道偏好为基础,支持按策略编码进行任务分组与频控。 +2. 自动催缴与人工催缴可并行;自动任务用于常规批量催缴,人工任务用于补发、核查或例外处置。 +3. `SYS-002` 负责催缴对象筛选、任务生成、业务事件编号、结果承接与历史查询;`SYS-010` 负责短信、微信公众号、站内信等触达执行与结果回传。 +4. `REV-006` 正式结果状态固定为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态,其中 `MANUAL_VERIFIED` 仅用于外部结果未定或需人工核查补记的场景。 +5. 停复水在本模块中仅定义联动触发条件、处置引用与追溯关系,不展开停复水内部审批、派工或现场执行流程。 +6. 当前后端中部分催缴汇总、停水明细对象未确认独立落表,文档中保持保守描述,不误写为已确认在线主表。 ### 核心数据 - `biz_charge`、`biz_charge_detail`:催缴对象来源。 - 催缴结果与通知日志:通过业务状态与消息结果联动留痕。 +#### 催缴对象与规则摘要 + +- `Reminder Candidate`:由欠费账单、客户类别、账龄分组、欠费金额、联系方式集合和命中策略编码组成,是催缴任务的输入对象。 +- `Reminder Strategy`:定义账龄规则、金额规则、客户类别规则、渠道优先级、重复触达拦截窗口和是否触发后续处置关注。 +- `Reminder Task`:一次正式催缴执行单元,至少包含 `taskNo`、`eventNo`、`strategyCode`、`channelType`、`triggerType`、`status` 和关联账单信息;正式业务接口编号固定为 `IF-REV-013`。 +- `Disposal Link`:用于记录催缴结果与停水、复水、工单或人工跟进之间的关联引用,只承担追溯职责,不替代下游业务对象。 + ### 迁移补充(旧系统承接) #### 催缴记录 - 旧系统支持催缴记录查询、导出和明细展开,记录中包含推送内容、号码、方式、结果等信息。 - 新系统可继续以消息协同结果和账单状态联动承接,但必须明确催缴记录查询口径,而不能仅保留“已发送/未发送”状态。 +- 历史查询最少保留客户号、账期、催缴方式、发送对象、发送时间、执行结果、关联账单、关联处置引用等字段,并兼容四态结果或其历史映射值。 #### 停水记录 - 停水记录不是孤立账务对象,应由催缴结果、业务处置和现场执行工单共同形成闭环。 - 迁移后需支持按客户、站点、停水原因、停水时间、复水状态查询,并能追溯到对应欠费账单和工单执行结果。 +- 正式设计只定义“何时建立联动、如何保存处置引用、如何追溯关联结果”,不在 `REV-006` 中展开停复水内部流程设计。 #### 预存短信 - 旧系统对预存款余额不足客户提供短信推送和发送记录查询。 - 新系统建议将其纳入催缴与通知统一策略,不再单建平行模型,但必须保留触发条件、发送内容、发送结果和补发记录。 +- 该类记录与催缴记录一样,按历史只读口径承接,不表述为新增同名在线主表。 ### 接口映射 -- `IF-REV-009`:催缴名单生成、任务下发与执行结果返回。 +- `IF-REV-013`:催缴任务生成、任务查询与结果承接接口,负责业务侧任务生成、四态状态维护和历史查询挂接。 - `IF-EXT-008`:消息协同结果回写接口(由 `SYS-010` 协同)。 ### 落地边界 -- **已落地**:以营业账为基础的欠费识别与消息协同前提数据。 -- **部分落地**:催缴登记汇总、停水汇总等对象暂未在 backend 中确认独立表。 -- **文档先行**:复杂催缴台账与停复水统计仅作为业务场景保留。 +- **已落地**:以营业账为基础的欠费识别前提数据、催缴对象来源字段和消息协同边界约束。 +- **部分落地**:催缴登记汇总、停水汇总等对象暂未在 backend 中确认独立表,当前以业务事件、操作留痕和历史查询口径承接。 +- **文档先行**:复杂催缴台账、停复水统计和人工核查界面仅作为业务场景保留,不表述为 backend 已完成能力。 diff --git a/docs/design/03_Technical_Design/01_Database_Design.md b/docs/design/03_Technical_Design/01_Database_Design.md index 4391643..51a4d82 100644 --- a/docs/design/03_Technical_Design/01_Database_Design.md +++ b/docs/design/03_Technical_Design/01_Database_Design.md @@ -1149,7 +1149,7 @@ retrieval_priority: P0 | 预存退款、已销调整、价差调整、分账调整、违约金减免、呆坏账明细 | `REV-004` 账务处理业务场景 | 旧细粒度台账以历史只读方式保留;新发生业务由流程与日志承接 | 至少支持汇总、明细、状态、审批结果和关联账单查询 | | 柜台结账、打印记录、补打记录 | 收费结果 + 打印/操作留痕 | 旧查询菜单作为历史只读能力保留,不单独建设新结账台账表 | 至少支持班次、营业所、柜员、打印类型、结账状态查询 | | 发票明细、营业账开票关系、开票配置快照 | 发票主模型 + 历史关系快照 | 旧细表和配置快照按历史只读保留;新在线模型只保留开票必需主数据 | 至少支持发票号、账单号、开票批次、配置版本和结果状态查询 | -| 催缴记录、停水记录、预存短信记录 | 催缴/停复水/消息联动业务场景 | 旧记录菜单按历史只读保留,与新通知/工单链路分层承接 | 至少支持客户、账期、催缴方式、执行结果、发送时间查询 | +| 催缴记录、停水记录、预存短信记录 | 催缴/停复水/消息联动业务场景 | 旧记录菜单按历史只读保留,与 `IF-REV-013` 的任务结果、通知链路和工单处置引用分层承接,不新增同名在线主表 | 至少支持客户、账期、催缴方式、执行结果、发送对象、发送时间、关联账单、处置引用查询 | | 水表检定、领用、出库、退库、报废单据 | `METER-003` 生命周期场景 | 当前在线主表承接水表状态,旧单据与检定证书按历史只读保留 | 至少支持表号、仓库、单据类型、检定结论、证书编号查询 | #### 迁移验收最低对账口径 @@ -1160,7 +1160,7 @@ retrieval_priority: P0 | 缴费记录 | 收费笔数、实收金额、渠道、核销状态 | `biz_collection`、`bk_transaction*` | 支持按渠道、日期、营业所汇总比对 | | 发票记录 | 开票笔数、金额、状态、票据类型 | `biz_invoice*` + 历史开票关系 | 支持按发票状态、开票日期比对 | | 红冲与账务调整 | 调整笔数、调整金额、处理结果 | 账务处理结果 + 历史台账 | 支持汇总与单据级差异定位 | -| 催缴与停复水 | 通知笔数、执行结果、停复水状态 | 新流程结果 + 历史记录 | 支持按账期、客户、执行状态比对 | +| 催缴与停复水 | 通知笔数、执行结果、停复水状态 | `IF-REV-013` 任务结果 + 历史记录 | 支持按账期、客户、执行状态、处置引用比对 | | 电子档案 | 附件数、附件类型、关联业务单数 | `biz_content_attach` + 历史档案目录 | 支持按业务类型、上传时间、来源系统比对 | #### 设计约束 @@ -1169,6 +1169,8 @@ retrieval_priority: P0 - 对 backend 当前未识别到独立实体表的旧细粒度台账,仅写为“历史只读查询对象”,不误写为“已存在新在线表”。 - 历史只读对象必须保留原系统关键标识(原单号、原客户号、原批次号或原附件标识)以支撑迁移验收与问题追溯。 - 涉及历史附件、影像、高拍仪资料时,正式数据库设计只约束“资料元数据 + 文件引用”口径,不在本轮臆造新的文件表族。 +- `REV-006` 的正式结果状态按 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态统一,数据库设计仅约束查询与追溯口径,不反推为已存在独立催缴结果主表。 +- 停复水、复水和工单处置在本轮仅保留“关联引用 + 状态摘要 + 建链时间”三类追溯字段要求,不展开下游业务表设计。 ## SYS-002 业务办理与资料表 (`biz_process*` / `biz_business_*` / `biz_content*`) diff --git a/docs/design/03_Technical_Design/03_Interface_Design.md b/docs/design/03_Technical_Design/03_Interface_Design.md index 0e4ea7e..450cfcd 100644 --- a/docs/design/03_Technical_Design/03_Interface_Design.md +++ b/docs/design/03_Technical_Design/03_Interface_Design.md @@ -264,6 +264,7 @@ retrieval_priority: P0 | IF-REV-007 | 账务调整接口 | REV-004 | 发起金额调整、退款、冲正、坏账等业务处理 | `biz_charge`、`biz_charge_detail`、`biz_operat_log` | | IF-REV-008 | 发票申请接口 | REV-005 | 后台发起单笔/批量开票申请并生成受理主键 | `biz_invoice`、`biz_invoice_taxrate`、`biz_cust_invoice` | | IF-REV-009 | 发票结果查询接口 | REV-005 | 按申请单号/受理号查询开票结果并执行补偿查询 | `biz_invoice`、`biz_operat_log` | +| IF-REV-013 | 催缴任务生成与结果承接接口 | REV-006 | 生成催缴任务、查询任务结果并承接四态状态回写 | `biz_charge`、`biz_operat_log`、历史催缴查询口径 | | IF-REV-010 | 统计查询接口 | REV-007 | 查询营收、收费、欠费、渠道、客户统计结果 | 聚合视图 / 统计结果集 | | IF-REV-011 | 银行代收协同接口 | REV-008 | 发起代扣、回盘、对账、结算协同 | `biz_withholding`、`bk_reconcile_batch`、`bk_settlement_batch` | | IF-REV-012 | 业务参数配置接口 | REV-009 | 查询和维护价格模板、优惠方案、业务参数配置 | `biz_parameter_settings`、`biz_price_*`、`biz_page_settings*` | @@ -430,6 +431,23 @@ retrieval_priority: P0 | 功能描述 | 后台按申请单号/受理号查询开票、作废或红冲结果,并支持系统补偿查询兜底 | | 核心表 | `biz_invoice`、`biz_operat_log` | +### IF-REV-013 催缴任务生成与结果承接接口 + +| 项目 | 说明 | +|------|------| +| 接口编号 | IF-REV-013 | +| 归属模块 | REV-006 | +| 请求方式 | POST | +| 请求路径 | `/admin-api/revenue/reminder/task`(查询:`/admin-api/revenue/reminder/task/query`,人工核查:`/admin-api/revenue/reminder/task/manual-verify`) | +| 功能描述 | 基于欠费账单、催缴策略和渠道偏好生成催缴任务,查询任务状态,并承接业务侧四态结果与处置引用 | +| 核心表 | `biz_charge`、`biz_charge_detail`、`biz_operat_log`、历史催缴查询口径 | + +边界约束: +- `IF-REV-013` 是 `REV-006` 的正式业务接口编号,不再复用 `IF-REV-009`。 +- `SYS-002` 负责催缴对象筛选、任务生成、业务事件号维护、四态状态承接和历史查询;`SYS-010` 只负责触达执行与结果回传。 +- 接口状态固定为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态,不在本轮扩展“已阅读”“已补发”等细粒度业务状态。 +- 停复水仅作为联动边界与处置引用承接项,不在本接口中展开停复水内部流程。 + ### IF-REV-011 银行代收协同接口 | 项目 | 说明 | @@ -865,6 +883,46 @@ retrieval_priority: P0 - 对已发起作废或红冲的记录,查询结果应允许把终态更新为 `INVALID` 或 `RED_INK`,并同步刷新 `latestResult`、`latestError`、账单关联状态与后处理上下文。 - 已进入 `SUCCESS` 的正常开票终态不得被后续失败查询结果覆盖;若外部返回异常,应记录到操作留痕并保留人工核查入口。 +### IF-REV-013 催缴任务生成与结果承接接口 + +#### 请求参数 + +| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 | +|------|------|------|------|---------------| +| taskNo | String | 否 | 催缴任务号;查询/人工核查时必填 | 任务主键 | +| custId | Long | 是 | 客户标识 | `biz_charge.cust_id` | +| chargeIds | Array | 是 | 欠费账单集合 | `biz_charge.id` | +| billPeriod | String | 是 | 账期 | `biz_charge.bill_period` | +| arrearsAmount | Decimal | 是 | 欠费金额汇总 | 欠费汇总结果 | +| strategyCode | String | 是 | 命中的催缴策略编码 | 策略规则 | +| channelType | String | 是 | 触达渠道:短信/微信公众号/站内信等 | 任务分组结果 | +| triggerType | String | 是 | 触发方式:`AUTO` / `MANUAL` | 任务触发上下文 | +| eventNo | String | 否 | 业务事件号;生成后返回,回写承接时作为关联键 | 协同事件主键 | +| relatedDisposalRef | String | 否 | 关联停复水或工单引用 | 联动追溯信息 | +| manualVerifyNote | String | 否 | 人工核查说明;仅人工核查时填写 | 核查留痕 | + +#### 响应参数 + +| 字段 | 类型 | 说明 | 主要来源 | +|------|------|------|----------| +| taskNo | String | 催缴任务号 | 任务主键 | +| interfaceCode | String | 固定返回 `IF-REV-013` | 接口常量 | +| eventNo | String | 业务事件号 | 协同主键 | +| status | String | 状态:`PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` | 任务状态 | +| resultTime | DateTime | 最近结果时间 | 结果回写时间 | +| failureReason | String | 失败原因 | 失败回写 | +| resultChannel | String | 实际触达渠道 | 协同结果 | +| relatedDisposalRef | String | 关联停复水或工单引用 | 联动追溯 | +| msg | String | 处理说明 | 返回消息 | + +#### 任务生成与状态承接约束 + +- 任务生成前必须完成欠费账单、客户类别、联系方式和策略命中校验;至少存在一个可用触达渠道。 +- 相同业务事件与同一接收对象在去重窗口内不得重复生成等效任务;若为人工补发,应显式记录 `triggerType=MANUAL`。 +- `PENDING` 表示已生成任务并发起协同,等待 `SYS-010` 回写或人工核查;`SUCCESS`、`FAIL` 由协同结果或明确失败确认触发。 +- 当外部结果长期未定、历史回执不足或人工核查已确认结果时,可将任务补记为 `MANUAL_VERIFIED`,并保留核查人和核查说明。 +- 接口返回的 `relatedDisposalRef` 仅用于追溯停复水、复水或工单处置引用,不表示本接口承担下游流程控制。 + ### IF-REV-011 银行代收协同接口 #### 请求参数 @@ -1344,13 +1402,13 @@ sequenceDiagram participant SYS010 as SYS-010消息服务 participant User as 客户 - Job->>SYS002: 触发催缴任务(IF-REV-009) + Job->>SYS002: 触发催缴任务(IF-REV-013) SYS002->>SYS002: 按欠费账单、渠道偏好生成催缴名单 SYS002->>SYS010: 提交通知下发请求(IF-EXT-008) SYS010->>User: 发送短信/公众号/APP消息 User-->>SYS010: 触达回执或阅读反馈 SYS010-->>SYS002: 回写发送结果与触达状态 - SYS002->>SYS002: 更新催缴记录、通知状态与后续策略 + SYS002->>SYS002: 更新催缴记录、四态状态与后续策略 SYS002-->>Job: 返回催缴任务执行结果 ``` @@ -1440,9 +1498,11 @@ sequenceDiagram | 催缴通知 | `templateCode` | `templateCode` | 消息模板编码 | 模板参数 | | 催缴通知 | `arrearsAmount` | `payload.arrearsAmount` | 欠费金额 | `biz_charge.total_amount` / 汇总结果 | | 催缴通知 | `billPeriod` | `payload.billPeriod` | 账期 | `biz_charge.bill_period` | +| 催缴通知 | `strategyCode` | `payload.strategyCode` | 命中的催缴策略编码 | 任务分组结果 | +| 催缴通知 | `triggerType` | `payload.triggerType` | 自动/人工触发方式 | 任务触发上下文 | | 办理进度通知 | `processCode` | `payload.processCode` | 业务办理单号 | `biz_process.code` | | 办理进度通知 | `processStatus` | `payload.processStatus` | 办理状态 | `biz_process.status` | -| 发送结果回写 | `sendStatus` | `sendStatus` | 发送状态 | 消息结果 | +| 发送结果回写 | `status` | `sendStatus` | 四态结果在业务侧映射为 `PENDING/SUCCESS/FAIL` | 消息结果 | | 发送结果回写 | `reachStatus` | `reachStatus` | 触达/阅读状态 | 渠道回执 | | 发送结果回写 | `sendTime` | `sendTime` | 发送时间 | 消息结果 | | 发送结果回写 | `msg` | `resultMsg` | 结果说明 | 返回消息 | @@ -1498,8 +1558,9 @@ sequenceDiagram | `1_002_006_003` | IF-REV-011 | 对账差异未处理,禁止结算确认 | 需先完成差异处置 | | `1_002_007_001` | IF-CS-006 | 业务办理单不存在 | 返回空结果并提示核对单号 | | `1_002_007_002` | IF-CS-006 | 当前节点不允许补件或重复提交 | 返回当前流程节点状态 | -| `1_002_008_001` | IF-REV-009 / IF-EXT-008 | 消息模板不存在或目标联系方式缺失 | 记录失败原因并允许后续补发 | +| `1_002_008_001` | IF-REV-013 / IF-EXT-008 | 消息模板不存在或目标联系方式缺失 | 记录失败原因并允许后续补发 | | `1_002_008_002` | IF-EXT-008 | 消息通道调用超时 | 标记待重试,不直接判定业务失败 | +| `1_002_008_003` | IF-REV-013 | 人工核查补记缺少核查说明或关联任务不存在 | 拒绝补记并提示补齐核查上下文 | ### 幂等与状态冲突控制 @@ -1513,7 +1574,7 @@ sequenceDiagram | 发票结果回写 | IF-EXT-007 | `requestNo + invoiceStatus` | 相同发票状态重复回写仅更新回执日志 | | 银行批次下发 | IF-REV-011 / IF-EXT-001 | `batchNo` | 同一代扣批次禁止重复发送 | | 银行回盘接收 | IF-EXT-002 | `batchNo + fileSerialNo` | 同一回盘文件只处理一次 | -| 催缴通知 | IF-REV-009 / IF-EXT-008 | `messageBizNo + templateCode + receiver` | 同一业务事件与同一接收方避免重复发送 | +| 催缴通知 | IF-REV-013 / IF-EXT-008 | `messageBizNo + templateCode + receiver` | 同一业务事件与同一接收方避免重复发送 | | 业务补件 | IF-CS-006 | `processId + action + attachmentDigest` | 相同补件内容重复提交仅保留一次 | #### 状态冲突处理原则 @@ -1556,7 +1617,7 @@ sequenceDiagram | 缴费记录、柜台结账、实时收费 | `IF-CS-002`、`IF-REV-006`、`IF-REV-011` | `biz_collection`、`bk_transaction*` + 历史收费记录 | 原流水号、渠道、实收金额、收费时间、柜员/营业所、核销状态 | 支撑渠道对账、柜面核查和历史收据核对 | | 红冲与账务调整 | `IF-REV-007` | 操作留痕、流程结果 + 历史调整台账 | 调整类型、关联原单号、调整金额、原因、审批状态、处理时间 | 支撑预存退款、已销调整、价差调整、分账调整、呆坏账查询 | | 发票与开票关系 | `IF-REV-008`、`IF-CS-004` | `biz_invoice*` + 历史开票关系快照 | 发票号、申请单号、关联账单、票据状态、票据类型、文件地址 | 支撑发票结果核查与历史补打定位 | -| 催缴、停复水、预存短信 | `IF-REV-009`、`IF-METER-002` | 通知结果、流程工单 + 历史催缴记录 | 客户号、账期、催缴方式、消息状态、停复水状态、执行人、执行时间 | 支撑催缴处置闭环核查 | +| 催缴、停复水、预存短信 | `IF-REV-013`、`IF-METER-002` | 通知结果、流程工单 + 历史催缴记录 | 客户号、账期、催缴方式、消息状态、停复水状态、执行人、执行时间、处置引用 | 支撑催缴处置闭环核查 | | 业务进度与电子档案 | `IF-CS-006` | `biz_process*`、`biz_content*` + 历史附件目录 | 业务单号、节点状态、处理轨迹、附件数量、附件元数据 | 支撑微网厅与柜台办理进度、电子档案查询 | | 水表生命周期、检定与库存流转 | `IF-METER-001`、`IF-METER-003` | `biz_meter*` + 历史仓储/检定单据 | 表号、当前状态、单据类型、仓库、检定结论、证书编号、时间 | 支撑表务迁移核查与历史作业追溯 | | 页面参数、业务字段、微信配置 | `IF-REV-012`、`IF-CS-006` | `biz_parameter_settings`、`biz_page_settings*`、`sys_wechat_app_settings` | 参数编码、原值、新值、启用状态、生效时间、适用渠道 | 支撑微网厅后台配置迁移核查 | @@ -1568,7 +1629,7 @@ sequenceDiagram | 开账迁移核对 | `IF-REV-005`、`IF-CS-002` | 账期、营业所、客户类型、账单状态 | 同时提供汇总金额/笔数与可追溯明细清单 | | 收费迁移核对 | `IF-REV-006`、`IF-REV-011`、`IF-CS-002` | 日期、渠道、营业所、收费状态 | 同时提供实收金额、流水数量和异常流水列表 | | 发票迁移核对 | `IF-REV-008`、`IF-CS-004` | 开票日期、票据类型、开票状态 | 同时提供开票汇总、失败原因和票据明细定位 | -| 催缴与停复水核对 | `IF-REV-009`、`IF-METER-002` | 账期、催缴方式、执行状态、处理人 | 同时提供任务统计与执行明细 | +| 催缴与停复水核对 | `IF-REV-013`、`IF-METER-002` | 账期、催缴方式、执行状态、处理人 | 同时提供任务统计、执行明细与处置引用 | | 业务办理与档案核对 | `IF-CS-006` | 业务类型、流程状态、附件类型、创建时间 | 同时提供流程轨迹、附件元数据和缺失标记 | | 表务仓储与检定核对 | `IF-METER-001`、`IF-METER-003` | 仓库、单据类型、水表状态、检定结论 | 同时提供数量汇总和单据级追溯信息 | diff --git a/specs/003-rev006-reminder-event-design/checklists/requirements.md b/specs/003-rev006-reminder-event-design/checklists/requirements.md new file mode 100644 index 0000000..29e35fe --- /dev/null +++ b/specs/003-rev006-reminder-event-design/checklists/requirements.md @@ -0,0 +1,36 @@ +# Specification Quality Checklist: REV-006 催缴事件与通知协同设计 + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-03-18 +**Feature**: [spec.md](../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 + +- Validation result: pass on first review. +- No unresolved clarification markers remain. +- Spec is ready for `/speckit.plan`; `/speckit.clarify` is optional rather than required. diff --git a/specs/003-rev006-reminder-event-design/contracts/rev006-interface-contract.md b/specs/003-rev006-reminder-event-design/contracts/rev006-interface-contract.md new file mode 100644 index 0000000..c2ab5c9 --- /dev/null +++ b/specs/003-rev006-reminder-event-design/contracts/rev006-interface-contract.md @@ -0,0 +1,102 @@ +# Contract: REV-006 催缴事件与通知协同 + +## 1. Formal Interface Allocation + +| Interface | Role | Direction | +|---|---|---| +| `IF-REV-013` | `REV-006` 催缴任务生成、任务查询、结果承接的正式业务接口 | `SYS-002` 内部正式业务接口 | +| `IF-EXT-008` | `SYS-002` 与 `SYS-010` 的消息触达协同接口 | `SYS-002 -> SYS-010` 发送,`SYS-010 -> SYS-002` 回写 | + +约束: + +- `IF-REV-009` 继续保留给 `REV-005` 发票结果查询,不得再用于 `REV-006`。 +- `IF-REV-013` 是本 feature 新增的正式业务接口编号。 + +## 2. IF-REV-013 Business Contract + +### Purpose + +统一承接催缴任务生成、任务状态查询和业务侧结果查看,不承担消息平台内部发送逻辑。 + +### Request Shape + +| Field | Meaning | Required | +|---|---|---| +| `taskNo` | 催缴任务号 | 查询时是;生成时否 | +| `custId` | 客户标识 | 是 | +| `chargeIds` | 账单集合 | 是 | +| `billPeriod` | 账期 | 是 | +| `arrearsAmount` | 欠费金额 | 是 | +| `strategyCode` | 催缴策略编码 | 是 | +| `channelType` | 触达渠道 | 是 | +| `triggerType` | 触发方式 | 是 | +| `eventNo` | 业务事件号 | 生成后返回;回写承接时是 | + +### Response Shape + +| Field | Meaning | +|---|---| +| `taskNo` | 催缴任务号 | +| `interfaceCode` | 固定为 `IF-REV-013` | +| `status` | `PENDING` / `SUCCESS` / `FAIL` / `MANUAL_VERIFIED` | +| `resultTime` | 最近结果时间 | +| `failureReason` | 失败原因 | +| `relatedDisposalRef` | 关联停复水或工单引用 | + +## 3. IF-EXT-008 Collaboration Contract + +### Outbound to SYS-010 + +| Field | Meaning | +|---|---| +| `eventNo` | 业务事件号 | +| `taskNo` | 催缴任务号 | +| `custId` | 客户标识 | +| `receiver` | 接收目标 | +| `channelType` | 触达渠道 | +| `templateCode` | 消息模板编码 | +| `arrearsAmount` | 欠费金额 | +| `billPeriod` | 账期 | +| `triggerType` | 自动/人工 | + +### Writeback from SYS-010 + +| Field | Meaning | +|---|---| +| `eventNo` | 业务事件号 | +| `status` | `SUCCESS` / `FAIL` / `PENDING` | +| `failureReason` | 失败原因 | +| `resultChannel` | 实际触达渠道 | +| `resultTime` | 结果时间 | + +### Manual Verification Supplement + +当外部结果长期未定或与业务侧核查结论不一致时,由 `SYS-002` 将任务状态补记为 `MANUAL_VERIFIED`,并保留核查人和核查说明。 + +## 4. State Contract + +| State | Meaning | Allowed Source | +|---|---|---| +| `PENDING` | 已生成任务,等待协同结果或人工核查 | `SYS-002` | +| `SUCCESS` | 已确认触达成功 | `SYS-010` 回写 | +| `FAIL` | 已确认发送失败 | `SYS-010` 回写或失败确认 | +| `MANUAL_VERIFIED` | 经过人工核查后补记为有效结果 | `SYS-002` 人工核查 | + +## 5. History Query Contract + +历史查询最小字段集必须支持: + +- 客户号 +- 账期 +- 催缴方式 +- 执行结果 +- 发送时间 +- 发送对象 +- 关联账单 +- 关联停复水/工单引用 + +该查询合同用于: + +- 正式设计中的历史只读口径 +- 迁移验收对账 +- 后续催缴与停复水核查 diff --git a/specs/003-rev006-reminder-event-design/data-model.md b/specs/003-rev006-reminder-event-design/data-model.md new file mode 100644 index 0000000..17c4cf1 --- /dev/null +++ b/specs/003-rev006-reminder-event-design/data-model.md @@ -0,0 +1,159 @@ +# Data Model: REV-006 催缴事件与通知协同设计 + +## 1. Reminder Candidate + +### Purpose + +表示进入催缴评估范围的欠费账单或客户对象集合,是催缴任务生成的输入对象。 + +### Key Fields + +| Field | Description | Rule | +|---|---|---| +| `custId` | 客户标识 | 必填;关联客户主档 | +| `chargeId` | 账单标识 | 必填;关联欠费账单 | +| `billPeriod` | 账期 | 必填;用于催缴分组和历史查询 | +| `arrearsAmount` | 欠费金额 | 必填;用于策略匹配 | +| `agingBucket` | 欠费账龄分组 | 必填;用于策略筛选 | +| `customerCategory` | 客户类别 | 必填;用于差异化催缴 | +| `contactChannelSet` | 可用联系方式集合 | 至少存在一个有效触达渠道 | +| `strategyCode` | 命中的催缴策略编码 | 必填;来源于策略规则 | + +### Relationships + +- 来自 `biz_charge` / `biz_charge_detail` +- 关联客户主档与联系方式 +- 可生成一个或多个 `Reminder Task` + +## 2. Reminder Strategy + +### Purpose + +定义催缴对象筛选、任务分组、触达渠道和频控约束的业务规则。 + +### Key Fields + +| Field | Description | Rule | +|---|---|---| +| `strategyCode` | 策略编码 | 唯一 | +| `agingRule` | 账龄匹配规则 | 必填 | +| `amountRule` | 金额匹配规则 | 必填 | +| `customerCategoryRule` | 客户类别匹配规则 | 可为空;为空表示通用 | +| `channelPriority` | 触达渠道优先级 | 必填;至少 1 个渠道 | +| `dedupeWindow` | 重复触达拦截窗口 | 必填 | +| `escalationFlag` | 是否触发后续处置关注 | 必填 | + +### Relationships + +- 一个 `Reminder Strategy` 可匹配多个 `Reminder Candidate` +- 一个 `Reminder Strategy` 可驱动多个 `Reminder Task` + +## 3. Reminder Task + +### Purpose + +表示一次正式催缴执行单元,负责承接业务触发、协同下发和结果回写。 + +### Key Fields + +| Field | Description | Rule | +|---|---|---| +| `taskNo` | 催缴任务号 | 唯一;正式业务主键 | +| `interfaceCode` | 正式接口编号 | 固定使用 `IF-REV-013` | +| `eventNo` | 业务事件号 | 唯一;用于与 `SYS-010` 协同 | +| `custId` | 客户标识 | 必填 | +| `chargeId` | 账单标识 | 必填 | +| `strategyCode` | 策略编码 | 必填 | +| `channelType` | 触达渠道 | 必填;短信/微信公众号/站内信等 | +| `triggerType` | 触发方式 | 必填;自动/人工 | +| `status` | 当前任务状态 | 必填;`PENDING` / `SUCCESS` / `FAIL` / `MANUAL_VERIFIED` | +| `sourceType` | 任务来源 | 必填;系统任务/人工补发/核查回补 | +| `createdTime` | 创建时间 | 必填 | +| `lastResultTime` | 最近结果时间 | 可为空;初次发送前为空 | + +### State Transitions + +| From | To | Condition | +|---|---|---| +| 新建 | `PENDING` | 已生成任务并发起协同 | +| `PENDING` | `SUCCESS` | 收到成功回写 | +| `PENDING` | `FAIL` | 收到失败回写或确认失败 | +| `PENDING` | `MANUAL_VERIFIED` | 人工核查后确认结果 | +| `FAIL` | `MANUAL_VERIFIED` | 人工核查补记结果 | + +### Relationships + +- 由一个 `Reminder Candidate` 和一个 `Reminder Strategy` 组合产生 +- 关联一个或多个 `Reminder Result` +- 可关联一个 `Disposal Link` + +## 4. Reminder Result + +### Purpose + +表示 `SYS-010` 回传或人工核查得到的触达结果。 + +### Key Fields + +| Field | Description | Rule | +|---|---|---| +| `eventNo` | 业务事件号 | 必填;与 `Reminder Task` 对应 | +| `status` | 结果状态 | 必填;仅允许四态 | +| `failureReason` | 失败原因 | `FAIL` 时必填 | +| `resultChannel` | 实际触达渠道 | 必填 | +| `resultTime` | 结果时间 | 必填 | +| `verifiedBy` | 核查人 | `MANUAL_VERIFIED` 时必填 | +| `verifiedNote` | 核查说明 | `MANUAL_VERIFIED` 时建议填写 | + +### Relationships + +- 归属于一个 `Reminder Task` +- 结果会回写到任务状态与历史查询记录 + +## 5. Reminder History Record + +### Purpose + +为历史查询和迁移验收提供最小保留信息集合。 + +### Key Fields + +| Field | Description | Rule | +|---|---|---| +| `custId` | 客户标识 | 必填 | +| `billPeriod` | 账期 | 必填 | +| `channelType` | 催缴方式 | 必填 | +| `messageContentRef` | 触达内容引用 | 必填;可为模板或摘要引用 | +| `receiver` | 接收目标 | 必填;手机号/OpenID/站内信对象 | +| `status` | 执行结果 | 必填;使用四态或历史映射值 | +| `sendTime` | 发送时间 | 必填 | +| `operatorSource` | 操作来源 | 必填;自动/人工/历史迁移 | +| `relatedChargeId` | 关联账单 | 必填 | +| `relatedDisposalRef` | 关联处置引用 | 可为空;用于停复水/工单追溯 | + +### Relationships + +- 可由 `Reminder Task` 和 `Reminder Result` 聚合生成 +- 同时承接历史催缴记录、停水记录、预存短信记录的查询口径 + +## 6. Disposal Link + +### Purpose + +记录催缴结果与停水、复水、工单或人工处置之间的追溯关系。 + +### Key Fields + +| Field | Description | Rule | +|---|---|---| +| `eventNo` | 关联业务事件号 | 必填 | +| `disposalType` | 处置类型 | 必填;停水/复水/工单/人工跟进 | +| `triggerCondition` | 触发条件摘要 | 必填 | +| `disposalRefNo` | 下游处置引用号 | 可为空;未创建时为空 | +| `disposalStatus` | 下游处置状态 | 可为空;仅作追溯,不定义内部流程 | +| `linkedTime` | 建立关联时间 | 必填 | + +### Relationships + +- 一个 `Reminder Task` 最多关联一个当前生效的 `Disposal Link` +- 不替代下游业务对象,只做引用和追溯 diff --git a/specs/003-rev006-reminder-event-design/plan.md b/specs/003-rev006-reminder-event-design/plan.md new file mode 100644 index 0000000..f2436fb --- /dev/null +++ b/specs/003-rev006-reminder-event-design/plan.md @@ -0,0 +1,109 @@ +# Implementation Plan: REV-006 催缴事件与通知协同设计 + +**Branch**: `003-rev006-reminder-event-design` | **Date**: 2026-03-18 | **Spec**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/spec.md) +**Input**: Feature specification from `/specs/003-rev006-reminder-event-design/spec.md` + +**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow. + +## Summary + +本 feature 用于补齐 `REV-006` 在正式文档体系中的设计闭环,重点收口催缴对象生成、催缴任务触发、`SYS-010` 消息协同结果回写、停复水联动边界以及历史查询最小保留集。实施方式以修订既有主文档和治理台账为主,不进入 backend 代码实现;同时将现有接口冲突纠正为 `REV-006` 使用新的独立正式接口编号,发票查询继续保留 `IF-REV-009`。 + +## Technical Context + + + +**Primary Work Product**: Markdown 设计文档、接口/数据库专题文档、管理台账文档 +**Source of Truth Documents**: + - `/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/03_Technical_Design/01_Database_Design.md` + - `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/04_Writing_Guide.md` + - `/Volumes/Dpan/github/fujian_water_biz_doc/AGENTS.md` +**Reference Sources**: + - `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` + - `/Volumes/Dpan/github/fujian_water_biz_doc/docs/guides/BACKEND_CURRENT_STATUS.md` + - `/Volumes/Dpan/github/fujian_water_biz_doc/docs/guides/BACKEND_TABLE_MAPPING.md` + - `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md` + - `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/04_Appendix/Archive/01_Requirements/` +**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/03_Technical_Design/01_Database_Design.md` + - `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` + - `make validate-file FILE=docs/design/00_Management/01_Project_Progress.md` + - `make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md` + - `make check-links` +**Target Scope**: + - `12_REV_Detailed.md` 中 `REV-006` 正文、流程、规则、落地边界 + - `03_Interface_Design.md` 中 `REV-006` 与 `SYS-010` 的接口编号、接口定义、时序、映射表、异常码、幂等策略 + - `01_Database_Design.md` 中催缴/停复水/预存短信历史只读口径与在线主模型承接边界 + - `15_SYS002_Requirement_Breakdown.md` 中实现评估和 Story/Task 建议 + - `01_Project_Progress.md`、`03_Task_Checklist.md` 的治理回写 +**Project Type**: 文档治理仓库 +**Constraints**: + - 不新增平行正式主稿,所有正式内容回写既有主文档 + - 不臆造 backend 已实现事实,只能写“已实现 / 部分实现 / 文档先行 / 历史只读” + - 仓库内引用保持相对路径 + - 停复水只定义联动边界,不展开内部处置流程 + - `REV-006` 必须使用独立正式接口编号,不再复用 `IF-REV-009` + - 催缴结果状态固定为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` +**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`、`01_Database_Design.md` 与治理台账,不新增平行正式稿。 +- [x] **范围基线已确认**:`REV-006` 已存在于 `03_Summary_Design.md`、`12_REV_Detailed.md` 和 `15_SYS002_Requirement_Breakdown.md`,本轮仅补齐既有范围内的设计与接口口径,不引入超范围新模块。 +- [x] **Archive 使用方式合规**:Archive 仅用于核对旧“催缴记录/停水记录/预存短信”来源与历史只读口径,不直接作为正式结论输出。 +- [x] **一致性影响已列出**:受影响项包括 `REV-006` 接口编号、结果状态术语、催缴/停复水边界、历史只读查询口径、时序图与映射表。 +- [x] **校验与台账动作已规划**:已规划单文件校验、链接校验,并要求同步更新 `01_Project_Progress.md` 与 `03_Task_Checklist.md`。 + +## Project Structure + +### Documentation (this feature) + +```text +specs/[###-feature]/ +├── plan.md # This file (/speckit.plan command output) +├── research.md # Phase 0 output (/speckit.plan command) +├── data-model.md # Optional: document entities/traceability objects +├── quickstart.md # Optional: validation or review quickstart +├── contracts/ # Optional: interface or section-level artifacts +└── tasks.md # Phase 2 output (/speckit.tasks command) +``` + +### Repository Touchpoints + +```text +docs/design/ +├── 00_Management/ +├── 01_Overview/ +├── 02_Detailed_Design/ +├── 03_Technical_Design/ +└── 04_Appendix/Archive/ + +README.md +AGENTS.md +.specify/templates/ +``` + +**Structure Decision**: + - 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md`:补齐 `REV-006` 详细设计正文与落地边界。 + - 更新 `docs/design/03_Technical_Design/03_Interface_Design.md`:修正接口编号冲突,补齐 `REV-006` 正式接口、协同时序、异常码和幂等策略。 + - 更新 `docs/design/03_Technical_Design/01_Database_Design.md`:明确在线承接与历史只读查询口径,不把旧菜单机械映射为新表。 + - 更新 `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`:同步实现评估、TAPD/Speckit 建议和后续任务入口。 + - 更新 `docs/design/00_Management/01_Project_Progress.md` 与 `docs/design/00_Management/03_Task_Checklist.md`:完成治理闭环。 + +## Complexity Tracking + +> **Fill ONLY if Constitution Check has violations that must be justified** + +| Violation | Why Needed | Simpler Alternative Rejected Because | +|-----------|------------|-------------------------------------| +| 无 | - | - | diff --git a/specs/003-rev006-reminder-event-design/quickstart.md b/specs/003-rev006-reminder-event-design/quickstart.md new file mode 100644 index 0000000..c2426a6 --- /dev/null +++ b/specs/003-rev006-reminder-event-design/quickstart.md @@ -0,0 +1,57 @@ +# Quickstart: REV-006 催缴事件与通知协同设计 + +## 目标 + +本 quickstart 用于指导评审者和文档维护者快速完成 `REV-006` 设计补齐的检查,不涉及 backend 实施。 + +## 步骤 1:阅读规格与研究结论 + +1. 阅读 `spec.md`,确认三项澄清已固定: + - 停复水仅定义联动边界 + - `REV-006` 使用独立接口编号 `IF-REV-013` + - 结果状态固定为四态 +2. 阅读 `research.md`,确认所有关键设计决策已有依据和备选方案说明。 + +## 步骤 2:执行文档改动时的目标落点 + +1. 在 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 补齐 `REV-006`: + - 任务生成规则 + - 结果回写规则 + - 停复水联动边界 + - 历史查询最小保留集 +2. 在 `docs/design/03_Technical_Design/03_Interface_Design.md`: + - 新增或替换 `IF-REV-013` + - 保留 `IF-EXT-008` + - 删除 `REV-006` 对 `IF-REV-009` 的错误引用 +3. 在 `docs/design/03_Technical_Design/01_Database_Design.md`: + - 明确在线主模型和历史只读查询口径 +4. 在治理台账中回写: + - `01_Project_Progress.md` + - `03_Task_Checklist.md` + +## 步骤 3:建议校验命令 + +```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/03_Technical_Design/01_Database_Design.md +make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md +make validate-file FILE=docs/design/00_Management/01_Project_Progress.md +make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md +make check-links +``` + +## 步骤 4:验收检查点 + +- `REV-006` 不再复用 `IF-REV-009` +- 正式文档中统一使用四态结果集 +- 停复水只写联动边界,不扩写内部流程 +- 历史“催缴记录 / 停水记录 / 预存短信”不被误写成新在线主表 +- 台账和正式文档同步更新 + +## 步骤 5:本轮实现摘要 + +- 已完成 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`、`15_SYS002_Requirement_Breakdown.md`、`01_Project_Progress.md`、`03_Task_Checklist.md` 的正式文档回写。 +- `REV-006` 的正式业务接口编号已固定为 `IF-REV-013`,`IF-REV-009` 继续保留给 `REV-005` 发票结果查询。 +- 催缴结果已统一为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态;数据库与历史查询口径同步收口。 +- 已执行并通过全部单文件校验与 `make check-links`。 diff --git a/specs/003-rev006-reminder-event-design/research.md b/specs/003-rev006-reminder-event-design/research.md new file mode 100644 index 0000000..be51f14 --- /dev/null +++ b/specs/003-rev006-reminder-event-design/research.md @@ -0,0 +1,58 @@ +# Phase 0 Research: REV-006 催缴事件与通知协同设计 + +## 决策 1:`REV-006` 使用新的独立正式接口编号 + +- **Decision**: `REV-006` 使用新的独立正式接口编号 `IF-REV-013` 作为“催缴任务生成与结果查询/回写承接”的正式业务接口编号;`IF-REV-009` 保留给 `REV-005` 发票结果查询。 +- **Rationale**: + - 当前 `03_Interface_Design.md` 已明确 `IF-REV-009` 属于 `REV-005` 发票结果查询,继续复用会造成接口总表、异常码、幂等策略和时序图冲突。 + - 现有 `IF-REV-*` 编号已经覆盖到 `IF-REV-012`,顺延 `IF-REV-013` 是最小改动且最不易误解的做法。 + - 该决策能直接消除 `12_REV_Detailed.md` 中 `REV-006` 与接口主文档的冲突口径。 +- **Alternatives considered**: + - 继续复用 `IF-REV-009`:被否决,因为与发票查询主口径冲突。 + - 暂不落编号,只写业务能力:被否决,因为会推迟核心冲突到实施阶段。 + - 改用 `IF-EXT-*`:被否决,因为 `REV-006` 的业务接口主责仍属于 `SYS-002`,`IF-EXT-008` 只适用于与 `SYS-010` 的外部协同。 + +## 决策 2:催缴结果状态固定为四态 + +- **Decision**: `REV-006` 正式状态集固定为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED`。 +- **Rationale**: + - 四态足以覆盖“待回写/待核查”“成功触达”“失败”“人工核查确认”四类评审和实施必需场景。 + - 过少状态会导致补偿与人工核查无法落地;过多状态会在当前未实现阶段引入不必要的细粒度设计。 + - 四态同时便于后续接口、数据库和台账统一。 +- **Alternatives considered**: + - 两态(成功/失败):无法表达未回写和人工核查状态。 + - 三态(待处理/成功/失败):无法区分人工核查后的确认结果。 + - 更细状态(已送达/已阅读/已补发):当前阶段超出设计收口所需。 + +## 决策 3:停复水仅定义联动边界,不展开内部流程 + +- **Decision**: 本 feature 仅定义催缴结果与停复水之间的联动边界、触发条件、查询字段和追溯关系,不展开停复水内部处置流程、审批节点或现场执行细节。 +- **Rationale**: + - 停复水属于后续业务处置链,深入展开会把当前专题扩展到工单/现场作业子系统。 + - 当前 `REV-006` 的首要目标是把催缴闭环范围和责任边界收口,而不是设计全部后置处置流程。 + - 这样既能满足历史查询和审计追溯,又不破坏范围控制。 +- **Alternatives considered**: + - 把停复水完整流程纳入 `REV-006`:被否决,因为会扩大到非本轮范围。 + - 完全不写停复水联动:被否决,因为会留下历史查询和后续处置链断点。 + +## 决策 4:历史“催缴记录/停水记录/预存短信”按历史只读口径承接 + +- **Decision**: 旧系统“催缴记录、停水记录、预存短信记录”继续按历史只读查询对象承接,不新增同名在线主表;在线主模型以 `biz_charge`、操作留痕和消息协同结果为主。 +- **Rationale**: + - `01_Database_Design.md` 已对这些对象给出“历史只读保留”口径,且当前 backend 未见明确独立表族。 + - 直接新增同名新表会违反“不得臆造已实现事实”和“单一真源”的原则。 + - 历史只读策略既能满足迁移验收,也不影响后续按业务链逐步演进。 +- **Alternatives considered**: + - 为每个旧菜单新增在线主表:被否决,因为没有实现证据且破坏当前主模型。 + - 完全不保留历史查询口径:被否决,因为不满足迁移验收和追溯要求。 + +## 决策 5:`REV-006` 与 `SYS-010` 的职责分界 + +- **Decision**: `SYS-002/REV-006` 负责催缴对象筛选、任务分组、业务事件生成、状态承接、历史查询和处置关联;`SYS-010` 负责短信、微信公众号、站内信等触达执行与结果回传。 +- **Rationale**: + - 该分界与 `03_Interface_Design.md` 中跨系统协同表一致。 + - 业务筛选和状态归属留在 `SYS-002`,能保证催缴逻辑与账单口径一致。 + - 触达能力放在 `SYS-010`,避免 `REV-006` 越权扩展到消息平台实现。 +- **Alternatives considered**: + - 让 `SYS-010` 负责催缴对象筛选:被否决,因为会削弱营收主系统对账单规则的控制。 + - 让 `SYS-002` 直接承担全部消息发送:被否决,因为与既有系统边界不一致。 diff --git a/specs/003-rev006-reminder-event-design/spec.md b/specs/003-rev006-reminder-event-design/spec.md new file mode 100644 index 0000000..a19fa5f --- /dev/null +++ b/specs/003-rev006-reminder-event-design/spec.md @@ -0,0 +1,141 @@ +# 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 项文档校验或一致性检查而无需二次猜测。 diff --git a/specs/003-rev006-reminder-event-design/tasks.md b/specs/003-rev006-reminder-event-design/tasks.md new file mode 100644 index 0000000..fc9991e --- /dev/null +++ b/specs/003-rev006-reminder-event-design/tasks.md @@ -0,0 +1,187 @@ +# Tasks: REV-006 催缴事件与通知协同设计 + +**Input**: Design documents from `/specs/003-rev006-reminder-event-design/` +**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/ + +**Validation**: Validation tasks are NOT optional in this repository. Every document change task set MUST include the 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 (e.g. [US1], [US2], [US3]) +- Include exact file paths in descriptions + +## Path Conventions + +- Main documents: `docs/design/01_Overview/`, `docs/design/02_Detailed_Design/`, `docs/design/03_Technical_Design/` +- Governance documents: `docs/design/00_Management/` +- Archive references: `docs/design/04_Appendix/Archive/` +- Runtime guidance: `README.md`, `AGENTS.md`, `.specify/templates/` + +## Phase 1: Scope & Source Confirmation (Shared Foundation) + +**Purpose**: Confirm the source-of-truth set and impact boundary before editing. + +- [X] T001 Confirm target documents and exact `REV-006` touchpoints in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/spec.md` +- [X] T002 Confirm governing source-of-truth and allowed reference sources in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/plan.md` +- [X] T003 [P] Record final scope judgment for `REV-006` and exclusions in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/research.md` +- [X] T004 [P] Identify cross-document impacts for `IF-REV-013`、四态结果集、停复水联动边界和历史只读口径 in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/contracts/rev006-interface-contract.md` + +--- + +## Phase 2: Foundational Alignment (Blocking Prerequisites) + +**Purpose**: Prepare the cross-document baseline that all user stories depend on. + +- [X] T005 Consolidate `REV-006` decisions, entities, and contract fields from `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/research.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/data-model.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/contracts/rev006-interface-contract.md` +- [X] T006 [P] Cross-check current conflicting references to `IF-REV-009` and `REV-006` 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 [P] Cross-check historical-only retention rules for 催缴记录/停水记录/预存短信 in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md` and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md` +- [X] T008 Confirm ledger update expectations for this feature in `/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`, and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md` + +--- + +## Phase 3: User Story 1 - 定义催缴闭环范围 (Priority: P1) 🎯 MVP + +**Goal**: 让 `12_REV_Detailed.md` 中的 `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] T009 [US1] Update `REV-006` 功能说明、业务流程、关键规则和落地边界 in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` +- [X] T010 [P] [US1] Add `Reminder Candidate`、`Reminder Strategy`、`Reminder Task`、`Disposal Link` 对应的数据与规则摘要 to `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` +- [X] T011 [P] [US1] Sync `REV-006` implementation assessment and Story notes in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` +- [X] T012 [US1] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and capture result +- [X] T013 [US1] Run `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` and capture result + +**Checkpoint**: User Story 1 is reviewable and confirms the `REV-006` business boundary without depending on interface redesign. + +--- + +## Phase 4: User Story 2 - 统一消息协同与结果回写口径 (Priority: P2) + +**Goal**: 在接口主文档中为 `REV-006` 建立独立正式接口编号、四态结果集、`SYS-002 ↔ SYS-010` 协同字段和异常/幂等规则。 + +**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`,应能确认 `IF-REV-013` 的职责、`IF-EXT-008` 的协同边界、四态状态语义以及不再复用 `IF-REV-009`。 + +### Implementation for User Story 2 + +- [X] T014 [US2] Replace `REV-006` 对 `IF-REV-009` 的错误引用 with `IF-REV-013` in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md` +- [X] T015 [US2] Add `IF-REV-013` formal interface definition, request/response shape, and responsibility boundary in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md` +- [X] T016 [P] [US2] Update `IF-EXT-008` collaboration contract, state semantics, idempotency, exception codes, and timing diagrams in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md` +- [X] T017 [P] [US2] Sync `REV-006` interface mapping, interface numbering, and state terminology in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` +- [X] T018 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` and capture result +- [X] T019 [US2] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and capture result after interface sync + +**Checkpoint**: User Story 2 is reviewable and fully expresses the `REV-006` interface and integration contract independently. + +--- + +## Phase 5: User Story 3 - 明确历史查询与停复水联动边界 (Priority: P3) + +**Goal**: 在数据库和治理文档中收口历史只读查询口径、迁移验收字段和停复水联动追溯边界。 + +**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md` 与治理台账,应能确认旧“催缴记录/停水记录/预存短信”不被误写为新在线主表,同时查询字段和对账口径完整。 + +### Implementation for User Story 3 + +- [X] T020 [US3] Update historical read-only retention and online-model boundary for 催缴记录/停水记录/预存短信 in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md` +- [X] T021 [P] [US3] Add minimum query fields, traceability expectations, and disposal-link wording for `REV-006` in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md` +- [X] T022 [P] [US3] Sync feature completion, implementation status, and follow-up recommendations in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` +- [X] T023 [US3] Update `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md` with the `REV-006` design closure milestone +- [X] T024 [US3] Update `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md` with the `REV-006` tracked-task closure status +- [X] T025 [US3] Run `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` and capture result +- [X] T026 [US3] Run `make validate-file FILE=docs/design/00_Management/01_Project_Progress.md` and `make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md` and capture result + +**Checkpoint**: User Story 3 is reviewable and confirms the historical-query and ledger-governance closure independently. + +--- + +## Final Phase: Cross-Cutting Closure + +**Purpose**: Ensure repository-wide consistency after all story slices are complete. + +- [X] T027 [P] Re-check source-of-truth alignment 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/03_Technical_Design/01_Database_Design.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` +- [X] T028 [P] Run `make check-links` after all document changes and capture result +- [X] T029 Prepare final summary with modified files, validation results, remaining risks, and next-step suggestions in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/quickstart.md` + +--- + +## Dependencies & Execution Order + +### Phase Dependencies + +- **Phase 1: Scope & Source Confirmation**: No dependencies; MUST finish before content edits +- **Phase 2: Foundational Alignment**: Depends on Phase 1; MUST finish before user story work +- **Phase 3: User Story 1**: Depends on Phase 2 +- **Phase 4: User Story 2**: Depends on Phase 2 and should follow User Story 1 because interface mapping must align with the finalized `REV-006` business scope +- **Phase 5: User Story 3**: Depends on Phase 2 and should follow User Story 2 because database and ledger wording must use the finalized interface numbering and state terms +- **Final Phase**: Depends on all selected user stories being complete + +### Within Each User Story + +- Update target documents before syncing supporting or governance documents +- Complete content edits before validation +- Complete validation before ledger updates are marked done +- Complete ledger sync before final summary + +### User Story Completion Order + +`US1 -> US2 -> US3` + +### Parallel Opportunities + +- `T003` and `T004` can run in parallel after source confirmation +- `T006` and `T007` can run in parallel during foundational alignment +- In `US1`, `T010` and `T011` can run in parallel after `T009` +- In `US2`, `T016` and `T017` can run in parallel after `T014` and `T015` +- In `US3`, `T021` and `T022` can run in parallel after `T020` +- `T027` and `T028` can run in parallel during final closure + +## Parallel Execution Examples + +### User Story 1 + +```text +Run in parallel after T009: +- T010 [P] [US1] Add data/rule summaries in 12_REV_Detailed.md +- T011 [P] [US1] Sync implementation assessment in 15_SYS002_Requirement_Breakdown.md +``` + +### User Story 2 + +```text +Run in parallel after T014 and T015: +- T016 [P] [US2] Update IF-EXT-008 contract, states, exceptions, diagrams +- T017 [P] [US2] Sync interface mapping back into 12_REV_Detailed.md +``` + +### User Story 3 + +```text +Run in parallel after T020: +- T021 [P] [US3] Add query-field and traceability wording in 01_Database_Design.md +- T022 [P] [US3] Sync feature completion notes in 15_SYS002_Requirement_Breakdown.md +``` + +## Implementation Strategy + +### MVP First + +先完成 `US1`,因为 `12_REV_Detailed.md` 的业务边界是所有后续接口和数据库收口的前提。只要 `US1` 完成并通过校验,就可以先交付一版可评审的 `REV-006` 业务范围说明。 + +### Incremental Delivery + +1. 完成 `US1`,锁定业务边界和排除项 +2. 完成 `US2`,锁定接口编号、协同边界和四态结果集 +3. 完成 `US3`,锁定历史只读口径、迁移验收字段和治理台账闭环 +4. 最后统一执行全局一致性检查和链接校验 + +### Notes + +- 每个 story 都可以独立评审,不要求一次性改完全部文档 +- 所有任务都必须回写既有正式文档,不能新建平行正式稿 +- Archive 只作为核对来源,不直接替代主文档 +- 验证和台账同步不是可选项