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

---
doc_id: DT-01-DETAIL
doc_role: master_document
authority: primary
scope: 详细设计
source_of_truth: true
last_reviewed: 2026-03-11
retrieval_priority: P0
---

# 福建水务营收系统详细设计说明书

| 文件状态： | 文档密级： | 公开 |
| :--- | :--- | :--- |
| 【】草稿 | | |
| 【√】修改稿 | | |
| 【】正式发布 | | |
| | **当前版本：** | **V1.6** |
| | **作者：** | **唐伟杰** |
| | **完成日期：** | **2026-03-10** |

## 版本历史

| 日期 | 版本号 | 作者 | 备注 |
| :--- | :--- | :--- | :--- |
| 2025-07-01 | V1.0 | 唐伟杰 | 初版 |
| 2025-07-17 | V1.1 | 唐伟杰 | 补充详细设计内容 |
| 2025-08-01 | V1.2 | 唐伟杰 | 同步更新概要设计中的子系统和模块结构，补充数据库设计章节并统一主要模块逻辑。 |
| 2025-08-01 | V1.3 | 唐伟杰 | 数据库系统口径统一为达梦数据库 8.0+。 |
| 2025-08-01 | V1.4 | 唐伟杰 | 单点登录采用 OAuth2.0 协议，补充统一认证相关设计。 |
| 2026-03-10 | V1.6 | 唐伟杰 | 将分散的模块设计、数据库设计、接口设计、安全设计、部署设计与报装电子签章设计整合为统一主详设，统一系统名称、章节体系、模块/接口编号及数据库口径，清理重复内容与部署脏片段。 |

## 章节导航（精简）

