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

| 文件状态： | 文档密级： | 公开 |
| :--- | :--- | :--- |
| 【】草稿 | | |
| 【√】修改稿 | | |
| 【】正式发布 | | |
| | **当前版本：** | **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 | 唐伟杰 | 将分散的模块设计、数据库设计、接口设计、安全设计、部署设计与报装电子签章设计整合为统一主详设，统一系统名称、章节体系、模块/接口编号及数据库口径，清理重复内容与部署脏片段。 |

# 目录

- [福建水务营收系统详细设计说明书](#福建水务营收系统详细设计说明书)
  - [版本历史](#版本历史)
- [目录](#目录)
- [前言](#前言)
  - [编写目的](#编写目的)
  - [建设背景](#建设背景)
  - [设计范围](#设计范围)
  - [术语与缩略语](#术语与缩略语)
  - [参考资料](#参考资料)
- [系统总体设计](#系统总体设计)
  - [总体目标](#总体目标)
  - [逻辑架构设计](#逻辑架构设计)
  - [部署分区设计](#部署分区设计)
  - [子系统与模块划分](#子系统与模块划分)
- [统一平台详细设计](#统一平台详细设计)
  - [UP-001 统一认证与单点登录](#up-001-统一认证与单点登录)
  - [UP-002 组织用户与权限管理](#up-002-组织用户与权限管理)
  - [UP-003 参数字典与基础配置](#up-003-参数字典与基础配置)
  - [UP-004 审计监控与运维支撑](#up-004-审计监控与运维支撑)
- [营收业务详细设计](#营收业务详细设计)
  - [REV-001 客户资料管理](#rev-001-客户资料管理)
  - [REV-002 抄表开账](#rev-002-抄表开账)
  - [REV-003 营业收费](#rev-003-营业收费)
  - [REV-004 账务处理](#rev-004-账务处理)
  - [REV-005 发票与税务处理](#rev-005-发票与税务处理)
  - [REV-006 催缴与通知](#rev-006-催缴与通知)
  - [REV-007 统计分析](#rev-007-统计分析)
  - [REV-008 代收与银行业务](#rev-008-代收与银行业务)
  - [REV-009 业务参数配置](#rev-009-业务参数配置)
- [表务详细设计](#表务详细设计)
  - [METER-001 表务基础管理](#meter-001-表务基础管理)
  - [METER-002 表务工单管理](#meter-002-表务工单管理)
  - [METER-003 仓储与生命周期管理](#meter-003-仓储与生命周期管理)
  - [METER-004 物联网接入与数据同步](#meter-004-物联网接入与数据同步)
- [报装与签章详细设计](#报装与签章详细设计)
  - [INST-001 报装申请与受理](#inst-001-报装申请与受理)
  - [INST-002 现场踏勘与方案设计](#inst-002-现场踏勘与方案设计)
  - [INST-003 施工验收与立户通水](#inst-003-施工验收与立户通水)
  - [INST-004 合同签署与电子签章](#inst-004-合同签署与电子签章)
  - [INST-005 档案归档与过程留痕](#inst-005-档案归档与过程留痕)
- [客户服务模块详细设计](#客户服务模块详细设计)
  - [CS-001 账户绑定管理](#cs-001-账户绑定管理)
  - [CS-002 信息查询服务](#cs-002-信息查询服务)
  - [CS-003 在线缴费服务](#cs-003-在线缴费服务)
  - [CS-004 电子发票服务](#cs-004-电子发票服务)
  - [CS-005 营业网点服务](#cs-005-营业网点服务)
  - [CS-006 业务办理服务](#cs-006-业务办理服务)
  - [CS-007 柜面扫码支付](#cs-007-柜面扫码支付)
- [数据库详细设计](#数据库详细设计)
  - [数据库选型与原则](#数据库选型与原则)
  - [数据库逻辑架构](#数据库逻辑架构)
  - [核心数据模型](#核心数据模型)
  - [核心数据表设计](#核心数据表设计)
  - [索引与性能设计](#索引与性能设计)
- [接口详细设计](#接口详细设计)
  - [接口设计原则](#接口设计原则)
  - [统一平台接口](#统一平台接口)
  - [营收业务接口](#营收业务接口)
  - [表务与物联网接口](#表务与物联网接口)
  - [报装与签章接口](#报装与签章接口)
  - [客户渠道接口](#客户渠道接口)
  - [外部系统接口](#外部系统接口)
- [安全详细设计](#安全详细设计)
  - [安全目标与分层防护](#安全目标与分层防护)
  - [身份认证与访问控制](#身份认证与访问控制)
  - [数据安全与隐私保护](#数据安全与隐私保护)
  - [接口安全与审计追踪](#接口安全与审计追踪)
  - [安全运营与应急响应](#安全运营与应急响应)
- [部署与运维设计](#部署与运维设计)
  - [部署总体方案](#部署总体方案)
  - [环境规划](#环境规划)
  - [网络与分区设计](#网络与分区设计)
  - [监控告警与日志](#监控告警与日志)
  - [备份恢复与发布管理](#备份恢复与发布管理)
- [附录](#附录)
  - [附录A 模块编号说明](#附录a-模块编号说明)
  - [附录B 接口编号说明](#附录b-接口编号说明)
  - [附录C 设计约束与统一口径](#附录c-设计约束与统一口径)

# 前言

## 编写目的

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

## 建设背景

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

## 设计范围

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

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

## 术语与缩略语

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

## 参考资料

1. 《福建水务营收系统概要设计相关文档》
2. `02_Detailed/02_Module_Design.md`
3. `02_Detailed/03_CA_Installation_Design.md`
4. `03_Technical/01_Database_Design.md`
5. `03_Technical/02_Table_Specs.md`
6. `03_Technical/03_Interface_Design.md`
7. `03_Technical/04_Security_Design.md`
8. `03_Technical/05_Deployment_Design.md`
9. 福建水投相关业务操作手册及需求说明资料

# 系统总体设计

## 总体目标

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

- 建立统一认证、统一组织、统一权限、统一参数、统一审计基础能力。
- 构建覆盖营收、表务、报装、客户服务的完整业务闭环。
- 形成达梦数据库 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-004 |
| 报装与签章 | 覆盖受理、踏勘、施工、签约、电子签章、归档 | INST-001 ~ INST-005 |
| 客户服务模块 | 覆盖账户绑定、信息查询、在线缴费、电子发票、网点服务、业务办理与柜面扫码支付 | CS-001 ~ CS-007 |

# 统一平台详细设计

## UP-001 统一认证与单点登录

### 功能说明

UP-001 为全系统提供统一身份认证与单点登录能力，支撑 PC 管理端、移动作业端、客户渠道及外部集成应用的统一接入。

### 关键设计

1. 支持用户名密码登录、短信验证码登录、第三方授权登录。
2. 采用 OAuth2.0 + JWT 实现访问令牌签发与会话管理。
3. 对外部系统开放标准认证接口，支持令牌续期与退出失效。
4. 对高敏感操作支持 MFA 二次校验。

### 业务流程

```mermaid
sequenceDiagram
    participant 用户
    participant 接入端
    participant 认证中心
    participant 用户中心

    用户->>接入端: 提交登录信息
    接入端->>认证中心: 发起认证请求
    认证中心->>用户中心: 校验用户/角色/状态
    用户中心-->>认证中心: 返回校验结果
    认证中心-->>接入端: 返回Token/权限上下文
    接入端-->>用户: 登录成功并进入目标系统
```

### 核心数据

- `system_users`：用户基本信息。
- `system_oauth2_client`：客户端信息。
- `system_oauth2_access_token`：访问令牌。
- `system_oauth2_refresh_token`：刷新令牌。
- `system_login_log`：登录审计日志。

## UP-002 组织用户与权限管理

### 功能说明

UP-002 管理组织机构、岗位、角色、菜单、数据权限和用户授权关系，是业务系统权限控制与数据隔离的基础。

### 关键设计

1. 支持集团—区域公司—营业所三级及以上组织结构。
2. 基于 RBAC 实现菜单权限、按钮权限、数据权限。
3. 支持多租户/多单位数据隔离与用户归属控制。
4. 敏感操作如账务调整、退款、作废、签章回退必须经过权限校验。

### 主要规则

- 角色权限与组织权限叠加生效。
- 业务数据默认按所属单位、片区、岗位范围过滤。
- 超权限查询、批量导出、敏感字段查看需单独授权。

## UP-003 参数字典与基础配置

### 功能说明

UP-003 用于统一维护业务参数、地址参数、水价规则、短信模板、打印模板、字典数据与定时任务参数。

### 关键设计

| 配置类别 | 典型内容 | 用途 |
|---|---|---|
| 业务字典 | 客户类型、抄表方式、工单状态 | 统一编码与展示 |
| 地址参数 | 行政区划、片区、册本归属 | 客户与表务归属管理 |
| 价格体系 | 用水性质、阶梯水价、污水费规则 | 开账与账务计算 |
| 渠道参数 | 支付渠道、短信模板、税控配置 | 外部接口集成 |
| 任务参数 | 自动开账、对账、备份周期 | 运维调度 |

## UP-004 审计监控与运维支撑

### 功能说明

UP-004 提供操作日志、登录日志、接口日志、异常监控、在线用户、任务监控、性能监控等能力。

### 关键设计

1. 所有核心业务操作写入统一审计日志。
2. 接口调用成功率、响应时长、异常码进入监控平台。
3. 定时任务执行结果、失败重试与人工补偿过程可追踪。
4. 监控与告警支持短信、邮件、站内信等通知方式。

# 营收业务详细设计

## REV-001 客户资料管理

### 功能说明

负责客户主档、账户主档、联系人、客户分组、客户与水表关系、客户开票信息、客户渠道绑定及托收/代扣关系维护，是抄表、收费、发票、代扣等后续业务的主数据基础。

### 关键设计

1. 客户建档覆盖立户、变更、更名、过户、销户、报停等全生命周期处理。
2. 客户资料支持按客户类型、用水性质、片区、集团客户、重点客户等维度管理。
3. 客户与水表、开票主体、托收/代扣签约关系按关联表维护，避免在主表中堆叠多类属性。
4. 客户编号、集收标记、计划用水方案等规则类数据由统一配置与客户关系表共同支撑。

### 核心数据

- `biz_cust`：客户主档。
- `biz_account`：客户账户与账户状态。
- `biz_cust_contact`：联系人及联系方式。
- `biz_cust_group`：客户分组。
- `biz_cust_meter`：客户与水表绑定关系。
- `biz_cust_invoice`：客户开票信息。
- `biz_cust_app_binds`：渠道绑定关系。
- `biz_cust_collection_rel`：客户托收关系。
- `biz_cust_withholding_rel`：客户代扣关系。
- `biz_cust_water_use_scheme`、`biz_cust_water_scheme_rel`：客户计划用水方案关系。
- `biz_cust_no_rule`：客户编号规则。
- `biz_cust_hub_marks`：集收号/集收标记关系。

### 落地边界

- **已落地**：客户主档、账户、联系人、分组、绑定、开票、托收/代扣关系。
- **部分落地**：客户扩展关系、集收与规则类对象已见明确关系表，但具体业务场景仍需结合流程进一步细化。
- **文档先行**：主副卡、部分复杂客户关系对象在当前 backend 中未见完全独立表族，文档中仅保留业务对象表述。

## REV-002 抄表开账

### 功能说明

负责抄表计划、册本管理、抄表录入、抄表状态跟踪、异常复核、计费计算与账单生成，是营收核心处理链路的起点。

### 业务流程

```mermaid
flowchart TD
    A[制定抄表计划] --> B[生成抄表册本]
    B --> C[分配抄表任务]
    C --> D[人工/远传/自报抄表]
    D --> E[数据校验]
    E --> F{是否异常}
    F -->|是| G[异常复核处理]
    F -->|否| H[生成开账数据]
    G --> H
    H --> I[按价格模板与费用组成计费]
    I --> J[生成营业账与明细]
    J --> K[账单审核确认]
    K --> L[进入收费/催缴/开票]
```

### 关键规则

1. 抄表数据同时校验本次读数、上次读数、用量波动和抄表状态。
2. 异常抄表支持估抄、补抄、重录、人工复核。
3. 开账按价格归属、价格模板、费用组成、阶梯规则、计划用水方案综合计算。
4. 审核通过后的营业账方可进入收费、催缴和发票流程。
5. 远传抄表数据可由 `SYS-006` / IoT 能力提供采集支撑，但账单生成仍归属 SYS-002。

### 核心数据

- `biz_meter_book`：册本与抄表计划。
- `biz_meter_read`：抄表任务状态/执行状态。
- `biz_reading_data`：抄表数据。
- `biz_last_reading`：上次抄表结果。
- `biz_reading_logs`：抄表日志与过程留痕。
- `biz_meter`：计量水表主档引用。
- `biz_charge`：营业账主表。
- `biz_charge_detail`：营业账明细。
- `biz_price_category`：价格归属。
- `biz_price_template`：价格模板。
- `biz_price_adjustment_snap`：调价快照。
- `biz_price_tier_adjustment`：阶梯规则。
- `biz_cost_component`：费用组成。
- `biz_water_use_scheme`、`biz_water_use_scheme_tier`：计划用水方案与阶梯。

### 落地边界

- **已落地**：册本、抄表数据、上次抄表、抄表日志、营业账主明细、价格模板与阶梯规则。
- **部分落地**：部分异常场景对象可能仍通过状态字段和日志表承载，而非全部拆成独立业务表。
- **文档先行**：个别精细稽查、轨迹、下载同步对象当前未在本轮映射中确认为独立表。

## REV-003 营业收费

### 功能说明

支持柜台收费、预存款/余额抵扣、线上缴费回写、柜面扫码、营业网点收费及收费凭证管理，统一承接营收账单的核销处理。

### 业务流程

```mermaid
flowchart TD
    A[查询客户及待缴账单] --> B[选择账单与核销方式]
    B --> C[选择支付渠道]
    C --> D{支付方式}
    D -->|柜台现金/POS/扫码| E[现场收费]
    D -->|微信/支付宝/聚合支付| F[渠道下单]
    D -->|预存款/余额抵扣| G[账户余额核销]
    E --> H[更新营业账状态]
    F --> I[等待异步回调确认]
    G --> H
    I --> H
    H --> J[生成收费记录与凭证]
    J --> K[进入发票/对账流程]
```

### 关键规则

1. 一次缴费可对应多个账单或账单明细的组合核销。
2. 收费记录必须保留渠道、流水号、网点、操作员、终端信息。
3. 线上支付必须以回调或查询确认结果为准，不得以发起状态直接记账。
4. 支付能力由 `SYS-009` 提供，SYS-002 负责账单核销与业务状态回写。

### 核心数据

- `biz_charge`、`biz_charge_detail`：待缴与已缴账单主明细。
- `biz_collection`：托收/代收主表。
- `biz_withholding`：代扣/托收主表。
- `bk_transaction`：渠道交易流水。
- `bk_transaction_callback`：支付回调记录。
- `bk_transaction_exception`：支付异常记录。

### 落地边界

- **已落地**：营业账主明细、交易流水、回调、异常、托收/代扣主对象。
- **部分落地**：柜台班结、部分收费汇总类对象可能通过业务流程与报表实现，不一定存在独立表。
- **文档先行**：部分红冲、实时收费汇总类台账暂不表述为已确认独立实体表。

## REV-004 账务处理

### 功能说明

承担水量调整、金额调整、违约金减免、退款、冲正、呆坏账申请等账务修正与审批处理能力，保证收费后账务结果可追溯、可审计。

### 关键设计

1. 调整类操作以营业账主明细为基础，并通过日志与审批留痕记录前后变化。
2. 水量调整、金额调整、优惠调整等场景可引用价格模板、阶梯与优惠对象重新计算。
3. 退款、冲正等交易修正需与原支付流水及渠道状态联动校验。
4. 对于当前未见明确独立实体表的特账、跨周期水量、退款账等对象，文档以“业务处理场景”表述，不强行落为已实现表。

### 核心数据

- `biz_charge`、`biz_charge_detail`：账务调整的核心对象。
- 价格调整/优惠相关表：用于重算账单或差额追溯。
- `biz_operat_log`、`biz_operat_log_detail`：操作与变更留痕。

### 主要场景

| 场景 | 说明 | 控制要点 |
|---|---|---|
| 水量调整 | 更正异常水量 | 需复核原因、附件和原抄表依据 |
| 金额调整 | 更正账单金额 | 需记录依据、差异金额和审批链路 |
| 退款处理 | 退回客户支付资金或预存款 | 需校验原交易、退款余额与幂等性 |
| 错误缴费冲正 | 修正误收/误核销记录 | 需关联原交易与账单状态 |
| 呆坏账申请 | 对长期欠费进行分类处理 | 需结合账龄、客户状态与审批结果 |

### 落地边界

- **已落地**：营业账主明细、操作日志、价格/方案相关重算支撑。
- **部分落地**：精细化账务对象更多表现为流程与场景，并未在 backend 中全部体现为独立表族。
- **文档先行**：特账、退款账、跨周期水量等对象保留业务语义，不宣称为已实现独立表。

## REV-005 发票与税务处理

### 功能说明

负责发票申请、开票校验、开票结果回写、发票查询、作废与红冲处理，作为营收业务对发票服务的业务接入层。

### 关键设计

1. 发票申请以客户信息、缴费记录、账单信息、税率配置为基础。
2. 个人与企业开票均通过客户开票信息与税率表完成合法性校验。
3. 发票开具、作废、红冲由 `SYS-008` 统一承接，SYS-002 负责业务上下文传递与结果落账。
4. 电子发票可通过客户服务渠道推送或下载。

### 核心数据

- `biz_invoice`：发票主记录。
- `biz_invoice_taxrate`：税率配置。
- `biz_cust_invoice`：客户开票信息。

### 落地边界

- **已落地**：发票主记录、税率配置、客户开票信息。
- **部分落地**：发票修改、开票过程留痕在后端中已有相关对象，但整套发票明细/批次类对象尚未全部确认。
- **文档先行**：发票明细、营业账开票关系等对象仍按设计能力描述，不表述为本轮已确认独立表。

## REV-006 催缴与通知

### 功能说明

针对欠费账单按账龄、金额、客户类别等规则生成催缴任务，通过短信、微信、站内通知等方式触达客户，并回写催缴结果。

### 关键设计

1. 催缴策略以营业账状态、欠费金额、账龄分布和客户类别为基础。
2. 自动催缴与人工催缴可并行，支持停复水等后续处置联动。
3. 触达能力由 `SYS-010` 提供，SYS-002 负责生成待发送业务事件、催缴名单与结果回写。
4. 当前后端中部分催缴汇总、停水明细对象未确认独立落表，文档中保持保守描述。

### 核心数据

- `biz_charge`、`biz_charge_detail`：催缴对象来源。
- 催缴结果与通知日志：通过业务状态与消息结果联动留痕。

### 落地边界

- **已落地**：以营业账为基础的欠费识别与消息协同前提数据。
- **部分落地**：催缴登记汇总、停水汇总等对象暂未在 backend 中确认独立表。
- **文档先行**：复杂催缴台账与停复水统计仅作为业务场景保留。

## REV-007 统计分析

### 功能说明

提供营收、抄表、收费、欠费、渠道、客户、工单等多维度统计分析能力，为经营分析和业务监管提供数据支撑。

### 关键设计

1. 报表统计基于客户、账单、收费、渠道、时间、片区等维度聚合。
2. 常用统计口径包括售水量、收费金额、欠费规模、渠道占比、客户类型分布、抄表完成率等。
3. 导出与查询结果受数据权限控制，重点报表可采用预聚合或物化结果提升查询性能。

### 核心数据

- 客户维度：`biz_cust`、`biz_account`。
- 抄表维度：`biz_meter_book`、`biz_reading_data`、`biz_last_reading`。
- 账务与收费维度：`biz_charge`、`biz_charge_detail`。
- 渠道维度：`bk_transaction`、`bk_payment_channel`。

### 落地边界

- **已落地**：主要统计源数据在客户、抄表、收费、渠道等领域均已具备。
- **部分落地**：部分分析结果更多依赖报表层实现，而非单独分析表。
- **文档先行**：预测类、专题分析类深度模型暂不写成后端已实现能力。

## REV-008 代收与银行业务

### 功能说明

支持银行代收、银行代扣、实时收费、夜间批量扣款、对账与结算处理，是 SYS-002 面向 `SYS-009` 支付与银行结算能力的业务承接模块。

### 关键设计

1. 渠道、路由、接口配置、签约、交易、回调、异常、对账、结算形成完整银行业务链条。
2. 实时收费场景由渠道交易流水驱动账单核销，批量代扣场景由签约关系与批次处理驱动。
3. 对账结果区分一致、长款、短款、失败待处理等状态，支持差异追踪与人工补偿。
4. 国密报文、批量文件、标准 API 等技术细节由 `SYS-009` 承载，SYS-002 保留业务规则与状态协同。

### 核心数据

- `bk_payment_channel`：支付渠道。
- `bk_channel_api_config`：渠道接口配置。
- `bk_channel_route_rule`：渠道路由规则。
- `bk_withholding_agreement`：代扣签约。
- `bk_withholding_batch`、`bk_withholding_item`：代扣批次与明细。
- `bk_reconcile_batch`、`bk_reconcile_diff`：对账批次与差异。
- `bk_settlement_batch`：结算批次。
- `bk_transaction`、`bk_transaction_callback`、`bk_transaction_exception`：交易、回调、异常。
- `biz_collection`、`biz_withholding`：代收/代扣业务主对象。

### 落地边界

- **已落地**：渠道、路由、交易、回调、异常、签约、批次、对账、结算等主链路对象。
- **部分落地**：部分统计类、汇总类对象可能在渠道报表或外部结算文件层体现。
- **文档先行**：不将未明确扫描到的扩展银行台账写成已实现独立表。

## REV-009 业务参数配置

### 功能说明

负责营收域的价格参数、客户编号规则、页面配置、打印与渠道相关业务参数配置，为客户、开账、收费、发票、催缴等模块提供统一配置支撑。

### 关键设计

1. 业务参数按租户、单位、片区、业务类别分层管理。
2. 价格体系、客户编号规则、页面字段配置、打印与通知参数统一归口维护。
3. 配置变更应具备版本化、操作留痕与生效范围控制。

### 核心数据

- `biz_parameter_settings`：业务参数配置。
- `biz_page_settings`、`biz_page_settings_detail`：页面配置。
- `biz_price_category`、`biz_price_template`、`biz_template_dept_rel`：价格归属与模板站点关系。
- `biz_cust_no_rule`：客户编号规则。

# 客户服务模块详细设计

## CS-001 账户绑定管理

### 功能说明

面向微信、支付宝、微网厅等渠道实现客户账户绑定、解绑、默认账户设置、多账户切换与身份校验。

### 关键规则

1. 一个渠道账户可绑定多个用水账户。
2. 绑定、解绑、默认账户变更等敏感操作需进行身份校验。
3. 已销户、冻结或限制服务的账户不得新增绑定。

### 核心数据

- `biz_cust_app_binds`
- `biz_cust`
- `biz_account`

## CS-002 信息查询服务

### 功能说明

提供账单查询、缴费记录查询、用水分析、欠费查询、账户流水、历史账单等服务。

### 关键设计

1. 查询范围严格限制在已绑定客户与账户范围内。
2. 账单、缴费、发票、办理进度等数据通过 SYS-002 标准接口聚合展示。
3. 常用历史数据支持按最近周期快速查询。

### 核心数据

- `biz_cust`
- `biz_account`
- `biz_charge`
- `biz_charge_detail`
- `biz_invoice`

## CS-003 在线缴费服务

### 功能说明

提供微信支付、支付宝支付、银行卡支付、预存款支付等在线缴费能力。

### 关键规则

1. 下单前再次校验账单未缴状态和应缴金额。
2. 支付结果以 `SYS-009` 回调/查询确认为准。
3. 对失败订单支持补单、查询与结果回写。

### 核心数据

- `biz_charge`
- `biz_charge_detail`
- `bk_transaction`
- `bk_transaction_callback`

## CS-004 电子发票服务

### 功能说明

在客户渠道中提供电子发票申请、查询、下载以及缴费后发票推送能力。

### 关键设计

1. 电子发票开具能力经 `SYS-008` 统一提供。
2. 发票申请与客户开票信息、缴费记录和账单状态联动校验。
3. 发票结果支持下载、查看和渠道推送。

### 核心数据

- `biz_invoice`
- `biz_cust_invoice`
- `biz_invoice_taxrate`

## CS-005 营业网点服务

### 功能说明

提供营业网点查询、服务范围查看、办事指引与营业时间展示能力。

### 关键设计

1. 网点信息展示地址、联系电话、营业时间与可办理业务范围。
2. 网点服务以查询与引导为主，不在本模块中虚构额外业务实体表。
3. 与 CS-006 业务办理服务协同，支持从网点查询跳转到线上办理。

## CS-006 业务办理服务

### 功能说明

提供更名、过户、联系方式变更、开票方式变更、一户多人口、自主抄表、换表申请等线上业务办理入口。

### 关键设计

1. 业务办理统一调用工单/流程能力，不与后台流程表重复建模。
2. 办理结果与客户资料、工单状态、报装或表务流程联动更新。
3. 触达通知通过 `SYS-010` 完成结果通知。

## CS-007 柜面扫码支付

### 功能说明

支持营业厅柜台二维码收款、票据关联、结果回传，是柜台收费场景对线上支付能力的补充入口。

### 关键设计

1. 柜面扫码支付与 REV-003 营业收费统一核销口径。
2. 支付结果与交易流水经 `SYS-009` 回传后更新收费状态。
3. 支持支付凭证、发票申请与收费记录联动。

### 核心数据

- `biz_charge`
- `bk_transaction`
- `bk_transaction_callback`

# 表务详细设计

## METER-001 表务基础管理

### 功能说明

管理水表档案、厂家、型号、口径、量程、检定证书、安装位置、当前状态等基础信息。

### 关键设计

- 一块水表对应唯一档案主记录。
- 设备状态覆盖在库、在用、待检、故障、报废等。
- 与客户、水表工单、抄表记录形成关联闭环。

## METER-002 表务工单管理

### 功能说明

处理换表、移表、拆表、复装、校表、稽查、维修等表务工单。

### 关键设计

1. 工单类型决定必填字段、处理流程和附件要求。
2. 换表工单需同时记录旧表拆除信息与新表安装信息。
3. 表务工单完成后同步更新水表档案与客户绑定关系。

## METER-003 仓储与生命周期管理

### 功能说明

管理新表入库、领用、出库、退库、报废及全生命周期追踪。

### 核心数据

- `water_meter_stock`
- `water_meter_inventory`
- `water_meter_archive`

## METER-004 物联网接入与数据同步

### 功能说明

接入集抄系统、智能表平台及厂家物联网平台，实现远程抄表、状态查询、设备参数同步与异常告警。

### 业务流程

```mermaid
flowchart TD
    A[定时采集任务] --> B[发送采集请求]
    B --> C[物联网平台返回数据]
    C --> D[数据校验]
    D --> E{是否有效}
    E -->|有效| F[写入抄表记录]
    E -->|无效| G[异常标记并告警]
    F --> H[参与开账]
    G --> I[人工复核处理]
```

# 报装与签章详细设计

## INST-001 报装申请与受理

### 功能说明

支持新装、改造、一户一表等业务的申请受理、资料提交、受理审核与流程发起。

### 关键设计

- 统一采集申请人、地址、产权、用水性质、附件材料等信息。
- 支持政务平台、柜台、微网厅等多入口申请。
- 受理后自动生成报装编号并进入踏勘流程。

## INST-002 现场踏勘与方案设计

### 功能说明

组织现场勘查、工程条件确认、材料测算、施工方案与费用方案编制。

### 关键设计

1. 踏勘记录包括现场照片、供水接入条件、施工难点、估算费用。
2. 方案版本化管理，支持设计审核与退回修改。
3. 勘查结果直接驱动合同金额与施工计划。

## INST-003 施工验收与立户通水

### 功能说明

完成施工派工、安装实施、竣工验收、立户建档和通水确认。

### 关键设计

- 施工节点按派工、实施、验收、归档逐步留痕。
- 验收通过后自动触发客户建档、水表绑定和账户初始化。
- 与表务系统共享水表安装与换表数据。

## INST-004 合同签署与电子签章

### 功能说明

通过集成泛微 CA 电子签章系统，实现报装合同、用水协议等文件的电子签署、时间戳和电子存证。

### 集成架构

```mermaid
graph TD
    subgraph INST[报装业务系统]
        A[申请受理]
        B[合同管理]
        C[电子签章模块]
        D[档案归档]
    end

    subgraph CA[泛微CA电子签章系统]
        E[身份认证服务]
        F[电子签章服务]
        G[时间戳服务]
        H[电子存证服务]
    end

    A --> B
    B --> C
    C --> E
    C --> F
    C --> G
    C --> H
    C --> D
```

### 合同签署流程

```mermaid
sequenceDiagram
    participant 客户
    participant 报装系统
    participant 电子签章模块
    participant 泛微CA系统

    客户->>报装系统: 提交签署申请
    报装系统->>电子签章模块: 生成签署任务
    电子签章模块->>泛微CA系统: 发起身份认证
    泛微CA系统-->>电子签章模块: 返回认证结果
    电子签章模块->>泛微CA系统: 发起电子签章
    泛微CA系统-->>电子签章模块: 返回签章结果
    电子签章模块->>泛微CA系统: 申请时间戳与存证
    泛微CA系统-->>电子签章模块: 返回凭证
    电子签章模块-->>报装系统: 返回签署结果
    报装系统-->>客户: 通知合同签署完成
```

### 核心数据

| 数据对象 | 说明 |
|---|---|
| `installation_contract` | 报装合同主表 |
| `installation_signature` | 电子签章记录表 |
| `installation_evidence` | 电子存证记录表 |

### 关键规则

1. 合同签署前必须完成身份认证。
2. 合同正文、签署位置、签署人、签署时间必须完整留痕。
3. 签署完成文件必须归档并生成可验证凭证。
4. 外部 CA 接口异常时应支持重试与人工补偿处理。

## INST-005 档案归档与过程留痕

### 功能说明

归集申请材料、设计方案、合同文件、验收资料、签章回执和过程日志，形成完整报装档案。

### 关键设计

- 档案按申请单维度统一归档。
- 电子签章合同、验收附件、影像资料统一存储。
- 档案查询支持按申请编号、客户、地址、时间、状态检索。

# 数据库详细设计

## 数据库选型与原则

系统数据库统一采用达梦数据库 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 |

### 表务与工单类

| 表名 | 说明 | 关键字段 |
|---|---|---|
| `water_meter_workorder` | 表务工单表 | workorder_code、workorder_type、workorder_status、meter_id、customer_id |
| `water_meter_stock` | 水表库存表 | stock_code、meter_model、meter_caliber、stock_quantity |
| `water_meter_inventory` | 出入库记录表 | inventory_code、inventory_type、quantity、stock_id |
| `business_work_order` | 业务工单主表 | work_order_code、work_order_type、status、source_channel |

### 报装与签章类

| 表名 | 说明 | 关键字段 |
|---|---|---|
| `installation_apply` | 报装申请表 | apply_code、apply_type、customer_name、address、status |
| `installation_survey` | 现场踏勘表 | survey_code、apply_id、survey_result、estimated_fee |
| `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。

# 接口详细设计

## 接口设计原则

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 | 签署文档、元数据 | 存证凭证 |

# 安全详细设计

## 安全目标与分层防护

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

```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. 定期进行漏洞扫描、补丁更新、备份恢复演练和权限审计。

# 部署与运维设计

## 部署总体方案

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

```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 模块编号说明

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

## 附录B 接口编号说明

| 前缀 | 说明 |
|---|---|
| IF | 系统内部标准接口 |
| EXT | 对外系统接口 |
| EXT-CA | 电子签章专项外部接口 |

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

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