fujian_water_biz_doc/output/03_Interface_Design_processed.md

title, author, date, documentclass, geometry, fontsize, mainfont, CJKmainfont

title	author	date	documentclass	geometry	fontsize	mainfont	CJKmainfont
03_Interface_Design	系统设计团队	2024年12月19日	article	margin=1in	11pt	PingFang SC	PingFang SC

---

doc_id: TC-03-INTERFACE doc_role: master_document authority: primary scope: 接口设计 source_of_truth: true last_reviewed: 2026-03-12 retrieval_priority: P0

福建水务营收系统接口设计文档

文档信息

项目信息	详情
项目名称	福建水务营收系统
文档类型	接口设计文档
技术框架	Spring Cloud Alibaba + RuoYi-Vue-Pro + yudao-ui-admin-vue3
文档版本	v1.0
编写日期	2026-03-11
文档状态	✅ 已完成（按版本迭代）

章节导航（精简）

• 接口设计范围
• 设计原则与统一约束
• SYS-002 接口视图
• 外部接口设计
• 内部接口设计
• 数据对象与表口径
• 接口安全与异常处理
• 历史查询与迁移校验接口口径
• 实现状态说明

接口设计范围

本文档用于描述福建水务营收系统的接口边界、调用方式、核心接口清单以及与外围子系统的协同关系，重点统一 SYS-002 营收业务系统的接口口径。

本次接口整编遵循以下事实来源：

• docs/design/02_Detailed_Design/01_Detailed_Design.md
• docs/design/03_Technical_Design/01_Database_Design.md
• docs/guides/BACKEND_CURRENT_STATUS.md
• docs/guides/BACKEND_TABLE_MAPPING.md
• output/preview/福建水务营收系统整体架构图.html

说明：本文档优先描述正式设计边界与业务接口职责，不将 backend 中尚未明确识别的内部实现细节误写为既有接口事实。对于历史资料中存在、但当前 backend 未完全确认的接口对象，统一按“文档先行”处理。

设计原则与统一约束

接口设计原则

• 统一编号：接口编号统一采用 IF-UP-*、IF-REV-*、IF-CS-*、IF-METER-*、IF-INST-*、IF-EXT-* 规则。
• 统一边界：SYS-002 负责营收业务主流程，发票、支付结算、消息触达分别通过 SYS-008、SYS-009、SYS-010 协同完成。
• 统一数据口径：接口数据对象优先对齐真实 biz_* 与 bk_* 表，不再沿用旧稿中的 customer_*、billing_*、thirdpay_*、service_* 等历史命名。
• 统一协议风格：内部管理接口以 HTTPS REST 为主，跨系统集成根据场景采用 REST、文件交换、消息队列等方式。
• 统一安全机制：内部接口采用统一认证鉴权，外部接口按渠道要求实施签名、回调校验、白名单和审计留痕。

通用响应格式

内部 REST 接口统一采用如下响应模型：

{
  "code": 0,
  "data": {},
  "msg": "success"
}

分页响应统一采用：

{
  "code": 0,
  "data": {
    "list": [],
    "total": 0,
    "pageNo": 1,
    "pageSize": 10
  },
  "msg": "success"
}

SYS-002 接口视图

模块分组

营收核心模块群

模块编号	模块名称	接口职责定位
REV-001	客户资料管理	客户、账户、联系人、水表绑定等主数据查询与维护
REV-002	抄表开账	抄表任务、抄表数据、校验、开账触发
REV-003	营业收费	收费受理、账单核销、柜台与渠道收款状态回写
REV-004	账务处理	调整、退款、冲正、坏账等账务处理申请与结果回写
REV-005	发票管理	发票申请、开票结果回写、票据状态查询
REV-006	催缴管理	催缴名单生成、催缴任务下发、通知结果回写
REV-007	统计分析	营收、抄表、收费、客户、渠道统计查询
REV-008	代收业务	银行代收、代扣、送盘、回盘、对账、结算协同
REV-009	业务参数配置	水价、费用组成、业务参数、页面参数等配置接口

客户服务模块群

模块编号	模块名称	接口职责定位
CS-001	账户绑定管理	客户绑定、解绑、默认客户切换
CS-002	信息查询服务	账单、欠费、用水、缴费、停水公告等查询
CS-003	在线缴费服务	创建线上支付订单、支付状态查询
CS-004	电子发票服务	发票申请、发票列表、下载与推送
CS-005	营业网点服务	网点查询、预约、导航、业务事项查询
CS-006	业务办理服务	更名、过户、低保、换表、自主抄表等线上办理
CS-007	柜面扫码支付	柜台二维码收款、订单生成、支付结果回写

跨系统协同边界

协同子系统	协同内容	SYS-002 职责	对方职责
SYS-008 发票服务	发票开具、作废、红冲、票据查询	提供业务上下文、账单信息、客户开票信息，接收结果回写	承接税控与电子发票能力
SYS-009 支付与银行结算	微信/支付宝支付、银行实时收费、代扣、对账、结算	发起订单、接收支付结果、维护账单核销状态	承接支付渠道、交易流水、回调、对账与结算
SYS-010 消息服务	催缴通知、缴费结果通知、办理进度通知	生成待通知业务事件与目标用户	承接短信、微信公众号、站内信等触达能力

外部接口设计

外部接口分类

接口分类	主要对接方	典型协议	说明
银行代收/代扣接口	银行、银联、托收平台	文件交换 / HTTPS REST	主要服务 REV-008
聚合支付接口	微信支付、支付宝等	HTTPS REST + 回调	主要服务 REV-003、CS-003、CS-007
发票协同接口	税控/电子发票平台	HTTPS REST	主要服务 REV-005、CS-004
消息通知接口	短信平台、消息网关	HTTPS REST / MQ	主要服务 REV-006、CS-006
物联网集抄接口	集抄平台、IoT 平台	HTTPS REST / MQ	主要服务 REV-002

IF-EXT-001 银行代扣批次下发接口

项目	说明
接口编号	IF-EXT-001
接口名称	银行代扣批次下发接口
归属模块	REV-008
调用方向	SYS-002 → SYS-009 / 银行渠道
接口方式	文件交换或 HTTPS REST
业务说明	按账期生成待代扣账单批次，交由银行渠道执行代扣
核心数据支撑	biz_withholding、bk_withholding_batch、bk_withholding_item

关键报文信息包括：客户号、签约号、扣款金额、账期、渠道编码、批次号等。

边界约束：

• 当前正式设计包含代扣送盘、回盘与对账的目标边界；其中 BankWithholding 已具备送盘、送盘状态查询、取消送盘等六条银行入口的最小实现态闭环证据。
• 正式文档可将 BankWithholding 六条银行入口写为“已实现”，但需同时注明真实银行文件解析、SFTP/文件通道联调与运行态样本仍待补证。
• 涉及批量文件交互时，正式口径保留 HTTP/REST/SFTP 与文件命名、批次号约束，不下沉到特定银行私有报文字段。
• 运行时文件传输配置统一由解析器输出 protocol/resolvedDir/resolvedPath/fileName/sourceScope；优先级固定为 TENANT_CHANNEL > TENANT > CHANNEL > DEFAULT，高优先级仅覆盖部分字段时按字段级回退。
• 命中协议缺少 host/port/username/credentialRef、阶段目录为空或模板变量非法时，接口必须立即返回配置错误，不得回退到错误租户或错误通道。

IF-EXT-002 银行代扣回盘接收接口

项目	说明
接口编号	IF-EXT-002
接口名称	银行代扣回盘接收接口
归属模块	REV-008
调用方向	银行渠道 / SYS-009 → SYS-002
接口方式	文件交换或 HTTPS REST
业务说明	接收代扣成功、失败、退票等结果并回写业务状态
核心数据支撑	bk_withholding_batch、bk_withholding_item、bk_transaction、bk_transaction_exception

边界约束：

• 回盘处理、回盘状态查询、差异核对和结算确认属于同一能力簇；其中 BankWithholding 的回盘与回盘状态查询已具备最小实现态闭环证据，但完整差异核对、异常补偿和结算确认仍属后续完善项。
• 当前正式文档允许保留回盘文件名、批次号、回盘日期、结果状态等正式字段约束，但不得把未落地的真实文件解析、异常补偿和结算闭环写成既成事实。

IF-EXT-003 银行实时收费接口

项目	说明
接口编号	IF-EXT-003
接口名称	银行实时收费接口
归属模块	REV-003 / REV-008
调用方向	银行渠道 / SYS-009 ↔ SYS-002
接口方式	HTTPS REST
业务说明	支撑柜台、网银、手机银行实时查询应收并完成缴费
核心数据支撑	biz_charge、biz_charge_detail、bk_transaction、bk_transaction_callback

边界约束：

• 当前 backend 已确认欠费查询与缴费处理具备实现证据，可作为正式文档中的已落地基础能力。
• 代理收费对账、汇总对账和当日未对账红冲等扩展能力当前仍未形成完整实现闭环，正式文档须标注为后续完善项。

银行签约、状态查询与批次控制扩展接口

接口动作	推荐归属	当前代码路径	当前状态	正式口径
代扣签约	REV-008 / SYS-009	BankWithholdingController#signing	已实现	可作为正式接口能力写入
代扣解约	REV-008 / SYS-009	BankWithholdingController#termination	已实现	可作为正式接口能力写入
托收签约	REV-008 / SYS-009	BankCollectionController#signing	已实现	可作为正式接口能力写入
托收解约	REV-008 / SYS-009	BankCollectionController#termination	已实现	可作为正式接口能力写入
客户状态查询	REV-008 / SYS-009	BankWithholdingController#customerCheck / BankCollectionController#customerCheck	代扣已实现；托收部分实现	代扣可作为正式接口能力写入；托收仅保留正式契约边界与结果状态
送盘	REV-008 / SYS-009	BankWithholdingController#sendDisc / BankCollectionController#sendDisc	代扣已实现；托收部分实现	代扣可作为正式接口能力写入；托收仅保留正式契约边界与批次发送语义
送盘状态查询	REV-008 / SYS-009	BankWithholdingController#sendDiscCheck / BankCollectionController#sendDiscCheck	代扣已实现；托收部分实现	代扣可作为正式接口能力写入；托收仅保留正式契约边界与批次状态语义
取消送盘	REV-008 / SYS-009	BankWithholdingController#cancelDisc / BankCollectionController#cancelDisc	代扣已实现；托收部分实现	代扣可作为正式接口能力写入；托收仅保留正式契约边界与可取消条件
回盘	REV-008 / SYS-009	BankWithholdingController#backDisc / BankCollectionController#backDisc	代扣已实现；托收部分实现	代扣可作为正式接口能力写入；托收仅保留正式契约边界与回盘处理语义
回盘状态查询	REV-008 / SYS-009	BankWithholdingController#backDiscCheck / BankCollectionController#backDiscCheck	代扣已实现；托收部分实现	代扣可作为正式接口能力写入；托收仅保留正式契约边界与回盘状态语义

