tangweijie/fujian_water_biz_doc
1
0
Fork 0
Code Issues Pull Requests 12 Actions Packages Projects Releases 1 Wiki Activity

docs(rev004): formal write-back of design documents (RWB-01~RWB-04)

Browse Source
This commit is contained in:
tangweijie 2026-05-18 17:37:31 +08:00
parent 8bb2496c16
commit 7ea2d5cbc9
5 changed files with 197 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
docs/design/00_Management/01_Project_Progress.md
View File

@ -118,6 +118,15 @@
| 2026-03-26 | 方案二整体部署方案独立成文 | 1）新增 `docs/design/03_Technical_Design/08_Integrated_Deployment_Design_PlanB.md`，将已采纳 PostgreSQL 16 方案二后的整体部署方案独立成文；2）结合当前前后端分层部署形态，补齐应用、数据库、中间件、静态存储的一体化部署结构；3）新增软件拓扑图、网络拓扑图、主机角色划分、资源配置建议、网络需求和端口访问建议；4）在 `07_PostgreSQL16_DR_Resource_Application.md` 增加独立文档引用说明，在技术专项目录增加入口。 | 用户明确要求不要仅在 `07` 文档内保留方案二内容，而是需要形成独立文件，并作为已采纳数据库方案后的整体部署方案提交评审。 | 正面影响，数据库资源申请专题与整体部署方案实现职责分离；后续甲方可分别评审“数据库容灾资源申请”和“系统整体部署方案”，减少口径混杂并提升部署审批的可读性。 |
| 2026-04-02 | 方案二整体部署文档按网络图口径对齐 | 1）将 `docs/design/03_Technical_Design/08_Integrated_Deployment_Design_PlanB.md` 的网络分区口径统一为“办公区 / 公网区域 / 互联网区DMZ / 内网区”；2）将 `Nginx` 入口、业务应用节点、`SFTP/FTP` 文件交换服务器的部署区域说明统一调整为与评审图一致；3）同步修正网络拓扑图、访问链路、带宽/端口、资源角色及结论段落中的命名与边界表述。 | 用户提供最新部署图，要求正式文档向图片口径靠拢，消除 `内网 Nginx`、应用区/DMZ、办公区等描述不一致问题。 | 正面影响，整体部署方案的图文一致性显著提升，便于甲方按统一网络边界和主机分区口径开展安全评审与资源审批。 |
| 2026-04-03 | REV-004 全量账务领域设计骨架落地 | 1）新增 `docs/guides/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md`，将“完整承载旧系统账务业务”的目标建模路线落为单一设计底稿；2）统一旧系统账务对象、目标分层、正式业务实体、关系图、目标表设计骨架、迁移与兼容策略、逐步细化计划；3）明确该文档作为后续正式主文档回写前的统一骨架，不与现有 `REV-004` 一期 spec 冲突。 | 用户提出当前目标不是“一期最小闭环”，而是“新系统完整承载旧系统账务业务”，需要先搭建设计骨架再逐步细化并统一口径。 | 正面影响，后续关于账务实体、台账迁移、查询兼容、审批流和数据库设计的讨论有了统一底稿，可显著降低“继续沿用一期口径”和“直接机械平移旧表”之间的反复摇摆。 |
| 2026-04-03 | REV-004 详设正式回写首批收口（RWB-01） | 1）按 `RWB-01` 规则生成正式详设快照 `docs/design/04_Appendix/Archive/08_Formal_Doc_Snapshots/RWB-01/2026-04-03-RWB-01-12_REV_Detailed.md`，基线对应 docs 仓 commit `9d2ecf1`；2）重写 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 的 `REV-004 账务处理` 章节，改为“当前正式边界 + 全量目标边界”双层写法，并纳入全量账务对象、审批分层、迁移承接和现状/目标边界；3）保持 `IF-REV-007` 当前统一入口事实，不将目标态误写为已全部落地实现。 | 用户同意从回写准备进入 `RWB-01`，要求先把 `12_REV_Detailed.md` 中 `REV-004` 正式详设改写为可承接全量账务领域的正式入口。 | 正面影响，`REV-004` 正式详设已从“一期五类场景”提升为“可承接全量账务对象的正式入口”，为后续数据库设计、接口设计与迁移专题回写建立了稳定锚点，同时保留了现状/目标分层表达，降低将目标态误判为当前实现的风险。 |
| 2026-04-03 | REV-004 数据库专项正式回写首批收口（RWB-02） | 1）按 `RWB-02` 规则生成数据库专项快照 `docs/design/04_Appendix/Archive/08_Formal_Doc_Snapshots/RWB-02/2026-04-03-RWB-02-01_Database_Design.md`，基线对应 docs 仓 commit `9d2ecf1`；2）更新 `docs/design/03_Technical_Design/01_Database_Design.md` 中 `SYS-002 开账、收费与票据表`、`biz_operat_log*`、历史台账迁移口径、索引关注点与归档补充，将 `REV-004` 从“一期不新增细表”扩展为“统一骨架 + 目标对象 + 查询投影 / 历史映射”的数据库专项口径；3）正式命名 `AccountingWorkflowRef` 与 `AccountingLegacyMapping` 为目标数据库承接对象，但仍保持“待补字段关注点”写法，不误写成已落地真实表。 | 用户同意进入 `RWB-02` 正式回写，要求先把数据库专项调整为能够承接全量账务领域的正式数据库设计入口。 | 正面影响，数据库专项已从“只描述现有骨架表”提升为“同时约束统一骨架、目标对象、历史映射和查询投影”的正式口径，为后续接口设计回写和实现落表讨论建立了稳定边界，同时避免把目标对象误判为已全部物理落地。 |
| 2026-04-03 | REV-004 接口专项正式回写首批收口（RWB-03） | 1）按 `RWB-03` 规则生成接口专项快照 `docs/design/04_Appendix/Archive/08_Formal_Doc_Snapshots/RWB-03/2026-04-03-RWB-03-03_Interface_Design.md`，基线对应 docs 仓 commit `9d2ecf1`；2）更新 `docs/design/03_Technical_Design/03_Interface_Design.md` 中 `IF-REV-007`、其请求/响应参数、数据对象与表口径、历史查询与迁移校验接口口径、实现状态说明，将 `REV-004` 从“一期五类场景统一入口”扩展为“当前统一入口 + 全量账务对象承接边界 + 历史查询分层”的正式接口口径；3）保持专属接口仍为后续方向，不误写成当前 backend 已完整落地能力。 | 用户同意进入 `RWB-03` 正式回写，要求先把接口专项调整为能够承接全量账务领域的正式接口设计入口。 | 正面影响，接口专项已从“一期统一处理接口说明”提升为“统一入口、对象承接边界、历史查询出口、实现状态分层”并存的正式口径，为后续总体设计回写和实现拆接口讨论建立了稳定约束，同时避免把目标专属接口误判为当前既成事实。 |
| 2026-04-03 | REV-004 总体摘要正式回写收口（RWB-04） | 1）按 `RWB-04` 规则生成总体摘要快照 `docs/design/04_Appendix/Archive/08_Formal_Doc_Snapshots/RWB-04/2026-04-03-RWB-04-03_Summary_Design.md`，基线对应 docs 仓 commit `9d2ecf1`；2）更新 `docs/design/01_Overview/03_Summary_Design.md` 中总体接口定义、营收业务系统外部接口、营收核心模块群概述、模块列表与 `REV-004` 模块摘要，使 REV-004 从“一期五类处理摘要”收敛为“当前统一入口 + 全量账务对象目标边界”的概要口径；3）继续保留当前已落地事实与目标设计边界分层表达，不将专属接口或独立对象实现写成已全部落地。 | 用户同意进入 `RWB-04`，要求完成 REV-004 全量账务领域在总体摘要层的正式收口。 | 正面影响，概要、详设、数据库、接口四层文档现已围绕 REV-004 形成一致口径；后续再讨论实现拆分、迁移验收与对象落表时，可直接基于统一的正式文档体系推进，显著降低跨层级表述不一致风险。 |
| 2026-04-03 | REV-004 实现分发清单与 Agent 交接模板落地 | 1）新增 `docs/guides/REV004_IMPLEMENTATION_HANDOFF.md`，将 REV-004 全量账务领域的后端、前端、联调任务拆分为可直接分发的实现清单；2）同步整理对象范围、统一入口约束、历史只读/映射层边界、建议任务包与给其他 Agent 的提示模板；3）保持该文档定位为实现交接指南，不替代正式设计真源。 | 用户需要一份可直接分发给前后端实现 Agent 的功能清单和对应需求，用于后续协作执行。 | 正面影响，后续多 Agent 协作不再需要重复从正式文档中人工提炼任务；实现范围、分工边界与交接提示可直接复用，降低理解偏差和重复沟通成本。 |
| 2026-04-07 | REV-004 前端实现正式 handoff 落地 | 1）新增 `docs/guides/REV004_FRONTEND_IMPLEMENTATION_HANDOFF.md`，将已批准的 REV-004 前端实现方案转为正式交接文档；2）明确本轮仅覆盖管理后台，不纳入微网厅/客户端实现；3）补齐四张正式执行表：页面清单、路由清单、通用组件清单、lane ownership 清单，并固化 `../water-frontend` 目录下的 `omx team` 执行边界。 | 用户要求把已达成共识的 REV-004 前端实现计划转为正式 handoff Markdown，并细化为可直接执行的正式表格。 | 正面影响，前端实现协作从“计划草案”升级为“执行交接文档”；后续在 `water-frontend` 中可直接按页面清单、路由清单、组件清单和 lane ownership 推进，降低前端实现阶段的范围漂移和分工冲突。 |
| 2026-04-07 | REV-004 前端 team prompts 落地 | 1）新增 `docs/guides/REV004_FRONTEND_OMX_TEAM_PROMPTS.md`，将 leader 启动提示与 Lane A~F 执行 prompt 固化为可直接用于 `../water-frontend` 的 `omx team` 文本；2）保持本轮范围仅覆盖管理后台，不纳入微网厅/客户端实现；3）同步固化启动顺序、lane 职责边界与最终统一输出要求。 | 用户要求直接生成可在前端目录执行的 `omx team` prompts，用于下一步正式启动多 lane 实现。 | 正面影响，前端执行已从“交接文档阶段”进入“可直接开干的 prompt 阶段”；leader 与各 lane 不再需要临时编写任务说明，可直接按固定文本启动团队执行，降低启动成本与分工歧义。 |
| 2026-04-07 | REV-004 前端 team prompts 落地 | 1）新增 `docs/guides/REV004_FRONTEND_TEAM_PROMPTS.md`，将 leader 启动提示与 Lane A~F 执行 prompt 固化为可直接用于 `../water-frontend` 的 `omx team` 文本；2）保持本轮范围仅覆盖管理后台，不纳入微网厅/客户端实现；3）同步固化启动顺序、lane 职责边界与最终统一输出要求。 | 用户要求直接生成可在前端目录执行的 `omx team` prompts，用于下一步正式启动多 lane 实现。 | 正面影响，前端执行已从“交接文档阶段”进入“可直接开干的 prompt 阶段”；leader 与各 lane 不再需要临时编写任务说明，可直接按固定文本启动团队执行，降低启动成本与分工歧义。 |
| 2026-03-18 | REV-005 统计模板补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 为 `T055`、`T060`、`T061`、`T062`、`T063` 新增可直接填写的样本记录模板；2）将 SC-001 ~ SC-004 的建议统计口径细化为表格字段与待补说明，避免后续只剩抽象待办；3）保持“模板已补齐但实际统计结果仍待联调/测试环境补录”的真实状态，不虚构样本结果。 | 用户继续推进 REV-005，希望把剩余统计类待办进一步收敛成可执行模板，便于后续直接补录真实样本而不是重新设计统计格式。 | 正面影响，REV-005 当前已具备统一的统计与日志抽样记录模板；后续补 `T055`、`T060 ~ T063` 时可直接按模板填充真实环境数据，减少再次整理验证文档结构的成本。 |
| 2026-03-18 | REV-005 verify 执行入口补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 补齐 `/business/invoice/apply`、`/query`、`/query/compensate`、`/write-back`、`/customer/query`、`/customer/download`、`/customer/push`、`/invalidate`、`/red-ink` 的最小请求模板；2）继续补齐 `T055`、`T060 ~ T063` 的执行命令草稿与样本采集顺序，明确仅作为测试/联调环境占位模板，真实地址、鉴权信息、业务主键与统计结果均待后续替换和回填；3）同步 `03_Task_Checklist.md`，将 verify 阶段推进到“替换真实环境参数即可执行”的状态。 | 用户继续推进 REV-005，希望不要停留在抽象验证建议，而是把剩余 verify 工作推进到可直接执行、可直接补样本的程度。 | 正面影响，REV-005 当前已具备统一的验证入口、请求模板、命令草稿与采样顺序；后续在测试或联调环境中可直接替换参数发起请求并回填 `T055`、`T060 ~ T063` 的真实结果，减少重复梳理接口和命令的成本。 |