- [前言](#sec-preface)
- [系统总体设计](#sec-overall-design)
- [详细模块设计](#sec-module-detail)
  - [统一平台详细设计](#sec-platform-detail)
  - [营收业务详细设计](#sec-revenue-detail)
  - [客户服务模块详细设计](#sec-customer-detail)
  - [表务详细设计](#sec-meter-detail)
  - [报装与签章详细设计](#sec-installation-detail)
- [数据库详细设计](#sec-database-detail)
- [接口详细设计](#sec-interface-detail)
- [安全详细设计](#sec-security-detail)
- [部署与运维设计](#sec-deployment-detail)
- [附录](#sec-appendix)
- [模块正文文件索引](#sec-module-files)

<a id="sec-preface"></a>

# 前言

## 编写目的

本文档用于指导福建水务营收系统的详细设计、开发实现、联调测试、部署上线及后续运维，是本项目详细设计阶段的统一主说明书。本文档以 `docs/design/02_Detailed_Design/01_Detailed_Design.md` 作为唯一主详设文件，吸收模块设计、数据库设计、接口设计、安全设计、部署设计以及报装电子签章专项设计中的可复用内容，形成可直接交付和实施使用的统一版本。

## 建设背景

福建水务营收系统面向集团化、多组织、多渠道的营收业务场景，覆盖客户资料、抄表开账、营业收费、账务处理、表务管理、报装立户、电子签章、客户服务、移动作业、外部支付与政务对接等核心业务。系统建设目标是形成统一平台、统一数据、统一接口、统一安全管控的营收业务支撑体系，满足集团及下属单位的标准化与可扩展管理要求。

## 设计范围

本文档覆盖以下设计内容：

1. 系统总体架构与部署架构设计。
2. 统一平台、营收业务、表务、报装与签章、客户服务渠道等业务模块详细设计。
3. 达梦数据库 8.0+ 口径下的核心数据模型、核心表结构、索引与性能设计。
4. 内部接口、外部接口、安全控制、部署与运维方案。
5. 关键业务流程、模块关系、接口交互与审计留痕要求。

## 术语与缩略语

| 术语/缩略语 | 说明 |
|---|---|
| SSO | 单点登录 |
| OAuth2.0 | 统一认证授权协议 |
| RBAC | 基于角色的访问控制模型 |
| DM8 | 达梦数据库 8.0+ |
| API | 应用程序接口 |
| CA | 电子认证与电子签章能力 |
| MFA | 多因素认证 |
| ETL | 数据抽取、转换、加载 |

## 参考资料

1. 《福建水务营收系统概要设计相关文档》
2. `docs/design/02_Detailed_Design/02_Module_Traceability_Index.md`
3. `docs/design/02_Detailed_Design/03_CA_Esignature_Supplement.md`
4. `docs/design/02_Detailed_Design/11_UP_Detailed.md`
5. `docs/design/02_Detailed_Design/12_REV_Detailed.md`
6. `docs/design/02_Detailed_Design/13_CS_Detailed.md`
7. `docs/design/02_Detailed_Design/14_METER_Detailed.md`
8. `docs/design/02_Detailed_Design/15_INST_Detailed.md`
9. `docs/design/03_Technical_Design/01_Database_Design.md`
10. `docs/design/03_Technical_Design/02_Table_Specs.md`（历史命名映射补充）
11. `docs/design/03_Technical_Design/03_Interface_Design.md`
12. `docs/design/03_Technical_Design/04_Security_Design.md`
13. `docs/design/03_Technical_Design/05_Deployment_Design.md`
14. 福建水投相关业务操作手册及需求说明资料
15. `docs/design/01_Overview/05_Module_Inventory.md`

<a id="sec-module-files"></a>

## 模块正文文件索引

- 总体层模块清单与承接映射：`docs/design/01_Overview/05_Module_Inventory.md`
- 统一平台模块正文：`docs/design/02_Detailed_Design/11_UP_Detailed.md`
- 营收业务模块正文：`docs/design/02_Detailed_Design/12_REV_Detailed.md`
- 客户服务模块正文：`docs/design/02_Detailed_Design/13_CS_Detailed.md`
- 表务模块正文：`docs/design/02_Detailed_Design/14_METER_Detailed.md`
- 报装与签章模块正文：`docs/design/02_Detailed_Design/15_INST_Detailed.md`

<a id="sec-overall-design"></a>

# 系统总体设计

## 总体目标

福建水务营收系统总体设计遵循“统一平台、业务协同、数据集中、接口标准、安全可控”的原则，实现以下目标：

- 建立统一认证、统一组织、统一权限、统一参数、统一审计基础能力。
- 构建覆盖营收、表务、报装、客户服务的完整业务闭环。
- 形成达梦数据库 8.0+ 为核心的数据架构，支撑集团化数据管理与查询分析。
- 通过标准化接口接入银行、第三方支付、短信、税控、物联网、政务、CA 签章等外部系统。
- 满足生产部署、容灾备份、日志审计与安全监管要求。

## 逻辑架构设计


```mermaid
graph TB
    U1[柜台/客服/管理人员] --> A1[PC管理端]
    U2[抄表员/表务人员] --> A2[移动作业端]
    U3[客户用户] --> A3[微信/支付宝/微服务窗]
    U4[第三方系统] --> A4[外部系统接口]

    subgraph G[接入与网关层]
        G1[统一门户]
        G2[API网关]
        G3[统一认证中心]
    end

    subgraph B[业务服务层]
        B1[统一平台服务]
        B2[营收业务服务]
        B3[表务管理服务]
        B4[报装与签章服务]
        B5[客户服务渠道服务]
        B6[消息通知与任务调度]
    end

    subgraph D[数据与支撑层]
        D1[(达梦数据库 8.0+)]
        D2[(Redis缓存)]
        D3[对象存储/文件服务]
        D4[消息队列]
        D5[日志审计与监控]
    end

    A1 --> G1
    A2 --> G1
    A3 --> G1
    A4 --> G2
    G1 --> G2 --> G3
    G2 --> B1
    G2 --> B2
    G2 --> B3
    G2 --> B4
    G2 --> B5
    B1 --> D1
    B2 --> D1
    B3 --> D1
    B4 --> D1
    B5 --> D1
    B2 --> D2
    B3 --> D2
    B4 --> D3
    B5 --> D4
    B1 --> D5
    B2 --> D5
    B3 --> D5
    B4 --> D5
    B5 --> D5

```


### 设计说明

1. 统一平台服务提供认证、组织、权限、参数、审计等公共能力。
2. 营收业务服务承担客户、抄表、开账、收费、账务、发票、催缴、统计与业务工单等核心处理。
3. 表务管理服务承担设备档案、表务工单、仓储、物联网集抄对接等处理。
4. 报装与签章服务承担申请受理、现场踏勘、施工验收、合同签署与资料归档。
5. 客户服务渠道服务面向微信、支付宝、微服务窗等客户侧渠道提供查询、缴费、电子发票与业务办理。

## 部署分区设计


```mermaid
graph TB
    INTERNET[互联网/政务外网/合作机构] --> DMZ[DMZ接入区]
    DMZ --> APP[应用服务区]
    APP --> DATA[数据服务区]
    APP --> OPS[管理运维区]

    subgraph DMZ[DMZ接入区]
        LB[负载均衡/Nginx]
        WAF[WAF与边界防护]
        GW[API网关]
    end

    subgraph APP[应用服务区]
        APP1[统一平台服务]
        APP2[营收业务服务]
        APP3[表务服务]
        APP4[报装签章服务]
        APP5[客户渠道服务]
    end

    subgraph DATA[数据服务区]
        DBM[(达梦主库)]
        DBS[(达梦备库/从库)]
        REDIS[(Redis)]
        FILE[文件存储]
    end

    subgraph OPS[管理运维区]
        MON[监控平台]
        LOG[日志平台]
        BAK[备份服务]
        JUMP[堡垒机/跳板机]
    end

```


## 子系统与模块划分

| 子系统 | 说明 | 核心模块 |
|---|---|---|
| 统一平台 | 提供统一认证、组织、权限、参数、审计与监控基础能力 | UP-001 ~ UP-004 |
| 营收业务 | 覆盖客户、抄表、收费、账务、发票、催缴、统计、代收与业务工单 | REV-001 ~ REV-009 |
| 表务管理 | 覆盖水表基础参数、仓储库存、设备档案以及工单和物联网同步等支撑能力 | METER-001 ~ METER-003 |
| 报装与签章 | 覆盖报装流程管理、工程管理、档案管理及其下挂签章归档能力 | INST-001 ~ INST-003 |
| 客户服务模块 | 覆盖账户绑定、信息查询、在线缴费、电子发票、网点服务、业务办理与柜面扫码支付 | CS-001 ~ CS-007 |

### 与架构图模块清单的承接说明

1. 架构图中的模块枚举基线以 `../01_Overview/05_Module_Inventory.md` 为准。
2. 当前详细设计采用“业务域正文承接多个架构层模块”的组织方式，不强制为 `MOBILE-*`、`WECHAT-*`、`WORK-*` 单独建立平行正式主稿。
3. `WECHAT-*` 当前按客户服务渠道视角并入 `CS-*` 体系承接；`MOBILE-*` 当前作为抄表与表务协同端能力分散承接于营收与表务正文；`WORK-*` 当前作为工单协同与流程支撑能力在客户服务、表务、报装正文中交叉引用。
4. 若后续需要新增独立正文，必须先确认该模块已具备稳定边界、独立接口和核心数据域，并同步更新概要设计与追溯索引。

<a id="sec-module-detail"></a>
<a id="sec-platform-detail"></a>

# 统一平台详细设计

## 章节定位

为避免主详设与分模块文件重复维护，本章仅保留统一平台模块摘要与入口链接，详细正文统一维护在模块文件中。

## 模块摘要

| 模块编号 | 模块名称 | 设计摘要 | 正文链接 |
|---|---|---|---|
| `UP-001` | 统一认证与单点登录 | 统一身份认证、单点登录、令牌生命周期管理与高敏感二次校验 | [UP-001](./11_UP_Detailed.md#mod-up-001) |
| `UP-002` | 组织用户与权限管理 | 组织、岗位、角色、菜单与数据权限统一管控 | [UP-002](./11_UP_Detailed.md#mod-up-002) |
| `UP-003` | 参数字典与基础配置 | 统一维护字典、价格、地址、渠道和任务参数 | [UP-003](./11_UP_Detailed.md#mod-up-003) |
| `UP-004` | 审计监控与运维支撑 | 操作审计、接口监控、任务追踪与告警通知 | [UP-004](./11_UP_Detailed.md#mod-up-004) |

## 正文入口

- [统一平台模块正文](./11_UP_Detailed.md#sec-content)

<a id="sec-revenue-detail"></a>

# 营收业务详细设计

## 章节定位

本章保留营收业务模块的设计摘要，详细流程、数据域与规则说明统一维护在分模块正文文件中。

## 模块摘要

| 模块编号 | 模块名称 | 设计摘要 | 正文链接 |
|---|---|---|---|
| `REV-001` | 客户资料管理 | 客户主档、账户、联系人、绑定关系等主数据管理 | [REV-001](./12_REV_Detailed.md#mod-rev-001) |
| `REV-002` | 抄表开账 | 抄表计划、异常复核、计费与账单生成 | [REV-002](./12_REV_Detailed.md#mod-rev-002) |
| `REV-003` | 营业收费 | 多渠道缴费、账单核销与收费凭证管理 | [REV-003](./12_REV_Detailed.md#mod-rev-003) |
| `REV-004` | 账务处理 | 调整、退款、冲正、呆坏账等账务修正 | [REV-004](./12_REV_Detailed.md#mod-rev-004) |
| `REV-005` | 发票与税务处理 | 发票申请、回写、作废与红冲协同 | [REV-005](./12_REV_Detailed.md#mod-rev-005) |
| `REV-006` | 催缴与通知 | 欠费催缴策略、触达与结果回写 | [REV-006](./12_REV_Detailed.md#mod-rev-006) |
| `REV-007` | 统计分析 | 营收、收费、欠费、渠道等多维统计 | [REV-007](./12_REV_Detailed.md#mod-rev-007) |
| `REV-008` | 代收与银行业务 | 代收代扣、对账、结算与差异处理 | [REV-008](./12_REV_Detailed.md#mod-rev-008) |
| `REV-009` | 业务参数配置 | 价格模板、页面配置与规则参数管理 | [REV-009](./12_REV_Detailed.md#mod-rev-009) |

## 正文入口

- [营收业务模块正文](./12_REV_Detailed.md#sec-content)

<a id="sec-customer-detail"></a>

# 客户服务模块详细设计

## 章节定位

本章保留客户服务模块摘要与入口，详细设计内容由分模块正文文件统一承载。

## 模块摘要

| 模块编号 | 模块名称 | 设计摘要 | 正文链接 |
|---|---|---|---|
| `CS-001` | 账户绑定管理 | 渠道账号与客户账户绑定、解绑、默认设置 | [CS-001](./13_CS_Detailed.md#mod-cs-001) |
| `CS-002` | 信息查询服务 | 账单、缴费、欠费、用水分析与历史查询 | [CS-002](./13_CS_Detailed.md#mod-cs-002) |
| `CS-003` | 在线缴费服务 | 多渠道在线支付下单、回调确认与补单 | [CS-003](./13_CS_Detailed.md#mod-cs-003) |
| `CS-004` | 电子发票服务 | 发票申请、查询、下载与推送 | [CS-004](./13_CS_Detailed.md#mod-cs-004) |
| `CS-005` | 营业网点服务 | 网点信息、服务范围与办事引导 | [CS-005](./13_CS_Detailed.md#mod-cs-005) |
| `CS-006` | 业务办理服务 | 线上办理入口与办理状态流转协同 | [CS-006](./13_CS_Detailed.md#mod-cs-006) |
| `CS-007` | 柜面扫码支付 | 柜面二维码收款与收费状态联动 | [CS-007](./13_CS_Detailed.md#mod-cs-007) |

## 正文入口

- [客户服务模块正文](./13_CS_Detailed.md#sec-content)

<a id="sec-meter-detail"></a>

# 表务详细设计

## 章节定位

本章保留表务模块摘要，详细流程与对象说明统一在分模块正文文件维护。

## 模块摘要

| 模块编号 | 模块名称 | 设计摘要 | 正文链接 |
|---|---|---|---|
| `METER-001` | 表务基础管理 | 水表档案、状态与参数基础管理 | [METER-001](./14_METER_Detailed.md#mod-meter-001) |
| `METER-002` | 仓库与库存管理 | 入库、出库、退库、报废与库存预警 | [METER-002](./14_METER_Detailed.md#mod-meter-002) |
| `METER-003` | 设备档案管理 | 设备主档、状态流转、工单协同与远传同步 | [METER-003](./14_METER_Detailed.md#mod-meter-003) |

## 正文入口

- [表务模块正文](./14_METER_Detailed.md#sec-content)

<a id="sec-installation-detail"></a>

# 报装与签章详细设计

## 章节定位

本章保留报装与签章模块摘要，详细流程、CA 集成与异常补偿策略统一维护在分模块正文及 CA 专项补充文档。

## 模块摘要

| 模块编号 | 模块名称 | 设计摘要 | 正文链接 |
|---|---|---|---|
| `INST-001` | 报装流程管理 | 申请受理、踏勘流转与方案编制 | [INST-001](./15_INST_Detailed.md#mod-inst-001) |
| `INST-002` | 工程管理 | 施工验收、立户通水与合同签章协同 | [INST-002](./15_INST_Detailed.md#mod-inst-003) |
| `INST-003` | 档案管理 | 材料归档、签章回执留存与过程可追溯 | [INST-003](./15_INST_Detailed.md#mod-inst-005) |

## 正文入口

- [报装与签章模块正文](./15_INST_Detailed.md#sec-content)
- [报装 CA 电子签章专项补充](./03_CA_Esignature_Supplement.md#sec-position)

<a id="sec-database-detail"></a>

# 数据库详细设计

## 数据库选型与原则

系统数据库统一采用达梦数据库 8.0+。数据库设计遵循以下原则：

1. 统一主数据模型，避免多口径重复建模。
2. 面向业务闭环设计客户、水表、账单、缴费、工单、报装、签章等核心对象。
3. 兼顾 OLTP 事务处理与统计查询性能。
4. 支持多单位、多区域的数据隔离与权限过滤。
5. 敏感数据字段满足加密、脱敏和审计要求。

## 数据库逻辑架构


```mermaid
graph TB
    APP[业务应用] --> ORM[数据访问层]
    APP --> CACHE[Redis缓存]
    ORM --> MASTER[(达梦主库)]
    MASTER --> SLAVE[(达梦从库/备库)]
    MASTER --> FILE[文件与归档索引]

```


## 核心数据模型


```mermaid
erDiagram
    BIZ_CUST ||--o{ BIZ_CUST_CONTACT : 包含
    BIZ_CUST ||--o{ BIZ_CUST_METER : 绑定
    BIZ_CUST ||--|| BIZ_ACCOUNT : 对应
    BIZ_METER ||--o{ BIZ_READING_DATA : 产生
    BIZ_READING_DATA ||--|| BIZ_CHARGE : 生成
    BIZ_CHARGE ||--o{ BIZ_CHARGE_DETAIL : 包含
    BIZ_CHARGE ||--o{ BK_TRANSACTION : 核销
    BIZ_CUST ||--o{ BIZ_INVOICE : 开票
    INSTALLATION_APPLY ||--o{ INSTALLATION_CONTRACT : 生成
    INSTALLATION_CONTRACT ||--o{ INSTALLATION_SIGNATURE : 签署
    INSTALLATION_CONTRACT ||--o{ INSTALLATION_EVIDENCE : 存证

```


## 核心数据表设计

### 客户与账户类

| 表名 | 说明 | 关键字段 |
|---|---|---|
| `biz_cust` | 客户主档表 | code、name、cust_type、id_no、mobile、address、status |
| `biz_account` | 客户账户表 | code、cust_id、balance、arrears_amount、status |
| `biz_cust_contact` | 客户联系人表 | cust_id、name、mobile、contact_type、is_default |
| `biz_cust_app_binds` | 渠道绑定关系表 | cust_id、app_type、app_user_id、status |
| `biz_cust_invoice` | 客户开票信息表 | cust_id、invoice_title、tax_no、email、mobile |

### 水表与抄表类

| 表名 | 说明 | 关键字段 |
|---|---|---|
| `biz_meter` | 水表信息表 | code、meter_no、model_code、caliber_code、status |
| `biz_cust_meter` | 客户与水表关系表 | cust_id、meter_id、bind_status、bind_time |
| `biz_meter_book` | 抄表册本表 | code、name、reader_id、cycle_type、status |
| `biz_reading_data` | 抄表数据表 | meter_id、cust_id、reading_time、current_reading、usage_amount |
| `biz_last_reading` | 上次抄表结果表 | meter_id、last_reading、last_reading_time |
| `biz_meter_read` | 抄表任务状态表 | book_id、meter_id、read_status、reader_id |

### 账单、收费与发票类

| 表名 | 说明 | 关键字段 |
|---|---|---|
| `biz_charge` | 营业账主表 | code、cust_id、record_id、total_amount、charge_status |
| `biz_charge_detail` | 营业账明细表 | charge_id、cost_component_code、usage_amount、detail_amount |
| `biz_collection` | 托收资料表 | cust_id、channel_code、collection_status、apply_time |
| `biz_withholding` | 代扣资料表 | cust_id、agreement_no、withholding_status、sign_time |
| `biz_invoice` | 发票主表 | code、cust_id、invoice_status、invoice_type、issue_time |
| `biz_invoice_taxrate` | 发票税率表 | tax_code、tax_name、tax_rate、status |

### 银行渠道与交易类

| 表名 | 说明 | 关键字段 |
|---|---|---|
| `bk_payment_channel` | 支付渠道表 | channel_code、channel_name、channel_type、status |
| `bk_channel_api_config` | 渠道接口配置表 | channel_code、api_url、sign_type、status |
| `bk_channel_route_rule` | 渠道路由规则表 | business_type、channel_code、priority、status |
| `bk_transaction` | 渠道交易流水表 | trade_no、biz_order_no、channel_code、trade_amount、trade_status |
| `bk_transaction_callback` | 支付回调表 | trade_no、callback_status、callback_time、payload |
| `bk_transaction_exception` | 渠道异常表 | trade_no、exception_type、exception_status、remark |
| `bk_withholding_agreement` | 代扣签约表 | agreement_no、cust_id、bank_code、status |
| `bk_withholding_batch` | 代扣批次表 | batch_no、batch_date、total_count、status |
| `bk_withholding_item` | 代扣明细表 | batch_no、cust_id、charge_id、item_status |
| `bk_reconcile_batch` | 对账批次表 | batch_no、channel_code、reconcile_date、status |
| `bk_reconcile_diff` | 对账差异表 | batch_no、trade_no、diff_type、diff_amount |
| `bk_settlement_batch` | 结算批次表 | batch_no、channel_code、settlement_date、status |

### 表务与工单类

| 表名 | 说明 | 关键字段 |
|---|---|---|
| `biz_meter_log` | 表务工单/过程留痕表 | biz_type、biz_id、operate_user、operate_time、remark |
| `biz_meter_in_out` | 水表出入库主表 | code、in_out_type、warehouse_id、operate_time、status |
| `biz_meter_in_out_rel` | 出入库关联明细表 | in_out_id、meter_id、quantity、status |
| `biz_process` | 业务工单主表 | code、biz_type_code、cust_id、process_status |

### 报装与签章类

| 表名 | 说明 | 关键字段 |
|---|---|---|
| `biz_process` | 报装申请主表 | code、biz_type_code、cust_id、process_status |
| `biz_process_transfer` | 现场踏勘与流转表 | process_id、from_user、to_user、transfer_time |
| `installation_contract` | 报装合同表 | contract_code、installation_id、contract_type、contract_status |
| `installation_signature` | 签章记录表 | signature_code、contract_id、signer_id、signature_time、signature_status |
| `installation_evidence` | 存证记录表 | evidence_code、contract_id、evidence_hash、evidence_status |

## 索引与性能设计

### 主要索引策略

1. 唯一索引：客户编号、水表编号、账单编号、缴费编号、合同编号等业务唯一键。
2. 复合索引：
   - 客户查询：`(customer_type, status)`
   - 账单查询：`(customer_id, bill_month, bill_status)`
   - 抄表查询：`(meter_id, reading_date)`
   - 缴费查询：`(customer_id, payment_time)`
3. 时间分区：账单、缴费、日志等大表按月或按年管理归档。
4. 热点缓存：参数字典、用户会话、移动端任务、发票状态等进入 Redis。

<a id="sec-interface-detail"></a>

# 接口详细设计

## 接口设计原则

1. 内部接口统一采用 RESTful 风格，JSON 作为主要报文格式。
2. 外部接口根据对接方规范支持 HTTPS API、SFTP 文件交换等方式。
3. 接口编号统一采用 `IF-` 或 `EXT-` 前缀，与模块编号区分。
4. 关键交易接口必须支持幂等控制、签名校验、失败重试与调用日志。

## 统一平台接口

| 接口编号 | 接口名称 | 功能描述 | 调用方 | 协议 |
|---|---|---|---|---|
| IF-UP-001 | 用户登录接口 | 用户登录并获取访问令牌 | PC端/移动端/渠道端 | HTTPS REST |
| IF-UP-002 | 用户信息接口 | 获取当前登录用户上下文 | 各业务系统 | HTTPS REST |
| IF-UP-003 | 权限校验接口 | 校验菜单、按钮和数据权限 | 各业务模块 | HTTPS REST |
| IF-UP-004 | 参数字典接口 | 获取字典与业务参数 | 各业务模块 | HTTPS REST |

## 营收业务接口

| 接口编号 | 接口名称 | 功能描述 | 调用方 | 协议 |
|---|---|---|---|---|
| IF-REV-001 | 客户信息查询接口 | 查询客户档案、账户状态、联系人与水表绑定关系 | 柜台/客户渠道/工单 | HTTPS REST |
| IF-REV-004 | 抄表数据提交接口 | 提交人工或远传抄表数据并触发校验 | 抄表APP/集抄系统 | HTTPS REST |
| IF-REV-005 | 账单生成接口 | 根据抄表结果、水价模板和费用组成生成账单 | 开账任务 | HTTPS REST |
| IF-REV-006 | 缴费处理接口 | 创建收费记录并核销账单 | 柜台/线上渠道 | HTTPS REST |
| IF-REV-007 | 账务调整接口 | 发起金额调整、退款、冲正、坏账等业务处理 | 财务/营业人员 | HTTPS REST |
| IF-REV-008 | 发票申请接口 | 发起开票申请并接收票据状态回写 | 柜台/客户渠道 | HTTPS REST |
| IF-REV-009 | 催缴任务接口 | 生成催缴名单并提交消息触达请求 | 营收系统/消息服务 | HTTPS REST |
| IF-REV-010 | 统计查询接口 | 查询营收、收费、欠费、渠道、客户统计结果 | 管理后台/统计分析端 | HTTPS REST |
| IF-REV-011 | 银行代收协同接口 | 发起代扣、回盘、对账、结算协同 | 银行代收模块/SYS-009 | HTTPS REST / 文件交换 |
| IF-REV-012 | 业务参数配置接口 | 查询和维护价格模板、优惠方案、业务参数配置 | 管理后台/参数管理端 | HTTPS REST |

## 表务与物联网接口

| 接口编号 | 接口名称 | 功能描述 | 调用方 | 协议 |
|---|---|---|---|---|
| IF-METER-001 | 水表档案查询接口 | 查询水表与生命周期信息 | 表务/营收/报装 | HTTPS REST |
| IF-METER-002 | 表务工单处理接口 | 提交换表、移表等结果 | 移动作业端 | HTTPS REST |
| IF-METER-003 | 库存出入库接口 | 处理领用、退库、报废 | 仓储管理端 | HTTPS REST |
| IF-METER-004 | 集抄数据接收接口 | 接收远程抄表数据 | 物联网平台 | HTTPS REST |

## 报装与签章接口

| 接口编号 | 接口名称 | 功能描述 | 调用方 | 协议 |
|---|---|---|---|---|
| IF-INST-001 | 报装申请提交接口 | 提交报装申请与附件 | 柜台/微网厅/政务平台 | HTTPS REST |
| IF-INST-002 | 踏勘结果回填接口 | 回填现场踏勘结果 | 报装人员 | HTTPS REST |
| IF-INST-003 | 合同签署发起接口 | 创建签章任务 | 报装系统 | HTTPS REST |
| IF-INST-004 | 签章回执接口 | 回写签章结果和存证信息 | CA系统/报装系统 | HTTPS REST |
| IF-INST-005 | 报装归档接口 | 归档申请、合同和验收资料 | 报装系统 | HTTPS REST |

## 客户渠道接口

| 接口编号 | 接口名称 | 功能描述 | 调用方 | 协议 |
|---|---|---|---|---|
| IF-CS-001 | 账户绑定接口 | 绑定或解绑客户账户 | 微信/支付宝/微网厅 | HTTPS REST |
| IF-CS-002 | 历史账单查询接口 | 查询账单、欠费、用水趋势 | 客户端 | HTTPS REST |
| IF-CS-003 | 在线支付下单接口 | 创建微信/支付宝支付订单 | 客户端 | HTTPS REST |
| IF-CS-004 | 发票申请接口 | 提交电子发票申请 | 客户端 | HTTPS REST |
| IF-CS-005 | 网点与业务办理接口 | 查询网点、提交业务办理 | 客户端 | HTTPS REST |
| IF-CS-006 | 业务办理进度接口 | 查询业务办理和工单进度 | 客户端 | HTTPS REST |
| IF-CS-007 | 柜面扫码支付接口 | 创建柜面扫码支付订单并回写结果 | 柜台终端/营业前台 | HTTPS REST |

## 外部系统接口

### 金融支付接口

| 接口编号 | 接口名称 | 功能描述 | 协议 | 输入参数 | 输出结果 |
|---|---|---|---|---|---|
| EXT-001 | 银行代扣接口 | 批量代扣水费 | HTTPS/SFTP | 客户信息、账单金额、代扣日期 | 扣款结果 |
| EXT-101 | 微信支付统一下单 | 创建微信支付订单 | HTTPS | 订单信息、金额 | 预支付信息 |
| EXT-201 | 支付宝统一收单 | 创建支付宝支付订单 | HTTPS | 订单信息、金额 | 支付结果 |

### 税务与消息接口

| 接口编号 | 接口名称 | 功能描述 | 协议 | 输入参数 | 输出结果 |
|---|---|---|---|---|---|
| EXT-301 | 短信发送接口 | 发送催缴或通知短信 | HTTPS | 手机号、模板、参数 | 发送结果 |
| EXT-401 | 邮件发送接口 | 发送电子发票或通知邮件 | HTTPS | 邮箱、主题、内容 | 发送结果 |
| EXT-501 | 电子发票开具接口 | 税控平台开票 | HTTPS | 发票信息、税率 | 发票结果 |

### 物联网、政务与签章接口

| 接口编号 | 接口名称 | 功能描述 | 协议 | 输入参数 | 输出结果 |
|---|---|---|---|---|---|
| EXT-601 | 水表数据采集接口 | 获取远程抄表数据 | HTTPS | 水表编号、时间范围 | 抄表数据 |
| EXT-701 | 政务数据汇聚接口 | 向政务平台推送业务数据 | HTTPS | 业务数据、统计数据 | 推送结果 |
| EXT-801 | 环卫收费对接接口 | 同步污水费/环卫收费数据 | HTTPS | 收费数据 | 同步结果 |
| EXT-901 | 客服工单创建接口 | 与客服系统同步工单 | HTTPS | 工单信息 | 工单编号 |
| EXT-1001 | 消火栓控制接口 | 控制取水权限与设备状态 | HTTPS | 设备信息、控制指令 | 控制结果 |
| EXT-CA-001 | 身份认证接口 | 验证合同签署方身份 | HTTPS REST | 用户信息、认证方式 | 认证结果 |
| EXT-CA-002 | 电子签章接口 | 执行电子签章 | HTTPS REST | 文档内容、签章位置 | 签章结果 |
| EXT-CA-003 | 时间戳接口 | 申请签署时间戳 | HTTPS REST | 文档哈希 | 时间戳凭证 |
| EXT-CA-004 | 电子存证接口 | 存储签署后合同 | HTTPS REST | 签署文档、元数据 | 存证凭证 |

<a id="sec-security-detail"></a>

# 安全详细设计

## 安全目标与分层防护

系统安全设计遵循机密性、完整性、可用性、可审计性原则，采用边界安全、应用安全、数据安全、运维安全四层防护模式。


```mermaid
graph TB
    T[外部威胁] --> N[边界安全]
    N --> A[应用安全]
    A --> D[数据安全]
    D --> O[运维安全]
    O --> C[核心业务资产]

```


## 身份认证与访问控制

1. 采用 OAuth2.0 + JWT 统一认证。
2. 高风险操作支持 MFA 二次认证。
3. 基于 RBAC 的菜单、按钮、数据权限控制。
4. 管理端、移动端、客户端、外部系统按不同安全域实施权限隔离。

## 数据安全与隐私保护

1. 核心数据库统一为达梦数据库 8.0+，关键数据按要求启用加密存储。
2. 身份证号、手机号、银行账户等敏感字段按角色脱敏展示。
3. 文件、合同、签章凭证、验收附件统一归档并控制访问权限。
4. 备份数据加密存储，支持异地容灾保管。

## 接口安全与审计追踪

- 所有外部接口采用 HTTPS 加密传输。
- 关键接口支持签名、时间戳、随机数防重放。
- 支付、退款、签章、账务调整等交易型接口必须具备幂等控制。
- 统一记录调用时间、调用方、请求摘要、响应结果、异常码与处理人。

## 安全运营与应急响应

1. 建立暴力破解、异常访问、接口失败、支付异常、签章异常等监控规则。
2. 按 P0~P3 级别定义安全事件处置流程。
3. 定期进行漏洞扫描、补丁更新、备份恢复演练和权限审计。

<a id="sec-deployment-detail"></a>

# 部署与运维设计

## 部署总体方案

系统采用集中部署模式，生产环境分为接入区、应用区、数据区、运维管理区，支持主备容灾与横向扩展。


```mermaid
graph TB
    U[外部访问] --> LB[负载均衡/Nginx]
    LB --> APP1[应用节点1]
    LB --> APP2[应用节点2]
    LB --> APP3[应用节点3]
    APP1 --> DB[(达梦主库)]
    APP2 --> DB
    APP3 --> DB
    DB --> DBS[(达梦备库/从库)]
    APP1 --> REDIS[(Redis)]
    APP1 --> FILE[对象存储]
    APP1 --> MON[监控与日志平台]

```


## 环境规划

| 环境 | 用途 | 说明 |
|---|---|---|
| 开发环境 | 开发联调 | 功能开发、单元验证 |
| 测试环境 | 集成测试 | 接口联调、业务测试、性能测试 |
| 预生产环境 | 上线前验证 | 模拟生产配置，进行发布演练 |
| 生产环境 | 正式运行 | 双机或多节点高可用部署 |

## 网络与分区设计

1. DMZ 区部署负载均衡、WAF、网关等对外接入组件。
2. 应用区部署统一平台、营收、表务、报装、客户渠道等应用节点。
3. 数据区部署达梦数据库、Redis、对象存储与备份服务。
4. 管理区部署堡垒机、日志平台、监控平台和运维工具。

## 监控告警与日志

### 监控指标

| 类别 | 监控项 |
|---|---|
| 主机监控 | CPU、内存、磁盘、网络 |
| 应用监控 | QPS、响应时间、错误率、线程池 |
| 数据库监控 | 连接数、慢 SQL、锁等待、主备同步 |
| 业务监控 | 开账量、收费量、退款量、签章成功率 |

### 日志分类

- 操作日志
- 登录日志
- 接口调用日志
- 任务执行日志
- 安全审计日志
- 外部系统对接日志

## 备份恢复与发布管理

1. 数据库执行每日增量、每周全量备份。
2. 关键文件、合同、电子发票、签章凭证同步纳入备份。
3. 发布采用版本化管理，执行发布审批、健康检查、回滚预案。
4. 对支付、签章、银行代扣等关键链路执行灰度验证前置检查，但生产方案不保留脚本碎片或临时配置片段。

<a id="sec-appendix"></a>

# 附录

## 附录A 模块编号说明

| 前缀 | 模块域 |
|---|---|
| UP | 统一平台 |
| REV | 营收业务 |
| METER | 表务管理 |
| INST | 报装与签章 |
| CS | 客户服务与渠道 |

## 附录B 接口编号说明

| 前缀 | 说明 |
|---|---|
| IF-UP / IF-REV / IF-CS / IF-METER / IF-INST | 系统内部标准接口 |
| IF-EXT | 对外系统接口 |
| EXT-CA | 历史资料中的电子签章专项外部接口编号（存量引用） |

## 附录C 设计约束与统一口径

1. 系统名称统一为“福建水务营收系统”。
2. 数据库口径统一为“达梦数据库 8.0+”。
3. 模块编号统一采用 `UP/REV/METER/INST/CS-001` 风格。
4. 接口编号统一采用 `IF-UP/IF-REV/IF-CS/IF-METER/IF-INST/IF-EXT-001` 风格，历史 `EXT-*` 仅用于存量资料引用。
5. 本文档为唯一主详设文件，其他专项文档作为历史参考与内容来源，不再作为并行主文件使用。