IF-EXT-004 聚合支付下单接口

项目	说明
接口编号	IF-EXT-004
接口名称	聚合支付下单接口
归属模块	REV-003 / CS-003 / CS-007
调用方向	SYS-002 → SYS-009
接口方式	HTTPS REST
业务说明	创建微信、支付宝等支付订单，返回二维码、收银参数或支付跳转信息
核心数据支撑	biz_charge、biz_collection、bk_transaction

IF-EXT-005 聚合支付结果回调接口

项目	说明
接口编号	IF-EXT-005
接口名称	聚合支付结果回调接口
归属模块	REV-003 / CS-003 / CS-007
调用方向	SYS-009 → SYS-002
接口方式	HTTPS REST + 签名校验
业务说明	接收支付成功、失败、关闭、退款等异步事件，并更新收费状态
核心数据支撑	bk_transaction_callback、biz_collection、biz_charge

IF-EXT-006 发票开具协同接口

项目	说明
接口编号	IF-EXT-006
接口名称	发票开具协同接口
归属模块	REV-005 / CS-004
调用方向	SYS-002 → SYS-008
接口方式	HTTPS REST
业务说明	传递账单、客户、抬头、税率等信息，由 SYS-008 承接开票
核心数据支撑	biz_invoice、biz_invoice_taxrate、biz_cust_invoice

IF-EXT-007 发票结果回写接口

项目	说明
接口编号	IF-EXT-007
接口名称	发票结果回写接口
归属模块	REV-005 / CS-004
调用方向	SYS-008 → SYS-002
接口方式	HTTPS REST
业务说明	回写开票状态、票据编号、下载地址、作废/红冲结果
核心数据支撑	biz_invoice、biz_process_invoice_modifys

IF-EXT-008 消息触达接口

项目	说明
接口编号	IF-EXT-008
接口名称	消息触达接口
归属模块	REV-006 / CS-006
调用方向	SYS-002 → SYS-010
接口方式	HTTPS REST 或 MQ
业务说明	承接催缴通知、办理进度通知、缴费结果通知等消息事件，返回受理结果并回传执行结果
核心数据支撑	biz_charge、biz_process、biz_operat_log

边界约束：

• IF-EXT-008 只负责渠道触达执行与回执回传，不负责催缴候选对象筛选、任务生成或业务状态主控。
• SYS-010 回传的渠道执行结果需由 SYS-002 映射为 PENDING、SUCCESS、FAIL、MANUAL_VERIFIED 四态业务状态。
• 当仅返回受理成功但未返回终态时，SYS-002 维持 PENDING；若长期无终态且人工核查确认，可转 MANUAL_VERIFIED。
• 消息模板、供应商协议和重试细节由 SYS-010 管理，不在 IF-EXT-008 展开实现细节。

IF-EXT-009 集抄数据接入接口

项目	说明
接口编号	IF-EXT-009
接口名称	集抄数据接入接口
归属模块	REV-002
调用方向	IoT 平台 / 集抄平台 → SYS-002
接口方式	HTTPS REST / MQ
业务说明	接收远传读数、设备状态、异常告警，触发抄表校验与开账准备
核心数据支撑	biz_meter_read、biz_reading_data、biz_last_reading

内部接口设计

SYS-002 内部接口清单

REV 接口清单

接口编号	接口名称	归属模块	主要用途	主要数据对象
IF-REV-001	客户信息查询接口	REV-001	查询客户档案、联系人、账户、水表绑定关系	biz_cust、biz_account、biz_cust_contact、biz_cust_meter
IF-REV-002	客户主数据维护接口	REV-001	新增、变更客户档案及开票/托收/代扣关系	biz_cust、biz_cust_invoice、biz_cust_collection_rel、biz_cust_withholding_rel
IF-REV-003	抄表任务下发接口	REV-002	按册本、片区、抄表周期生成抄表任务	biz_meter_book、biz_meter_read
IF-REV-004	抄表数据提交接口	REV-002	提交抄表数据、图片、异常标记并触发校验	biz_reading_data、biz_reading_logs、biz_last_reading
IF-REV-005	账单生成接口	REV-002	根据抄表结果、价格模板和费用组成生成账单	biz_charge、biz_charge_detail、biz_price_template、biz_cost_component
IF-REV-006	缴费处理接口	REV-003	创建收费记录、核销账单、回写收款结果	biz_collection、biz_charge、bk_transaction
IF-REV-007	账务调整接口	REV-004	发起金额调整、退款、冲正、坏账等业务处理	biz_charge、biz_charge_detail、biz_operat_log
IF-REV-008	发票申请接口	REV-005	后台发起单笔/批量开票申请并生成受理主键	biz_invoice、biz_invoice_taxrate、biz_cust_invoice
IF-REV-009	发票结果查询接口	REV-005	按申请单号/受理号查询开票结果并执行补偿查询	biz_invoice、biz_operat_log
IF-REV-013	催缴任务生成与结果承接接口	REV-006	生成催缴任务、查询任务结果并承接四态状态回写	biz_charge、biz_operat_log、历史催缴查询口径
IF-REV-010	统计查询接口	REV-007	查询营收、收费、欠费、渠道、客户统计结果	聚合视图 / 统计结果集
IF-REV-011	银行代收协同接口	REV-008	发起代扣、回盘、对账、结算协同	biz_withholding、bk_reconcile_batch、bk_settlement_batch
IF-REV-012	业务参数配置接口	REV-009	查询和维护价格模板、优惠方案、业务参数配置	biz_parameter_settings、biz_price_*、biz_page_settings*

CS 接口清单

接口编号	接口名称	归属模块	主要用途	主要数据对象
IF-CS-001	账户绑定接口	CS-001	绑定、解绑、切换默认客户	biz_cust_app_binds、biz_cust
IF-CS-002	历史账单查询接口	CS-002	查询账单、欠费、用水历史、缴费记录	biz_charge、biz_charge_detail、biz_reading_data
IF-CS-003	在线支付下单接口	CS-003	创建微信/支付宝线上支付订单	biz_charge、biz_collection、bk_transaction
IF-CS-004	电子发票消费接口	CS-004	查询、下载、推送本人已开具电子发票	biz_invoice、biz_cust_invoice
IF-CS-005	网点与业务办理接口	CS-005	查询营业网点、预约信息、可办事项	biz_outlets、biz_business_types
IF-CS-006	业务办理进度接口	CS-006	提交业务申请、查询办理进度与附件	biz_process、biz_process_transfer、biz_content_attach
IF-CS-007	柜面扫码支付接口	CS-007	创建柜面扫码支付订单并回写结果	biz_collection、bk_transaction、biz_charge

UP 接口清单

接口编号	接口名称	归属模块	主要用途	主要数据对象
IF-UP-001	用户登录接口	UP-001	用户登录并获取访问令牌	system_users、system_oauth2_access_token、system_login_log
IF-UP-002	用户信息接口	UP-001	查询当前登录用户上下文信息	system_users、system_dept
IF-UP-003	权限校验接口	UP-002	校验菜单、按钮、数据权限	system_role、system_role_menu、system_user_role
IF-UP-004	参数字典接口	UP-003	查询字典、参数、配置项	system_dict_type、system_dict_data、biz_parameter_settings

METER 接口清单

接口编号	接口名称	归属模块	主要用途	主要数据对象
IF-METER-001	水表档案查询接口	METER-001	查询水表档案、状态与生命周期信息	biz_meter、biz_meter_model、biz_meter_caliber、biz_meter_range
IF-METER-002	表务工单处理接口	METER-003	提交换表、移表、校表、维修等工单处理结果	biz_meter_log、biz_process、biz_process_transfer
IF-METER-003	库存出入库接口	METER-002	处理领用、退库、报废等库存动作	biz_meter_in_out、biz_meter_in_out_rel
IF-METER-004	集抄数据接收接口	METER-003	接收远传抄表、异常告警并同步状态	biz_reading_data、biz_meter_read、biz_last_reading

INST 接口清单

接口编号	接口名称	归属模块	主要用途	主要数据对象
IF-INST-001	报装申请提交接口	INST-001	提交报装申请、附件与基础资料	biz_process、biz_content、biz_content_attach
IF-INST-002	踏勘结果回填接口	INST-001	回填现场踏勘、方案与审核结果	biz_process_transfer、biz_business_datas
IF-INST-003	合同签署发起接口	INST-002	发起电子签章任务并传输合同信息	installation_contract、installation_signature
IF-INST-004	签章回执接口	INST-002	回写签章结果、时间戳和存证信息	installation_signature、installation_evidence
IF-INST-005	报装归档接口	INST-003	归档申请、合同、验收与签章回执资料	biz_content_attach、installation_evidence

关键内部接口说明

IF-UP-001 用户登录接口

项目	说明
接口编号	IF-UP-001
归属模块	UP-001
请求方式	POST
请求路径	/admin-api/system/auth/login
功能描述	统一认证入口，签发访问令牌并输出用户上下文
核心表	system_users、system_oauth2_access_token、system_login_log

IF-REV-001 客户信息查询接口

项目	说明
接口编号	IF-REV-001
归属模块	REV-001
请求方式	GET
请求路径	/admin-api/revenue/customer/{id}
功能描述	查询客户主档、账户状态、联系人、水表绑定及开票资料
核心表	biz_cust、biz_account、biz_cust_contact、biz_cust_meter、biz_cust_invoice

响应结果以客户主档为中心，组合返回账户余额、欠费金额、联系人列表、水表列表与开票资料摘要。

IF-REV-004 抄表数据提交接口

项目	说明
接口编号	IF-REV-004
归属模块	REV-002
请求方式	POST
请求路径	/admin-api/revenue/reading-data/create
功能描述	接收人工或远传抄表数据，执行校验、估抄判断、异常标记
核心表	biz_meter_read、biz_reading_data、biz_last_reading、biz_reading_logs

典型请求体：

{
  "meterReadId": 1001,
  "meterId": 2001,
  "readTime": "2026-03-11 09:30:00",
  "currentReading": 156.32,
  "readType": "MANUAL",
  "photoList": [
    "file-001",
    "file-002"
  ],
  "gps": "119.2965,26.0745",
  "remark": "现场抄表正常"
}

IF-REV-005 账单生成接口

项目	说明
接口编号	IF-REV-005
归属模块	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<String>，仅表达“本次复核成功X条 / 本次开账成功Y条”，尚未提供正式契约要求的成功清单、失败清单、生成汇总和主明细结果对象。
• 单条失败当前主要以 log.warn + false 跳过处理，尚未形成可直接对外返回的结构化阻断码、失败原因集合与对象范围。

IF-REV-006 缴费处理接口

项目	说明
接口编号	IF-REV-006
归属模块	REV-003
请求方式	POST
请求路径	/admin-api/revenue/collection/create
功能描述	处理柜台收费、预存抵扣、渠道收款确认与账单核销
核心表	biz_collection、biz_charge、bk_transaction