16
docs/design/01_Overview/03_Summary_Design.md
View File

@ -878,6 +878,7 @@ graph TB
| IF-REV-004 | 抄表数据提交接口 | 提交人工或远传抄表数据并触发校验 | 手机抄表APP/集抄系统 | HTTPS REST | 抄表任务ID、水表ID、读数、图片证据、GPS位置 | 上传结果、校验状态、异常标记 |
| IF-REV-005 | 账单生成接口 | 根据抄表结果、水价模板和费用组成生成账单 | 开账任务/批量任务 | HTTPS REST | 抄表批次、账期、客户范围、应收日期 | 账单结果、失败清单、生成汇总 |
| IF-REV-006 | 缴费处理接口 | 创建收费记录并核销账单 | 柜台/线上渠道 | HTTPS REST | 客户ID、账单ID列表、支付方式、实收金额 | 收费结果、核销状态、交易流水 |
| IF-REV-007 | 账务处理接口 | 当前统一承接账务调整、退款/冲正、坏账申请及全量账务对象通用处理申请 | 柜台/管理后台/协同任务 | HTTPS REST | 账单ID、对象类型、处理类型、原因、审批边界、原交易号 | 处理结果、审批状态、账单回写状态、结果对象编号 |
| IF-REV-008 | 发票申请接口 | 发起电子发票申请并接收票据状态回写 | 柜台/客户渠道 | HTTPS REST | 客户ID、账单ID列表、开票抬头、税号、邮箱 | 发票申请结果、票据状态、下载地址 |
| IF-REV-011 | 银行代收协同接口 | 发起代扣、回盘、对账、结算协同 | 银行代收模块/SYS-009 | HTTPS REST / 文件交换 | 批次号、渠道编码、账期、账单明细 | 批次状态、回盘结果、对账差异、结算结果 |
| IF-REV-012 | 业务参数配置接口 | 查询和维护价格模板、优惠方案、业务参数配置 | 管理后台/参数管理端 | HTTPS REST | 参数分类、模板编码、站点范围 | 参数明细、模板信息、更新结果 |
@ -1749,7 +1750,7 @@ graph TD
- **客户资料管理**：客户档案建立、信息维护、分组管理
- **抄表开账**：抄表数据录入、复核确认、自动开账
- **营业收费**：柜台收费、移动收费、在线缴费
- **账务处理**：一期先聚焦水量调整、金额调整、退款、冲正、坏账申请，统一经 `IF-REV-007` 承接，并按共性能力先统一、场景能力再分批推进
- **账务处理**：当前仍由 `IF-REV-007` 统一承接账务处理入口，统一覆盖账单修正、退款/冲正、坏账申请，并向预存退款、红冲、价差调整、违约金减免、分账调整、退款账、跨周期水量等全量账务对象边界扩展
- **发票管理**：发票开具、查询、重开、作废
- **催缴管理**：欠费统计、催缴通知、停水管理
- **统计分析**：多维度数据统计和报表分析
@ -1805,6 +1806,7 @@ graph TD
| IF-REV-004 | 抄表数据提交接口 | 提交人工或远传抄表数据并触发校验 | 手机抄表APP/集抄系统 | HTTPS REST | 抄表任务ID、水表ID、读数、图片证据、GPS位置 | 上传结果、校验状态、异常标记 |
| IF-REV-005 | 账单生成接口 | 根据抄表结果、水价模板和费用组成生成账单 | 开账任务/批量任务 | HTTPS REST | 抄表批次、账期、客户范围、应收日期 | 账单结果、失败清单、生成汇总 |
| IF-REV-006 | 缴费处理接口 | 创建收费记录并核销账单 | 柜台/线上渠道 | HTTPS REST | 客户ID、账单ID列表、支付方式、实收金额 | 收费结果、核销状态、交易流水 |
| IF-REV-007 | 账务处理接口 | 当前统一承接账务调整、退款/冲正、坏账申请及全量账务对象通用处理申请 | 柜台/管理后台/协同任务 | HTTPS REST | 账单ID、对象类型、处理类型、原因、审批边界、原交易号 | 处理结果、审批状态、账单回写状态、结果对象编号 |
| IF-REV-008 | 发票申请接口 | 发起电子发票申请并接收票据状态回写 | 柜台/客户渠道 | HTTPS REST | 客户ID、账单ID列表、开票抬头、税号、邮箱 | 发票申请结果、票据状态、下载地址 |
| IF-REV-011 | 银行代收协同接口 | 发起代扣、回盘、对账、结算协同 | 银行代收模块/SYS-009 | HTTPS REST / 文件交换 | 批次号、渠道编码、账期、账单明细 | 批次状态、回盘结果、对账差异、结算结果 |
| IF-REV-012 | 业务参数配置接口 | 查询和维护价格模板、优惠方案、业务参数配置 | 管理后台/参数管理端 | HTTPS REST | 参数分类、模板编码、站点范围 | 参数明细、模板信息、更新结果 |
@ -1975,7 +1977,7 @@ graph TB
| REV-001 | 客户资料管理 | 客户档案管理、客户分组、信息变更 | 自行开发 |
| REV-002 | 抄表开账 | 抄表录入、复核开账、异常处理 | 自行开发 |
| REV-003 | 营业收费 | 柜台收费、移动收费、在线缴费 | 自行开发 |
| REV-004 | 账务处理 | 账务调整、退款处理、坏账管理 | 自行开发 |
| REV-004 | 账务处理 | 统一账务处理、退款/冲正、红冲/价差/分账/坏账及历史账务承接 | 自行开发 |
| REV-005 | 发票管理 | 发票开具、查询管理、电子发票 | 自行开发 |
| REV-006 | 催缴管理 | 欠费催缴、短信通知、停水管理 | 自行开发 |
| REV-007 | 统计分析 | 多维度数据统计和报表分析功能 | 自行开发 |
@ -2334,14 +2336,14 @@ flowchart TD
**功能概述:**
  负责处理各类复杂的账务调整、退款、坏账等业务，确保账务的准确性和合规性。
  负责统一承接营收核心链路中的账务处理能力。当前正式口径仍以 `IF-REV-007` 作为统一入口，承接账单修正、退款/冲正、坏账申请等处理；目标设计边界进一步覆盖预存退款、红冲、已销调整、价差调整、违约金减免、分账调整、退款账结果与跨周期水量等全量账务对象，并保持当前事实与目标设计分层表达。
