---
title: "03_Interface_Design"
author: "系统设计团队"
date: "2024年12月19日"
documentclass: article
geometry: margin=1in
fontsize: 11pt
mainfont: "PingFang SC"
CJKmainfont: "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 |
| **文档状态** | ✅ 已完成（按版本迭代） |

## 章节导航（精简）
- [接口设计范围](#sec-scope)
- [设计原则与统一约束](#sec-principles)
- [SYS-002 接口视图](#sec-rev-interface-view)
- [外部接口设计](#sec-external-interface)
- [内部接口设计](#sec-internal-interface)
- [数据对象与表口径](#sec-data-object)
- [接口安全与异常处理](#sec-security-exception)
- [历史查询与迁移校验接口口径](#sec-migration-readonly)
- [实现状态说明](#sec-status)

<a id="sec-scope"></a>
## 接口设计范围

本文档用于描述福建水务营收系统的接口边界、调用方式、核心接口清单以及与外围子系统的协同关系，重点统一 `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 未完全确认的接口对象，统一按“文档先行”处理。

<a id="sec-principles"></a>
## 设计原则与统一约束

### 接口设计原则

- **统一编号**：接口编号统一采用 `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 接口统一采用如下响应模型：

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

分页响应统一采用：

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

<a id="sec-rev-interface-view"></a>
## 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 消息服务 | 催缴通知、缴费结果通知、办理进度通知 | 生成待通知业务事件与目标用户 | 承接短信、微信公众号、站内信等触达能力 |

<a id="sec-external-interface"></a>
## 外部接口设计

## 外部接口分类

| 接口分类 | 主要对接方 | 典型协议 | 说明 |
|---------|------------|----------|------|
| 银行代收/代扣接口 | 银行、银联、托收平台 | 文件交换 / 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` |

<a id="sec-internal-interface"></a>
## 内部接口设计

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

典型请求体：

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

边界约束：
- 本接口只负责抄表校验完成后的账单生成，不直接承接收费核销、发票申请、催缴执行或统计汇总。
- 正式请求范围可按抄表批次、客户集合或抄表任务集合组织；当前 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<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-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<String> | 否 | 依据附件 | 附件系统 |
| 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<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` |
| 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<Long> | 是 | 欠费账单集合 | `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<String> | 否 | 状态集合 | 账单/收费/抄表等状态筛选 |
| groupBy | Array<String> | 否 | 分组维度集合 | 结果分组 |
| 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<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 | 处理说明 | 返回消息 |

### 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<Long> | 是 | 水表 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<String> | 否 | 告警编码列表 | 告警结果 |
| 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<String> | 否 | 申请附件列表 | `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<String> | 否 | 现场照片与方案附件 | `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<String> | 是 | 归档附件列表 | `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. 在线支付下单与回调时序


```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 税控/开票平台
    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. 银行代扣批次与回盘时序


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


```mermaid
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: 返回催缴任务执行结果

```


<a id="sec-data-object"></a>
## 数据对象与表口径

### 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` | 结果说明 | 返回消息 |

<a id="sec-security-exception"></a>
## 接口安全与异常处理

### 认证与鉴权

- 管理后台接口：统一采用登录态 + 权限控制 + 数据权限。
- 客户渠道接口：采用账户绑定态、手机号/验证码、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` |
| 支付回调 | 先收到失败回调，后收到成功回调 | 以最终成功状态为准，但全过程保留回调日志 |
| 发票申请 | 单据已开票成功后再次申请 | 拒绝重复申请，返回既有发票信息 |
| 发票回写 | 已成功开票后收到失败回写 | 不覆盖成功状态，转入异常核查 |
| 银行代扣 | 批次已发送后再次下发 | 拒绝重复发送，保留原批次状态 |
| 对账结算 | 差异未消除即发起结算 | 禁止结算，提示先处理差异明细 |
| 催缴通知 | 同一账期、同一模板短时间内重复催缴 | 按通知频控策略拦截重复下发 |
| 业务办理 | 流程已办结后再次补件 | 拒绝补件，返回当前流程终态 |

### 异常处理要求

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

<a id="sec-migration-readonly"></a>
## 历史查询与迁移校验接口口径

### 设计原则

- 历史查询接口一律只读，不承担迁移修正、补写或状态变更职责。
- 不为迁移场景发明新的独立接口编号体系，统一挂靠既有 `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` | 仓库、单据类型、水表状态、检定结论 | 同时提供数量汇总和单据级追溯信息 |

### 接口约束补充

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

<a id="sec-status"></a>
## 实现状态说明

### 已落地

结合 `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` 与本主文档的一致性。