IF-REV-007 账务调整接口

项目	说明
接口编号	IF-REV-007
归属模块	REV-004
请求方式	POST
请求路径	/admin-api/revenue/accounting/adjust
功能描述	发起水量调整、金额调整、退款、冲正、坏账申请五类账务处理，并统一返回处理结果、审批边界与账单回写状态
核心表	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-008 发票申请接口

项目	说明
接口编号	IF-REV-008
归属模块	REV-005
请求方式	POST
请求路径	/business/invoice/apply
功能描述	后台对已收费未开票账单发起单笔/批量开票申请，并在同一管理域内受理作废/红冲后处理入口
核心表	biz_invoice、biz_invoice_taxrate、biz_cust_invoice

边界约束：

• 一期仅支持后台营业收费员/财务人员发起申请，客户侧不直接调用本接口。
• 发票开具、作废、红冲能力均由 SYS-008 统一承接税控侧处理，SYS-002 负责业务单据归集、申请发起、后台作废/红冲触发、查询补偿与结果落账。
• 后台发票后处理沿同一管理域补充 /business/invoice/invalidate 与 /business/invoice/red-ink 两个入口，分别承接作废与红冲动作；处理结果继续通过 IF-REV-009 或 IF-EXT-007 统一收口。
• 原始单账单不支持直接任意部分金额开票；如需多张发票，应基于拆账/分账后的账单集合申请。

IF-REV-009 发票结果查询接口

项目	说明
接口编号	IF-REV-009
归属模块	REV-005
请求方式	POST
请求路径	/business/invoice/query（补偿查询：/business/invoice/query/compensate）
功能描述	后台按申请单号/受理号查询开票、作废或红冲结果，并支持系统补偿查询兜底
核心表	biz_invoice、biz_operat_log

IF-REV-013 催缴任务生成与结果承接接口

项目	说明
接口编号	IF-REV-013
归属模块	REV-006
请求方式	POST
请求路径	/admin-api/revenue/reminder/task（查询：/admin-api/revenue/reminder/task/query，人工核查：/admin-api/revenue/reminder/task/manual-verify）
功能描述	基于欠费账单、催缴策略和渠道偏好生成催缴任务，查询任务状态，并承接业务侧四态结果与处置引用
核心表	biz_charge、biz_charge_detail、biz_operat_log、历史催缴查询口径

边界约束：

• IF-REV-013 是 REV-006 的正式业务接口编号，不再复用 IF-REV-009。
• SYS-002 负责催缴对象筛选、任务生成、业务事件号维护、四态状态承接和历史查询；SYS-010 只负责触达执行与结果回传。
• 接口状态固定为 PENDING、SUCCESS、FAIL、MANUAL_VERIFIED 四态，不在本轮扩展“已阅读”“已补发”等细粒度业务状态。
• 停复水仅作为联动边界与处置引用承接项，不在本接口中展开停复水内部流程。

IF-REV-010 统计查询接口

项目	说明
接口编号	IF-REV-010
归属模块	REV-007
请求方式	POST
请求路径	/admin-api/revenue/statistics/query（导出：/admin-api/revenue/statistics/export）
功能描述	面向营收经营分析场景查询统计主题、维度汇总和指标结果，并在权限范围内支持导出
核心表	biz_charge、biz_charge_detail、biz_collection、bk_transaction、biz_cust、biz_account、biz_meter_book、biz_reading_data

边界约束：

• IF-REV-010 只承接经营统计查询，不扩展到预测分析、BI 专题大屏或独立数仓查询。
• 统计口径按“主题 + 维度 + 指标”组织，避免仅以报表名称表达接口范围。
• 导出属于查询扩展能力，必须受数据权限和导出权限控制。
• 没有明确实现证据的独立统计表、专题分析表或离线汇总表不得写成既成事实。

IF-REV-011 银行代收协同接口

项目	说明
接口编号	IF-REV-011
归属模块	REV-008
请求方式	POST
请求路径	/admin-api/revenue/bank/withholding/batch
功能描述	创建代扣批次、发起对账、接收结算回写
核心表	biz_withholding、bk_withholding_batch、bk_reconcile_batch、bk_settlement_batch

边界约束：

• IF-REV-011 在当前阶段主要承接正式业务协同边界，不等同于送盘、回盘、对账、结算全部已闭环。
• 已确认的后台管理入口可证明批次、差异、结算台账对象存在，但不能替代银行 app 协同接口的完成度判断。

IF-REV-012 业务参数配置接口

项目	说明
接口编号	IF-REV-012
归属模块	REV-009
请求方式	GET / POST
请求路径	/admin-api/revenue/parameter/config
功能描述	查询与维护价格模板、业务参数、页面参数与规则配置
核心表	biz_parameter_settings、biz_price_*、biz_page_settings*

IF-CS-001 账户绑定接口

项目	说明
接口编号	IF-CS-001
归属模块	CS-001
请求方式	POST
请求路径	/app-api/customer/account/bind
功能描述	绑定、解绑、切换默认客户账户，并校验渠道身份与客户关系
核心表	biz_cust_app_binds、biz_cust、biz_account

IF-CS-002 历史账单查询接口

项目	说明
接口编号	IF-CS-002
归属模块	CS-002
请求方式	GET
请求路径	/app-api/customer/bill/history
功能描述	查询账单、欠费、缴费、用水历史及发票摘要
核心表	biz_charge、biz_charge_detail、biz_reading_data、biz_invoice

IF-CS-003 在线支付下单接口

项目	说明
接口编号	IF-CS-003
归属模块	CS-003
请求方式	POST
请求路径	/app-api/customer/payment/order
功能描述	面向微网厅、微信、支付宝等客户渠道创建支付订单
核心表	biz_charge、biz_collection、bk_transaction

边界约束：

• 支付通道、支付回调、对账流水由 SYS-009 负责。
• SYS-002 负责校验待缴账单、生成业务订单、更新核销结果。

IF-CS-004 电子发票消费接口

项目	说明
接口编号	IF-CS-004
归属模块	CS-004
请求方式	POST
请求路径	/business/invoice/customer/query、/business/invoice/customer/download、/business/invoice/customer/push
功能描述	面向客户渠道查询、下载、推送本人已开具电子发票
核心表	biz_invoice、biz_cust_invoice、biz_invoice_taxrate

边界约束：

• 一期客户侧仅消费已形成 SUCCESS 终态且具备票据地址的电子发票结果，不直接发起开票申请。
• 发票作废、红冲仍由 SYS-008 统一承接税控侧处理；IF-CS-004 仅消费当前仍可展示、下载、推送的有效电子发票结果，不开放客户侧直接发起作废或红冲。

IF-CS-006 业务办理进度接口

项目	说明
接口编号	IF-CS-006
归属模块	CS-006
请求方式	GET / POST
请求路径	/app-api/customer/process
功能描述	提交业务办理申请、查询办理进度、补充附件资料
核心表	biz_process、biz_process_transfer、biz_business_datas、biz_content_attach

IF-CS-007 柜面扫码支付接口

项目	说明
接口编号	IF-CS-007
归属模块	CS-007
请求方式	POST
请求路径	/admin-api/counter/scan-pay/create
功能描述	柜台生成扫码订单，接收支付结果并回写收费状态
核心表	biz_collection、bk_transaction、biz_charge

IF-METER-001 水表档案查询接口

项目	说明
接口编号	IF-METER-001
归属模块	METER-001
请求方式	GET
请求路径	/admin-api/meter/archive/{id}
功能描述	查询水表档案、状态、参数与生命周期信息
核心表	biz_meter、biz_meter_model、biz_meter_caliber、biz_meter_range

IF-METER-002 表务工单处理接口

项目	说明
接口编号	IF-METER-002
归属模块	METER-003
请求方式	POST
请求路径	/admin-api/meter/work-order/handle
功能描述	提交换表、移表、校表、维修等工单处理结果并回写设备状态
核心表	biz_meter_log、biz_process、biz_process_transfer

IF-METER-003 库存出入库接口

项目	说明
接口编号	IF-METER-003
归属模块	METER-002
请求方式	POST
请求路径	/admin-api/meter/stock/in-out
功能描述	处理领用、退库、报废等库存动作并更新生命周期状态
核心表	biz_meter_in_out、biz_meter_in_out_rel、biz_meter

IF-METER-004 集抄数据接收接口

项目	说明
接口编号	IF-METER-004
归属模块	METER-003
请求方式	POST
请求路径	/admin-api/meter/iot/reading/receive
功能描述	接收远传抄表、设备状态和异常告警并同步读数状态
核心表	biz_reading_data、biz_meter_read、biz_last_reading

IF-INST-001 报装申请提交接口

项目	说明
接口编号	IF-INST-001
归属模块	INST-001
请求方式	POST
请求路径	/admin-api/installation/apply/create
功能描述	提交报装申请、基础资料与附件，并创建流程实例
核心表	biz_process、biz_content、biz_content_attach

IF-INST-002 踏勘结果回填接口

项目	说明
接口编号	IF-INST-002
归属模块	INST-001
请求方式	POST
请求路径	/admin-api/installation/survey/result
功能描述	回填现场踏勘结果、方案版本和审核结论
核心表	biz_process_transfer、biz_business_datas

IF-INST-003 合同签署发起接口

项目	说明
接口编号	IF-INST-003
归属模块	INST-002
请求方式	POST
请求路径	/admin-api/installation/contract/sign/initiate
功能描述	发起报装合同签署流程，并与 CA 系统协同处理签章、时间戳和存证
核心表	installation_contract、installation_signature、installation_evidence

IF-INST-004 签章回执接口

项目	说明
接口编号	IF-INST-004
归属模块	INST-002
请求方式	POST
请求路径	/admin-api/installation/contract/sign/callback
功能描述	回写签章结果、时间戳、存证回执与签章文件地址
核心表	installation_signature、installation_evidence

IF-INST-005 报装归档接口

项目	说明
接口编号	IF-INST-005
归属模块	INST-003
请求方式	POST
请求路径	/admin-api/installation/archive/submit
功能描述	归档申请资料、验收附件、合同文件与签章回执
核心表	biz_content_attach、installation_evidence、biz_process

字段级请求与响应定义

说明：以下字段级定义服务于接口设计说明，重点体现业务含义、来源对象与跨系统协同所需关键字段，不等同于数据库表的完整字段清单。

IF-REV-001 客户信息查询接口

请求参数

字段	类型	必填	说明	主要来源
id	Long	否	客户主键 ID，与 code 二选一	biz_cust.id
code	String	否	客户编号，与 id 二选一	biz_cust.code
mobile	String	否	客户手机号，支持模糊校验查询	biz_cust.mobile / biz_cust_contact.mobile
queryType	String	否	查询类型：base、account、meter、invoice、all	查询控制参数

响应参数