**核心功能:**
- **未销账调整**: 对未支付账单进行调整。
- **分账调整**: 将一笔总账单拆分为多笔子账单。
- **预付款退款**: 处理客户预付款的退还流程。
- **呆坏账处理**: 对长期无法收回的欠款进行核销。
- **统一账务处理入口**: 通过 `IF-REV-007` 统一受理账务对象处理申请，返回处理结果、审批边界与账单回写状态。
- **账务对象承接**: 在概要层承接预存退款、红冲、已销调整、价差调整、违约金减免、分账调整、坏账等对象族语义。
- **结果与追溯**: 保留退款账结果、跨周期水量、历史账务查询、审批留痕与原单据追溯边界。
- **分层边界控制**: 当前已落地能力继续保留统一入口事实；专属接口、独立对象实现和 BPM 细节作为后续方向，不在概要层误写成既成事实。
#### REV-005: 发票管理

99
docs/design/02_Detailed_Design/12_REV_Detailed.md
View File

@ -294,74 +294,93 @@ flowchart TD
### 功能说明
REV-004 一期仅覆盖水量调整、金额调整、退款、冲正、坏账申请五类场景，统一挂靠 `IF-REV-007` 作为账务处理入口，目标是在既有正式文档体系内先收敛范围、承接口径、留痕要求与审批边界。
REV-004 当前正式口径仍以统一账务处理能力为核心，继续由 `IF-REV-007` 承接当前在线处理入口，统一处理账单承接、原交易校验、处理结果表达、操作留痕与审批边界。当前正式实现边界仍以营业账主明细、支付交易校验、操作日志与价格/方案重算支撑为基础，不将尚未落地为独立物理表族的对象误写成已实现事实。
本阶段按“共性能力先统一、场景能力再分批”组织：先统一账单承接、原交易校验、结果表达、操作留痕与审批边界，再分别展开五类场景。违约金减免、分账调整、价差调整、跨周期水量、预存退款细表等内容仅作为旧系统迁移语义或后续扩展参考，不作为一期新增独立范围。
在全量目标设计下，REV-004 不再只覆盖一期五类场景，而是统一承接全量账务对象族：`PrepaidRefund`、`RedinkRecord`、`WrittenoffAdjust`、`PriceDiffAdjust`、`LateFeeReduce`、`BadDebtRecord`、`SplitAdjust`、特殊开账 / 特账承接方式、`RefundBill`、`CrossCycleWaterRecord`。其中，特账按特殊开账类型挂接 `Charge` / `ChargeDetail` 主模型承接，`RefundBill` 作为退款处理结果对象保留，`CrossCycleWaterRecord` 作为账单重算和阶梯累计支撑对象保留；IC 卡账务当前仍按历史只读 + 映射层承接，不纳入在线主写范围。
### 业务流程
```mermaid
flowchart TD
A[发起账务调整申请] --> B[校验账单状态与权限]
B --> C{是否通过}
C -->|否| D[驳回并记录原因]
C -->|是| E[执行重算或退款冲正]
E --> F[更新账单与明细状态]
F --> G[写入操作日志与审批留痕]
G --> H[返回处理结果]
A[提交账务处理或账务对象申请] --> B[校验账单、原交易、权限与来源依据]
B --> C{是否需要审批}
C -->|是| D[进入审批留痕与待审状态]
D --> E{审批是否通过}
E -->|否| F[驳回并记录原因]
E -->|是| G[执行重算、退款、红冲、核销修正或结果生成]
C -->|否| G
G --> H[回写账单、结果对象与关联状态]
H --> I[记录操作日志、审批引用与历史映射]
I --> J[返回处理结果]
```
### 关键规则
1. 一期场景严格限定为水量调整、金额调整、退款、冲正、坏账申请，不扩展到其他接口族或独立账务台账重构。
2. 所有场景均以 `biz_charge` / `biz_charge_detail` 为主承接对象，并通过 `biz_operat_log` / `biz_operat_log_detail` 记录处理依据、前后变化和责任归属。
3. 退款、冲正必须联动 `bk_transaction`、`bk_transaction_callback`、`bk_transaction_exception` 等原支付流水及渠道状态校验，不允许仅依据账单状态直接处理。
4. 接口结果统一返回 `resultStatus`、`writeBackStatus`，其中 `resultStatus` 表示处理结论，`writeBackStatus` 表示账单状态回写结论，两者不得混用。
5. 审批相关内容一期仅保留 `approvalRequired`、`PENDING_APPROVAL` 与审批边界说明，不展开完整 BPM 流程、节点、流转规则或审批回写实现细节。
6. 对于当前未见明确独立实体表的特账、跨周期水量、退款账等对象，文档以“业务处理场景”表述，不强行落为已实现表。
1. 当前正式边界仍以 `IF-REV-007` 统一承接在线账务处理入口；目标设计边界扩展为覆盖全量账务对象族，但不把未来专属接口和独立表族误写成当前全部已落地事实。
2. 所有在线处理场景均以 `biz_charge` / `biz_charge_detail` 为统一账单承接骨架，并通过 `biz_operat_log` / `biz_operat_log_detail` 记录处理依据、前后变化、附件和责任归属；独立业务对象在详设层保留为正式业务语义，不再简单压平为单一“金额调整”子类型。
3. 退款、红冲、冲正及其他资金回退相关场景，必须联动 `bk_transaction`、`bk_transaction_callback`、`bk_transaction_exception` 等原支付流水和渠道状态校验，不允许仅依据账单状态直接处理。
4. 接口结果至少统一表达 `resultStatus`、`writeBackStatus`；涉及审批的场景还应明确 `approvalRequired`、`approvalStatus` 等边界，但当前正式文档仍不展开完整 BPM 节点、流转规则和引擎实现细节。
5. 审批承接按对象分层：`PrepaidRefund`、`BadDebtRecord` 倾向独立审批流对象；`WrittenoffAdjust`、`PriceDiffAdjust`、`LateFeeReduce`、`SplitAdjust`、`RedinkRecord` 当前先保留审批能力位或可升级边界；`RefundBill`、`CrossCycleWaterRecord` 不单独承接审批流。
6. 特账不是单独的在线主写账务实体，而是特殊开账类型；应通过开账来源类型、费用类型、原因编码和留痕信息挂接在 `Charge` / `ChargeDetail` 主模型中承接。
7. 旧系统账务对象必须按“统一骨架、独立业务实体、查询投影、历史映射”四类分层承接；实时收费、对账日志等查询类对象不强行回写为在线主写对象，IC 卡账务保持历史只读 + 映射层口径。
8. 所有账务处理场景都必须保留与原单据、原账单、原交易、审批痕迹和经办留痕的追溯关系，避免迁移后出现对账、审计和责任链断裂。
### 核心数据
- `biz_charge`、`biz_charge_detail`：账务调整的核心对象，承接调整前后账单主明细状态。
- `bk_transaction`、`bk_transaction_callback`、`bk_transaction_exception`：退款、冲正场景的原交易校验与异常追溯对象。
- 价格调整/优惠相关表：用于重算账单或差额追溯。
- `biz_operat_log`、`biz_operat_log_detail`：操作与变更留痕，记录字段差异、处理说明、附件依据与责任归属。
- **当前统一骨架对象**：`biz_charge`、`biz_charge_detail`，承接账务处理前后账单主明细状态和费用结果。
- **当前交易校验对象**：`bk_transaction`、`bk_transaction_callback`、`bk_transaction_exception`，承接退款、红冲、冲正等资金相关场景的原交易核验与异常追溯。
- **当前/目标留痕对象**：`biz_operat_log`、`biz_operat_log_detail`，记录字段差异、处理说明、附件依据、责任人和操作时间。
- **目标正式业务对象**：`PrepaidRefund`、`RedinkRecord`、`WrittenoffAdjust`、`PriceDiffAdjust`、`LateFeeReduce`、`BadDebtRecord`、`SplitAdjust`、`RefundBill`、`CrossCycleWaterRecord`；其中特账按特殊开账类型挂接 `Charge` / `ChargeDetail` 承接。
- **目标审批引用对象**：`AccountingWorkflowRef`，用于统一承接 `approvalRequired`、`approvalStatus`、旧 `TaskId` / `StepId` / `FlowRemark` 与后续审批引用。
- **目标历史映射对象**：`AccountingLegacyMapping`，用于保留旧单据标识、旧账单标识、迁移批次、承接方式和历史追溯关系。
### 主要场景
| 场景 | 说明 | 控制要点 |
|---|---|---|
| 水量调整 | 更正异常水量 | 需复核原因、附件和原抄表依据 |
| 金额调整 | 更正账单金额 | 需记录依据、差异金额和审批边界 |
| 退款 | 退回客户支付资金或预存款 | 需校验原交易、退款余额与幂等性 |
| 冲正 | 修正误收/误核销记录 | 需关联原交易与账单状态 |
| 坏账申请 | 对长期欠费进行分类处理 | 需结合账龄、客户状态与审批边界 |
| 场景对象 | 场景说明 | 当前正式边界 | 控制要点 |
|---|---|---|---|
| `PrepaidRefund` | 预存退款申请与处理 | 当前仍通过统一账务处理能力承接 | 校验原支付、退款余额、审批边界和退款结果回写 |
| `RedinkRecord` | 红冲 / 冲正记录 | 当前保留统一处理入口与历史查询能力 | 必须关联原交易、原收费记录和红冲原因 |
| `WrittenoffAdjust` | 已收费后修正 | 当前按统一调账场景承接 | 保留原账单、调整原因和前后差异 |
| `PriceDiffAdjust` | 调价差额重算 | 当前以重算与差额修正场景表达 | 保留原价格口径、新价格口径和生效时间 |
| `LateFeeReduce` | 违约金减免 | 当前以滞纳金修正场景表达 | 支持减免原因、减免金额和审批边界 |
| `BadDebtRecord` | 呆坏账申请与生效 | 当前为统一账务处理中的独立场景 | 保留账龄、客户状态、审批结果和核销状态 |
| `SplitAdjust` | 分账调整 | 当前作为费用组成重分摊场景表达 | 支持按水量 / 按费用组成等分摊策略 |
| 特殊开账 / 特账 | 特殊开账形成的收费结果 | 当前挂接开账主模型，不单列独立表族 | 保留特殊来源类型、费用类型、原因编码与留痕 |
| `RefundBill` | 退款处理结果对象 | 当前不单独作为在线提交入口 | 关联退款申请、支付退款结果与账单状态 |
| `CrossCycleWaterRecord` | 跨周期水量支撑对象 | 当前作为重算和阶梯累计支撑语义 | 保留跨期水量、累计逻辑和关联场景来源 |
### 迁移补充（旧系统承接）
| 旧账务对象 | 当前承接方式 | 迁移口径 |
|---|---|---|
| 预存退款 / 预存退款详情 | 作为账务处理场景承接 | 保留申请单、原支付引用、退款结果与审批留痕 |
| 已销调整汇总 / 明细 | 作为已收费后修正场景承接 | 保留原账单、调整原因、前后差异、处理结果 |
| 价差调整汇总 / 明细 | 作为重算与差额修正场景承接 | 保留原价格口径、新价格口径、差额和生效时间 |
| 分账调整汇总 / 明细 | 作为费用组成重分摊场景承接 | 保留原分摊结果、调整后结果、责任人和审批链 |
| 账单-违约金减免 | 作为滞纳金修正场景承接 | 保留减免原因、减免金额、审批结果和生效时间 |
| 账单-呆坏账 | 作为坏账申请与生效场景承接 | 保留账龄、申请原因、审批结果、核销状态 |
| 旧账务对象 | 目标分层 | 当前承接方式 | 迁移口径 |
|---|---|---|---|
| 预存退款 / 预存退款详情 | `L2` 独立业务层 | 在线主模型 + 独立业务语义 | 保留申请单、原支付引用、退款结果、审批留痕 |
| 已销调整汇总 / 明细 | `L2` 独立业务层 | 在线主模型 + 场景承接 | 保留原账单、调整原因、前后差异、处理结果 |
| 价差调整汇总 / 明细 | `L2` 独立业务层 | 在线主模型 + 重算差额场景 | 保留原价格口径、新价格口径、差额和生效时间 |
| 分账调整汇总 / 明细 | `L2` 独立业务层 | 在线主模型 + 费用重分摊场景 | 保留原分摊结果、调整后结果、策略类型和责任链 |
| 账单-违约金减免 | `L2` 独立业务层 | 在线主模型 + 减免场景 | 保留减免原因、减免金额、审批结果和生效时间 |
| 账单-呆坏账 | `L2` 独立业务层 | 在线主模型 + 坏账申请场景 | 保留账龄、申请原因、审批结果、核销状态 |
| 特账 / 特殊开账 | `L2` 独立业务层（挂主开账模型） | 开账主模型扩展承接 | 保留特殊来源、费用类型、原因编码和关联账单 |
| 退款账 | `L2` 独立业务层（结果对象） | 退款结果对象承接 | 保留退款申请、退款结果、账单/支付关联 |
| 跨周期水量 | `L2` 基础支撑对象 | 重算与阶梯累计支撑对象 | 保留跨期水量、账单重算来源和累计口径 |
| 实时收费汇总 / 日志 / 明细、对账日志 | `L3` 查询投影层 | `projection-only` | 保留历史查询、报表和对账出口，不强接在线主写 |
| IC 卡账务表族 | `L4` 历史映射层 | `history-readonly + mapping-only` | 保留历史只读查询、旧主键映射和迁移追溯 |
1. P0 阶段不要求为每一类旧账务台账都新增独立实体表，但必须在业务对象和历史查询层形成可追溯闭环。
1. 正式详设层不要求把每一类旧账务对象都立即落为已实现独立物理表，但必须先明确其在目标模型中的层级、角色和承接方式。
2. 旧系统精细台账迁移后至少保留：原单据标识、原账单标识、处理类型、处理原因、处理前后金额/水量、申请/审批/生效时间、经办人与附件依据。
3. 与支付、发票、渠道回调强关联的处理场景，必须保留与原交易、原发票、原收费记录的关联关系，避免后续对账和审计断链。
### 接口映射
- `IF-REV-007`：账务调整、退款、冲正、坏账等处理入口。
- `IF-REV-006`：与收费核销状态联动，确保调账后账单状态一致。
- `IF-REV-007`：当前正式统一账务处理入口，继续承接调账、退款、冲正、坏账等在线处理场景。
- `IF-REV-006`：与收费核销状态联动，确保调账后账单状态、核销状态和结果回写一致。
- 查询类对象后续可按“业务对象查询接口”和“历史只读 / 投影查询接口”分层拆分，但当前正式文档暂不新增专属接口编号。
- 特殊开账 / 特账继续挂接 `IF-REV-005` 与开账主模型边界承接，不在本节单独定义新的在线处理入口。
### 落地边界
- **已落地**：营业账主明细、操作日志、价格/方案相关重算支撑。
- **部分落地**：精细化账务对象更多表现为流程与场景，并未在 backend 中全部体现为独立表族。
- **文档先行**：特账、退款账、跨周期水量等对象保留业务语义，不宣称为已实现独立表。
- **已落地**：营业账主明细、支付交易校验、操作日志、价格/方案相关重算支撑，已构成当前统一账务处理骨架。
- **部分落地**：精细化账务对象目前更多表现为处理场景、查询口径和留痕规则，尚未在 backend 中全部体现为独立表族或专属接口。
- **目标设计**：后续将按正式业务对象、审批引用、历史映射和查询投影逐步回写数据库设计、接口设计和总体设计；IC 卡账务继续固定为历史只读 + 映射层，不纳入在线主写范围。
<a id="mod-rev-005"></a>

