2024年12月19日
本文档为 01_Detailed_Design.md
中“营收业务详细设计”章节的模块正文拆分稿，便于按模块独立维护。正式交付口径以主详设为准。
SYS-002
负责营收主流程，发票、支付结算、消息触达分别通过
SYS-008、SYS-009、SYS-010
协同完成，外部系统仅回写结果状态。biz_* 与 bk_*
命名体系，历史命名仅用于追溯，不作为本章节正式设计口径。说明：详细字段与报文以
../03_Technical_Design/03_Interface_Design.md为准，数据库字段口径以../03_Technical_Design/01_Database_Design.md为准。
| REV 模块 | 关键接口 | 核心数据域（摘要） | 主要协同对象 |
|---|---|---|---|
| REV-001 客户资料管理 | IF-REV-001 |
biz_cust、biz_account、biz_cust_* |
客户服务模块、报装模块 |
| REV-002 抄表开账 | IF-REV-004、IF-REV-005 |
biz_meter_book、biz_meter_read、biz_reading_*、biz_charge* |
抄表APP、物联网集抄 |
| REV-003 营业收费 | IF-REV-006 |
biz_charge*、biz_collection、bk_transaction* |
SYS-009 |
| REV-004 账务处理 | IF-REV-007 |
biz_charge*、biz_operat_log* |
财务与营业人员 |
| REV-005 发票与税务处理 | IF-REV-008 |
biz_invoice*、biz_cust_invoice |
SYS-008 |
| REV-006 催缴与通知 | IF-REV-013 |
biz_charge*、催缴结果留痕 |
SYS-010 |
| REV-007 统计分析 | IF-REV-010 |
客户、抄表、收费、渠道聚合对象 | 统计分析端 |
| REV-008 代收与银行业务 | IF-REV-011 |
bk_withholding_*、bk_reconcile_*、bk_settlement_* |
SYS-009、银行 |
| REV-009 业务参数配置 | IF-REV-012 |
biz_parameter_settings、biz_page_settings*、biz_price_* |
统一平台、营收模块 |
负责客户主档、账户主档、联系人、客户分组、客户与水表关系、客户开票信息、客户渠道绑定及托收/代扣关系维护，是抄表、收费、发票、代扣等后续业务的主数据基础。
biz_cust：客户主档。biz_account：客户账户与账户状态。biz_cust_contact：联系人及联系方式。biz_cust_group：客户分组。biz_cust_meter：客户与水表绑定关系。biz_cust_invoice：客户开票信息。biz_cust_app_binds：渠道绑定关系。biz_cust_collection_rel：客户托收关系。biz_cust_withholding_rel：客户代扣关系。biz_cust_water_use_scheme、biz_cust_water_scheme_rel：客户计划用水方案关系。biz_cust_no_rule：客户编号规则。biz_cust_hub_marks：集收号/集收标记关系。IF-REV-001：客户档案、账户状态、联系人与水表绑定关系查询。IF-CS-001、IF-CS-002：客户服务侧账户绑定与信息查询场景复用客户域数据。负责抄表计划、册本管理、抄表录入、抄表状态跟踪、异常复核、计费计算与账单生成，是营收核心处理链路的起点。
flowchart TD
A[制定抄表计划] --> B[生成抄表册本]
B --> C[分配抄表任务]
C --> D[人工/远传/自报抄表]
D --> E[数据校验]
E --> F{是否异常}
F -->|是| G[异常复核处理]
F -->|否| H[生成开账数据]
G --> H
H --> I[按价格模板与费用组成计费]
I --> J[生成营业账与明细]
J --> K[账单审核确认]
K --> L[进入收费/催缴/开票]
IF-REV-005
的正式边界是“抄表校验完成后的账单生成”，不负责收费核销、发票开具、催缴执行和统计分析。biz_charge 与
biz_charge_detail
承接：主表表达客户、账期、应收日期、账单总金额和主状态，明细表表达费用组成、用量、单价和明细金额。SYS-006 / IoT
能力提供采集支撑，但账单生成仍归属 SYS-002。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
只负责生成营业账结果并交由后续审核/收费链路消费，不在本章节扩展收费核销、发票申请或催缴执行细节。biz_meter_book：册本与抄表计划。biz_meter_read：抄表任务状态/执行状态。biz_reading_data：抄表数据。biz_last_reading：上次抄表结果。biz_reading_logs：抄表日志与过程留痕。biz_meter：计量水表主档引用。biz_charge：营业账主表。biz_charge_detail：营业账明细。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_charge、biz_charge_detail
作为开账结果承载对象，不建议额外平行建设“特殊开账账表”。IF-REV-004：抄表数据提交与异常标记。IF-REV-005：账单生成与开账结果返回。IF-METER-004：远传抄表数据接收后进入开账流程。支持柜台收费、预存款/余额抵扣、线上缴费回写、柜面扫码、营业网点收费及收费凭证管理，统一承接营收账单的核销处理。
flowchart TD
A[查询客户及待缴账单] --> B[选择账单与核销方式]
B --> C[选择支付渠道]
C --> D{支付方式}
D -->|柜台现金/POS/扫码| E[现场收费]
D -->|微信/支付宝/聚合支付| F[渠道下单]
D -->|预存款/余额抵扣| G[账户余额核销]
E --> H[更新营业账状态]
F --> I[等待异步回调确认]
G --> H
I --> H
H --> J[生成收费记录与凭证]
J --> K[进入发票/对账流程]
SYS-009 提供，SYS-002
负责账单核销与业务状态回写。PayCeb
的欠费查询、缴费处理基础闭环可用，但代理收费对账仍为预留能力；正式文档不得将实时收费对账写成已闭环能力。biz_charge、biz_charge_detail：待缴与已缴账单主明细。biz_collection：托收/代收主表。biz_withholding：代扣/托收主表。bk_transaction：渠道交易流水。bk_transaction_callback：支付回调记录。bk_transaction_exception：支付异常记录。IF-REV-006：创建收费记录、执行账单核销并回写状态。IF-CS-003、IF-CS-007：客户渠道与柜面扫码支付场景复用收费核销链路。REV-004
一期仅覆盖水量调整、金额调整、退款、冲正、坏账申请五类场景，统一挂靠
IF-REV-007
作为账务处理入口，目标是在既有正式文档体系内先收敛范围、承接口径、留痕要求与审批边界。
本阶段按“共性能力先统一、场景能力再分批”组织：先统一账单承接、原交易校验、结果表达、操作留痕与审批边界，再分别展开五类场景。违约金减免、分账调整、价差调整、跨周期水量、预存退款细表等内容仅作为旧系统迁移语义或后续扩展参考，不作为一期新增独立范围。
flowchart TD
A[发起账务调整申请] --> B[校验账单状态与权限]
B --> C{是否通过}
C -->|否| D[驳回并记录原因]
C -->|是| E[执行重算或退款冲正]
E --> F[更新账单与明细状态]
F --> G[写入操作日志与审批留痕]
G --> H[返回处理结果]
biz_charge /
biz_charge_detail 为主承接对象，并通过
biz_operat_log / biz_operat_log_detail
记录处理依据、前后变化和责任归属。bk_transaction、bk_transaction_callback、bk_transaction_exception
等原支付流水及渠道状态校验，不允许仅依据账单状态直接处理。resultStatus、writeBackStatus，其中
resultStatus 表示处理结论，writeBackStatus
表示账单状态回写结论，两者不得混用。approvalRequired、PENDING_APPROVAL
与审批边界说明，不展开完整 BPM
流程、节点、流转规则或审批回写实现细节。biz_charge、biz_charge_detail：账务调整的核心对象，承接调整前后账单主明细状态。bk_transaction、bk_transaction_callback、bk_transaction_exception：退款、冲正场景的原交易校验与异常追溯对象。biz_operat_log、biz_operat_log_detail：操作与变更留痕，记录字段差异、处理说明、附件依据与责任归属。| 场景 | 说明 | 控制要点 |
|---|---|---|
| 水量调整 | 更正异常水量 | 需复核原因、附件和原抄表依据 |
| 金额调整 | 更正账单金额 | 需记录依据、差异金额和审批边界 |
| 退款 | 退回客户支付资金或预存款 | 需校验原交易、退款余额与幂等性 |
| 冲正 | 修正误收/误核销记录 | 需关联原交易与账单状态 |
| 坏账申请 | 对长期欠费进行分类处理 | 需结合账龄、客户状态与审批边界 |
| 旧账务对象 | 当前承接方式 | 迁移口径 |
|---|---|---|
| 预存退款 / 预存退款详情 | 作为账务处理场景承接 | 保留申请单、原支付引用、退款结果与审批留痕 |
| 已销调整汇总 / 明细 | 作为已收费后修正场景承接 | 保留原账单、调整原因、前后差异、处理结果 |
| 价差调整汇总 / 明细 | 作为重算与差额修正场景承接 | 保留原价格口径、新价格口径、差额和生效时间 |
| 分账调整汇总 / 明细 | 作为费用组成重分摊场景承接 | 保留原分摊结果、调整后结果、责任人和审批链 |
| 账单-违约金减免 | 作为滞纳金修正场景承接 | 保留减免原因、减免金额、审批结果和生效时间 |
| 账单-呆坏账 | 作为坏账申请与生效场景承接 | 保留账龄、申请原因、审批结果、核销状态 |
IF-REV-007：账务调整、退款、冲正、坏账等处理入口。IF-REV-006：与收费核销状态联动，确保调账后账单状态一致。负责发票业务闭环的业务接入与状态落账，覆盖后台发票申请、开票校验、SYS-008
异步协同、查询兜底、结果回写、账单关联、客户侧已开票电子发票查询/下载/推送，以及后台作废与红冲处理。
flowchart TD
A[后台提交发票申请] --> B[校验账单、客户开票信息、税率与限额]
B --> C{是否满足开票条件}
C -->|否| D[返回不可开票原因]
C -->|是| E[生成申请单号并写入SUBMITTED]
E --> F[调用SYS-008发起异步开票]
F --> G[记录受理号并转为PENDING]
G --> H[系统轮询或后台查询兜底]
H --> I{开票结果}
I -->|成功| J[回写SUCCESS并更新账单-发票关联]
I -->|失败| K[回写FAIL并记录失败原因]
J --> L[客户侧查询/下载/推送电子发票]
SUBMITTED：后台申请已受理，已完成本地校验并生成申请单。PENDING：已提交
SYS-008，等待异步结果或查询补偿结果。SUCCESS：已取得有效发票代码、号码或电子票地址，且账单关联已完成更新。FAIL：开票失败，需保留失败原因、最近查询结果与后续人工核查依据。INVALID：发票已作废，作为后续能力预留状态。RED_INK：发票已红冲，作为后续能力预留状态。SYS-008 采用“异步申请 +
查询兜底”模式，成功状态不得被后续失败查询结果覆盖。SUCCESS
且存在票据文件地址时允许客户侧下载或推送。SYS-008
统一承接税控侧处理，SYS-002
负责后台触发入口、状态校验、查询补偿、结果落账与日志留痕；当前轮次按二期范围补齐
backend 实现入口。SUBMITTED/PENDING
状态流转，失败校验场景不进入外部协同。applicationNo 或
custId + chargeIds 为主，避免相同账单组合重复申请。SYS-002 先写入
biz_invoice 申请记录，再向 SYS-008
发起异步开票请求，并记录 sysRequestNo
作为后续查询与回写的协同主键。SYS-008 返回“已受理”后，发票状态转为
PENDING；若仅完成本地受理但尚未拿到受理号，则保留
SUBMITTED 并进入待补偿查询状态。IF-EXT-007
回写为首选结果来源，后台人工查询与系统定时补偿查询共用同一结果落账逻辑。SUCCESS
属于正常开票闭环终态，一旦已取得有效发票代码、发票号码或电子票据地址，后续失败查询结果不得覆盖成功状态。FAIL 仅在 SYS-008
明确返回失败结论或多次补偿查询确认失败时写入，并同步保留失败原因、最近查询结果与人工核查依据。IF-EXT-007 回写成功结果时，除更新
biz_invoice.invoice_status、invoice_code、invoice_number、file_url
外，还应同步刷新账单快照、账单关联状态与推送状态初值。biz_invoice.charge_id +
charge_ids_snapshot 记录本次开票覆盖账单集合，并同步把对应
biz_charge.invoice_state
更新为“开票完成”，保留失败原因与开票时间，便于账单明细、收费记录和客户侧结果统一展示。custId
访问已存在的发票记录；可通过
invoiceId、applicationNo 或
sysRequestNo 定位，但都必须命中同一客户名下记录。SUCCESS 且
fileUrl
非空；不满足条件时仅返回不可下载/推送原因，不得伪造文件地址。pushStatus=PUSHED，失败则写入 FAIL
并保留失败原因供人工处理。biz_invoice：发票主记录。biz_invoice_taxrate：税率配置。biz_cust_invoice：客户开票信息。biz_invoice、biz_invoice_taxrate、biz_cust_invoice，但迁移时不能忽略旧开票明细和账单关联关系。IF-REV-008：后台发票申请接口，负责单笔/批量申请、幂等控制与受理号生成。IF-REV-009：发票结果查询接口，负责后台按申请单号/受理号查询以及系统补偿查询。IF-CS-004：客户侧电子发票消费接口，负责已开票结果查看、下载、推送。IF-EXT-007：发票结果回写协同接口（由发票服务侧回传）。SYS-008
统一承接，但当前轮次补齐后台触发入口、状态流转、结果回写与日志留痕，不再仅停留于文档预留。针对欠费账单按账龄、金额、客户类别等规则生成催缴任务，通过短信、微信、站内通知等方式触达客户，并回写催缴结果；本模块同时定义催缴与停复水/工单处置之间的联动边界与追溯关系，但不展开停复水内部处置流程。
flowchart TD
A[生成欠费客户清单] --> B[按策略分组催缴任务]
B --> C[触发IF-REV-013生成催缴任务]
C --> D[调用IF-EXT-008协同SYS-010]
D --> E[接收发送结果回写]
E --> F[更新催缴状态与后续策略]
F --> G[按联动边界挂接停复水/工单处置]
SYS-002
负责催缴对象筛选、任务生成、业务事件编号、结果承接与历史查询；SYS-010
负责短信、微信公众号、站内信等触达执行与结果回传。REV-006 正式结果状态固定为
PENDING、SUCCESS、FAIL、MANUAL_VERIFIED
四态，其中 MANUAL_VERIFIED
仅用于外部结果未定或需人工核查补记的场景。IF-REV-013
任务生成前必须完成候选筛选，筛选最小维度为：欠费状态、欠费金额、账龄分组、客户类别、渠道偏好和策略编码。triggerType
区分自动与人工；自动用于批量触发，人工用于补发、核查和例外补记，不改变正式接口编号与状态语义。biz_charge、biz_charge_detail：催缴对象来源。Reminder Candidate：由欠费账单、客户类别、账龄分组、欠费金额、联系方式集合和命中策略编码组成，是催缴任务的输入对象。Reminder Strategy：定义账龄规则、金额规则、客户类别规则、渠道优先级、重复触达拦截窗口和是否触发后续处置关注。Reminder Task：一次正式催缴执行单元，至少包含
taskNo、eventNo、strategyCode、channelType、triggerType、status
和关联账单信息；正式业务接口编号固定为 IF-REV-013。Reminder Result：承接 IF-EXT-008
回传结果后由业务侧映射的正式四态结果，最少记录
status、lastCallbackTime、failReason
与回传摘要。Disposal Link：用于记录催缴结果与停水、复水、工单或人工跟进之间的关联引用，只承担追溯职责，不替代下游业务对象。PENDING：已生成任务并完成外部受理或等待外部终态回传，尚未形成业务终态。SUCCESS：外部触达结果明确成功，且业务侧已完成结果承接。FAIL：外部返回明确失败或业务判定失败，必须记录失败原因。MANUAL_VERIFIED：仅用于外部结果长期未定、人工核查补记或例外核销说明场景；必须留存核查说明与核查人。REV-006 中展开停复水内部流程设计。Disposal Link
的处置引用承接，最少包含任务号、处置类型、处置引用号和建联时间。IF-REV-013：催缴任务生成、任务查询与结果承接接口，负责业务侧任务生成、四态状态维护和历史查询挂接。IF-EXT-008：消息协同结果回写接口（由
SYS-010 协同）。提供营收、抄表、收费、欠费、渠道、客户等多维度统计查询能力，为经营分析、业务监管和迁移核查提供统一的数据口径支撑；本模块以经营查询为主，不扩展到预测分析、专题大屏或独立 BI 平台实现。
biz_cust、biz_account。biz_meter_book、biz_reading_data、biz_last_reading。biz_charge、biz_charge_detail。biz_collection、bk_transaction。bk_transaction、bk_payment_channel。system_dept、数据权限控制结果。Statistics Theme：按经营主题组织查询，至少覆盖营收、收费、欠费、客户、渠道、抄表完成率和必要的业务概览。Statistics Dimension：按时间、账期、营业所/片区、客户类别、渠道、客户/账户、状态等条件筛选或分组。Statistics Indicator：至少明确应收金额、实收金额、欠费余额、账单数、客户数、交易笔数、渠道占比、完成率等指标含义和单位。Aggregation Source：统计结果以现有在线主数据聚合、视图或汇总口径承接，不反推为已存在独立统计表族。IF-REV-010：营收、收费、欠费、渠道、客户等统计查询接口，承接主题查询、维度筛选、指标汇总和权限/导出边界。支持银行代收、银行代扣、实时收费、夜间批量扣款、对账与结算处理，是
SYS-002 面向 SYS-009 支付与银行结算能力的业务承接模块。
flowchart TD
A[生成代扣批次] --> B[校验签约与待扣账单]
B --> C[调用IF-REV-011下发批次]
C --> D[SYS-009对接银行处理]
D --> E[回写扣款结果]
E --> F[执行对账与差异识别]
F --> G{差异是否已处理}
G -->|否| H[进入人工补偿]
G -->|是| I[确认结算并更新状态]
SYS-009
承载，SYS-002 保留业务规则与状态协同。BankWithholding
六条银行入口（客户状态查询、送盘、送盘状态查询、取消送盘、回盘、回盘状态查询）已形成最小实现态闭环；BankCollection
平行链路、对账与结算协同仍以“部分实现或文档先行”表述，不得统一写成已闭环能力。TENANT_CHANNEL > TENANT > CHANNEL > DEFAULT。send/back/reconcile/archive/localTemp
五类阶段；上层覆盖未完整定义时按字段级回退，不允许生成空路径。{tenantId}、{companyId}、{channelCode}、{yyyyMMdd}、{yyyyMM}、{batchNo}、{fileName}
七个固定变量；命中未声明变量或缺少变量取值时立即阻断文件动作。BankWithholding 在送盘创建时固化
sendProtocol/sendDir/sendFilePath 与
backProtocol/backDir，配置切换仅影响新发起文件动作，已落库批次继续沿用原解析结果。bk_payment_channel：支付渠道。bk_channel_api_config：渠道接口配置。bk_channel_route_rule：渠道路由规则。bk_withholding_agreement：代扣签约。bk_withholding_batch、bk_withholding_item：代扣批次与明细。bk_reconcile_batch、bk_reconcile_diff：对账批次与差异。bk_settlement_batch：结算批次。bk_transaction、bk_transaction_callback、bk_transaction_exception：交易、回调、异常。biz_collection、biz_withholding：代收/代扣业务主对象。bk_channel_api_config 使用专用
apiType=FILE_TRANSFER_CONFIG
承接文件传输覆盖配置，extParams
记录作用域、业务类型、协议、连接引用和五类目录字段。bk_withholding_batch
固化送盘/回盘目录与协议，bk_reconcile_batch
固化对账阶段最终
protocol/dir/filePath/fileName，用于审计与问题回放。biz_collection + bk_*
渠道模型，迁移时应补出“旧托收菜单 →
托收批次/交易/回盘结果”的映射，而不是按旧菜单名平移建模。bk_transaction*
作为主承接对象，并补充按结算日期、银行/渠道、收费结果、差异状态查询和导出能力说明。PayCeb
路径已具备欠费查询、缴费处理、流水唯一性校验和交易日志留痕，可作为实时收费基础闭环的实现证据。BankWithholding
路径已具备签约、解约、客户状态查询、送盘、送盘状态查询、取消送盘、回盘、回盘状态查询及对应交易留痕的实现证据，可作为代扣最小实现态闭环依据。BankCollection
路径当前仍仅能确认签约、解约与协议/交易日志处理具备实现证据。IF-REV-011：代扣批次、对账与结算协同入口。IF-EXT-001：银行代扣批次下发与回盘协同。IF-EXT-003：银行实时收费查询、缴费与结果确认协同。BankWithholding
的客户状态查询、送盘、送盘状态查询、取消送盘、回盘、回盘状态查询和对应日志留痕等主对象已具备明确实现证据。BankCollection
批次、明细、送盘、回盘、状态查询、差异台账和后台资源管理入口已具备对象或骨架，但不等同于银行协同闭环全部完成；BankWithholding
的真实文件解析、异常补偿和运行态联调证据仍待补齐。负责营收域的价格参数、客户编号规则、页面配置、打印与渠道相关业务参数配置，为客户、开账、收费、发票、催缴等模块提供统一配置支撑。
biz_parameter_settings：业务参数配置。biz_page_settings、biz_page_settings_detail：页面配置。biz_price_category、biz_price_template、biz_template_dept_rel：价格归属与模板站点关系。biz_cust_no_rule：客户编号规则。sys_wechat_app_settings：微信/微网厅基础配置。IF-REV-012：查询与维护价格模板、业务参数、页面参数配置。IF-UP-004：统一平台参数字典能力协同，为营收域参数提供基础字典支撑。