字段	类型	说明	主要来源
id	Long	客户主键 ID	biz_cust.id
code	String	客户编号	biz_cust.code
name	String	客户名称	biz_cust.name
custType	String	客户类型	biz_cust.cust_type
mobile	String	主要联系电话	biz_cust.mobile
address	String	客户地址	biz_cust.address
accountInfo	Object	账户信息对象	biz_account
accountInfo.balance	Decimal	账户余额	biz_account.balance
accountInfo.arrearsAmount	Decimal	欠费金额	biz_account.arrears_amount
accountInfo.status	String	账户状态	biz_account.status
contactList	Array	联系人列表	biz_cust_contact
meterList	Array	绑定水表列表	biz_cust_meter、biz_meter
invoiceInfo	Object	开票信息摘要	biz_cust_invoice

IF-REV-004 抄表数据提交接口

请求参数

字段	类型	必填	说明	主要来源/去向
meterReadId	Long	是	抄表任务 ID	biz_meter_read.id
meterId	Long	是	水表 ID	biz_meter.id
readTime	Datetime	是	抄表时间	biz_reading_data.read_time
currentReading	Decimal	是	本次读数	biz_reading_data.current_reading
readType	String	是	抄表方式：MANUAL、IOT、IMPORT	biz_reading_data.read_type
usageAmount	Decimal	否	本次用量，可由系统自动计算	biz_reading_data.usage_amount
photoList	Array	否	表盘照片或现场图片文件标识	附件系统 / 文件服务
gps	String	否	现场坐标	扩展信息
remark	String	否	异常说明或现场备注	biz_reading_logs.remark
abnormalFlag	Boolean	否	是否标记异常	过程状态

响应参数

字段	类型	说明	主要来源
readingId	Long	抄表数据主键	biz_reading_data.id
meterReadId	Long	抄表任务 ID	biz_meter_read.id
validateStatus	String	校验状态：PASS、WARN、REJECT	校验结果
abnormalFlag	Boolean	是否识别为异常	过程判断
nextAction	String	后续动作：BILLING、RECHECK、MANUAL_REVIEW	流程控制
msg	String	处理说明	返回消息

IF-REV-005 账单生成接口

请求参数

字段	类型	必填	说明	主要来源/去向
billPeriod	String	是	账期，如 2026-03	开账批次参数
readingBatchNo	String	否	抄表批次号	抄表批次
customerIds	Array	否	指定客户范围	biz_cust.id
meterReadIds	Array	否	指定抄表任务范围	biz_meter_read.id
dueDate	Date	是	应收截止日期	biz_charge.due_date
operatorId	Long	否	发起操作人	操作上下文

响应参数

字段	类型	说明	主要来源
generateCount	Integer	成功生成账单数量	汇总信息
successList	Array	成功明细列表	biz_charge
successList[].chargeId	Long	账单主键	biz_charge.id
successList[].chargeCode	String	账单编号	biz_charge.code
successList[].custId	Long	客户 ID	biz_charge.cust_id
successList[].totalAmount	Decimal	账单总金额	biz_charge.total_amount
failureList	Array	失败明细列表	处理结果
failureList[].reason	String	失败原因	异常信息

IF-REV-006 缴费处理接口

请求参数

字段	类型	必填	说明	主要来源/去向
custId	Long	是	客户 ID	biz_charge.cust_id
chargeIds	Array	是	待核销账单 ID 列表	biz_charge.id
paymentChannel	String	是	支付渠道：CASH、WECHAT、ALIPAY、BANK、PREPAY	渠道参数
paymentAmount	Decimal	是	本次支付金额	biz_collection.amount
actualAmount	Decimal	否	实收金额，柜台收费场景使用	柜台收费扩展
tradeNo	String	否	外部交易流水号	bk_transaction.trade_no
outletCode	String	否	柜台或网点编号	biz_outlets.code
remark	String	否	收费备注	biz_collection.remark

响应参数

字段	类型	说明	主要来源
collectionId	Long	收费记录 ID	biz_collection.id
collectionCode	String	收费业务编号	biz_collection.code
writeOffStatus	String	核销状态：SUCCESS、PARTIAL、PENDING	业务状态
paidAmount	Decimal	已支付金额	汇总结果
remainAmount	Decimal	剩余待支付金额	汇总结果
tradeNo	String	渠道交易流水号	bk_transaction.trade_no
invoiceAvailable	Boolean	是否可发起开票	业务判断

IF-REV-007 账务调整接口

请求参数

字段	类型	必填	说明	主要来源/去向
chargeId	Long	是	目标账单 ID	biz_charge.id
adjustType	String	是	调整类型：USAGE、AMOUNT、REFUND、REVERSE、BAD_DEBT	业务类型
adjustAmount	Decimal	否	调整金额	biz_charge_detail / 业务计算
adjustUsage	Decimal	否	调整水量	业务计算
sourceTradeNo	String	否	原交易流水号，退款/冲正场景使用	bk_transaction.trade_no
reasonCode	String	是	调整原因编码	业务字典
remark	String	否	调整说明	biz_operat_log.remark
attachmentList	Array	否	依据附件	附件系统
operatorId	Long	是	操作人 ID	操作上下文

响应参数

字段	类型	说明	主要来源
adjustmentNo	String	调整业务编号	业务流水
chargeId	Long	目标账单 ID	biz_charge.id
resultStatus	String	处理状态：SUCCESS、PENDING_APPROVAL、FAIL	业务状态
writeBackStatus	String	账单回写状态	业务状态
approvalRequired	Boolean	是否进入审批	流程判断
msg	String	处理说明	返回消息

IF-REV-008 发票申请接口

请求参数

字段	类型	必填	说明	主要来源/去向
applicationNo	String	否	发票申请单号	服务端生成，作为幂等主键之一
custId	Long	是	客户 ID	biz_invoice.cust_id
chargeIds	Array	是	开票关联账单 ID 列表	业务单据关联
invoiceType	String	是	发票类型：ELECTRONIC、PAPER	biz_invoice.invoice_type
invoiceTitle	String	是	发票抬头	biz_cust_invoice.invoice_title
taxNo	String	否	税号	biz_cust_invoice.tax_no
email	String	否	电子发票接收邮箱	biz_cust_invoice.email
mobile	String	否	接收手机号	biz_cust_invoice.mobile
sourceChannel	String	是	来源渠道：COUNTER、FINANCE_BACKOFFICE	业务来源
remark	String	否	申请备注	操作留痕

响应参数

字段	类型	说明	主要来源
invoiceId	Long	发票申请记录 ID	biz_invoice.id
applicationNo	String	发票申请单号	biz_invoice.application_no
invoiceStatus	String	状态：SUBMITTED、PENDING、REJECTED	biz_invoice.invoice_status
sysRequestNo	String	发往 SYS-008 的受理号	协同流水
msg	String	处理说明	返回消息

申请校验与幂等约束

• 所有关联账单必须满足“已收费、未开票、未作废”。
• 一期不支持原始单账单直接任意部分金额开票；如需多张发票，必须基于拆账/分账后的账单集合发起申请。
• 企业抬头场景应校验 taxNo 完整性；电子发票场景优先校验 email 或 mobile 至少一项可用。
• 幂等键优先使用 applicationNo，未传入时按 custId + chargeIds 组合控制重复申请。
• 申请成功后必须创建查询补偿上下文，不依赖回调作为唯一结果来源。

后台作废请求参数（/business/invoice/invalidate）

字段	类型	必填	说明	主要来源/去向
invoiceId	Long	是	发票记录 ID	biz_invoice.id
invalidReason	String	是	作废原因	biz_invoice.invalid_reason
invalidRemark	String	否	作废备注	biz_invoice.invalid_remark
originalInvoiceCode	String	否	原发票代码；传入时必须与当前发票记录一致	biz_invoice.original_invoice_code
originalInvoiceNumber	String	否	原发票号码；传入时必须与当前发票记录一致	biz_invoice.original_invoice_number

后台红冲请求参数（/business/invoice/red-ink）

字段	类型	必填	说明	主要来源/去向
invoiceId	Long	是	发票记录 ID	biz_invoice.id
redInkReason	String	是	红冲原因	biz_invoice.red_ink_reason
redInkRemark	String	否	红冲备注	biz_invoice.red_ink_remark
originalInvoiceCode	String	否	原发票代码；传入时必须与当前发票记录一致	biz_invoice.original_invoice_code
originalInvoiceNumber	String	否	原发票号码；传入时必须与当前发票记录一致	biz_invoice.original_invoice_number

后台作废/红冲处理约束

• 作废与红冲仅允许对当前 invoiceStatus=SUCCESS 的记录发起；已进入 INVALID 或 RED_INK 的记录必须拒绝重复处理。
• 后台提交作废或红冲后，应同步写入原因、备注、原票引用与触发来源，当前实现的触发来源分别为 ADMIN_INVALIDATE、ADMIN_RED_INK。
• 作废与红冲的即时返回仅表示后台已受理本次后处理动作；最终状态仍通过 IF-REV-009 查询补偿或 IF-EXT-007 回写统一收口。
• 后处理动作必须保留操作日志，记录触发人、目标状态、原因、备注与原发票代码/号码。

IF-REV-009 发票结果查询接口

请求参数

字段	类型	必填	说明	主要来源/去向
applicationNo	String	否	发票申请单号，与 sysRequestNo 二选一	biz_invoice.application_no
sysRequestNo	String	否	SYS-008 受理号，与 applicationNo 二选一	biz_invoice.sys_request_no
querySource	String	是	查询来源：MANUAL、AUTO_COMPENSATE、CALLBACK_VERIFY	查询触发上下文

响应参数

字段	类型	说明	主要来源
invoiceId	Long	发票主记录 ID	biz_invoice.id
applicationNo	String	发票申请单号	biz_invoice.application_no
sysRequestNo	String	SYS-008 受理号	biz_invoice.sys_request_no
invoiceStatus	String	状态：SUBMITTED、PENDING、SUCCESS、FAIL、INVALID、RED_INK	biz_invoice.invoice_status
invoiceCode	String	发票代码	biz_invoice.invoice_code
invoiceNumber	String	发票号码	biz_invoice.invoice_number
fileUrl	String	电子发票文件地址	biz_invoice.file_url
failReason	String	失败原因	biz_invoice.fail_reason
pushStatus	String	电子发票推送状态	biz_invoice.push_status
lastQueryTime	DateTime	最近一次查询时间	biz_invoice.last_try_time
tryCount	Integer	累计查询次数	biz_invoice.try_count
latestResult	String	最近一次查询结果摘要	biz_invoice.latest_result
latestError	String	最近一次查询异常说明	biz_invoice.latest_error
msg	String	处理说明	返回消息

查询补偿与状态流转约束