80
docs/design/03_Technical_Design/01_Database_Design.md
View File

@ -1078,14 +1078,18 @@ retrieval_priority: P0
| 字段名 | 说明 |
| :--- | :--- |
| `id` | 主键 |
| `code` | 账单编号 |
| `code` | 账单编号 / 账务主单编号 |
| `cust_id` | 客户 ID |
| `record_id` | 抄表记录或开账来源 ID |
| `bill_period` | 账单期间 |
| `total_amount` | 账单总金额 |
| `charge_status` | 收费状态 |
| `charge_status` | 收费状态 / 账务处理结果状态关注字段 |
| `due_date` | 应缴日期 |
> 当前真实表事实：`biz_charge` 仍是当前 backend 已落地的营业账主表。
>
> `RWB-02` 目标承接口径：除继续承接 REV-002 开账结果外，`biz_charge` 同时作为 REV-004 全量账务领域的统一骨架主对象，负责承接账单主状态、账务处理主结果、来源单据引用、账单结果回写和查询主入口；对尚未独立落表的目标业务对象，本节仅定义“承接边界 / 待补字段组 / 历史映射要求”，不误写为已存在独立物理表。
### biz_charge_detail (营业账明细表)
| 字段名 | 说明 |
| :--- | :--- |
@ -1096,6 +1100,10 @@ retrieval_priority: P0
| `unit_price` | 单价 |
| `detail_amount` | 明细金额 |
> 当前真实表事实：`biz_charge_detail` 仍是当前 backend 已落地的营业账明细表。
>
> `RWB-02` 目标承接口径：`biz_charge_detail` 除继续承接账单费用明细外，还应承接价差调整、违约金减免、分账调整、特殊开账 / 特账等费用差异结果的明细表达；当前数据库专项只冻结“由明细层承接差异结果”的方向，不在本轮直接展开独立实体表 DDL。
#### REV-002 账单生成承接口径
| 对象 | 正式口径 | 承接说明 |
@ -1112,8 +1120,23 @@ retrieval_priority: P0
> 当前 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` 作为账单主明细承接对象；当前数据库主文档不新增独立账务细表来承接一期场景。
#### REV-004 全量账务数据库承接口径
| 目标对象 | 当前数据库口径 | 目标承接方式 | 当前写法约束 |
| :--- | :--- | :--- | :--- |
| `PrepaidRefund` | 当前作为统一账务处理场景 | `biz_charge` / `biz_charge_detail` + 留痕 + 目标结果对象 | 当前不宣称已存在独立退款主表 |
| `RedinkRecord` | 当前以账务处理场景 + 历史查询表达 | 账单结果 + 原交易校验 + 历史只读查询 | 当前不宣称已落地独立红冲表族 |
| `WrittenoffAdjust` | 当前作为已收费后修正场景 | 统一骨架 + 差异结果 + 留痕 | 当前不下沉独立 DDL |
| `PriceDiffAdjust` | 当前作为重算差额场景 | 统一骨架 + 价格规则来源 + 明细差异表达 | 当前先冻结承接方向 |
| `LateFeeReduce` | 当前作为滞纳金修正场景 | 统一骨架 + 费用组成差异 + 审批留痕 | 当前先写待补字段关注点 |
| `BadDebtRecord` | 当前作为坏账申请场景 | 统一骨架 + 审批引用 + 历史追溯 | 当前不误写为已存在坏账主表 |
| `SplitAdjust` | 当前作为费用重分摊场景 | 统一骨架 + 明细差异 + 策略类型字段组 | 当前只冻结设计方向 |
| 特殊开账 / 特账 | 当前由开账同模型承接 | `biz_charge` / `biz_charge_detail` 同模型承接 | 不新增平行“特账表” |
| `RefundBill` | 当前作为退款结果语义 | 退款结果对象 + 历史映射 / 查询出口 | 当前不作为独立提交表宣称已落地 |
| `CrossCycleWaterRecord` | 当前作为重算支撑语义 | 账单重算基础数据对象 + 查询支撑 | 当前不写成强流程主表 |
| `AccountingWorkflowRef` | 当前数据库主文档未单独命名 | 目标审批引用对象 | 当前仅建立数据库承接边界和待补字段关注点 |
| `AccountingLegacyMapping` | 当前数据库主文档未单独命名 | 目标历史映射对象 | 当前仅建立历史映射承接边界和待补字段关注点 |
### biz_collection / biz_withholding (托收与代扣主表)
| 表名 | 关键字段 | 说明 |
@ -1142,9 +1165,11 @@ retrieval_priority: P0
| `biz_operat_log` | `biz_type`, `biz_id`, `operate_user`, `operate_time` | 业务操作主日志 |
| `biz_operat_log_detail` | `log_id`, `field_name`, `before_value`, `after_value` | 字段级变更留痕 |
> REV-004 留痕口径：`biz_operat_log*` 统一承接账务处理的一期留痕，至少覆盖处理类型、目标账单、原交易引用、处理前后差异、原因说明、附件依据与操作人。
> REV-004 留痕口径：`biz_operat_log*` 继续作为当前正式留痕主入口，但承接范围从“一期账务处理留痕”扩展为“全量账务操作留痕 + 审批痕迹 + 原单据关联 + 历史追溯”。
>
> 边界说明：旧数据字典中的“跨周期水量、特账、红冲、已销调整、呆坏账、实时收费日志”等对象，在当前 backend 范围内未全部识别到独立实体表，数据库专项中统一按业务处理场景描述，不误写为已明确落地的真实表。
> 数据库关注点：至少覆盖处理类型、目标账单、原交易引用、处理前后差异、原因说明、附件依据、审批状态、审批引用、操作人和操作时间。
>
> 边界说明：旧数据字典中的“跨周期水量、特账、红冲、已销调整、呆坏账、实时收费日志”等对象，在当前 backend 范围内未全部识别到独立实体表；数据库专项中统一按“在线骨架承接 / 历史只读保留 / 映射对象追溯”三层口径描述，不误写为已明确落地的真实表。
### 旧系统历史台账迁移与只读查询口径
@ -1153,22 +1178,32 @@ retrieval_priority: P0
| 旧对象/旧菜单 | 当前主口径 | 承接方式 | 数据策略 |
| :--- | :--- | :--- | :--- |
| 开账记录、特殊开账 | `biz_charge`、`biz_charge_detail`、`biz_operat_log*` | 统一纳入营业账主表与明细表，特殊开账按来源类型、业务类型、依据说明留痕，不单设平行“特殊开账表” | 在线保留 |
| 预存退款、已销调整、价差调整、分账调整、违约金减免、呆坏账新发生业务 | `biz_charge*` + 留痕骨架 + 目标对象语义 | 新发生业务优先走统一骨架承接，数据库文档保留目标对象命名和待补字段组，但不误写为已全部落地物理表 | 在线保留 |
| 柜台收费、实时收费、代收代扣 | `biz_collection`、`biz_withholding`、`bk_transaction*`、`bk_withholding_*` | 统一纳入收费主模型与渠道交易模型，柜台班结/实时收费日志按交易结果和操作留痕归并 | 在线保留 |
| 发票申请、开票结果、票据税率 | `biz_invoice`、`biz_invoice_taxrate`、`biz_cust_invoice` | 统一纳入发票主表、税率表和客户开票信息，不为旧“营业账开票表”机械复制新在线表 | 在线保留 |
| 微网厅业务字段、页面配置、微信参数 | `biz_business_types`、`biz_business_datas`、`biz_page_settings*`、`biz_parameter_settings`、`sys_wechat_app_settings` | 统一归并为业务类型、页面配置和渠道参数模型 | 在线保留 |
| 办理附件、电子档案 | `biz_content`、`biz_content_attach` | 当前新增与迁移后新增资料统一按资料主表与附件表承接 | 在线保留 |
#### 历史只读保留范围
#### 查询投影 / 历史映射保留范围
| 历史对象 | 当前正式口径 | 保留策略 | 查询要求 |
| :--- | :--- | :--- | :--- |
| 红冲记录、红冲原因、红冲前后账务快照 | 账单状态 + 账务处理场景 + 操作留痕 | 保留历史只读，不强制拆为新主库独立实体表 | 至少支持原单号、红冲单号、金额、原因、经办人、时间查询 |
| 预存退款、已销调整、价差调整、分账调整、违约金减免、呆坏账明细 | `REV-004` 账务处理业务场景 | 旧细粒度台账以历史只读方式保留；新发生业务由流程与日志承接 | 至少支持汇总、明细、状态、审批结果和关联账单查询 |
| 红冲记录、红冲原因、红冲前后账务快照 | 账单状态 + 账务处理场景 + 操作留痕 | 保留历史只读，不强制拆为新主库独立实体表；后续可作为 `RedinkRecord` 查询投影出口 | 至少支持原单号、红冲单号、金额、原因、经办人、时间查询 |
| 预存退款、已销调整、价差调整、分账调整、违约金减免、呆坏账明细 | `REV-004` 账务处理业务场景 | 旧细粒度台账以历史只读方式保留；新发生业务由统一骨架、目标对象语义和留痕承接 | 至少支持汇总、明细、状态、审批结果和关联账单查询 |
| 退款账结果、跨周期水量、疑难重笔账 | 结果对象 / 基础支撑对象 / 历史问题单据 | 保留为查询投影或历史只读出口，不强行落为在线主写对象 | 至少支持结果状态、来源单据、时间、关联账单查询 |
| 柜台结账、打印记录、补打记录 | 收费结果 + 打印/操作留痕 | 旧查询菜单作为历史只读能力保留，不单独建设新结账台账表 | 至少支持班次、营业所、柜员、打印类型、结账状态查询 |
| 发票明细、营业账开票关系、开票配置快照 | 发票主模型 + 历史关系快照 | 旧细表和配置快照按历史只读保留；新在线模型只保留开票必需主数据 | 至少支持发票号、账单号、开票批次、配置版本和结果状态查询 |
| 催缴记录、停水记录、预存短信记录 | 催缴/停复水/消息联动业务场景 | 旧记录菜单按历史只读保留，与 `IF-REV-013` 的任务结果、通知链路和工单处置引用分层承接，不新增同名在线主表 | 至少支持客户、账期、催缴方式、执行结果、发送对象、发送时间、关联账单、处置引用查询 |
| IC 卡账务表族 | 当前冻结为历史只读 + 映射层 | 保留 `history-readonly + mapping-only`，不进入在线主写数据库口径 | 至少支持卡号、客户、金额、时间、旧单据标识查询 |
| 水表检定、领用、出库、退库、报废单据 | `METER-003` 生命周期场景 | 当前在线主表承接水表状态，旧单据与检定证书按历史只读保留 | 至少支持表号、仓库、单据类型、检定结论、证书编号查询 |
#### 目标引用对象与待补字段关注点
| 目标对象 | 当前数据库状态 | 待补字段关注点 | 说明 |
| :--- | :--- | :--- | :--- |
| `AccountingWorkflowRef` | 当前主文档未单列真实表 | `accounting_case_id`、`workflow_type`、`approval_required`、`approval_status`、`legacy_task_id`、`legacy_step_id`、`legacy_flow_remark` | 当前只建立数据库专题锚点，不宣称已存在真实表 |
| `AccountingLegacyMapping` | 当前主文档未单列真实表 | `legacy_object_type`、`legacy_object_id`、`new_object_type`、`new_object_id`、`mapping_mode`、`migration_batch_no`、`trace_status` | 当前只建立历史映射承接边界，不宣称已存在真实表 |
#### 迁移验收最低对账口径
| 对账主题 | 最低核对维度 | 主口径来源 | 验收要求 |
@ -1177,13 +1212,14 @@ retrieval_priority: P0
| 缴费记录 | 收费笔数、实收金额、渠道、核销状态 | `biz_collection`、`bk_transaction*` | 支持按渠道、日期、营业所汇总比对 |
| 发票记录 | 开票笔数、金额、状态、票据类型 | `biz_invoice*` + 历史开票关系 | 支持按发票状态、开票日期比对 |
| 红冲与账务调整 | 调整笔数、调整金额、处理结果 | 账务处理结果 + 历史台账 | 支持汇总与单据级差异定位 |
| 退款与坏账结果 | 结果笔数、结果金额、审批状态、关联账单 | 统一骨架结果 + 历史只读台账 | 支持按对象类型、状态、账期、时间定位 |
| 催缴与停复水 | 通知笔数、执行结果、停复水状态 | `IF-REV-013` 任务结果 + 历史记录 | 支持按账期、客户、执行状态、处置引用比对 |
| 电子档案 | 附件数、附件类型、关联业务单数 | `biz_content_attach` + 历史档案目录 | 支持按业务类型、上传时间、来源系统比对 |
#### 设计约束
- 不以“旧菜单一项对应一张新表”为原则，优先复用当前已确认的 `biz_*`、`bk_*` 在线主模型。
- 对 backend 当前未识别到独立实体表的旧细粒度台账，仅写为“历史只读查询对象”，不误写为“已存在新在线表”。
- 对 backend 当前未识别到独立实体表的旧细粒度台账，仅写为“历史只读查询对象”或“目标对象 / 待补字段关注点”，不误写为“已存在新在线表”。
- 历史只读对象必须保留原系统关键标识（原单号、原客户号、原批次号或原附件标识）以支撑迁移验收与问题追溯。
- 涉及历史附件、影像、高拍仪资料时，正式数据库设计只约束“资料元数据 + 文件引用”口径，不在本轮臆造新的文件表族。
- `REV-006` 的正式结果状态按 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态统一，数据库设计仅约束查询与追溯口径，不反推为已存在独立催缴结果主表。
@ -1536,7 +1572,7 @@ retrieval_priority: P0
| start_time | timestamp(6) | Y | | 开始时间 |
| end_time | timestamp(6) | Y | | 结束时间 |
| work_duration | int4 | Y | 0 | 工作时长（分钟） |
| work_status | int2 | N | 0 | 工单状态：0-待处理，1-处理中，2-已完成 |
| work_status | int2 | N | 0 | 工单状态：0-未处理（工单创建，待审核/待处理），1-已审核（审核通过/无需审批，待完成），2-已完成（处理成功且已回写完成），3-已撤销（工单已撤销） |
| work_result | varchar(500) | Y | | 工作结果 |
| completion_photos | text | Y | | 完成照片 |
| customer_signature | varchar(500) | Y | | 客户签名 |
@ -1991,6 +2027,16 @@ CREATE INDEX idx_bk_withholding_batch_date ON bk_withholding_batch(batch_date, b
CREATE INDEX idx_bk_reconcile_batch_bill_date ON bk_reconcile_batch(bill_date, reconcile_status);
```
> `RWB-02` 索引关注点：在保持上述现有真实索引口径不变的前提下，后续应重点关注以下账务查询路径：
>
> - 账务主单 / 账单结果查询：`cust_id + bill_period`、`charge_status + due_date`、`code + tenant_id`
> - 账务明细差异查询：`charge_id + cost_component_code`，必要时补“差异类型 / 结果类型”类字段索引
> - 原单据 / 原交易追溯：`biz_order_no`、`trade_no`、原单号 / 原申请单号 / 原结果单号
> - 审批引用查询：后续若引入 `AccountingWorkflowRef`，应优先关注 `accounting_case_id`、`approval_status`、`workflow_type`
> - 历史映射查询：后续若引入 `AccountingLegacyMapping`，应优先关注 `legacy_object_type + legacy_object_id`、`new_object_type + new_object_id`、`migration_batch_no`
>
> 当前数据库文档仅冻结索引关注点，不在本轮直接新增未落地表的 SQL 索引语句。
## 分区表设计
### 日志表分区策略
@ -2020,6 +2066,12 @@ CREATE TABLE biz_price_adjustment_history_y2024 PARTITION OF biz_price_adjustmen
FOR VALUES FROM ('2024-01-01') TO ('2025-01-01');
```
> `RWB-02` 历史数据关注点：对 REV-004 全量账务领域，后续应把“历史只读台账、查询投影、映射关系”与“在线主写骨架”分开管理。
>
> - 历史只读对象：红冲记录、旧退款账、旧分账调整、旧价差调整、IC 卡账务等按历史查询保留，不并入在线主写分区策略
> - 查询投影对象：实时收费、对账日志、结果投影可按时间或账期做轻量分区/归档优化
> - 映射对象：若后续引入 `AccountingLegacyMapping`，优先按迁移批次号和时间做归档/检索设计
## 查询优化建议
### 多租户查询优化
@ -2058,6 +2110,12 @@ SELECT * FROM dept_tree;
- **归档周期**: 每月执行一次归档作业
- **存储方式**: 使用列式存储优化查询性能
### REV-004 历史账务归档补充
- **在线骨架对象**：`biz_charge`、`biz_charge_detail`、`biz_operat_log*` 保留当前在线口径，优先服务当前账务处理、审计与查询。
- **历史只读对象**：旧红冲、旧退款账、旧价差调整、旧分账调整、IC 卡账务等优先走历史只读归档，不反向要求在线主表一比一复刻。
- **查询投影对象**：实时收费、对账日志、账务结果投影可按账期或时间做归档分层，确保老数据查询不拖累在线主写。
- **映射对象**：后续若落地 `AccountingLegacyMapping`，应按迁移批次、对象类型、时间维度设计归档与抽检策略。
### 历史数据处理
```sql
-- 创建归档表

