From 54d7b0f5693ae0c468edc343252ccc1a0c9ee0a0 Mon Sep 17 00:00:00 2001 From: tangweijie <877588133@qq.com> Date: Tue, 17 Mar 2026 10:25:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20REV-005=20?= =?UTF-8?q?=E5=8F=B0=E8=B4=A6=E5=B9=B6=E8=A1=A5=E5=85=85=20SYS-002=20?= =?UTF-8?q?=E6=8B=86=E8=A7=A3=E6=80=BB=E8=A1=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .../00_Management/01_Project_Progress.md | 6 + .../design/00_Management/03_Task_Checklist.md | 8 + .../15_SYS002_Requirement_Breakdown.md | 303 ++++++++++++++++++ 3 files changed, 317 insertions(+) create mode 100644 docs/design/00_Management/15_SYS002_Requirement_Breakdown.md diff --git a/docs/design/00_Management/01_Project_Progress.md b/docs/design/00_Management/01_Project_Progress.md index 1919ad2..bb619a8 100644 --- a/docs/design/00_Management/01_Project_Progress.md +++ b/docs/design/00_Management/01_Project_Progress.md @@ -116,6 +116,7 @@ > 说明：本表中的历史记录按当时原始表述保留；当前正式数据库口径统一以“达梦数据库 8.0+”为准。 +| 2026-03-17 | REV-005 作废与红冲边界转后续阶段预留（US4） | 1）在 `12_REV_Detailed.md`、`03_Interface_Design.md` 继续明确作废、红冲仅保留正式文档入口与状态预留，不纳入一期正常开票闭环实现；2）将当前交付边界收敛为“后台申请 + 查询兜底 + 结果回写 + 账单关联 + 客户侧电子票消费”；3）为后续扩展作废、红冲与更多电子票渠道保留可追溯入口。 | 当前已完成 REV-005 US1~US3 的最小闭环，需要继续按 `/speckit.implement` 收口 US4 文档边界，避免一期实现范围与后续能力混淆。 | 正面影响，REV-005 一期交付边界更稳定，评审与后续开发可明确区分“已交付正常开票闭环”和“后续扩展的作废/红冲能力”，减少范围蔓延与误判。 | | 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 临时编排成本。 | @@ -300,3 +301,8 @@ --- **🎊 项目圆满完成！所有核心设计文档已达到甲方A级交付标准，可正式交付！** + +### 2026-03-17 更新 + +- 新增 `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`，完成 `SYS-002` 需求总览、Story/feature 映射、代码实现评估与 TAPD 转换建议整理。 +- 形成 `SYS002-REQ-001 ~ 015` 的统一拆解口径，可直接用于 Speckit 立项、TAPD Story/Task 建模与后续文档/实现对齐跟踪。 diff --git a/docs/design/00_Management/03_Task_Checklist.md b/docs/design/00_Management/03_Task_Checklist.md index 5ad7acf..c40cc1e 100644 --- a/docs/design/00_Management/03_Task_Checklist.md +++ b/docs/design/00_Management/03_Task_Checklist.md @@ -190,6 +190,14 @@ - [x] `InvoiceController.java`、`InvoiceServiceImpl.java`、`InvoiceMapper.java` 与相关 VO/DO 已完成客户归属校验、下载/推送前置校验、账单状态联动与推送状态回写 ✅ - [x] 已完成 `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` 文档校验 ✅ - [x] 已完成 `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` 最小编译验证 ✅ +- [x] **完成 REV-005 作废与红冲边界预留收口（US4）** ✅ (2026-03-17) + - [x] 已在 `12_REV_Detailed.md` 明确 `INVALID`、`RED_INK` 仅作为后续阶段状态与扩展入口，不纳入一期正常开票闭环 ✅ + - [x] 已在 `03_Interface_Design.md` 明确 `IF-REV-008`、`IF-CS-004` 当前阶段不承诺作废/红冲消费与处理实现，仅保留协同与状态入口 ✅ + - [x] 已在 `01_Project_Progress.md` 回写 US4 边界收口决策，便于后续评审与任务拆解引用 ✅ +- [x] **完成 SYS-002 需求拆解总表与实现评估整理** ✅ (2026-03-17) + - [x] 新增 `15_SYS002_Requirement_Breakdown.md`，形成 `SYS002-REQ-001 ~ 015` 的统一需求拆解口径 ✅ + - [x] 基于 `backend/sw-business` 与 `backend/sw-business-bank` 输出已实现 / 部分实现 / 未见实现评估结果 ✅ + - [x] 形成 TAPD Story/Task 转换建议，可直接用于后续 TAPD 建模与跟踪 ✅ ### 📋 工作范围基线对齐 diff --git a/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md b/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md new file mode 100644 index 0000000..997df1e --- /dev/null +++ b/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md @@ -0,0 +1,303 @@ +# SYS-002 需求拆解与实现评估 + +## 文档定位 + +本文档用于沉淀 `SYS-002` 营收业务系统的需求拆解结果、当前代码实现评估以及 TAPD 转换建议，作为后续 Speckit 立项、TAPD Story/Task 建模、文档修订与开发闭环跟踪的统一入口。 + +## 事实来源 + +- `docs/design/02_Detailed_Design/01_Detailed_Design.md` +- `docs/design/02_Detailed_Design/12_REV_Detailed.md` +- `docs/design/02_Detailed_Design/13_CS_Detailed.md` +- `docs/design/03_Technical_Design/03_Interface_Design.md` +- `backend/sw-business/` +- `backend/sw-business-bank/` +- `docs/design/00_Management/03_Task_Checklist.md` + +## 粒度说明 + +- 本文中的 `SYS002-REQ-xxx` 作为最小需求粒度，适合对应一个 TAPD Story 或一个 speckit feature。 +- 本文中的 `T-xxx-xx` 作为执行粒度，适合对应 TAPD Task 或 speckit.tasks 中的任务项。 + +## SYS-002 需求总览表 + +| 需求编号 | 所属模块 | 需求名称 | 需求说明 | 协同系统 | 关键接口 | 核心数据对象 | 建议粒度 | +|---|---|---|---|---|---|---|---| +| SYS002-REQ-001 | REV-001 | 客户主档与账户管理 | 维护客户、账户、联系人、水表绑定等主数据 | CS / INST | IF-REV-001 / IF-REV-002 | biz_cust、biz_account、biz_cust_contact、biz_cust_meter | Story | +| SYS002-REQ-002 | REV-001 | 开票/托收/代扣关系维护 | 维护客户开票资料、托收关系、代扣关系、渠道绑定关系 | SYS-008 / SYS-009 | IF-REV-002 | biz_cust_invoice、biz_cust_collection_rel、biz_cust_withholding_rel、biz_cust_app_binds | Story | +| SYS002-REQ-003 | REV-002 | 抄表任务与数据采集 | 生成抄表任务并提交人工/远传抄表数据 | IoT / SYS-006 | IF-REV-004 / IF-EXT-009 | biz_meter_read、biz_reading_data、biz_last_reading、biz_reading_logs | Story | +| SYS002-REQ-004 | REV-002 | 开账计费与账单生成 | 基于价格模板、阶梯规则、费用组成生成营业账 | - | IF-REV-005 | biz_charge、biz_charge_detail、biz_price_*、biz_cost_component | Story | +| SYS002-REQ-005 | REV-003 | 收费核销处理 | 柜台收费、余额抵扣、多账单组合核销 | SYS-009 | IF-REV-006 | biz_charge、biz_charge_detail、biz_collection | Story | +| SYS002-REQ-006 | REV-003 | 支付下单与结果回写 | 发起支付订单并处理异步回调结果 | SYS-009 | IF-EXT-004 / IF-EXT-005 | bk_transaction、bk_transaction_callback、bk_transaction_exception | Story | +| SYS002-REQ-007 | REV-004 | 账务调整处理 | 支持金额调整、水量调整、退款、冲正、坏账 | - | IF-REV-007 | biz_charge、biz_charge_detail、biz_operat_log、bk_transaction* | Story | +| 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-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 | +| SYS002-REQ-015 | REV-009 | 业务参数配置 | 维护价格模板、业务参数、页面参数、规则配置 | UP | IF-REV-012 | biz_parameter_settings、biz_price_*、biz_page_settings* | Story | + +## Story 与 speckit feature 映射表 + +| 需求编号 | feature 名称 | 中文标题 | 类型 | +|---|---|---|---| +| SYS002-REQ-001 | `sys002-customer-master-design` | SYS-002：补齐客户主档与账户管理设计 | design | +| SYS002-REQ-002 | `sys002-customer-billing-relations-alignment` | SYS-002：统一客户开票/托收/代扣关系口径 | alignment | +| SYS002-REQ-003 | `sys002-meter-reading-design` | SYS-002：补齐抄表任务与数据采集设计 | design | +| SYS002-REQ-004 | `sys002-billing-generation-rules` | SYS-002：补齐开账计费与账单生成规则 | rules | +| SYS002-REQ-005 | `sys002-payment-writeoff-design` | SYS-002：补齐收费核销设计闭环 | design | +| SYS002-REQ-006 | `sys002-payment-channel-sync` | SYS-002：统一支付下单与结果回写口径 | sync | +| SYS002-REQ-007 | `sys002-accounting-adjustment-rules` | SYS-002：补齐账务调整处理规则 | rules | +| SYS002-REQ-008 | `sys002-invoice-apply-design` | SYS-002：补齐发票申请设计闭环 | design | +| SYS002-REQ-009 | `sys002-invoice-result-query-rules` | SYS-002：补齐发票结果查询与补偿规则 | rules | +| SYS002-REQ-010 | `sys002-invoice-writeback-sync` | SYS-002：统一发票结果回写口径 | sync | +| SYS002-REQ-011 | `sys002-reminder-event-design` | SYS-002：补齐催缴事件与通知协同设计 | design | +| SYS002-REQ-012 | `sys002-revenue-statistics-design` | SYS-002：补齐营收统计查询设计 | design | +| SYS002-REQ-013 | `sys002-bank-withholding-sync` | SYS-002：统一银行代扣与回盘协同口径 | sync | +| SYS002-REQ-014 | `sys002-reconcile-settlement-rules` | SYS-002：补齐对账与结算处理规则 | rules | +| SYS002-REQ-015 | `sys002-parameter-config-design` | SYS-002：补齐业务参数配置设计 | design | + +## 代码实现评估 + +> 评估口径： +> +> - **已实现**：在 `backend` 中已看到较明确的 Controller/Service/DO/VO/Mapper 等实现痕迹，且与当前文档口径基本对齐。 +> - **部分实现**：已看到部分实体或接口实现，但与文档中的完整业务闭环仍存在缺口，或缺少明确的端到端实现证据。 +> - **未见实现**：当前检索范围内未看到明显实现入口，或仅见文档口径，未见对应业务实现骨架。 + +| 需求编号 | 需求名称 | 实现判断 | 主要代码证据 | 说明 | +|---|---|---|---|---| +| SYS002-REQ-001 | 客户主档与账户管理 | 已实现 | `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/cust/CustController.java`、`custcontact/CustContactController.java`、`custmeter/CustMeterController.java`、`custgroup/CustGroupController.java` | 客户主档、联系人、客户分组、水表关系等已有明确后台入口。 | +| SYS002-REQ-002 | 开票/托收/代扣关系维护 | 已实现 | `custinvoice/CustInvoiceController.java`、`custcollectionrel/CustCollectionRelController.java`、`custwithholdingrel/CustWithholdingRelController.java`、`custappbinds/CustAppBindsController.java`、`custwaterusescheme/CustWaterUseSchemeController.java`、`custwaterschemerel/CustWaterSchemeRelController.java`、`custnorule/CustNoRuleController.java`、`custhubmarks/CustHubMarksController.java` | 开票、托收、代扣、绑定、规则与计划用水方案关系均见独立入口。 | +| SYS002-REQ-003 | 抄表任务与数据采集 | 已实现 | `meterbook/MeterBookController.java`、`meterread/MeterReadController.java`、`readingdata/ReadingDataController.java`、`readinglogs/ReadingLogsController.java`、`lastreading/LastReadingController.java` | 抄表计划、抄表数据、日志、上次读数均见实现入口。 | +| SYS002-REQ-004 | 开账计费与账单生成 | 部分实现 | `charge/ChargeController.java`、`chargedetail/ChargeDetailController.java`、`collection/CollectionController.java` | 已看到账单、明细、收费相关入口，但当前检索结果中未直接看到与文档 `IF-REV-005` 完全对应的“账单生成”专用接口证据。 | +| SYS002-REQ-005 | 收费核销处理 | 已实现 | `charge/ChargeController.java`、`collection/CollectionController.java`、`app/charge/AppChargeController.java`、`src/test/java/.../ChargeControllerTest.java` | 收费、账单、前台查询与基础测试均已存在。 | +| SYS002-REQ-006 | 支付下单与结果回写 | 部分实现 | `backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/app/bankcollection/BankCollectionController.java`、`transactioncallback` 相关 DO/VO、`bk_transaction_callback` 对应对象 | 银行/支付侧基础能力存在，但当前未在 `sw-business` 中直接看到与 `IF-EXT-004/005` 完全同名的营收主入口定义，整体按部分实现保守判断。 | +| SYS002-REQ-007 | 账务调整处理 | 已实现 | `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/charge/ChargeServiceImpl.java`、`controller/admin/charge/vo/AccountingAdjustRespVO.java` | 已见 `approvalRequired`、`writeBackStatus`、账务调整响应 VO 与服务逻辑。 | +| 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-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` | 对账批次、差异、结算批次与状态枚举均已具备。 | +| SYS002-REQ-015 | 业务参数配置 | 已实现 | `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/parametersettings/ParameterSettingsController.java`、`controller/app/parametersettings/AppParameterSettingsController.java` | 后台与 App 侧参数配置入口均已存在。 | + +## TAPD 转换建议 + +### Story 建议表 + +| TAPD Story 标题 | 对应需求编号 | feature 名称 | 当前实现状态 | 建议优先级 | 建议说明 | +|---|---|---|---|---|---| +| SYS-002：补齐客户主档与账户管理设计 | SYS002-REQ-001 | `sys002-customer-master-design` | 已实现 | 中 | 以文档收口、接口/数据库/详设一致性校核为主。 | +| SYS-002：统一客户开票/托收/代扣关系口径 | SYS002-REQ-002 | `sys002-customer-billing-relations-alignment` | 已实现 | 中 | 重点核对关系表、主数据边界与上下游依赖。 | +| SYS-002：补齐抄表任务与数据采集设计 | SYS002-REQ-003 | `sys002-meter-reading-design` | 已实现 | 中 | 适合作为文档与实现追溯收口项。 | +| SYS-002：补齐开账计费与账单生成规则 | SYS002-REQ-004 | `sys002-billing-generation-rules` | 部分实现 | 高 | 当前最适合继续做文档与代码对齐核查。 | +| SYS-002：补齐收费核销设计闭环 | SYS002-REQ-005 | `sys002-payment-writeoff-design` | 已实现 | 中 | 重点补收费规则、凭证、核销边界。 | +| SYS-002：统一支付下单与结果回写口径 | SYS002-REQ-006 | `sys002-payment-channel-sync` | 部分实现 | 高 | 需继续核实营收主系统与银行/支付子系统的边界。 | +| SYS-002：补齐账务调整处理规则 | SYS002-REQ-007 | `sys002-accounting-adjustment-rules` | 已实现 | 中 | 以规则闭环和接口字段口径统一为主。 | +| 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-012 | `sys002-revenue-statistics-design` | 未见实现 | 中 | 建议先确认范围，再决定是否立项。 | +| SYS-002：统一银行代扣与回盘协同口径 | SYS002-REQ-013 | `sys002-bank-withholding-sync` | 已实现 | 中 | 已有银行子系统实现，建议做跨文档口径收口。 | +| SYS-002：补齐对账与结算处理规则 | SYS002-REQ-014 | `sys002-reconcile-settlement-rules` | 已实现 | 中 | 重点收口对账差异分类与结算边界。 | +| SYS-002：补齐业务参数配置设计 | SYS002-REQ-015 | `sys002-parameter-config-design` | 已实现 | 中 | 适合做参数配置与统一平台边界校核。 | + +### Task 模板（TAPD） + +建议每个 Story 下面至少拆以下通用 Task： + +| Task 模板标题 | 任务说明 | +|---|---| +| 对齐详细设计口径 | 检查 `12_REV_Detailed.md` 与相关正文模块是否完整覆盖该需求 | +| 对齐接口设计口径 | 检查 `03_Interface_Design.md` 中接口边界、字段、状态是否一致 | +| 对齐数据库口径 | 检查 `01_Database_Design.md` 与实际 DO/Mapper 是否一致 | +| 校核代码实现状态 | 检查 Controller/Service/DO/VO/Mapper 是否已形成完整闭环 | +| 输出验收结论 | 形成“已实现 / 部分实现 / 未见实现”与后续动作建议 | + +## 当前建议优先推进项 + +### P0 + +- `SYS002-REQ-004` 开账计费与账单生成 +- `SYS002-REQ-006` 支付下单与结果回写 +- `SYS002-REQ-011` 催缴与通知协同 + +### P1 + +- `SYS002-REQ-012` 营收统计查询 +- `SYS002-REQ-013` 银行代扣与回盘 +- `SYS002-REQ-014` 对账与结算处理 + +### 已完成度较高，可转验收/归档 + +- `SYS002-REQ-008` 发票申请受理 +- `SYS002-REQ-009` 发票结果查询与补偿 +- `SYS002-REQ-010` 发票结果回写 + +## 可直接录入 TAPD 的 Story / Task 清单 + +> 说明：以下内容按 TAPD 录入习惯整理，可直接作为 Story 标题、描述与 Task 子项使用。 + +### P0：优先立项 + +#### Story 1 + +- 标题：`SYS-002：补齐开账计费与账单生成规则` +- 对应需求：`SYS002-REQ-004` +- feature：`sys002-billing-generation-rules` +- 优先级：`高` +- 当前实现状态：`部分实现` +- Story 描述： + - 目标：补齐抄表后开账计费、费用组成、阶梯计价、账单生成与营业账落库规则。 + - 事实来源：`12_REV_Detailed.md` 中 REV-002、`03_Interface_Design.md` 中 `IF-REV-005`、现有 `charge/chargedetail/collection` 相关实现。 + - 当前判断：已看到账单与收费相关后台入口，但未直接看到与“账单生成”闭环完全对应的专用接口与规则收口。 + - 验收要点：明确账单生成入口、计费规则来源、费用明细结构、异常处理与落账结果。 +- 推荐 Task： + - `T-004-01` 对齐详细设计中的开账计费规则与账单生成流程 + - `T-004-02` 对齐接口设计中 `IF-REV-005` 的输入输出与状态语义 + - `T-004-03` 对齐数据库设计中的账单主表、明细表、价格模板与费用项关系 + - `T-004-04` 校核 `ChargeController` / `ChargeDetailController` 与账单生成闭环是否一致 + - `T-004-05` 输出“已实现缺口 / 文档缺口 / 后续动作”结论 + +#### Story 2 + +- 标题：`SYS-002：统一支付下单与结果回写口径` +- 对应需求：`SYS002-REQ-006` +- feature：`sys002-payment-channel-sync` +- 优先级：`高` +- 当前实现状态：`部分实现` +- Story 描述： + - 目标：统一营收主系统、银行/支付子系统之间的支付下单、异步回调、异常补偿与结果回写口径。 + - 事实来源：`03_Interface_Design.md` 中 `IF-EXT-004` / `IF-EXT-005`、`sw-business-bank` 中交易与回调相关对象。 + - 当前判断：银行/支付侧基础能力存在，但营收主系统入口、边界归属与回写闭环仍需进一步核实。 + - 验收要点：明确支付订单创建责任方、回调幂等规则、异常补偿机制、支付结果与账务核销关系。 +- 推荐 Task： + - `T-006-01` 对齐支付下单与回调处理的业务边界 + - `T-006-02` 对齐 `IF-EXT-004` / `IF-EXT-005` 字段口径与状态含义 + - `T-006-03` 校核 `bk_transaction`、`bk_transaction_callback`、异常表与主业务单据关系 + - `T-006-04` 校核 `sw-business` 与 `sw-business-bank` 的控制器/服务闭环 + - `T-006-05` 输出支付链路实现结论与缺口清单 + +#### Story 3 + +- 标题：`SYS-002：补齐催缴事件与通知协同设计` +- 对应需求：`SYS002-REQ-011` +- feature：`sys002-reminder-event-design` +- 优先级：`高` +- 当前实现状态：`未见实现` +- Story 描述： + - 目标：补齐欠费催缴对象生成、通知触发、通知结果回写与催缴追踪闭环。 + - 事实来源：`12_REV_Detailed.md` 中 REV-006、`03_Interface_Design.md` 中 `IF-EXT-008`。 + - 当前判断：当前代码检索范围内未见明确的催缴、通知、消息协同控制器或服务骨架。 + - 验收要点：明确催缴触发时机、催缴对象筛选条件、通知方式、回写字段与失败重试机制。 +- 推荐 Task： + - `T-011-01` 对齐催缴业务场景、触发条件与对象筛选规则 + - `T-011-02` 对齐通知协同接口与通知结果回写字段 + - `T-011-03` 对齐催缴过程表、操作日志与状态流转规则 + - `T-011-04` 校核当前代码中是否存在可复用的消息/通知基础能力 + - `T-011-05` 输出是否需独立立项开发的结论 + +### P1：第二优先级 + +#### Story 4 + +- 标题：`SYS-002：补齐营收统计查询设计` +- 对应需求：`SYS002-REQ-012` +- feature：`sys002-revenue-statistics-design` +- 优先级：`中` +- 当前实现状态：`未见实现` +- Story 描述： + - 目标：补齐营收、收费、欠费、渠道、客户维度统计查询能力与口径定义。 + - 当前判断：文档已定义统计范围，但当前代码检索中未见明确统计/报表后台入口。 +- 推荐 Task： + - `T-012-01` 对齐统计主题、维度、指标口径 + - `T-012-02` 对齐统计接口与查询条件定义 + - `T-012-03` 对齐统计视图/汇总表与数据来源 + - `T-012-04` 校核代码是否已有隐含统计实现或需新增模块 + - `T-012-05` 输出统计专题立项建议 + +#### Story 5 + +- 标题：`SYS-002：统一银行代扣与回盘协同口径` +- 对应需求：`SYS002-REQ-013` +- feature：`sys002-bank-withholding-sync` +- 优先级：`中` +- 当前实现状态：`已实现` +- Story 描述： + - 目标：统一代扣协议、批次生成、回盘明细与状态回写口径。 + - 当前判断：银行子系统已具备代扣批次、明细、协议与应用侧入口，重点在跨文档一致性收口。 +- 推荐 Task： + - `T-013-01` 对齐代扣业务流程与回盘处理说明 + - `T-013-02` 对齐银行接口字段与批次状态枚举 + - `T-013-03` 对齐数据库对象与实现对象映射 + - `T-013-04` 校核批次、明细、协议实现闭环 + - `T-013-05` 输出验收与归档结论 + +#### Story 6 + +- 标题：`SYS-002：补齐对账与结算处理规则` +- 对应需求：`SYS002-REQ-014` +- feature：`sys002-reconcile-settlement-rules` +- 优先级：`中` +- 当前实现状态：`已实现` +- Story 描述： + - 目标：补齐对账批次、差异处理、结算批次与状态流转规则。 + - 当前判断：对账与结算后台骨架较完整，重点是规则、差异分类与边界定义收口。 +- 推荐 Task： + - `T-014-01` 对齐对账、差异、结算的业务规则与流程 + - `T-014-02` 对齐状态机、差异分类与处理动作 + - `T-014-03` 对齐数据库设计与状态枚举定义 + - `T-014-04` 校核对账批次、差异、结算实现闭环 + - `T-014-05` 输出规则闭环与验收建议 + +### 验收 / 归档优先项 + +#### Story 7 + +- 标题：`SYS-002：补齐发票申请设计闭环` +- 对应需求：`SYS002-REQ-008` +- feature：`sys002-invoice-apply-design` +- 优先级：`高` +- 当前实现状态：`已实现` +- 推荐 Task： + - `T-008-01` 对齐发票申请受理流程与字段口径 + - `T-008-02` 对齐申请单号、受理号、幂等控制与落库规则 + - `T-008-03` 校核接口、数据库与实现一致性 + - `T-008-04` 输出验收与归档结论 + +#### Story 8 + +- 标题：`SYS-002：补齐发票结果查询与补偿规则` +- 对应需求：`SYS002-REQ-009` +- feature：`sys002-invoice-result-query-rules` +- 优先级：`高` +- 当前实现状态：`已实现` +- 推荐 Task： + - `T-009-01` 对齐发票结果查询、补偿与兜底机制 + - `T-009-02` 对齐重试次数、最近结果、错误信息等字段口径 + - `T-009-03` 校核实现逻辑与文档规则一致性 + - `T-009-04` 输出验收与归档结论 + +#### Story 9 + +- 标题：`SYS-002：统一发票结果回写口径` +- 对应需求：`SYS002-REQ-010` +- feature：`sys002-invoice-writeback-sync` +- 优先级：`高` +- 当前实现状态：`已实现` +- 推荐 Task： + - `T-010-01` 对齐发票状态、票号、下载地址、红冲/作废回写字段 + - `T-010-02` 对齐回写幂等、状态保护与异常处理规则 + - `T-010-03` 校核回写接口、Mapper 与服务逻辑一致性 + - `T-010-04` 输出验收与归档结论 + +## 使用建议 + +1. 若用于 TAPD：优先按上面的 9 个 Story 直接建单，再按对应 `T-xxx-xx` 录入 Task。 +2. 若用于 speckit：按 feature 名称逐一建立 `spec.md`，将“代码实现评估”作为 `Current State` 输入。 +3. 若用于文档治理：优先处理“部分实现 / 未见实现”的需求项，减少文档与实现偏差。