• 查询入口同时服务于后台人工查询与系统补偿查询，两类触发必须复用同一状态落账规则。
• 当 querySource=AUTO_COMPENSATE 时，接口语义表示由系统补偿任务触发一次兜底查询，并刷新最近查询时间、下次计划时间与累计次数。
• 查询结果若确认开票成功，应回写票号、票据地址与账单-发票关联状态；若仍处理中，仅维持 PENDING 并更新补偿上下文。
• 对已发起作废或红冲的记录，查询结果应允许把终态更新为 INVALID 或 RED_INK，并同步刷新 latestResult、latestError、账单关联状态与后处理上下文。
• 已进入 SUCCESS 的正常开票终态不得被后续失败查询结果覆盖；若外部返回异常，应记录到操作留痕并保留人工核查入口。

IF-REV-013 催缴任务生成与结果承接接口

请求参数

字段	类型	必填	说明	主要来源/去向
taskNo	String	否	催缴任务号；查询/人工核查时必填	任务主键
custId	Long	是	客户标识	biz_charge.cust_id
chargeIds	Array	是	欠费账单集合	biz_charge.id
billPeriod	String	是	账期	biz_charge.bill_period
arrearsAmount	Decimal	是	欠费金额汇总	欠费汇总结果
strategyCode	String	是	命中的催缴策略编码	策略规则
channelType	String	是	触达渠道：短信/微信公众号/站内信等	任务分组结果
triggerType	String	是	触发方式：AUTO / MANUAL	任务触发上下文
eventNo	String	否	业务事件号；生成后返回，回写承接时作为关联键	协同事件主键
relatedDisposalRef	String	否	关联停复水或工单引用	联动追溯信息
manualVerifyNote	String	否	人工核查说明；仅人工核查时填写	核查留痕

响应参数

字段	类型	说明	主要来源
taskNo	String	催缴任务号	任务主键
interfaceCode	String	固定返回 IF-REV-013	接口常量
eventNo	String	业务事件号	协同主键
status	String	状态：PENDING、SUCCESS、FAIL、MANUAL_VERIFIED	任务状态
resultTime	DateTime	最近结果时间	结果回写时间
failureReason	String	失败原因	失败回写
resultChannel	String	实际触达渠道	协同结果
relatedDisposalRef	String	关联停复水或工单引用	联动追溯
msg	String	处理说明	返回消息

任务生成与状态承接约束

• 任务生成前必须完成欠费账单、客户类别、联系方式和策略命中校验；至少存在一个可用触达渠道。
• 相同业务事件与同一接收对象在去重窗口内不得重复生成等效任务；若为人工补发，应显式记录 triggerType=MANUAL。
• PENDING 表示已生成任务并发起协同，等待 SYS-010 回写或人工核查；SUCCESS、FAIL 由协同结果或明确失败确认触发。
• 当外部结果长期未定、历史回执不足或人工核查已确认结果时，可将任务补记为 MANUAL_VERIFIED，并保留核查人和核查说明。
• 接口返回的 relatedDisposalRef 仅用于追溯停复水、复水或工单处置引用，不表示本接口承担下游流程控制。

失败阻断与人工核查约束

• 候选账单不满足欠费前提、策略编码无效或触达信息缺失时，应阻断任务生成并返回明确原因，不得写入伪成功状态。
• 频控规则命中时允许部分阻断，必须返回被跳过对象与原因摘要，避免“全成功”误判。
• 渠道协同超时或仅返回受理结果时，不直接判定 FAIL，保持 PENDING 并等待回执或进入人工核查流程。
• 人工核查补记必须校验 taskNo 存在且 manualVerifyNote 非空；不满足条件时应拒绝补记并返回校验错误。
• 人工核查仅用于状态收口，不替代 SYS-010 的渠道执行职责，也不扩展停复水/工单内部流程控制。

IF-REV-010 统计查询接口

请求参数

字段	类型	必填	说明	主要来源/去向
themeCode	String	是	统计主题编码	查询主题
dateFrom	Date	是	开始日期	时间维度
dateTo	Date	是	结束日期	时间维度
billPeriod	String	否	账期	biz_charge.bill_period
deptId	Long	否	营业所/部门	system_dept.id
regionCode	String	否	片区/区域编码	区域维度
customerCategory	String	否	客户类别	客户标签/分类
channelCode	String	否	收费/交易渠道	bk_payment_channel.channel_code
accountId	Long	否	账户标识	biz_account.id
custId	Long	否	客户标识	biz_cust.id
statusSet	Array	否	状态集合	账单/收费/抄表等状态筛选
groupBy	Array	否	分组维度集合	结果分组
exportFlag	Boolean	否	是否导出	导出控制

响应参数

字段	类型	说明	主要来源
themeCode	String	统计主题编码	查询主题
themeName	String	统计主题名称	主题定义
dimensionSummary	Object	查询维度摘要	查询条件
indicatorList	Array	指标结果集合	聚合结果
indicatorList[].indicatorCode	String	指标编码	指标定义
indicatorList[].indicatorName	String	指标名称	指标定义
indicatorList[].indicatorValue	Decimal/String	指标值	聚合结果
indicatorList[].unit	String	指标单位	指标定义
groupRows	Array	分组结果集合	维度分组结果
exportAllowed	Boolean	是否允许导出	权限结果
msg	String	处理说明	返回消息

查询主题与口径约束

• 本接口至少支持营收汇总、收费与实收、欠费规模与账龄、客户结构、渠道交易、抄表完成率等主题查询。
• 应收金额、实收金额、欠费余额、账单数、客户数、交易笔数、渠道占比、完成率等指标必须按业务含义区分，不得混写。
• 当查询涉及历史只读口径时，历史数据仅作为补充来源或迁移核查辅助，不替代在线主数据统计结果。
• 权限边界必须同时作用于在线查询和导出动作；不允许越过现有数据权限返回全量统计结果。

IF-REV-011 银行代收协同接口

请求参数

字段	类型	必填	说明	主要来源/去向
batchNo	String	是	代扣批次号	bk_withholding_batch.batch_no
businessType	String	是	业务类型：WITHHOLDING、RECONCILE、SETTLEMENT	协同类型
channelCode	String	是	渠道编码	bk_payment_channel.channel_code
billPeriod	String	否	账期	批处理参数
itemList	Array	否	批次明细列表	bk_withholding_item
itemList[].custId	Long	是	客户 ID	bk_withholding_item.cust_id
itemList[].chargeId	Long	是	账单 ID	bk_withholding_item.charge_id
itemList[].amount	Decimal	是	扣款金额	业务金额

响应参数

字段	类型	说明	主要来源
batchNo	String	批次号	bk_withholding_batch.batch_no
batchStatus	String	批次状态：CREATED、SENT、RETURNED、RECONCILED、SETTLED	批次状态
successCount	Integer	成功处理条数	汇总结果
failCount	Integer	失败条数	汇总结果
reconcileStatus	String	对账状态	bk_reconcile_batch.status
settlementStatus	String	结算状态	bk_settlement_batch.status
diffList	Array	差异清单摘要	bk_reconcile_diff

IF-REV-012 业务参数配置接口

请求参数

字段	类型	必填	说明	主要来源/去向
action	String	是	动作：QUERY、CREATE、UPDATE	配置动作
configType	String	是	配置类型：PRICE、RULE、PAGE、NOTICE	biz_parameter_settings.config_type
configCode	String	否	配置编码	biz_parameter_settings.config_code
configValue	String	否	配置值或 JSON 内容	biz_parameter_settings.config_value
deptId	Long	否	生效单位	作用域参数
effectiveDate	Date	否	生效日期	生效控制
operatorId	Long	否	操作人 ID	操作上下文

响应参数

字段	类型	说明	主要来源
configId	Long	配置主键	biz_parameter_settings.id
configCode	String	配置编码	biz_parameter_settings.config_code
configVersion	String	配置版本	版本信息
effectScope	String	生效范围	作用域结果
effectStatus	String	生效状态：DRAFT、ACTIVE、EXPIRED	业务状态
msg	String	处理说明	返回消息

IF-CS-001 账户绑定接口

请求参数

字段	类型	必填	说明	主要来源/去向
action	String	是	动作：BIND、UNBIND、SET_DEFAULT	绑定动作
channelType	String	是	渠道类型：WECHAT、ALIPAY、MINIAPP	渠道上下文
channelUserId	String	是	渠道用户标识，如 OpenId	渠道上下文
custId	Long	是	客户 ID	biz_cust.id
accountId	Long	否	账户 ID	biz_account.id
verifyCode	String	否	验证码或身份校验码	安全校验
defaultFlag	Boolean	否	是否设为默认账户	biz_cust_app_binds.is_default

响应参数

字段	类型	说明	主要来源
bindId	Long	绑定关系 ID	biz_cust_app_binds.id
bindStatus	String	绑定状态：BOUND、UNBOUND	业务状态
defaultFlag	Boolean	是否默认账户	biz_cust_app_binds.is_default
custSummary	Object	客户摘要信息	biz_cust
msg	String	处理说明	返回消息

IF-CS-002 历史账单查询接口

请求参数

字段	类型	必填	说明	主要来源/去向
custId	Long	是	客户 ID	客户上下文
queryType	String	是	查询类型：BILL、PAYMENT、USAGE、ARREARS、INVOICE	查询控制
billPeriod	String	否	账期，如 2026-03	biz_charge.bill_period
chargeStatus	String	否	账单状态筛选	biz_charge.status
pageNo	Integer	否	页码	分页参数
pageSize	Integer	否	每页数量	分页参数

响应参数

字段	类型	说明	主要来源
total	Integer	总记录数	分页结果
list	Array	查询结果列表	聚合结果
list[].chargeId	Long	账单 ID	biz_charge.id
list[].billPeriod	String	账期	biz_charge.bill_period
list[].usageAmount	Decimal	用量	biz_reading_data.usage_amount
list[].payStatus	String	缴费状态	业务状态
list[].invoiceStatus	String	开票状态	biz_invoice.invoice_status

IF-CS-004 电子发票消费接口

查询/下载请求参数

字段	类型	必填	说明	主要来源/去向
custId	Long	是	客户 ID	biz_invoice.cust_id
invoiceId	Long	否	发票记录 ID，三选一优先键	biz_invoice.id
applicationNo	String	否	发票申请单号	biz_invoice.application_no
sysRequestNo	String	否	SYS-008 受理号	biz_invoice.sys_request_no

推送请求参数

字段	类型	必填	说明	主要来源/去向
custId	Long	是	客户 ID	biz_invoice.cust_id
invoiceId	Long	是	发票记录 ID	biz_invoice.id
applicationNo	String	否	发票申请单号	biz_invoice.application_no
pushChannel	String	是	推送方式：EMAIL、SMS	推送动作
pushEmail	String	否	推送邮箱，EMAIL 时优先使用	目标地址
pushMobile	String	否	推送手机号，SMS 时优先使用	目标地址

响应参数

