diff --git a/docs/design/00_Management/01_Project_Progress.md b/docs/design/00_Management/01_Project_Progress.md index 25fe1ae..c618327 100644 --- a/docs/design/00_Management/01_Project_Progress.md +++ b/docs/design/00_Management/01_Project_Progress.md @@ -330,3 +330,8 @@ - 明确旧“催缴记录 / 停水记录 / 预存短信记录”按历史只读口径承接,不新增同名在线主表;停复水在本轮仅保留联动边界、处置引用和追溯关系。 - 启动并完成 `REV-007` Speckit feature `004-rev007-revenue-statistics-design` 的 `specify -> plan -> tasks` 工件链,形成统计主题、维度、指标、`IF-REV-010` 与数据库承接口径的正式设计基线。 - `REV-007` 当前收口结论为“设计补齐推进中、代码入口未见明确实现”;本轮重点是统一正式文档与治理台账,不将预测分析、BI 专题或独立数仓能力写成既成事实。 +- 完成 `REV-002` Speckit feature `005-rev002-billing-generation-gap` 的第一轮正式文档收口,补齐 `12_REV_Detailed.md` 中开账触发前提、规则来源、结果表达、特殊开账统一模型与下游排除项。 +- 完成 `03_Interface_Design.md` 中 `IF-REV-005` 的边界补强,明确请求前提、失败阻断语义、成功/失败结果表达以及与收费、发票、催缴链路的职责边界。 +- 完成 `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` 结算方式,因此治理判断继续维持“部分实现”。 diff --git a/docs/design/00_Management/03_Task_Checklist.md b/docs/design/00_Management/03_Task_Checklist.md index 9b91d3b..2fd2a8b 100644 --- a/docs/design/00_Management/03_Task_Checklist.md +++ b/docs/design/00_Management/03_Task_Checklist.md @@ -213,6 +213,11 @@ - [x] 新增 `15_SYS002_Requirement_Breakdown.md`,形成 `SYS002-REQ-001 ~ 015` 的统一需求拆解口径 ✅ - [x] 基于 `backend/sw-business` 与 `backend/sw-business-bank` 输出已实现 / 部分实现 / 未见实现评估结果 ✅ - [x] 形成 TAPD Story/Task 转换建议,可直接用于后续 TAPD 建模与跟踪 ✅ +- [x] **完成 REV-002 开账计费与账单生成缺口第一轮文档收口** ✅ (2026-03-18) + - [x] `12_REV_Detailed.md` 已补齐开账触发前提、计费规则来源、结果表达、特殊开账统一模型与下游排除项 ✅ + - [x] `03_Interface_Design.md` 已补齐 `IF-REV-005` 的请求前提、阻断语义、成功/失败结果表达与与收费/发票/催缴的边界说明 ✅ + - [x] `01_Database_Design.md`、`15_SYS002_Requirement_Breakdown.md` 已明确 `biz_charge` / `biz_charge_detail`、价格规则对象和历史特殊开账的正式承接口径,并保持 `SYS002-REQ-004` 为“部分实现” ✅ + - [x] 已结合 `ChargeController`、`ChargeServiceImpl` 与 `ReadingDataServiceImpl` 证据精修 `REV-002` 判断,确认已支持按 `readingDataIds` 批量复核/开账并落库 `biz_charge` / `biz_charge_detail`,但仍保留输入范围、结构化返回与非 `ACTUAL_USAGE` 结算支持缺口 ✅ - [x] **完成整体架构图模块清单整理与详细设计承接对齐** ✅ (2026-03-18) - [x] 新增 `docs/design/01_Overview/05_Module_Inventory.md`,整理整体架构图中的层级、子系统、模块与当前详设承接关系 ✅ - [x] 更新 `01_Overview/README.md` 与 `02_Detailed_Design/README.md`,明确模块清单作为模块枚举与承接核对入口 ✅ diff --git a/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md b/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md index 893a3ca..a93bf7e 100644 --- a/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md +++ b/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md @@ -72,7 +72,7 @@ | 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-004 | 开账计费与账单生成 | 部分实现 | `charge/ChargeController.java`、`service/charge/ChargeServiceImpl.java`、`service/readingdata/impl/ReadingDataServiceImpl.java` | 已见 `/business/charge/charge-batch` 与 `/business/charge/check-charge-batch` 两个后台入口,可按 `readingDataIds` 批量复核/开账,并由 `generateSingleChargeWithCache` 写入 `biz_charge` / `biz_charge_detail`;但当前请求仍只接受 `readingDataIds`,返回值仅为成功条数字符串,单条失败依赖日志/布尔值跳过,且仅支持 `ACTUAL_USAGE` 结算方式,因此与正式 `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 与服务逻辑。 | @@ -94,7 +94,7 @@ | 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-004 | `sys002-billing-generation-rules` | 部分实现 | 高 | 本轮已核实 backend 具备按 `readingDataIds` 批量复核/开账并落库 `biz_charge` / `biz_charge_detail` 的能力;下一步应补齐正式 `IF-REV-005` 的请求范围扩展、结构化成功/失败结果以及非 `ACTUAL_USAGE` 结算方式支持。 | | 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` | 已实现 | 中 | 以规则闭环和接口字段口径统一为主。 | diff --git a/docs/design/02_Detailed_Design/12_REV_Detailed.md b/docs/design/02_Detailed_Design/12_REV_Detailed.md index 9d40088..d21be32 100644 --- a/docs/design/02_Detailed_Design/12_REV_Detailed.md +++ b/docs/design/02_Detailed_Design/12_REV_Detailed.md @@ -153,11 +153,23 @@ flowchart TD ### 关键规则 -1. 抄表数据同时校验本次读数、上次读数、用量波动和抄表状态。 -2. 异常抄表支持估抄、补抄、重录、人工复核。 -3. 开账按价格归属、价格模板、费用组成、阶梯规则、计划用水方案综合计算。 -4. 审核通过后的营业账方可进入收费、催缴和发票流程。 -5. 远传抄表数据可由 `SYS-006` / IoT 能力提供采集支撑,但账单生成仍归属 SYS-002。 +1. 抄表数据同时校验本次读数、上次读数、用量波动和抄表状态,只有通过校验或完成异常复核的数据才能进入开账。 +2. 异常抄表支持估抄、补抄、重录、人工复核;异常处理的目标是形成可继续开账或明确阻断的统一结论,而不是绕开开账规则单独落账。 +3. `IF-REV-005` 的正式边界是“抄表校验完成后的账单生成”,不负责收费核销、发票开具、催缴执行和统计分析。 +4. 开账计费按价格归属、价格模板、费用组成、阶梯规则、计划用水方案综合计算;价格配置缺失、费用组成不完整或规则冲突时,必须阻断生成并返回失败原因。 +5. 账单生成结果统一由 `biz_charge` 与 `biz_charge_detail` 承接:主表表达客户、账期、应收日期、账单总金额和主状态,明细表表达费用组成、用量、单价和明细金额。 +6. 特殊开账、无码客户开账、罚款类开账等非标准来源,仍纳入同一营业账主明细模型承接,通过来源类型、业务类型、依据说明和操作留痕区分,不单独扩展平行账表。 +7. 审核通过后的营业账方可进入收费、催缴和发票流程;后续链路只能消费已生成账单结果,不反向改变本接口的生成边界。 +8. 远传抄表数据可由 `SYS-006` / IoT 能力提供采集支撑,但账单生成仍归属 SYS-002。 + +### 开账触发与结果表达 + +- 触发前提:正式口径下可按抄表批次、指定客户范围或指定抄表任务范围组织生成;当前 backend 已落地的入口为按 `readingDataIds` 批量复核并开账,对应 `ChargeController.generateCheckChargeBatch`、`ChargeServiceImpl.generateCheckChargeBatch` 与 `ReadingDataServiceImpl.batchReCheckReadingData`。 +- 规则来源:价格归属决定客户适用的价格口径;价格模板、阶梯规则、费用组成和计划用水方案共同决定营业账主表金额与明细拆分方式。 +- 当前承接证据:`ChargeServiceImpl.generateSingleChargeWithCache` 成功路径会写入 `biz_charge` 主表、循环写入 `biz_charge_detail` 明细,并回写抄表数据开账状态,说明现有实现已具备“按抄表数据 ID 生成营业账主明细”的 backend 基础。 +- 结果表达:正式 `IF-REV-005` 应返回成功清单、失败清单、生成汇总及主明细级结果;当前 backend 返回仍为“本次复核成功X条 / 本次开账成功Y条”的字符串拼接,尚未形成结构化成功/失败结果对象。 +- 阻断与限制:价格模板不存在、费用调整配置缺失、结算方式非 `ACTUAL_USAGE` 等场景当前会直接阻断单条生成;其中固定水量、按人口数、最低消费等非实际水量结算方式仍未纳入当前实现。 +- 下游边界:`REV-002` 只负责生成营业账结果并交由后续审核/收费链路消费,不在本章节扩展收费核销、发票申请或催缴执行细节。 ### 核心数据 diff --git a/docs/design/03_Technical_Design/01_Database_Design.md b/docs/design/03_Technical_Design/01_Database_Design.md index 73ecbec..771c05b 100644 --- a/docs/design/03_Technical_Design/01_Database_Design.md +++ b/docs/design/03_Technical_Design/01_Database_Design.md @@ -1096,6 +1096,23 @@ retrieval_priority: P0 | `unit_price` | 单价 | | `detail_amount` | 明细金额 | +#### REV-002 账单生成承接口径 + +| 对象 | 正式口径 | 承接说明 | +| :--- | :--- | :--- | +| `biz_charge` | 账单生成主结果对象 | 统一表达客户、账期、抄表/开账来源、账单总金额、收费状态与应缴日期,不单独发明新的在线账单主模型 | +| `biz_charge_detail` | 账单生成明细对象 | 统一表达费用组成、用量、单价、明细金额,与主表通过 `charge_id` 建立主明细关系 | +| `biz_price_category`、`biz_price_template`、`biz_price_adjustment_snap`、`biz_price_tier_adjustment` | 计费规则来源对象 | 用于表达价格归属、基础价格、调价快照与阶梯规则来源,支撑账单金额计算与追溯 | +| `biz_cost_component` | 费用组成定义对象 | 用于表达水费、污水费、附加费、罚款类费用等明细分类,不将费用组成直接硬编码到主表 | +| `biz_water_use_scheme`、`biz_water_use_scheme_tier`、`biz_exceed_water_use_scheme` | 计划用水与超计划规则对象 | 用于承接计划用水、超计划与阶梯类扩展规则,不额外发明平行的特殊开账规则表 | +| 历史开账记录、特殊开账 | 历史只读 / 同模型承接对象 | 统一纳入 `biz_charge`、`biz_charge_detail` 与操作留痕承接,通过来源类型、业务类型、依据说明区分,不单设“特殊开账表” | + +> REV-002 承接口径:账单生成结果统一由 `biz_charge`、`biz_charge_detail` 承接,关键规则来源继续由 `biz_price_*`、`biz_cost_component` 与计划用水相关对象提供;当价格模板、费用组成或规则关系不完整时,应按“阻断生成”口径处理。 +> +> 当前 backend 证据:`ChargeServiceImpl.generateSingleChargeWithCache` 成功路径已执行 `chargeMapper.insert(charge)`、`chargeDetailService.insertChargeDetail(detail)` 与 `updateReadingDataCheckState(readingDataId, 1)`,说明现有实现已能把按 `readingDataIds` 复核/开账的结果落入 `biz_charge`、`biz_charge_detail`。 +> +> 当前承接缺口:接口层返回仍为成功条数字符串,失败阻断主要依赖日志与布尔值,且仅支持 `ACTUAL_USAGE` 结算方式;`biz_charge` / `biz_charge_detail` 的主明细结果、失败对象范围和结构化原因尚未提升为正式 `IF-REV-005` 契约返回。 +> > REV-004 承接口径:水量调整、金额调整、退款、冲正、坏账申请统一以 `biz_charge`、`biz_charge_detail` 作为账单主明细承接对象;当前数据库主文档不新增独立账务细表来承接一期场景。 ### biz_collection / biz_withholding (托收与代扣主表) diff --git a/docs/design/03_Technical_Design/03_Interface_Design.md b/docs/design/03_Technical_Design/03_Interface_Design.md index 0ebf8ee..2fa94fa 100644 --- a/docs/design/03_Technical_Design/03_Interface_Design.md +++ b/docs/design/03_Technical_Design/03_Interface_Design.md @@ -372,9 +372,21 @@ retrieval_priority: P0 | 归属模块 | REV-002 | | 请求方式 | POST | | 请求路径 | `/admin-api/revenue/charge/generate` | -| 功能描述 | 基于抄表结果、水价模板、阶梯规则、费用组成生成账单 | +| 功能描述 | 基于抄表结果、水价模板、阶梯规则、费用组成生成账单,并返回成功清单、失败清单与生成汇总 | | 核心表 | `biz_charge`、`biz_charge_detail`、`biz_price_template`、`biz_price_tier_adjustment`、`biz_cost_component` | +边界约束: +- 本接口只负责抄表校验完成后的账单生成,不直接承接收费核销、发票申请、催缴执行或统计汇总。 +- 正式请求范围可按抄表批次、客户集合或抄表任务集合组织;当前 backend 已实现入口为 `/business/charge/charge-batch` 与 `/business/charge/check-charge-batch`,请求体仅接受 `readingDataIds`。 +- 价格模板、费用组成、阶梯规则、计划用水方案等任一关键规则缺失时,应阻断生成并返回失败原因,而不是生成不完整账单。 +- 特殊开账、无码客户开账、罚款类开账等非标准来源仍沿用同一 `biz_charge` / `biz_charge_detail` 承接口径,不单设平行在线账表。 +- 当前实现仅支持 `SettleTypeEnum.ACTUAL_USAGE`;固定水量、按人口数、最低消费等结算方式暂未纳入现有开账链路。 + +当前 backend 证据与契约缺口: +- `ChargeServiceImpl.generateCheckChargeBatch` 已支持“批量复核 + 批量开账”,并通过 `generateSingleChargeWithCache` 写入 `biz_charge`、`biz_charge_detail`,说明主明细承接路径已存在。 +- 返回值当前为 `CommonResult`,仅表达“本次复核成功X条 / 本次开账成功Y条”,尚未提供正式契约要求的成功清单、失败清单、生成汇总和主明细结果对象。 +- 单条失败当前主要以 `log.warn` + `false` 跳过处理,尚未形成可直接对外返回的结构化阻断码、失败原因集合与对象范围。 + ### IF-REV-006 缴费处理接口 | 项目 | 说明 | diff --git a/specs/005-rev002-billing-generation-gap/checklists/requirements.md b/specs/005-rev002-billing-generation-gap/checklists/requirements.md new file mode 100644 index 0000000..1fd9aab --- /dev/null +++ b/specs/005-rev002-billing-generation-gap/checklists/requirements.md @@ -0,0 +1,34 @@ +# Specification Quality Checklist: REV-002 开账计费与账单生成缺口补齐 + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-03-18 +**Feature**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/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 + +- 当前规格基于现有正式主文档、治理台账和检索结论生成;`REV-002` 默认按“部分实现,但账单生成闭环仍需进一步收口”处理。 diff --git a/specs/005-rev002-billing-generation-gap/contracts/rev002-billing-contract.md b/specs/005-rev002-billing-generation-gap/contracts/rev002-billing-contract.md new file mode 100644 index 0000000..2e0486b --- /dev/null +++ b/specs/005-rev002-billing-generation-gap/contracts/rev002-billing-contract.md @@ -0,0 +1,53 @@ +# Contract: REV-002 开账计费与账单生成缺口补齐 + +## 1. Formal Interface Allocation + +| Interface | Role | Direction | +|---|---|---| +| `IF-REV-005` | `REV-002` 开账计费与账单生成的正式业务接口 | `SYS-002` 内部正式业务接口 | + +约束: + +- `IF-REV-005` 保持为 `REV-002` 的正式账单生成接口编号,不新增新的开账生成接口编号。 +- 本接口只承接开账计费与账单生成,不扩展到收费核销、发票申请或催缴触发。 + +## 2. Request Contract + +| Field | Meaning | Required | +|---|---|---| +| `billPeriod` | 账期 | 是 | +| `readingBatchNo` | 抄表批次号 | 否 | +| `customerIds` | 客户集合 | 否 | +| `meterReadIds` | 抄表任务集合 | 否 | +| `dueDate` | 应收截止日期 | 是 | +| `operatorId` | 发起人 | 否 | + +补充约束: + +- 请求前提是抄表数据已通过校验或异常复核允许进入开账。 +- 至少应提供批次、客户范围或抄表任务范围中的一种有效筛选条件。 + +## 3. Response Contract + +| Field | Meaning | +|---|---| +| `generateCount` | 成功生成账单数量 | +| `successList` | 成功明细集合 | +| `successList[].chargeId` | 账单主键 | +| `successList[].chargeCode` | 账单编号 | +| `successList[].custId` | 客户标识 | +| `successList[].totalAmount` | 账单总金额 | +| `failureList` | 失败明细集合 | +| `failureList[].reason` | 失败原因 | + +## 4. Result Boundary Contract + +- 账单生成结果统一以 `biz_charge` 作为主结果、`biz_charge_detail` 作为明细结果承接。 +- 特殊开账、无码客户开账或罚款类开账应通过来源类型、业务类型或依据说明纳入统一账单主模型,不单独发明平行主表。 +- 账单生成成功后只表达“已生成营业账”的结果边界,后续收费、催缴、开票由下游模块继续承接。 + +## 5. Exception Contract + +- 当价格模板、阶梯规则、费用组成、计划用水方案或必要来源数据缺失时,应阻断生成并返回失败原因。 +- 失败语义必须与现有抄表开账类错误码口径一致,不得仅写日志而不在接口结果中表达。 +- 异常复核、估抄、补抄、重录等场景只定义“是否允许进入生成”边界,不展开具体实现细节。 diff --git a/specs/005-rev002-billing-generation-gap/data-model.md b/specs/005-rev002-billing-generation-gap/data-model.md new file mode 100644 index 0000000..a93c7f6 --- /dev/null +++ b/specs/005-rev002-billing-generation-gap/data-model.md @@ -0,0 +1,137 @@ +# Data Model: REV-002 开账计费与账单生成缺口补齐 + +## 1. Billing Trigger + +### Purpose + +定义从抄表校验结果进入开账计费流程的正式触发条件。 + +### Key Fields + +| Field | Description | Rule | +|---|---|---| +| `billPeriod` | 账期 | 必填 | +| `readingBatchNo` | 抄表批次号 | 可为空 | +| `meterReadIds` | 抄表任务集合 | 至少存在批次或任务范围 | +| `validatedFlag` | 是否已通过校验 | 必填;未校验不得生成 | +| `dueDate` | 应收截止日期 | 必填 | +| `operatorId` | 发起人 | 可为空 | + +### Relationships + +- 来源于 `biz_meter_read`、`biz_reading_data`、`biz_last_reading` +- 可触发一个或多个 `Billing Result` + +## 2. Billing Rule Source + +### Purpose + +定义账单生成过程依赖的价格和费用规则来源。 + +### Key Fields + +| Field | Description | Rule | +|---|---|---| +| `priceCategoryCode` | 价格归属编码 | 必填 | +| `priceTemplateCode` | 价格模板编码 | 必填 | +| `tierRuleRef` | 阶梯规则引用 | 可为空;按场景适用 | +| `costComponentSet` | 费用组成集合 | 至少 1 项 | +| `waterUseSchemeRef` | 计划用水方案引用 | 可为空;按场景适用 | +| `ruleEffectiveFlag` | 规则是否完整有效 | 必填;无效时阻断生成 | + +### Relationships + +- 一个 `Billing Rule Source` 可服务多个 `Billing Trigger` +- 一个 `Billing Rule Source` 可生成多个 `Charge Detail` + +## 3. Billing Result + +### Purpose + +定义账单生成后的主结果表达。 + +### Key Fields + +| Field | Description | Rule | +|---|---|---| +| `chargeId` | 账单主键 | 唯一 | +| `chargeCode` | 账单编号 | 唯一 | +| `custId` | 客户标识 | 必填 | +| `accountId` | 账户标识 | 可为空;按账户体系承接 | +| `billPeriod` | 账期 | 必填 | +| `totalAmount` | 账单总金额 | 必填 | +| `sourceType` | 来源类型 | 必填;普通开账/特殊开账等 | +| `chargeStatus` | 账单状态 | 必填 | +| `dueDate` | 应收截止日期 | 必填 | + +### Relationships + +- 由一个 `Billing Trigger` 触发产生 +- 包含多个 `Charge Detail` +- 后续可流转到收费、催缴、发票等下游模块 + +## 4. Charge Detail + +### Purpose + +定义营业账明细中的费用组成表达。 + +### Key Fields + +| Field | Description | Rule | +|---|---|---| +| `chargeId` | 所属账单 ID | 必填 | +| `costComponentCode` | 费用组成代码 | 必填 | +| `usageAmount` | 用量 | 可为空;按费用项适用 | +| `unitPrice` | 单价 | 可为空;按费用项适用 | +| `detailAmount` | 明细金额 | 必填 | +| `detailRemark` | 明细说明 | 可为空 | + +### Relationships + +- 归属于一个 `Billing Result` +- 引用一个 `Billing Rule Source` + +## 5. Billing Exception Result + +### Purpose + +定义账单生成失败时的正式异常返回表达。 + +### Key Fields + +| Field | Description | Rule | +|---|---|---| +| `reasonCode` | 失败原因编码 | 必填 | +| `reasonText` | 失败说明 | 必填 | +| `relatedCustomer` | 相关客户 | 可为空 | +| `relatedMeterRead` | 相关抄表任务 | 可为空 | +| `blockingFlag` | 是否阻断生成 | 固定为是 | + +### Relationships + +- 与一个 `Billing Trigger` 关联 +- 不生成 `Billing Result` + +## 6. Billing Governance Record + +### Purpose + +用于在治理台账中记录 `REV-002` 的设计状态、实现评估和后续建议。 + +### Key Fields + +| Field | Description | Rule | +|---|---|---| +| `requirementCode` | 对应需求编号 | 固定为 `SYS002-REQ-004` | +| `featureName` | Speckit feature 名称 | 必填 | +| `designStatus` | 设计状态 | 必填;设计收口中/已收口 | +| `implementationStatus` | 实现评估 | 必填;当前为部分实现 | +| `nextAction` | 后续动作 | 必填 | +| `validationRecord` | 校验记录 | 必填 | + +### Relationships + +- 关联 `01_Project_Progress.md` +- 关联 `03_Task_Checklist.md` +- 关联 `15_SYS002_Requirement_Breakdown.md` diff --git a/specs/005-rev002-billing-generation-gap/plan.md b/specs/005-rev002-billing-generation-gap/plan.md new file mode 100644 index 0000000..bf61cad --- /dev/null +++ b/specs/005-rev002-billing-generation-gap/plan.md @@ -0,0 +1,123 @@ +# Implementation Plan: REV-002 开账计费与账单生成缺口补齐 + +**Branch**: `005-rev002-billing-generation-gap` | **Date**: 2026-03-18 | **Spec**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/spec.md) +**Input**: Feature specification from `/specs/005-rev002-billing-generation-gap/spec.md` + +**Note**: 本计划面向文档治理仓库,交付对象是正式设计文档与治理台账的收口,而不是业务代码实现。 + +## Summary + +本 feature 聚焦 `REV-002` 中“抄表校验后到账单生成”的文档缺口补齐,目标是在不扩展到收费核销、发票、催缴和统计分析的前提下,统一 `IF-REV-005` 的业务边界、账单生成规则、结果表达、`biz_charge` / `biz_charge_detail` 承接口径,以及治理台账中的“部分实现”结论。 + +## 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/03_Technical_Design/01_Database_Design.md` +- `docs/design/01_Overview/03_Summary_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` +**Reference Sources**: +- `docs/guides/BACKEND_CURRENT_STATUS.md` +- `docs/guides/BACKEND_TABLE_MAPPING.md` +- `docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md` +- `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**: `REV-002` 相关详细设计、接口设计、数据库设计与治理台账的交叉收口 +**Project Type**: 文档治理仓库 +**Constraints**: +- 不新增平行正式稿,只修改既有主文档和治理文档 +- 不凭空新增业务规则、接口编号、账单主模型或独立表族 +- `IF-REV-005` 继续作为正式账单生成接口编号 +- 正式文档使用中文,仓库内链接使用相对路径 +- 治理结论保持“部分实现,账单生成闭环仍需继续校核”的真实状态 +**Scale/Scope**: 跨 6 个正式文档的中等范围一致性修订 + +## Constitution Check + +*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* + +- [x] **主文档归属已确认**:本次只修改既有主文档与治理文档,不新增平行正式稿。 +- [x] **范围基线已确认**:`REV-002` 属于既有 `SYS-002` 营收业务范围,且本轮仅收口开账计费与账单生成缺口,不跨入 `REV-003` 收费核销或其他模块。 +- [x] **Archive 使用方式合规**:Archive 与 guides 仅用于核对现状、术语和数据口径,正式结论以主文档回写为准。 +- [x] **一致性影响已列出**:受影响项包括 `IF-REV-005` 编号语义、账单生成结果表述、`biz_charge` / `biz_charge_detail` 承接口径、特殊开账承接方式、治理台账中的实现状态文字。 +- [x] **校验与台账动作已规划**:已规划单文件校验与 `make check-links`,并纳入 `01_Project_Progress.md`、`03_Task_Checklist.md`、`15_SYS002_Requirement_Breakdown.md` 的同步更新。 + +## Project Structure + +### Documentation (this feature) + +```text +specs/005-rev002-billing-generation-gap/ +├── plan.md +├── research.md +├── data-model.md +├── quickstart.md +├── contracts/ +│ └── rev002-billing-contract.md +└── tasks.md +``` + +### Repository Touchpoints + +```text +docs/design/ +├── 00_Management/ +│ ├── 01_Project_Progress.md +│ ├── 03_Task_Checklist.md +│ └── 15_SYS002_Requirement_Breakdown.md +├── 01_Overview/ +│ └── 03_Summary_Design.md +├── 02_Detailed_Design/ +│ └── 12_REV_Detailed.md +├── 03_Technical_Design/ +│ ├── 01_Database_Design.md +│ └── 03_Interface_Design.md +└── 04_Appendix/Archive/ +``` + +**Structure Decision**: +- `docs/design/02_Detailed_Design/12_REV_Detailed.md`:补齐 `REV-002` 的触发前提、规则来源、结果表达、特殊开账统一模型和排除项。 +- `docs/design/03_Technical_Design/03_Interface_Design.md`:补齐 `IF-REV-005` 的请求前提、输出语义、失败/阻断语义,以及与后续收费链路的边界。 +- `docs/design/03_Technical_Design/01_Database_Design.md`:明确 `biz_charge`、`biz_charge_detail`、价格模板、阶梯规则、费用组成和历史开账/特殊开账的正式承接口径。 +- `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`:保持“部分实现”判断,同时记录本轮文档收口成果与后续建议。 +- `docs/design/00_Management/01_Project_Progress.md`:记录本轮 `REV-002` 文档治理动作与校验结果。 +- `docs/design/00_Management/03_Task_Checklist.md`:登记本轮任务闭环状态。 + +## Phase 0 Research Output + +- `research.md` 已固定 5 项关键决策: + - `IF-REV-005` 继续作为正式账单生成接口 + - 范围只收口“抄表校验后到账单生成” + - 账单结果统一由 `biz_charge` + `biz_charge_detail` 承接 + - 异常语义统一为“阻断生成 + 返回失败原因” + - 治理台账继续保持“部分实现” + +## Phase 1 Design Output + +- `data-model.md`:定义 `Billing Trigger`、`Billing Rule Source`、`Billing Result`、`Charge Detail`、`Billing Exception Result`、`Billing Governance Record` +- `contracts/rev002-billing-contract.md`:定义 `IF-REV-005` 的 request / response / result boundary / exception contract +- `quickstart.md`:给出目标落点、建议校验命令与验收检查点 +- `AGENTS.md`:已执行 `./.specify/scripts/bash/update-agent-context.sh codex`,完成 agent context 更新 + +## Post-Design Constitution Check + +- [x] 主文档承载策略未偏离,所有设计输出都指向既有正式文档修订 +- [x] 范围仍限定在 `REV-002` 账单生成闭环,不涉及跨模块扩写 +- [x] Archive 与 guides 仅用于佐证,不直接生成正式结论 +- [x] 一致性影响已沉淀到 data model、contract 与 quickstart,可直接支撑下一步 `tasks.md` +- [x] 校验与台账动作已被明确列入 quickstart 与后续任务拆解基础 + +## Complexity Tracking + +本次计划无宪法豁免项。 diff --git a/specs/005-rev002-billing-generation-gap/quickstart.md b/specs/005-rev002-billing-generation-gap/quickstart.md new file mode 100644 index 0000000..a964dad --- /dev/null +++ b/specs/005-rev002-billing-generation-gap/quickstart.md @@ -0,0 +1,51 @@ +# Quickstart: REV-002 开账计费与账单生成缺口补齐 + +## 目标 + +本 quickstart 用于指导评审者和文档维护者快速完成 `REV-002` 开账计费与账单生成缺口补齐的检查,不涉及 backend 实施。 + +## 步骤 1:阅读规格与计划结论 + +1. 阅读 `spec.md`,确认本轮范围只覆盖 `IF-REV-005`、开账规则、结果表达、数据库承接口径与治理同步。 +2. 阅读 `research.md`,确认以下决策已固定: + - `IF-REV-005` 保持为正式账单生成接口 + - 开账生成闭环只覆盖“抄表校验后到账单生成” + - 账单结果统一由 `biz_charge` + `biz_charge_detail` 承接 + - 异常采用“阻断生成 + 返回失败原因”的口径 + +## 步骤 2:执行文档改动时的目标落点 + +1. 在 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 补齐: + - 开账计费规则来源 + - 账单生成结果表达 + - 特殊开账与异常边界 + - 排除项与文档先行边界 +2. 在 `docs/design/03_Technical_Design/03_Interface_Design.md`: + - 补齐 `IF-REV-005` 的正式接口定义 + - 明确请求条件、输出结果和异常语义 +3. 在 `docs/design/03_Technical_Design/01_Database_Design.md`: + - 明确 `biz_charge`、`biz_charge_detail` 与价格规则对象的承接口径 +4. 在治理台账中回写: + - `15_SYS002_Requirement_Breakdown.md` + - `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-002` 的开账规则和结果表达不再停留在摘要级表述 +- `IF-REV-005` 的请求输出和异常语义已明确 +- 数据库主文档未把特殊开账误写为平行在线主表 +- 治理台账明确保持“部分实现,账单生成闭环仍需继续校核”的真实结论 +- 正式文档与台账同步更新 diff --git a/specs/005-rev002-billing-generation-gap/research.md b/specs/005-rev002-billing-generation-gap/research.md new file mode 100644 index 0000000..947ff8a --- /dev/null +++ b/specs/005-rev002-billing-generation-gap/research.md @@ -0,0 +1,56 @@ +# Phase 0 Research: REV-002 开账计费与账单生成缺口补齐 + +## 决策 1:`IF-REV-005` 继续作为正式账单生成接口 + +- **Decision**: `REV-002` 继续使用 `IF-REV-005` 作为正式账单生成接口编号,不新增新的 `IF-*` 编号。 +- **Rationale**: + - 当前正式接口总表和接口章节都已使用 `IF-REV-005`,缺的是闭环内容而不是编号本身。 + - 保持现有编号可以减少与其他模块编号治理的耦合。 + - 本轮重点是补齐规则、结果表达和数据库承接口径。 +- **Alternatives considered**: + - 新增新的账单生成接口编号:否决,因为没有编号冲突,只会制造额外扰动。 + - 维持总表项不补详细定义:否决,因为不足以支撑后续实现和评审。 + +## 决策 2:开账生成闭环仅覆盖“抄表校验后到账单生成” + +- **Decision**: 本 feature 的正式范围只覆盖从抄表校验结果进入开账计费、生成营业账及其结果表达的闭环,不扩展到收费核销、发票申请、催缴或统计分析链路。 +- **Rationale**: + - 当前缺口明确聚焦在 `IF-REV-005` 和账单生成规则。 + - 收费、发票、催缴都已有单独模块和接口编号,不应混入本轮。 + - 先收口“账单生成前后边界”更有利于后续对实现进行准确评估。 +- **Alternatives considered**: + - 把收费核销一起纳入:否决,因为会扩大到 `REV-003`。 + - 把发票和催缴后续链路一起写入:否决,因为超出当前缺口范围。 + +## 决策 3:账单结果以 `biz_charge` + `biz_charge_detail` 主明细表达 + +- **Decision**: 账单生成结果统一以 `biz_charge` 作为主表、`biz_charge_detail` 作为明细表承接,不新增平行“特殊开账表”或独立账单结果模型。 +- **Rationale**: + - 数据库主文档已明确 `biz_charge*` 是开账结果承接口径。 + - 当前 backend 也已见 `charge/chargedetail` 相关入口。 + - 这样既能覆盖普通开账,也能把特殊开账作为来源类型或业务类型扩展纳入统一表达。 +- **Alternatives considered**: + - 单独新增“特殊开账表”:否决,因为没有正式主文档或实现证据支持。 + - 仅描述账单主表、不写明细关系:否决,因为会削弱费用组成表达。 + +## 决策 4:异常与阻断场景采用“阻断生成 + 返回失败原因”的口径 + +- **Decision**: 当价格模板、阶梯规则、费用组成或必要来源数据缺失时,`IF-REV-005` 采用“阻断生成 + 返回失败原因”的统一异常语义。 +- **Rationale**: + - 现有接口主文档已经有 `1_002_002_003` 这类错误码线索。 + - 对账单生成而言,缺规则时继续生成不符合正式业务口径。 + - 统一异常语义有助于详细设计、接口设计和治理文档表达一致。 +- **Alternatives considered**: + - 自动降级生成部分账单:否决,因为缺乏正式依据且风险高。 + - 只在日志中记录、不在接口返回中表达:否决,因为不利于评审和实现。 + +## 决策 5:治理台账保持“部分实现,闭环未完全收口” + +- **Decision**: `REV-002` 的当前实现判断继续保持“部分实现”,但增加“账单生成规则与结果表达已完成文档收口”的说明。 +- **Rationale**: + - 当前治理台账已明确部分实现,且 backend 未见完整“账单生成专用闭环接口”证据。 + - 文档补齐不应被误读为实现已完成。 + - 这种表述更利于后续继续校核实现入口与缺口。 +- **Alternatives considered**: + - 改成“已实现”:否决,因为证据不足。 + - 保持“部分实现”但不提设计进展:否决,因为无法体现本轮交付价值。 diff --git a/specs/005-rev002-billing-generation-gap/spec.md b/specs/005-rev002-billing-generation-gap/spec.md new file mode 100644 index 0000000..c521b4f --- /dev/null +++ b/specs/005-rev002-billing-generation-gap/spec.md @@ -0,0 +1,130 @@ +# Feature Specification: REV-002 开账计费与账单生成缺口补齐 + +**Feature Branch**: `005-rev002-billing-generation-gap` +**Created**: 2026-03-18 +**Status**: Draft +**Input**: User description: "docs/design/02_Detailed_Design/12_REV_Detailed.md 中 REV-002 开账计费与账单生成缺口补齐,明确 IF-REV-005 的业务边界、账单生成规则、结果表达、数据承接口径与治理台账同步" + +## 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/01_Overview/03_Summary_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/05_Data_Dictionary/营收数据字典.md` + - `docs/design/04_Appendix/Archive/01_Requirements/` +- **Scope decision**: In scope. 本 feature 仅补齐 `REV-002` 中“开账计费与账单生成”缺口,重点收口 `IF-REV-005`、计费规则来源、账单生成结果表达、数据承接口径和治理台账同步;不扩展到整个抄表采集链路、收费核销链路或新增平行正式主稿。 + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 - 收口开账生成规则 (Priority: P1) + +作为文档维护者,我需要把 `REV-002` 的开账计费规则、账单生成触发条件、费用组成和结果表达写清楚,使评审者能够明确“抄表数据如何转为营业账”和“账单生成结果如何表达”。 + +**Why this priority**: 当前 `REV-002` 已具备抄表与开账摘要,但“IF-REV-005` 的闭环规则和结果表达”仍偏概括,后续接口、数据库和实现评估都依赖这部分先收口。 + +**Independent Test**: 单独评审 `12_REV_Detailed.md` 中 `REV-002` 相关章节,应能明确账单生成入口、价格规则来源、费用组成、异常处理和生成结果表达。 + +**Acceptance Scenarios**: + +1. **Given** 当前文档只说明“按价格模板和费用组成计费”, **When** 评审者阅读补齐后的详细设计, **Then** 能明确开账计费的输入、规则来源、结果对象和后续流转边界。 +2. **Given** 后续需要将账单生成闭环拆为研发任务, **When** 维护者依据该规格拆解工作, **Then** 不需要再回到 Archive 才能判断本轮正式范围和排除项。 + +--- + +### User Story 2 - 统一 IF-REV-005 与数据承接口径 (Priority: P2) + +作为接口与数据设计评审者,我需要看到 `IF-REV-005` 的输入输出、状态语义、异常口径和数据库承接口径,使账单生成不再停留在“生成账单”这种过于抽象的描述。 + +**Why this priority**: `REV-002` 当前被评为“部分实现”,核心风险就在于接口闭环和数据承接口径不够清楚,容易导致文档与已有 `charge/chargedetail` 实现映射失真。 + +**Independent Test**: 单独评审接口主文档和数据库主文档,应能确认 `IF-REV-005` 的查询/生成边界、结果字段语义和 `biz_charge*` 承接口径。 + +**Acceptance Scenarios**: + +1. **Given** 评审者查看接口设计, **When** 阅读 `IF-REV-005` 章节, **Then** 能明确请求条件、生成结果、异常语义和状态表达。 +2. **Given** 评审者查看数据库设计, **When** 阅读开账与账单相关章节, **Then** 能明确 `biz_charge`、`biz_charge_detail`、价格模板和费用组成在账单生成中的承接关系。 + +--- + +### User Story 3 - 同步治理与实现评估结论 (Priority: P3) + +作为后续立项和实施跟踪人员,我需要在治理台账中看到 `REV-002` 的当前缺口、设计收口结果和后续建议,避免继续把“部分实现”的范围说得过宽或过窄。 + +**Why this priority**: `15_SYS002_Requirement_Breakdown.md` 已明确 `REV-002` 的开账计费与账单生成为高优先缺口,文档收口后必须同步治理结论。 + +**Independent Test**: 单独检查治理台账,应能明确 `REV-002` 当前属于“文档收口后仍为部分实现”的状态,并能看到后续建议。 + +**Acceptance Scenarios**: + +1. **Given** 评审者查看需求拆解与实现评估文档, **When** 阅读 `SYS002-REQ-004` 对应内容, **Then** 能明确设计收口结果、当前实现状态和下一步建议。 +2. **Given** 项目需要记录本轮重要文档动作, **When** 查看项目进度与任务清单, **Then** 能定位 `REV-002` 的开账计费规则收口记录和校验结果。 + +--- + +### Edge Cases + +- 当抄表数据存在异常复核、估抄、补抄或重录场景时,账单生成规则如何保持正式文档口径一致,而不展开实现细节? +- 当特殊开账、无码客户开账或罚款类开账进入同一账单主模型时,如何定义结果表达而不误写为独立平行主表? +- 当价格模板、阶梯规则、费用组成缺失或冲突时,如何在接口和详细设计中统一表达“阻断生成”的异常语义? +- 当当前 backend 已有 `charge/chargedetail` 入口但未见明确“专用账单生成闭环接口”证据时,如何如实表达“部分实现”而不夸大为完整闭环? + +## Requirements *(mandatory)* + +### Functional Requirements + +- **FR-001**: Specification MUST identify the exact target documents for `REV-002` billing-generation closure and ledger sync. +- **FR-002**: Specification MUST identify `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md` as the main source-of-truth documents for this feature. +- **FR-003**: Specification MUST record that the feature is in scope only for `IF-REV-005` business boundary, billing-rule source, result expression, database-side retention, and governance sync, not for the entire meter-reading or payment domain. +- **FR-004**: Specification MUST preserve the single-source-of-truth model and MUST NOT create a parallel formal document for billing generation. +- **FR-005**: Specification MUST define the billing-generation trigger path from validated reading result to charge creation, including rule sources such as price category, price template, tier rule, cost component, and water-use scheme where applicable. +- **FR-006**: Specification MUST define the minimum result expression for generated charge outputs, including master/detail relationship, period, customer/account linkage, amount composition, and downstream handoff boundary. +- **FR-007**: Specification MUST define the formal boundary of `IF-REV-005`, including request preconditions, output result semantics, exception semantics, and what remains outside the interface. +- **FR-008**: Specification MUST define how abnormal reading and special-billing scenarios relate to the normal billing flow without requiring a new standalone online billing model. +- **FR-009**: Specification MUST define the database-side retention and mapping boundary for billing generation, clarifying the role of `biz_charge`、`biz_charge_detail` and related pricing objects. +- **FR-010**: Specification MUST define exclusions for this feature, including payment write-off, invoice issuance, reminder follow-up, and unrelated statistics/reporting concerns. +- **FR-011**: Specification MUST capture cross-document consistency impacts for `IF-REV-005`, billing terminology, result-state wording, historical “特殊开账/开账记录”承接 and governance wording. +- **FR-012**: Specification MUST list the validation actions required after document updates, including single-file validation for impacted docs and link consistency checks. +- **FR-013**: Specification MUST state that formal document changes under this feature require synchronized updates to `01_Project_Progress.md` and `03_Task_Checklist.md`. +- **FR-014**: Specification MUST record the current implementation judgment for this gap as “部分实现,需进一步收口账单生成闭环” unless stronger evidence is found later. + +### Assumptions + +- 本 feature 以正式文档补齐和后续研发立项准备为目标,默认不在本轮直接修改 backend 代码。 +- `IF-REV-005` 继续作为 `REV-002` 的正式账单生成接口编号,不新发明新的 `IF-*` 编号体系。 +- 当前 backend 已见 `charge/chargedetail/collection` 相关入口,因此本轮默认按“部分实现,闭环未完全收口”处理。 +- 账单生成结果主要由 `biz_charge`、`biz_charge_detail` 和价格/费用规则对象承接,本轮不臆造新的独立账单主模型。 +- 特殊开账属于营业账主模型下的来源类型或业务类型扩展,不默认要求新建平行表族。 + +### Key Entities *(include if feature involves data)* + +- **Billing Trigger**: 从抄表校验结果进入开账计费的正式触发条件集合。 +- **Billing Rule Source**: 价格归属、价格模板、阶梯规则、费用组成和计划用水方案等规则来源。 +- **Billing Result**: 账单生成后的主单/明细结果表达,包括账期、客户、金额组成和状态边界。 +- **Billing Query Contract**: `IF-REV-005` 的输入条件、输出结果和异常语义定义。 +- **Charge Master/Detail Mapping**: `biz_charge` 与 `biz_charge_detail` 的正式承接口径。 +- **Ledger Update**: 当 `REV-002` 文档收口后,需要同步回写到项目进度和任务清单的治理记录。 + +## Success Criteria *(mandatory)* + +### Measurable Outcomes + +- **SC-001**: 评审者可在 5 分钟内从规格中定位 `REV-002` 的目标文档、开账计费边界、规则来源和排除项。 +- **SC-002**: 规格中至少覆盖 3 类独立可评审内容:开账规则闭环、`IF-REV-005` 接口边界、数据库承接口径/实现评估。 +- **SC-003**: 规格明确区分至少 5 项关键生成口径或结果要素,如账期、客户/账户、应收金额、费用组成、主明细关系、异常阻断语义。 +- **SC-004**: 后续执行 `/speckit.plan` 时,规划者无需再补充范围澄清即可将工作拆分为详细设计补齐、接口补齐、数据库口径补齐和治理台账同步四类任务。 +- **SC-005**: 规格明确列出全部必要验证动作,审阅者可直接据此执行至少 4 项文档校验或一致性检查。 diff --git a/specs/005-rev002-billing-generation-gap/tasks.md b/specs/005-rev002-billing-generation-gap/tasks.md new file mode 100644 index 0000000..8411f5a --- /dev/null +++ b/specs/005-rev002-billing-generation-gap/tasks.md @@ -0,0 +1,126 @@ +# Tasks: REV-002 开账计费与账单生成缺口补齐 + +**Input**: Design documents from `/specs/005-rev002-billing-generation-gap/` +**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 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 + +## Phase 1: Scope & Source Confirmation (Shared Foundation) + +**Purpose**: Confirm the source-of-truth set, scope boundaries, and cross-document impact before editing. + +- [x] T001 Confirm target documents and target sections in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/spec.md` +- [x] T002 Confirm authoritative sources and allowed reference inputs in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/plan.md` +- [x] T003 [P] Confirm fixed decisions for `IF-REV-005`、账单结果承接和异常语义 in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/research.md` +- [x] T004 [P] Confirm entities, contract fields, and validation commands in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/data-model.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/contracts/rev002-billing-contract.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/quickstart.md` + +--- + +## Phase 2: User Story 1 - 收口开账生成规则 (Priority: P1) 🎯 MVP + +**Goal**: 补齐 `REV-002` 详细设计中的开账触发前提、规则来源、结果表达、特殊开账统一模型和排除项。 + +**Independent Test**: 单独评审 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 的 `REV-002` 章节,应能明确账单生成入口、价格规则来源、费用组成、异常阻断语义和下游边界。 + +### Implementation for User Story 1 + +- [x] T005 [US1] Read `docs/design/00_Management/01_Project_Progress.md`, `docs/design/00_Management/02_Delivery_Standards.md`, `docs/design/00_Management/03_Task_Checklist.md`, and `docs/design/02_Detailed_Design/12_REV_Detailed.md` before editing +- [x] T006 [US1] Update `docs/design/02_Detailed_Design/12_REV_Detailed.md` to define `REV-002` billing trigger path, billing rule sources, result expression, special-billing inclusion, and explicit exclusions +- [x] T007 [US1] Sync `REV-002` wording in `docs/design/01_Overview/03_Summary_Design.md` only if detailed-design terms or boundaries need matching references +- [x] T008 [US1] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and capture the result in work notes +- [x] T009 [US1] Run `make check-links` if `docs/design/02_Detailed_Design/12_REV_Detailed.md` headings, anchors, or cross-document links changed and capture the result in work notes + +**Checkpoint**: `REV-002` detailed design is independently reviewable and no longer stops at summary-level billing wording. + +--- + +## Phase 3: User Story 2 - 统一 IF-REV-005 与数据承接口径 (Priority: P2) + +**Goal**: 统一接口主文档和数据库主文档中的 `IF-REV-005`、账单结果承接和异常边界口径。 + +**Independent Test**: 单独评审 `docs/design/03_Technical_Design/03_Interface_Design.md` 与 `docs/design/03_Technical_Design/01_Database_Design.md`,应能明确请求条件、结果语义、异常阻断逻辑以及 `biz_charge` / `biz_charge_detail` 承接口径。 + +### Implementation for User Story 2 + +- [x] T010 [US2] Update `docs/design/03_Technical_Design/03_Interface_Design.md` to define `IF-REV-005` request preconditions, response semantics, exception semantics, and boundary with downstream charging flow +- [x] T011 [US2] Update `docs/design/03_Technical_Design/01_Database_Design.md` to align `biz_charge`, `biz_charge_detail`, pricing-rule objects, and historical/special billing retention with the approved `REV-002` model +- [x] T012 [P] [US2] Sync numbering, terminology, and cross-references between `docs/design/03_Technical_Design/03_Interface_Design.md` and `docs/design/03_Technical_Design/01_Database_Design.md` +- [x] T013 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` and capture the result in work notes +- [x] T014 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` and capture the result in work notes +- [x] T015 [US2] Run `make check-links` after interface/database cross-reference updates and capture the result in work notes + +**Checkpoint**: `IF-REV-005` and database retention are independently reviewable and use one consistent billing-generation model. + +--- + +## Phase 4: User Story 3 - 同步治理与实现评估结论 (Priority: P3) + +**Goal**: 在治理台账中回写 `REV-002` 本轮设计收口结果,并保持“部分实现”的真实实现评估。 + +**Independent Test**: 单独评审治理文档,应能明确本轮已完成的是文档收口,不是 backend 闭环实现完成,并能看到后续建议与校验记录。 + +### Implementation for User Story 3 + +- [x] T016 [US3] Update `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` to retain the `部分实现` judgment and add this round's design-closure result and next-step recommendation +- [x] T017 [US3] Update `docs/design/00_Management/01_Project_Progress.md` to record the `REV-002` documentation alignment action and validation outcome +- [x] T018 [US3] Update `docs/design/00_Management/03_Task_Checklist.md` to reflect the completed `REV-002` document-maintenance tasks +- [x] T019 [US3] Run `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` and capture the result in work notes +- [x] T020 [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 the results in work notes + +**Checkpoint**: Governance documents are independently reviewable and preserve the correct “部分实现” narrative. + +--- + +## Final Phase: Cross-Cutting Closure + +**Purpose**: Ensure repository-wide consistency after all story slices are complete. + +- [x] T021 [P] Re-check source-of-truth alignment across `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`, and `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` +- [x] T022 [P] Re-check relative links, stable anchors, and numbering consistency across all modified files with `make check-links` +- [x] T023 Prepare final summary from `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/quickstart.md` and actual validation results, including modified files, remaining risks, and next-step suggestions + +--- + +## Dependencies & Execution Order + +### Phase Dependencies + +- **Phase 1**: No dependencies; MUST finish before document edits +- **User Story 1**: Depends on Phase 1 and provides the billing-rule baseline for later phases +- **User Story 2**: Depends on User Story 1 wording being stable +- **User Story 3**: Depends on User Story 1 and User Story 2 conclusions being fixed +- **Final Phase**: Depends on all selected user stories being complete + +### Within Each User Story + +- Read required governance and target docs before editing +- Complete target document edits before terminology and reference sync +- Complete content edits before validation +- Complete validation before governance ledgers are considered closed + +### Parallel Opportunities + +- `T003` and `T004` can run in parallel during foundation review +- `T012` can run in parallel with validation preparation once interface and database edits are drafted +- `T021` and `T022` can run in parallel during final closure + +## Implementation Strategy + +- **MVP first**: 先完成 User Story 1,使 `REV-002` 详细设计具备独立评审价值 +- **Incremental delivery**: 再完成 User Story 2 收口接口与数据库,最后完成 User Story 3 的治理同步 +- **Validation-first closure**: 每个 story 完成后立即执行对应校验,再推进下一阶段,避免跨文档口径回滚 + +## Notes + +- 本 feature 只做文档治理,不默认修改 backend 代码 +- 不得新发明 `IF-*` 编号或“特殊开账平行主表” +- Archive 仅用于核对来源,不直接替代正式结论 +- `specs/001-rev004-accounting/checklists/scope-alignment.md` 与本轮无关,不应纳入本 feature 变更