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

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

## 目录
- [接口设计范围](#接口设计范围)
- [设计原则与统一约束](#设计原则与统一约束)
- [SYS-002 接口视图](#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 接口统一采用如下响应模型：

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

分页响应统一采用：

```json
{
  "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` |

典型请求体：

```json
{
  "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<String> | 否 | 表盘照片或现场图片文件标识 | 附件系统 / 文件服务 |
| 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<Long> | 否 | 指定客户范围 | `biz_cust.id` |
| meterReadIds | Array<Long> | 否 | 指定抄表任务范围 | `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<Long> | 是 | 待核销账单 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<Long> | 是 | 开票关联账单 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<Long> | 是 | 待支付账单 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<String> | 否 | 附件文件标识列表 | `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<Long> | 是 | 待支付账单 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. 在线支付下单与回调时序

```mermaid
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. 电子发票申请与回写时序

```mermaid
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. 银行代扣批次与回盘时序

```mermaid
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. 催缴通知下发与结果回写时序

```mermaid
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. 错误码明细与幂等规则。