字段	类型	说明	主要来源
invoiceId	Long	发票记录 ID	biz_invoice.id
applicationNo	String	发票申请单号	biz_invoice.application_no
invoiceStatus	String	当前状态	biz_invoice.invoice_status
invoiceCode	String	发票代码	biz_invoice.invoice_code
invoiceNumber	String	发票号码	biz_invoice.invoice_number
fileUrl	String	发票下载地址	biz_invoice.file_url
pushStatus	String	推送状态：NONE、PUSHED、FAIL	biz_invoice.push_status
chargeBindStatus	String	账单关联状态：UNBOUND、BOUND	biz_invoice.charge_bind_status
msg	String	处理说明	返回消息

客户侧消费约束

• 客户侧仅允许访问本人 custId 名下发票记录，invoiceId、applicationNo、sysRequestNo 任一定位成功后仍需再次校验客户归属。
• 下载与推送前必须校验 invoiceStatus=SUCCESS 且 fileUrl 非空；已作废、已红冲或缺少电子票地址的记录一律返回不可消费原因。
• 推送成功后回写 pushStatus=PUSHED；失败则更新为 FAIL 并记录失败原因。
• 客户侧只消费已形成有效电子票结果的记录，不暴露后台作废、红冲入口，也不直接展示后处理请求参数。

IF-CS-003 在线支付下单接口

请求参数

字段	类型	必填	说明	主要来源/去向
custId	Long	是	客户 ID	客户上下文
chargeIds	Array	是	待支付账单 ID 列表	biz_charge.id
paymentChannel	String	是	支付渠道：WECHAT、ALIPAY	渠道参数
paymentAmount	Decimal	是	支付金额	bk_transaction.trade_amount
openId	String	否	微信渠道用户标识	微信场景
returnUrl	String	否	前端完成跳转地址	前端场景
notifyUrl	String	否	支付结果通知地址	回调地址

响应参数

字段	类型	说明	主要来源
bizOrderNo	String	SYS-002 业务订单号	biz_collection.code / 业务单号
tradeNo	String	渠道交易流水号	bk_transaction.trade_no
orderStatus	String	订单状态：INIT、PAYING、SUCCESS、FAIL	交易状态
payUrl	String	支付链接或二维码地址	渠道返回
prepayInfo	Object	预支付参数对象	渠道返回
expireTime	Datetime	订单失效时间	交易参数

IF-CS-006 业务办理进度接口

请求参数

字段	类型	必填	说明	主要来源/去向
processId	Long	否	办理流程 ID，查询场景使用	biz_process.id
businessTypeCode	String	否	业务类型编码，如更名、过户、低保、换表	biz_business_types.code
custId	Long	否	客户 ID	客户上下文
applyData	Object	否	业务申请主体数据	biz_business_datas
attachmentList	Array	否	附件文件标识列表	biz_content_attach
action	String	否	动作：CREATE、QUERY、SUPPLEMENT	流程动作

响应参数

字段	类型	说明	主要来源
processId	Long	办理流程 ID	biz_process.id
processCode	String	流程编号	biz_process.code
processStatus	String	当前状态：INIT、ACCEPTED、PROCESSING、DONE、REJECTED	biz_process.status
currentNode	String	当前办理节点	流程状态
transferList	Array	流转轨迹	biz_process_transfer
attachmentRequired	Boolean	是否需要补件	业务判断
msg	String	办理说明	返回消息

IF-CS-007 柜面扫码支付接口

请求参数

字段	类型	必填	说明	主要来源/去向
counterCode	String	是	柜台编号	柜面终端
chargeIds	Array	是	待支付账单 ID 列表	biz_charge.id
paymentChannel	String	是	支付渠道：WECHAT、ALIPAY	渠道参数
orderAmount	Decimal	是	订单金额	bk_transaction.trade_amount
operatorId	Long	是	柜台操作员 ID	操作上下文
scene	String	否	场景标识，默认 COUNTER_SCAN_PAY	场景参数

响应参数

字段	类型	说明	主要来源
bizOrderNo	String	柜面业务订单号	biz_collection.code
tradeNo	String	渠道交易流水号	bk_transaction.trade_no
qrCode	String	柜面展示二维码内容	渠道返回
orderStatus	String	当前订单状态：INIT、PAYING、SUCCESS、FAIL	交易状态
writeBackStatus	String	营收状态回写结果	业务状态
msg	String	处理说明	返回消息

IF-METER-001 水表档案查询接口

请求参数

字段	类型	必填	说明	主要来源
id	Long	否	水表主键 ID，与 code 二选一	biz_meter.id
code	String	否	水表编号，与 id 二选一	biz_meter.code
queryType	String	否	查询类型：base、status、lifeCycle、all	查询控制参数

响应参数

字段	类型	说明	主要来源
id	Long	水表主键 ID	biz_meter.id
code	String	水表编号	biz_meter.code
meterStatus	String	水表状态	biz_meter.status
modelCode	String	型号编码	biz_meter.model_code
caliberCode	String	口径编码	biz_meter.caliber_code
rangeCode	String	量程编码	biz_meter.range_code
installAddress	String	安装地址	biz_meter.install_address
lastReading	Decimal	最近有效读数	biz_last_reading.last_reading

IF-METER-003 库存出入库接口

请求参数

字段	类型	必填	说明	主要来源/去向
action	String	是	动作：IN、OUT、RETURN、SCRAP	库存动作
batchNo	String	是	批次号	biz_meter_in_out.batch_no
warehouseCode	String	否	仓库编码	仓储参数
meterIds	Array	是	水表 ID 列表	biz_meter.id
remark	String	否	出入库说明	biz_meter_in_out.remark
operatorId	Long	是	操作人 ID	操作上下文

响应参数

字段	类型	说明	主要来源
inOutId	Long	出入库主记录 ID	biz_meter_in_out.id
batchNo	String	批次号	biz_meter_in_out.batch_no
actionStatus	String	处理状态：SUCCESS、PARTIAL、FAIL	业务状态
successCount	Integer	成功处理数量	汇总结果
failCount	Integer	失败数量	汇总结果
msg	String	处理说明	返回消息

IF-METER-004 集抄数据接收接口

请求参数

字段	类型	必填	说明	主要来源/去向
meterCode	String	是	水表编号	biz_meter.code
readTime	Datetime	是	采集时间	biz_reading_data.read_time
currentReading	Decimal	是	当前读数	biz_reading_data.current_reading
deviceStatus	String	否	设备状态：ONLINE、OFFLINE、ALARM	设备状态
alarmList	Array	否	告警编码列表	告警结果
fileSerialNo	String	否	上送批次或文件序列号	幂等辅助键
sourceSystem	String	是	来源系统：IOT、MDC	来源标识

响应参数

字段	类型	说明	主要来源
readingId	Long	读数记录 ID	biz_reading_data.id
meterReadId	Long	对应抄表任务 ID	biz_meter_read.id
acceptStatus	String	接收状态：SUCCESS、WARN、REJECT	处理状态
abnormalFlag	Boolean	是否异常	过程判断
nextAction	String	后续动作：BILLING、RECHECK、MANUAL_REVIEW	流程控制
msg	String	处理说明	返回消息

IF-INST-001 报装申请提交接口

请求参数

字段	类型	必填	说明	主要来源/去向
applyType	String	是	报装类型：NEW、REBUILD、ONE_METER_ONE_HOME	业务类型
applicantName	String	是	申请人姓名	申请资料
mobile	String	是	联系手机号	申请资料
address	String	是	申请地址	申请资料
waterUseType	String	是	用水性质	业务字典
sourceChannel	String	是	来源渠道：COUNTER、MINIAPP、GOV	来源标识
attachmentList	Array	否	申请附件列表	biz_content_attach

响应参数

字段	类型	说明	主要来源
processId	Long	流程实例 ID	biz_process.id
processCode	String	报装流程编号	biz_process.code
processStatus	String	当前状态：INIT、ACCEPTED、SURVEYING	biz_process.process_status
acceptStatus	String	受理结果	业务状态
msg	String	处理说明	返回消息

IF-INST-002 踏勘结果回填接口

请求参数

字段	类型	必填	说明	主要来源/去向
processId	Long	是	报装流程 ID	biz_process.id
schemeVersion	String	是	方案版本号	biz_business_datas
surveyResult	String	是	踏勘结论	biz_business_datas
estimateAmount	Decimal	否	预估费用	biz_business_datas
attachmentList	Array	否	现场照片与方案附件	biz_content_attach
auditResult	String	否	审核结果：PASS、REJECT	审核结果

响应参数

字段	类型	说明	主要来源
transferId	Long	流转记录 ID	biz_process_transfer.id
processStatus	String	当前流程状态	biz_process.process_status
nextNode	String	下一节点	流程控制
msg	String	处理说明	返回消息

IF-INST-004 签章回执接口

请求参数

字段	类型	必填	说明	主要来源/去向
contractId	Long	是	合同 ID	installation_contract.id
requestNo	String	是	签章请求号	协同流水
signStatus	String	是	签章状态：SUCCESS、FAIL、CANCEL	installation_signature.signature_status
signerId	String	否	签署人标识	installation_signature.signer_id
signatureTime	Datetime	否	签章时间	installation_signature.signature_time
evidenceNo	String	否	存证编号	installation_evidence.evidence_no
fileUrl	String	否	已签文件地址	结果回写
hashValue	String	否	存证哈希	installation_evidence.hash_value
resultMsg	String	否	结果说明	返回消息

响应参数

字段	类型	说明	主要来源
signatureId	Long	签章记录 ID	installation_signature.id
evidenceId	Long	存证记录 ID	installation_evidence.id
writeBackStatus	String	回写状态：SUCCESS、IGNORE_REPEAT、FAIL	业务状态
msg	String	处理说明	返回消息

IF-INST-005 报装归档接口

请求参数

字段	类型	必填	说明	主要来源/去向
processId	Long	是	报装流程 ID	biz_process.id
archiveType	String	是	归档类型：APPLY、ACCEPT、CHECK、CONTRACT、FINISH	归档分类
attachmentList	Array	是	归档附件列表	biz_content_attach
contractId	Long	否	合同 ID	installation_contract.id
evidenceId	Long	否	存证记录 ID	installation_evidence.id
operatorId	Long	否	归档操作人	操作上下文

响应参数

字段	类型	说明	主要来源
archiveBatchNo	String	归档批次号	业务流水
archiveStatus	String	归档状态：SUCCESS、PARTIAL、FAIL	业务状态
archiveCount	Integer	已归档文件数量	汇总结果
msg	String	处理说明	返回消息

关键接口时序图

说明：以下时序图用于说明 SYS-002 与客户渠道、外部协同子系统之间的交互边界，重点体现业务校验、协同调用、结果回写与状态更新链路。

1. 在线支付下单与回调时序