66
docs/design/03_Technical_Design/03_Interface_Design.md
View File

@ -442,14 +442,16 @@ retrieval_priority: P0
| 归属模块 | REV-004 |
| 请求方式 | POST |
| 请求路径 | `/admin-api/revenue/accounting/adjust` |
| 功能描述 | 发起水量调整、金额调整、退款、冲正、坏账申请五类账务处理，并统一返回处理结果、审批边界与账单回写状态 |
| 功能描述 | 当前继续作为 REV-004 统一账务处理入口，统一承接账单修正、退款/冲正、坏账申请以及全量账务对象的通用处理申请，并返回处理结果、审批边界与账单回写状态 |
| 核心表 | `biz_charge`、`biz_charge_detail`、`biz_operat_log`、`bk_transaction*` |
边界约束：
- 一期仅覆盖 `USAGE`、`AMOUNT`、`REFUND`、`REVERSE`、`BAD_DEBT` 五类 `adjustType`。
- 退款、冲正必须提供 `sourceTradeNo` 并完成原交易校验；其他场景不得误用支付流水替代业务依据。
- 审批相关内容仅保留 `approvalRequired`、`PENDING_APPROVAL` 与边界说明，不展开 BPM 节点与审批回写实现细节。
- `resultStatus` 与 `writeBackStatus` 必须分离表达，前者表示处理结论，后者表示账单状态回写结论。
- 当前正式事实仍以 `IF-REV-007` 为统一入口，不直接新增一整套新的正式专属接口编号族。
- 当前统一入口需能够覆盖 `PrepaidRefund`、`RedinkRecord`、`WrittenoffAdjust`、`PriceDiffAdjust`、`LateFeeReduce`、`BadDebtRecord`、`SplitAdjust`、特殊开账 / 特账、`RefundBill`、`CrossCycleWaterRecord` 的统一提交或统一受理边界；其中结果对象和基础支撑对象可仅保留受理/查询语义。
- 退款、红冲、冲正等资金回退相关场景必须提供 `sourceTradeNo` 并完成原交易校验；其他场景不得误用支付流水替代业务依据。
- 审批相关内容当前仍仅保留 `approvalRequired`、`approvalStatus` 与边界说明，不展开 BPM 节点、审批回写 API 与流程引擎实现细节。
- `resultStatus` 与 `writeBackStatus` 必须分离表达，前者表示处理结论，后者表示账单状态回写结论；后续若拆专属接口，也不得破坏该双状态语义。
- 专属接口方向当前只允许写成“后续建议拆分方向”，不得误写为当前 backend 已完整落地能力。
### IF-REV-008 发票申请接口
@ -833,12 +835,15 @@ retrieval_priority: P0
| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 |
|------|------|------|------|---------------|
| chargeId | Long | 是 | 目标账单 ID | `biz_charge.id` |
| adjustType | String | 是 | 调整类型：`USAGE`、`AMOUNT`、`REFUND`、`REVERSE`、`BAD_DEBT` | 业务类型 |
| objectType | String | 是 | 账务对象类型：`PREPAID_REFUND`、`REDINK_RECORD`、`WRITTENOFF_ADJUST`、`PRICE_DIFF_ADJUST`、`LATE_FEE_REDUCE`、`BAD_DEBT_RECORD`、`SPLIT_ADJUST`、`SPECIAL_BILLING`、`REFUND_BILL`、`CROSS_CYCLE_WATER` | 统一对象语义 |
| adjustType | String | 否 | 当前统一入口处理类型：`USAGE`、`AMOUNT`、`REFUND`、`REVERSE`、`BAD_DEBT` 等 | 业务类型 / 兼容字段 |
| adjustAmount | Decimal | 否 | 调整金额 | `biz_charge_detail` / 业务计算 |
| adjustUsage | Decimal | 否 | 调整水量 | 业务计算 |
| sourceTradeNo | String | 否 | 原交易流水号，退款/冲正场景使用 | `bk_transaction.trade_no` |
| sourceTradeNo | String | 否 | 原交易流水号，退款/红冲/冲正场景使用 | `bk_transaction.trade_no` |
| relatedBizNo | String | 否 | 原业务单号/结果单号/关联单号 | 历史追溯 / 业务流水 |
| reasonCode | String | 是 | 调整原因编码 | 业务字典 |
| remark | String | 否 | 调整说明 | `biz_operat_log.remark` |
| approvalRequired | Boolean | 否 | 是否触发审批能力位 | 审批边界判断 |
| remark | String | 否 | 处理说明 | `biz_operat_log.remark` |
| attachmentList | Array<String> | 否 | 依据附件 | 附件系统 |
| operatorId | Long | 是 | 操作人 ID | 操作上下文 |
@ -846,13 +851,22 @@ retrieval_priority: P0
| 字段 | 类型 | 说明 | 主要来源 |
|------|------|------|----------|
| adjustmentNo | String | 调整业务编号 | 业务流水 |
| adjustmentNo | String | 调整业务编号 / 统一处理流水号 | 业务流水 |
| chargeId | Long | 目标账单 ID | `biz_charge.id` |
| resultStatus | String | 处理状态：`SUCCESS`、`PENDING_APPROVAL`、`FAIL` | 业务状态 |
| objectType | String | 实际承接的账务对象类型 | 业务状态 |
| resultStatus | String | 处理状态：`SUCCESS`、`PENDING_APPROVAL`、`FAIL`、`PARTIAL_SUCCESS` 等 | 业务状态 |
| writeBackStatus | String | 账单回写状态 | 业务状态 |
| approvalRequired | Boolean | 是否进入审批 | 流程判断 |
| approvalStatus | String | 审批状态：`PENDING_APPROVAL`、`APPROVED`、`REJECTED` 等 | 审批边界 |
| resultObjectNo | String | 结果对象编号/结果单号 | 业务流水 / 结果对象 |
| msg | String | 处理说明 | 返回消息 |
> 参数口径补充：
>
> - `objectType` 用于统一表达全量账务对象语义；当前若 backend 尚未完整开放所有对象类型，可按“已开放对象 + 后续扩展对象”分批实现，但正式接口文档已固定该统一表达方向。
> - `adjustType` 当前保留作为统一入口兼容字段，后续若拆专属接口，可逐步从“处理类型”过渡到“对象类型 + 结果语义”表达。
> - `approvalRequired`、`approvalStatus` 仅用于承接审批能力位和审批状态边界，不代表当前已落地完整 BPM API。
### IF-REV-008 发票申请接口
#### 请求参数
@ -1543,6 +1557,7 @@ sequenceDiagram
| 客户与账户 | `biz_cust`、`biz_account`、`biz_cust_contact` | 用于客户查询、账户绑定、资料维护 |
| 客户扩展关系 | `biz_cust_meter`、`biz_cust_invoice`、`biz_cust_app_binds`、`biz_cust_collection_rel`、`biz_cust_withholding_rel` | 用于客户关联对象查询与服务协同 |
| 抄表与开账 | `biz_meter_book`、`biz_meter_read`、`biz_reading_data`、`biz_last_reading`、`biz_charge`、`biz_charge_detail` | 用于抄表任务、账单生成、费用明细查询 |
| 账务处理与结果对象 | `biz_charge`、`biz_charge_detail`、`biz_operat_log`、`bk_transaction*`、目标对象 `AccountingWorkflowRef`、`AccountingLegacyMapping` | 用于 REV-004 统一处理入口、审批边界、结果对象表达与历史追溯 |
| 价格与参数 | `biz_price_*`、`biz_cost_component`、`biz_parameter_settings`、`biz_page_settings*` | 用于价格模板、业务参数、页面配置 |
| 收费与票据 | `biz_collection`、`biz_withholding`、`biz_invoice`、`biz_invoice_taxrate` | 用于收费、代扣、发票申请与回写 |
| 办理与资料 | `biz_process*`、`biz_business_datas`、`biz_content*` | 用于业务办理与进度跟踪 |
@ -1552,7 +1567,8 @@ sequenceDiagram
1. 不再使用旧稿中的 `customer_*`、`water_*`、`billing_*`、`thirdpay_*`、`service_*` 作为 SYS-002 正式接口数据口径。
2. 若历史资料中仍存在旧命名，仅作为来源参考，不作为正式交付口径。
3. 对 backend 中尚未明确存在独立实体表的对象，例如部分精细账务台账、红冲明细、价差调整明细等，本文仅描述为业务处理场景，不强写为既有独立接口对象。
3. 对 backend 中尚未明确存在独立实体表的对象，例如部分精细账务台账、红冲明细、价差调整明细等，本文可正式命名其“接口对象语义”，但不误写为当前已完整落地的独立专属接口。
4. `AccountingWorkflowRef`、`AccountingLegacyMapping` 当前属于目标接口对象 / 目标数据对象命名，用于表达审批引用和历史映射边界，不表示已存在独立对外接口编号。
## 跨系统报文映射表
@ -1731,16 +1747,30 @@ sequenceDiagram
- 历史查询接口一律只读，不承担迁移修正、补写或状态变更职责。
- 不为迁移场景发明新的独立接口编号体系，统一挂靠既有 `IF-REV-*`、`IF-CS-*`、`IF-METER-*` 接口族扩展查询能力。
- 对 backend 当前未识别到独立实体表的旧细粒度对象，仅要求接口返回“历史摘要 + 原始标识 + 状态映射”，不强行承诺独立在线业务对象。
- 全量账务对象的查询出口按“两层口径”组织：一类为业务对象查询出口，一类为历史只读 / 投影查询出口。
- 对 backend 当前未识别到独立实体表的旧细粒度对象，接口至少返回“对象语义 + 历史摘要 + 原始标识 + 状态映射”，不强行承诺独立在线业务对象。
- 迁移验收接口必须同时支持“汇总对账”和“明细追溯”两类能力，避免只能看总数、无法定位差异。
### 全量账务对象查询出口分层
| 对象类型 | 当前挂靠接口 | 查询层级 | 最低返回要求 | 说明 |
|---------|--------------|----------|--------------|------|
| `PrepaidRefund`、`WrittenoffAdjust`、`PriceDiffAdjust`、`LateFeeReduce`、`BadDebtRecord`、`SplitAdjust` | `IF-REV-007` | 业务对象查询出口 | 对象类型、业务编号、关联账单、金额/水量差异、状态、审批状态、处理时间 | 当前继续挂统一入口查询语义，后续可拆专属查询接口 |
| `RedinkRecord` | `IF-REV-007` | 业务对象查询出口 + 历史只读出口 | 红冲单号、原单号、金额、原因、审批状态、处理时间 | 当前由统一入口和历史查询共同承接 |
| 特殊开账 / 特账 | `IF-REV-005`、`IF-CS-002` | 账单结果 / 历史账单查询出口 | 来源类型、费用类型、账单号、账期、金额、状态 | 继续挂开账主模型与历史账单查询 |
| `RefundBill` | `IF-REV-007`、`IF-CS-002` | 结果对象查询出口 | 结果单号、退款申请号、支付结果、关联账单、状态 | 当前不单列提交接口，但应保留查询出口 |
| `CrossCycleWaterRecord` | `IF-REV-007`、`IF-CS-002` | 基础支撑 / 历史查询出口 | 来源账单、跨期水量、账期范围、累计口径、关联场景 | 当前不作为强流程提交接口，仅保留查询语义 |
| 实时收费、对账日志、柜台结账 | `IF-CS-002`、`IF-REV-011` | 历史只读 / 投影查询出口 | 原流水号、渠道、金额、时间、柜员/营业所、状态 | 查询类对象不转为在线主写接口 |
| IC 卡账务表族 | 历史查询扩展接口 | 历史只读 / 映射查询出口 | 卡号、客户号、金额、时间、旧单据标识、映射状态 | 当前仅保留历史只读 + 映射层查询 |
### 最小历史查询保留集
| 查询主题 | 挂靠接口族 | 主要数据来源 | 最低返回要求 | 说明 |
|---------|------------|--------------|--------------|------|
| 历史账单、特殊开账 | `IF-CS-002`、`IF-REV-005` | `biz_charge*` + 历史账单来源 | 原账单号、新账单号、客户号、账期、金额、状态、来源类型 | 支撑账单迁移核查与客户侧历史查询 |
| 缴费记录、柜台结账、实时收费 | `IF-CS-002`、`IF-REV-006`、`IF-REV-011` | `biz_collection`、`bk_transaction*` + 历史收费记录 | 原流水号、渠道、实收金额、收费时间、柜员/营业所、核销状态 | 支撑渠道对账、柜面核查和历史收据核对 |
| 红冲与账务调整 | `IF-REV-007` | 操作留痕、流程结果 + 历史调整台账 | 调整类型、关联原单号、调整金额、原因、审批状态、处理时间 | 支撑预存退款、已销调整、价差调整、分账调整、呆坏账查询 |
| 红冲与账务调整 | `IF-REV-007` | 操作留痕、流程结果 + 历史调整台账 | 对象类型、关联原单号、调整金额、原因、审批状态、处理时间 | 支撑预存退款、已销调整、价差调整、分账调整、呆坏账查询 |
| 退款结果与跨周期支撑对象 | `IF-REV-007`、`IF-CS-002` | 统一结果对象 + 历史只读台账 | 结果单号、来源单号、关联账单、结果状态、时间 | 支撑退款账、跨周期水量、疑难账追溯 |
| 发票与开票关系 | `IF-REV-008`、`IF-CS-004` | `biz_invoice*` + 历史开票关系快照 | 发票号、申请单号、关联账单、票据状态、票据类型、文件地址 | 支撑发票结果核查与历史补打定位 |
| 催缴、停复水、预存短信 | `IF-REV-013`、`IF-METER-002` | 通知结果、流程工单 + 历史催缴记录 | 客户号、账期、催缴方式、消息状态、停复水状态、执行人、执行时间、处置引用 | 支撑催缴处置闭环核查 |
| 业务进度与电子档案 | `IF-CS-006` | `biz_process*`、`biz_content*` + 历史附件目录 | 业务单号、节点状态、处理轨迹、附件数量、附件元数据 | 支撑微网厅与柜台办理进度、电子档案查询 |
@ -1753,6 +1783,7 @@ sequenceDiagram
|---------|--------------|--------------|----------|
| 开账迁移核对 | `IF-REV-005`、`IF-CS-002` | 账期、营业所、客户类型、账单状态 | 同时提供汇总金额/笔数与可追溯明细清单 |
| 收费迁移核对 | `IF-REV-006`、`IF-REV-011`、`IF-CS-002` | 日期、渠道、营业所、收费状态 | 同时提供实收金额、流水数量和异常流水列表 |
| 账务对象迁移核对 | `IF-REV-007` | 对象类型、状态、审批状态、账期、时间 | 同时提供对象汇总、结果状态和单据级明细定位 |
| 发票迁移核对 | `IF-REV-008`、`IF-CS-004` | 开票日期、票据类型、开票状态 | 同时提供开票汇总、失败原因和票据明细定位 |
| 催缴与停复水核对 | `IF-REV-013`、`IF-METER-002` | 账期、催缴方式、执行状态、处理人 | 同时提供任务统计、执行明细与处置引用 |
| 业务办理与档案核对 | `IF-CS-006` | 业务类型、流程状态、附件类型、创建时间 | 同时提供流程轨迹、附件元数据和缺失标记 |
@ -1761,9 +1792,10 @@ sequenceDiagram
### 接口约束补充
- 历史查询结果应优先返回原系统标识与新系统标识的映射关系，例如原单号、原批次号、原附件标识、当前业务单号。
- 明细查询接口应支持按客户号、证件号、手机号、表号、账期、营业所、渠道、业务单号等组合检索，满足迁移验收定位需求。
- 明细查询接口应支持按客户号、证件号、手机号、表号、账期、营业所、渠道、业务单号、对象类型等组合检索，满足迁移验收定位需求。
- 若历史附件不直接由当前业务服务托管，接口至少返回附件元数据、来源系统、文件引用地址和可访问状态。
- 历史查询接口的导出能力属于查询扩展能力，不应与在线交易接口共用“状态变更”动作。
- 当前若尚未拆出专属账务对象查询接口，应在统一入口或查询扩展接口中保留 `objectType` 维度，避免后续迁移验收无法区分对象类别。
<a id="sec-status"></a>
## 实现状态说明
@ -1775,6 +1807,7 @@ sequenceDiagram
- 客户与账户查询、维护接口
- 抄表任务与抄表数据接口
- 账单生成与收费核销接口
- `IF-REV-007` 作为当前统一账务处理入口的正式接口位置
- 银行代收、代扣、交易回调、对账、结算接口
- 发票申请与票据状态回写接口的业务侧支撑
- 客户渠道的账户绑定、查询、缴费、业务办理进度接口
@ -1783,7 +1816,8 @@ sequenceDiagram
以下接口域已有主线支撑，但部分细粒度对象仍需结合后续实现继续核实：
- 账务调整、退款、坏账、冲正类精细接口
- `IF-REV-007` 对全量账务对象的完整对象化表达
- 账务调整、退款、坏账、冲正、红冲、价差调整、分账调整、违约金减免等精细对象查询能力
- 催缴管理中针对不同通知策略和停复水联动的细分接口
- 发票补开等扩展票据后处理接口
@ -1791,6 +1825,8 @@ sequenceDiagram
以下内容可保留设计说明，但当前不应直接表述为已完全落地：
- 后续专属账务对象接口方向（例如预存退款、红冲、价差调整、分账调整等专属接口）
- `AccountingWorkflowRef`、`AccountingLegacyMapping` 等目标对象在接口层的独立实现形态
- 历史数据字典中大量细粒度账务台账接口
- 未在 backend 当前扫描范围内明确识别到的独立业务对象接口
- 特定银行或地方平台的专有报文细节