fujian_water_biz_doc/03_Technical/03_Interface_Design.md

doc_id, doc_role, authority, scope, source_of_truth, last_reviewed, retrieval_priority

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

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

文档信息

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

目录

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

接口设计范围

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

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

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

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

设计原则与统一约束

接口设计原则

• 统一编号：接口编号统一采用 IF-REV-*、IF-CS-*、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

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

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

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

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-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-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

关键内部接口说明

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

IF-REV-006 缴费处理接口

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

IF-REV-008 发票申请接口

项目	说明
接口编号	IF-REV-008
归属模块	REV-005
请求方式	POST
请求路径	/admin-api/revenue/invoice/apply
功能描述	发起电子发票或纸质发票申请，并调用 SYS-008
核心表	biz_invoice、biz_invoice_taxrate、biz_cust_invoice

边界约束：

• 发票开具、作废、红冲能力由 SYS-008 统一承接。
• SYS-002 仅负责业务单据归集、申请发起与结果落账。

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-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-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-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-008 发票申请接口

请求参数

字段	类型	必填	说明	主要来源/去向
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
taxRateCode	String	否	税率编码	biz_invoice_taxrate.tax_code

响应参数

字段	类型	说明	主要来源
invoiceId	Long	发票申请记录 ID	biz_invoice.id
invoiceCode	String	发票申请编号	biz_invoice.code
invoiceStatus	String	状态：INIT、APPLYING、SUCCESS、FAIL	biz_invoice.invoice_status
requestNo	String	发往 SYS-008 的请求号	协同流水
fileUrl	String	发票文件地址，成功后返回	结果回写
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-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	处理说明	返回消息

关键接口时序图

说明：以下时序图用于说明 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 税控/开票平台

    Counter->>SYS002: 提交发票申请(IF-REV-008/IF-CS-004)
    SYS002->>SYS002: 校验客户、账单、开票抬头与金额
    SYS002->>SYS002: 生成发票申请记录biz_invoice
    SYS002->>SYS008: 发起开票协同(IF-EXT-006)
    SYS008->>Tax: 调用税控或电子发票平台
    Tax-->>SYS008: 返回受理结果/票号/文件地址
    SYS008-->>SYS002: 回写开票结果(IF-EXT-007)
    SYS002->>SYS002: 更新biz_invoice状态与票据地址
    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->>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-009)
    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
批次下发	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
回盘回写	successCount / failCount	successCount / failCount	成功失败数量汇总	汇总结果
对账回写	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
办理进度通知	processCode	payload.processCode	业务办理单号	biz_process.code
办理进度通知	processStatus	payload.processStatus	办理状态	biz_process.status
发送结果回写	sendStatus	sendStatus	发送状态	消息结果
发送结果回写	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-009 / IF-EXT-008	消息模板不存在或目标联系方式缺失	记录失败原因并允许后续补发
1_002_008_002	IF-EXT-008	消息通道调用超时	标记待重试，不直接判定业务失败

幂等与状态冲突控制

幂等键建议

场景	接口	建议幂等键	幂等判定说明
支付下单	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-009 / IF-EXT-008	messageBizNo + templateCode + receiver	同一业务事件与同一接收方避免重复发送
业务补件	IF-CS-006	processId + action + attachmentDigest	相同补件内容重复提交仅保留一次

状态冲突处理原则

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

异常处理要求

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

实现状态说明

已落地

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

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

部分落地

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

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

文档先行

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

• 历史数据字典中大量细粒度账务台账接口
• 未在 backend 当前扫描范围内明确识别到的独立业务对象接口
• 特定银行或地方平台的专有报文细节

---

本文档后续如继续细化，应优先补充：

1. 各接口的字段级请求/响应结构；
2. 典型时序图（支付、发票、代扣回盘、催缴通知）；
3. 与 SYS-008、SYS-009、SYS-010 的接口报文映射表；
4. 错误码明细与幂等规则。