sequenceDiagram
    autonumber
    participant Client as 客户渠道
    participant SYS002 as SYS-002营收系统
    participant SYS009 as SYS-009支付结算
    participant Channel as 支付渠道

    Client->>SYS002: 提交缴费下单请求(IF-CS-003)
    SYS002->>SYS002: 校验客户、账单状态与应付金额
    SYS002->>SYS002: 生成业务订单与收费记录草稿
    SYS002->>SYS009: 发起支付下单协同(IF-EXT-004)
    SYS009->>Channel: 调用微信/支付宝统一下单
    Channel-->>SYS009: 返回tradeNo、payUrl/prepayInfo
    SYS009-->>SYS002: 返回交易流水与支付参数
    SYS002-->>Client: 返回bizOrderNo、payUrl、expireTime

    Channel-->>SYS009: 异步支付结果通知
    SYS009->>SYS009: 校验签名与交易状态
    SYS009->>SYS002: 回写支付结果(IF-EXT-005)
    SYS002->>SYS002: 幂等校验并更新biz_collection/biz_charge
    SYS002-->>Client: 查询订单时返回最新支付状态

2. 电子发票申请、查询补偿与回写时序

sequenceDiagram
    autonumber
    participant Counter as 柜台或客户渠道
    participant SYS002 as SYS-002营收系统
    participant SYS008 as SYS-008发票服务
    participant Tax as 税控/开票平台
    participant Job as 查询补偿任务

    Counter->>SYS002: 提交发票申请(IF-REV-008/IF-CS-004)
    SYS002->>SYS002: 校验客户、账单、开票抬头与金额
    SYS002->>SYS002: 生成发票申请记录biz_invoice(SUBMITTED)
    SYS002->>SYS008: 发起开票协同(IF-EXT-006)
    SYS008->>Tax: 调用税控或电子发票平台
    Tax-->>SYS008: 返回受理结果/票号/文件地址
    SYS008-->>SYS002: 返回受理号或异步结果
    SYS002->>SYS002: 记录sysRequestNo并更新为PENDING
    alt 发票服务主动回写
        SYS008-->>SYS002: 回写开票结果(IF-EXT-007)
        SYS002->>SYS002: 更新biz_invoice状态、票据地址与账单关联
    else 未收到终态结果
        Job->>SYS002: 触发补偿查询(IF-REV-009)
        SYS002->>SYS008: 按申请单号/受理号查询结果
        SYS008-->>SYS002: 返回处理中/成功/失败
        SYS002->>SYS002: 刷新查询上下文并按终态规则落账
    end
    SYS002-->>Counter: 返回申请结果或供后续查询

3. 银行代扣批次与回盘时序

sequenceDiagram
    autonumber
    participant BatchJob as 代扣批处理任务
    participant SYS002 as SYS-002营收系统
    participant SYS009 as SYS-009支付结算
    participant Bank as 银行渠道

    BatchJob->>SYS002: 发起代扣批次处理(IF-REV-011)
    SYS002->>SYS002: 汇总代扣客户、账单与协议关系
    SYS002->>SYS002: 生成bk_withholding_batch/bk_withholding_item
    SYS002->>SYS002: 解析 send/back/reconcile 目录并固化协议、目录、文件路径
    SYS002->>SYS009: 下发银行代扣批次(IF-EXT-001)
    SYS009->>Bank: 发送代扣文件或报文
    Bank-->>SYS009: 返回受理结果
    SYS009-->>SYS002: 回写批次发送状态

    Bank-->>SYS009: 回盘文件/结果通知(IF-EXT-002)
    SYS009->>SYS009: 解析成功、失败、异常明细
    SYS009->>SYS002: 回写代扣结果、差异与结算状态
    SYS002->>SYS002: 更新biz_withholding、账单核销、对账结算状态
    SYS002-->>BatchJob: 返回批次处理汇总结果

4. 催缴通知下发与结果回写时序

sequenceDiagram
    autonumber
    participant Job as 催缴任务
    participant SYS002 as SYS-002营收系统
    participant SYS010 as SYS-010消息服务
    participant User as 客户

    Job->>SYS002: 触发催缴任务(IF-REV-013)
    SYS002->>SYS002: 按欠费账单、渠道偏好生成催缴名单
    SYS002->>SYS010: 提交通知下发请求(IF-EXT-008)
    SYS010->>User: 发送短信/公众号/APP消息
    User-->>SYS010: 触达回执或阅读反馈
    SYS010-->>SYS002: 回写发送结果与触达状态
    SYS002->>SYS002: 更新催缴记录、四态状态与后续策略
    SYS002-->>Job: 返回催缴任务执行结果

数据对象与表口径

SYS-002 接口核心数据对象

数据域	代表表	接口说明
客户与账户	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_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*	用于业务办理与进度跟踪
银行代收与结算	bk_transaction*、bk_withholding_*、bk_reconcile_*、bk_settlement_batch	用于支付流水、批次、回调、对账和结算

口径约束说明

1. 不再使用旧稿中的 customer_*、water_*、billing_*、thirdpay_*、service_* 作为 SYS-002 正式接口数据口径。
2. 若历史资料中仍存在旧命名，仅作为来源参考，不作为正式交付口径。
3. 对 backend 中尚未明确存在独立实体表的对象，例如部分精细账务台账、红冲明细、价差调整明细等，本文仅描述为业务处理场景，不强写为既有独立接口对象。

跨系统报文映射表

说明：以下映射表用于说明 SYS-002 与 SYS-008、SYS-009、SYS-010 之间的关键报文字段对应关系，重点体现业务主键、状态字段、金额字段与结果回写字段，不展开各外部平台私有扩展字段。

1. SYS-002 ↔ SYS-009 支付下单与结果回写映射

协同场景	SYS-002 字段	SYS-009/渠道字段	说明	主要来源
支付下单	bizOrderNo	businessOrderNo	SYS-002 业务订单号，作为支付协同主键	biz_collection.code
支付下单	chargeIds[]	orderItems[].sourceId	待缴账单明细标识	biz_charge.id
支付下单	custId	buyer.customerId	客户标识	biz_charge.cust_id / biz_cust.id
支付下单	paymentAmount	tradeAmount	交易总金额	bk_transaction.trade_amount
支付下单	paymentChannel	channelCode	支付渠道编码	渠道参数 / bk_payment_channel.channel_code
支付下单	notifyUrl	notifyUrl	支付结果异步通知地址	协同参数
下单返回	tradeNo	tradeNo	渠道交易流水号	bk_transaction.trade_no
下单返回	payUrl/prepayInfo	payUrl/payParams	二维码链接或预支付参数	渠道返回
结果回写	orderStatus	tradeStatus	交易状态映射：INIT/PAYING/SUCCESS/FAIL	bk_transaction.status
结果回写	paidAmount	successAmount	实际支付成功金额	biz_collection.amount / 渠道结果
结果回写	callbackTime	notifyTime	回调时间	bk_transaction_callback.create_time
结果回写	writeOffStatus	writeBackStatus	SYS-002 核销处理结果	业务状态

2. SYS-002 ↔ SYS-008 发票申请与结果回写映射

协同场景	SYS-002 字段	SYS-008 字段	说明	主要来源
发票申请	invoiceCode	requestNo	发票申请单号 / 协同请求号	biz_invoice.code
发票申请	custId	customerId	客户标识	biz_invoice.cust_id
发票申请	chargeIds[]	billList[].sourceBillId	开票关联账单标识	业务单据关联
发票申请	invoiceTitle	buyerName	购方名称 / 抬头	biz_cust_invoice.invoice_title
发票申请	taxNo	buyerTaxNo	购方税号	biz_cust_invoice.tax_no
发票申请	invoiceType	invoiceType	电子/纸质发票类型	biz_invoice.invoice_type
发票申请	taxRateCode	taxRateCode	税率编码	biz_invoice_taxrate.tax_code
发票申请	email / mobile	receiver.email / receiver.mobile	票据接收信息	biz_cust_invoice.email / biz_cust_invoice.mobile
结果回写	invoiceStatus	invoiceStatus	开票状态：受理中、成功、失败、作废、红冲等	biz_invoice.invoice_status
结果回写	invoiceNo	invoiceNo	发票号码	开票结果
结果回写	fileUrl	fileUrl	发票文件下载地址	回写结果
结果回写	msg	resultMsg	结果说明	返回消息

3. SYS-002 ↔ SYS-009 银行代扣、对账、结算映射

协同场景	SYS-002 字段	SYS-009/银行字段	说明	主要来源
批次下发	batchNo	batchNo	代扣批次号	bk_withholding_batch.batch_no
批次下发	businessType	businessType	代扣/对账/结算类型	协同参数
批次下发	channelCode	channelCode	渠道编码	bk_payment_channel.channel_code
批次下发	protocol	protocol	SFTP/FTP 传输协议	统一解析结果
批次下发	sendDir / sendFilePath	sendDir / sendFilePath	送盘目录与文件路径	bk_withholding_batch
批次下发	billPeriod	billPeriod	账期	批处理参数
批次明细	itemList[].custId	itemList[].customerId	客户标识	bk_withholding_item.cust_id
批次明细	itemList[].chargeId	itemList[].sourceBillId	账单标识	bk_withholding_item.charge_id
批次明细	itemList[].amount	itemList[].withholdingAmount	代扣金额	业务金额
回盘回写	batchStatus	batchStatus	批次状态：已发送、已回盘等	bk_withholding_batch.status
回盘回写	backProtocol / backDir / backFilePath	backProtocol / backDir / backFilePath	回盘阶段最终解析结果	bk_withholding_batch
回盘回写	successCount / failCount	successCount / failCount	成功失败数量汇总	汇总结果
对账回写	protocol / dir / filePath	protocol / dir / filePath	对账文件最终解析结果	bk_reconcile_batch
对账回写	reconcileStatus	reconcileStatus	对账状态	bk_reconcile_batch.status
对账回写	diffList[]	diffList[]	差异明细摘要	bk_reconcile_diff
结算回写	settlementStatus	settlementStatus	结算状态	bk_settlement_batch.status

4. SYS-002 ↔ SYS-010 催缴与业务通知映射

协同场景	SYS-002 字段	SYS-010 字段	说明	主要来源
催缴通知	messageBizNo	eventNo	消息事件编号	业务事件编号
催缴通知	custId	receiver.customerId	接收客户标识	biz_charge.cust_id / biz_process.cust_id
催缴通知	mobile	receiver.mobile	接收手机号	客户联系方式
催缴通知	templateCode	templateCode	消息模板编码	模板参数
催缴通知	arrearsAmount	payload.arrearsAmount	欠费金额	biz_charge.total_amount / 汇总结果
催缴通知	billPeriod	payload.billPeriod	账期	biz_charge.bill_period
催缴通知	strategyCode	payload.strategyCode	命中的催缴策略编码	任务分组结果
催缴通知	triggerType	payload.triggerType	自动/人工触发方式	任务触发上下文
办理进度通知	processCode	payload.processCode	业务办理单号	biz_process.code
办理进度通知	processStatus	payload.processStatus	办理状态	biz_process.status
发送结果回写	status	sendStatus	渠道回执由 SYS-002 统一映射为 PENDING/SUCCESS/FAIL/MANUAL_VERIFIED 四态	消息结果
发送结果回写	reachStatus	reachStatus	触达/阅读状态	渠道回执
发送结果回写	sendTime	sendTime	发送时间	消息结果
发送结果回写	msg	resultMsg	结果说明	返回消息

