# 福建水务业务系统接口设计

## 目录
- [1. 接口概述](#1-接口概述)
- [2. 外部接口](#2-外部接口)
- [3. 内部接口](#3-内部接口)
- [4. 接口标准](#4-接口标准)

## 1. 接口概述

福建水务业务系统提供丰富的接口，用于与外部系统集成以及系统内部各模块间的数据交换。接口设计遵循标准化、安全性、可扩展性的原则，基于RuoYi-Vue-Pro框架采用RESTful风格设计，支持JSON数据格式。

### 1.1 接口设计原则

- **统一性**：所有接口遵循统一的设计规范和数据格式
- **安全性**：接口通过认证授权、参数校验等机制保障安全
- **可维护性**：接口文档完善，便于维护和升级
- **兼容性**：接口设计考虑版本兼容，支持平滑升级
- **性能优化**：接口设计考虑性能，支持缓存、分页等机制

### 1.2 RESTful API规范

系统API接口采用RESTful风格设计，主要规范如下：

#### 1.2.1 资源命名

- 使用名词复数表示资源集合，如`/users`、`/meters`
- 使用资源ID标识特定资源，如`/users/1`、`/meters/123`
- 资源层级关系通过路径嵌套表示，如`/users/1/meters`

#### 1.2.2 HTTP方法

- GET：获取资源
- POST：创建资源
- PUT：更新资源（全量更新）
- PATCH：部分更新资源
- DELETE：删除资源

#### 1.2.3 状态码

- 200 OK：请求成功
- 201 Created：资源创建成功
- 400 Bad Request：请求参数错误
- 401 Unauthorized：未授权
- 403 Forbidden：权限不足
- 404 Not Found：资源不存在
- 500 Internal Server Error：服务器内部错误

#### 1.2.4 响应格式

系统统一采用以下JSON格式响应：

```json
{
  "code": 0,           // 业务状态码，0表示成功，非0表示失败
  "data": {},          // 响应数据
  "msg": "success"     // 响应消息
}
```

分页查询响应格式：

```json
{
  "code": 0,
  "data": {
    "list": [],        // 数据列表
    "total": 100,      // 总记录数
    "pageNum": 1,      // 当前页码
    "pageSize": 10     // 每页记录数
  },
  "msg": "success"
}
```

### 1.3 接口文档

系统使用Knife4j（基于Swagger）自动生成API文档，文档地址为：`http://{系统地址}/doc.html`。

主要特点：
- 在线接口文档：支持在线查看接口定义
- 接口调试：支持在线调试接口
- 文档导出：支持导出OpenAPI规范文档
- 权限控制：支持对接口文档的访问控制

## 2. 外部接口

### 2.1 与银行接口

#### 2.1.1 银行代扣接口

**功能描述**：通过银行系统自动从用户账户中扣除水费。

**接口规范**：
- 接口方式：文件交换或WebService
- 数据格式：文本文件或XML
- 交换频率：每日或实时

#### 2.1.2 银行实时缴费接口

**功能描述**：用户在银行柜台、网上银行或手机银行实时缴纳水费。

**接口规范**：
- 接口方式：WebService或HTTP接口
- 数据格式：XML或JSON
- 交换频率：实时

### 2.2 支付宝接口

**功能描述**：用户通过支付宝缴纳水费。

**接口规范**：
- 接口方式：HTTP接口
- 数据格式：JSON
- 交换频率：实时

### 2.3 微信支付接口

**功能描述**：用户通过微信支付缴纳水费。

**接口规范**：
- 接口方式：HTTP接口
- 数据格式：XML或JSON
- 交换频率：实时

### 2.4 短信接口

**功能描述**：向用户发送各类业务通知短信。

**接口规范**：
- 接口方式：HTTP接口
- 数据格式：JSON
- 交换频率：实时

### 2.5 物联网集抄平台接口

**功能描述**：与物联网集抄平台交互，获取智能水表数据。

**接口规范**：
- 接口方式：HTTP接口或WebService
- 数据格式：JSON或XML
- 交换频率：定时或实时

## 3. 内部接口

### 3.1 用户接口

#### 3.1.1 用户信息查询接口

**功能描述**：查询用户基本信息。

**接口规范**：
- 请求方式：GET
- 请求路径：/api/users/{userId}
- 返回格式：JSON

#### 3.1.2 用户信息更新接口

**功能描述**：更新用户基本信息。

**接口规范**：
- 请求方式：PUT
- 请求路径：/api/users/{userId}
- 请求/返回格式：JSON

### 3.2 水表接口

#### 3.2.1 水表信息查询接口

**功能描述**：查询水表基本信息。

**接口规范**：
- 请求方式：GET
- 请求路径：/api/meters/{meterId}
- 返回格式：JSON

#### 3.2.2 水表读数上传接口

**功能描述**：上传水表读数。

**接口规范**：
- 请求方式：POST
- 请求路径：/api/meters/{meterId}/readings
- 请求/返回格式：JSON

### 3.3 账单接口

#### 3.3.1 账单查询接口

**功能描述**：查询用户账单信息。

**接口规范**：
- 请求方式：GET
- 请求路径：/api/users/{userId}/bills
- 返回格式：JSON

#### 3.3.2 缴费接口

**功能描述**：处理用户缴费。

**接口规范**：
- 请求方式：POST
- 请求路径：/api/bills/{billId}/payments
- 请求/返回格式：JSON

### 3.4 工单接口

#### 3.4.1 工单创建接口

**功能描述**：创建业务工单。

**接口规范**：
- 请求方式：POST
- 请求路径：/api/workorders
- 请求/返回格式：JSON

#### 3.4.2 工单状态更新接口

**功能描述**：更新工单处理状态。

**接口规范**：
- 请求方式：PUT
- 请求路径：/api/workorders/{workorderId}/status
- 请求/返回格式：JSON

## 4. 接口标准

### 4.1 接口协议

系统接口主要采用以下协议：

- **RESTful API**：适用于系统内部模块间的交互以及移动应用等轻量级客户端
- **WebService**：适用于与外部系统的集成，特别是银行等传统机构
- **消息队列**：适用于异步处理的场景，如批量数据处理、通知推送等

### 4.2 数据格式

接口数据主要采用以下格式：

- **JSON**：主要用于RESTful API接口，结构简单清晰，适合Web应用
- **XML**：主要用于WebService接口，兼容性好，适合与传统系统对接
- **文本文件**：主要用于批量数据交换，如银行代扣文件等

### 4.3 接口安全

接口安全采用以下机制：

- **令牌认证**：使用JWT(JSON Web Token)进行身份认证
- **签名验证**：请求参数签名，确保数据完整性
- **IP白名单**：限制接口调用者的IP地址
- **传输加密**：使用HTTPS协议加密传输数据
- **接口限流**：限制单位时间内的请求次数
- **访问日志**：记录所有接口调用情况