接口安全与异常处理

认证与鉴权

• 管理后台接口：统一采用登录态 + 权限控制 + 数据权限。
• 客户渠道接口：采用账户绑定态、手机号/验证码、OAuth 或渠道令牌机制。
• 外部协同接口：按渠道要求使用 API Key、时间戳、数字签名、证书或国密算法。

安全控制要求

• 全部接口统一走 HTTPS。
• 外部回调接口必须执行签名校验、重复通知幂等处理与来源校验。
• 关键交易类接口需记录业务流水、渠道流水和操作日志。
• 敏感字段如证件号、手机号、银行账号按制度要求脱敏展示。

错误码分层建议

错误码段	说明
0	成功
400~499	请求参数、权限、资源不存在等通用错误
1_002_001_xxx	客户主数据类错误
1_002_002_xxx	抄表开账类错误
1_002_003_xxx	收费与核销类错误
1_002_004_xxx	账务处理类错误
1_002_005_xxx	发票协同类错误
1_002_006_xxx	银行代收与结算类错误
1_002_007_xxx	客户渠道与业务办理类错误
1_002_008_xxx	消息通知与触达类错误

典型错误码建议

错误码	适用接口/场景	说明	处理建议
1_002_001_001	IF-REV-001 / IF-REV-002	客户不存在或已停用	返回客户状态并阻断后续处理
1_002_001_002	IF-CS-001	账户绑定关系不存在	引导重新绑定客户
1_002_002_001	IF-REV-004	抄表任务不存在或已关闭	禁止提交抄表数据
1_002_002_002	IF-REV-004	本次读数小于上次读数且未通过异常审批	标记异常并进入复核
1_002_002_003	IF-REV-005	价格模板或费用组成缺失	阻断账单生成并提示补齐配置
1_002_003_001	IF-REV-006 / IF-CS-003 / IF-CS-007	账单已核销或不允许重复支付	返回当前账单支付状态
1_002_003_002	IF-REV-006	支付金额与待核销金额不一致	阻断核销并返回差额
1_002_003_003	IF-EXT-005	支付回调签名校验失败	记录异常回调并拒绝入账
1_002_004_001	IF-REV-007	账务调整目标状态不允许变更	返回当前账务状态
1_002_005_001	IF-REV-008 / IF-CS-004	发票申请单据不满足开票条件	返回不可开票原因
1_002_005_002	IF-EXT-007	发票结果回写状态非法或重复	按请求号执行幂等回写
1_002_006_001	IF-REV-011 / IF-EXT-001	代扣批次不存在或已发送	禁止重复下发批次
1_002_006_002	IF-EXT-002	银行回盘文件格式非法或批次号不匹配	记录异常并进入人工核查
1_002_006_003	IF-REV-011	对账差异未处理，禁止结算确认	需先完成差异处置
1_002_007_001	IF-CS-006	业务办理单不存在	返回空结果并提示核对单号
1_002_007_002	IF-CS-006	当前节点不允许补件或重复提交	返回当前流程节点状态
1_002_008_001	IF-REV-013 / IF-EXT-008	消息模板不存在或目标联系方式缺失	记录失败原因并允许后续补发
1_002_008_002	IF-EXT-008	消息通道调用超时	标记待重试，不直接判定业务失败
1_002_008_003	IF-REV-013	人工核查补记缺少核查说明或关联任务不存在	拒绝补记并提示补齐核查上下文

幂等与状态冲突控制

幂等键建议

场景	接口	建议幂等键	幂等判定说明
支付下单	IF-CS-003 / IF-CS-007	bizOrderNo 或 custId + chargeIds + paymentChannel	相同业务订单仅允许创建一次有效支付单
支付回调	IF-EXT-005	tradeNo + tradeStatus + notifyTime	同一交易成功回调只允许入账一次
发票申请	IF-REV-008 / IF-CS-004	invoiceCode 或 custId + chargeIds	相同账单组合避免重复申请开票
发票结果回写	IF-EXT-007	requestNo + invoiceStatus	相同发票状态重复回写仅更新回执日志
银行批次下发	IF-REV-011 / IF-EXT-001	batchNo	同一代扣批次禁止重复发送
银行回盘接收	IF-EXT-002	batchNo + fileSerialNo	同一回盘文件只处理一次
催缴通知	IF-REV-013 / IF-EXT-008	messageBizNo + templateCode + receiver	同一业务事件与同一接收方避免重复发送
业务补件	IF-CS-006	processId + action + attachmentDigest	相同补件内容重复提交仅保留一次

状态冲突处理原则

场景	冲突条件	处理原则
支付核销	账单已完成核销后再次支付	拒绝重复核销，返回现有 writeOffStatus
支付回调	先收到失败回调，后收到成功回调	以最终成功状态为准，但全过程保留回调日志
发票申请	单据已开票成功后再次申请	拒绝重复申请，返回既有发票信息
发票回写	已成功开票后收到失败回写	不覆盖成功状态，转入异常核查
银行代扣	批次已发送后再次下发	拒绝重复发送，保留原批次状态
对账结算	差异未消除即发起结算	禁止结算，提示先处理差异明细
催缴通知	同一账期、同一模板短时间内重复催缴	按通知频控策略拦截重复下发
业务办理	流程已办结后再次补件	拒绝补件，返回当前流程终态

异常处理要求

• 参数校验失败：直接返回明确字段错误信息。
• 外部渠道超时：记录重试状态，不直接覆盖业务成功状态。
• 重复回调：按业务流水执行幂等控制。
• 账务状态冲突：返回当前账单状态与冲突原因，禁止重复核销。
• 外部结果晚到：允许按幂等键补写回执，但不得回退已确认成功状态。
• 人工兜底场景：支付异常、银行回盘异常、发票状态冲突等需保留人工复核入口与操作日志。

历史查询与迁移校验接口口径

设计原则

• 历史查询接口一律只读，不承担迁移修正、补写或状态变更职责。
• 不为迁移场景发明新的独立接口编号体系，统一挂靠既有 IF-REV-*、IF-CS-*、IF-METER-* 接口族扩展查询能力。
• 对 backend 当前未识别到独立实体表的旧细粒度对象，仅要求接口返回“历史摘要 + 原始标识 + 状态映射”，不强行承诺独立在线业务对象。
• 迁移验收接口必须同时支持“汇总对账”和“明细追溯”两类能力，避免只能看总数、无法定位差异。

最小历史查询保留集

查询主题	挂靠接口族	主要数据来源	最低返回要求	说明
历史账单、特殊开账	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-008、IF-CS-004	biz_invoice* + 历史开票关系快照	发票号、申请单号、关联账单、票据状态、票据类型、文件地址	支撑发票结果核查与历史补打定位
催缴、停复水、预存短信	IF-REV-013、IF-METER-002	通知结果、流程工单 + 历史催缴记录	客户号、账期、催缴方式、消息状态、停复水状态、执行人、执行时间、处置引用	支撑催缴处置闭环核查
业务进度与电子档案	IF-CS-006	biz_process*、biz_content* + 历史附件目录	业务单号、节点状态、处理轨迹、附件数量、附件元数据	支撑微网厅与柜台办理进度、电子档案查询
水表生命周期、检定与库存流转	IF-METER-001、IF-METER-003	biz_meter* + 历史仓储/检定单据	表号、当前状态、单据类型、仓库、检定结论、证书编号、时间	支撑表务迁移核查与历史作业追溯
页面参数、业务字段、微信配置	IF-REV-012、IF-CS-006	biz_parameter_settings、biz_page_settings*、sys_wechat_app_settings	参数编码、原值、新值、启用状态、生效时间、适用渠道	支撑微网厅后台配置迁移核查

迁移验收对账接口要求

验收场景	推荐挂靠接口	最低查询维度	输出要求
开账迁移核对	IF-REV-005、IF-CS-002	账期、营业所、客户类型、账单状态	同时提供汇总金额/笔数与可追溯明细清单
收费迁移核对	IF-REV-006、IF-REV-011、IF-CS-002	日期、渠道、营业所、收费状态	同时提供实收金额、流水数量和异常流水列表
发票迁移核对	IF-REV-008、IF-CS-004	开票日期、票据类型、开票状态	同时提供开票汇总、失败原因和票据明细定位
催缴与停复水核对	IF-REV-013、IF-METER-002	账期、催缴方式、执行状态、处理人	同时提供任务统计、执行明细与处置引用
业务办理与档案核对	IF-CS-006	业务类型、流程状态、附件类型、创建时间	同时提供流程轨迹、附件元数据和缺失标记
表务仓储与检定核对	IF-METER-001、IF-METER-003	仓库、单据类型、水表状态、检定结论	同时提供数量汇总和单据级追溯信息

接口约束补充

• 历史查询结果应优先返回原系统标识与新系统标识的映射关系，例如原单号、原批次号、原附件标识、当前业务单号。
• 明细查询接口应支持按客户号、证件号、手机号、表号、账期、营业所、渠道、业务单号等组合检索，满足迁移验收定位需求。
• 若历史附件不直接由当前业务服务托管，接口至少返回附件元数据、来源系统、文件引用地址和可访问状态。
• 历史查询接口的导出能力属于查询扩展能力，不应与在线交易接口共用“状态变更”动作。

实现状态说明

已落地

结合 backend 当前已确认模块与真实表，可明确支撑以下接口域：

• 客户与账户查询、维护接口
• 抄表任务与抄表数据接口
• 账单生成与收费核销接口
• 银行代收、代扣、交易回调、对账、结算接口
• 发票申请与票据状态回写接口的业务侧支撑
• 客户渠道的账户绑定、查询、缴费、业务办理进度接口

部分落地

以下接口域已有主线支撑，但部分细粒度对象仍需结合后续实现继续核实：

• 账务调整、退款、坏账、冲正类精细接口
• 催缴管理中针对不同通知策略和停复水联动的细分接口
• 发票补开等扩展票据后处理接口

文档先行

以下内容可保留设计说明，但当前不应直接表述为已完全落地：

• 历史数据字典中大量细粒度账务台账接口
• 未在 backend 当前扫描范围内明确识别到的独立业务对象接口
• 特定银行或地方平台的专有报文细节
• 历史查询与迁移校验接口在实施时所依赖的只读库、归档库或映射表物理形态

---

版本迭代维护说明

当前主文档已覆盖 UP / REV / CS / METER / INST / EXT 六类接口域的统一编号、清单、关键接口与字段级定义。后续版本迭代按以下顺序增量维护：

1. 先更新接口清单与归属模块，再补充字段级请求/响应结构；
2. 涉及跨系统协同时，同步维护 SYS-008、SYS-009、SYS-010 报文映射；
3. 涉及异常策略变化时，同步更新错误码与幂等规则；
4. 完成后同步校验 02_Detailed_Design/01_Detailed_Design.md 与本主文档的一致性。