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

## 文档信息
| 项目信息 | 详情 |
|---------|------|
| **项目名称** | 福建水务营收系统 |
| **文档类型** | 概要设计文档 |
| **技术框架** | RuoYi-Vue-Pro + yudao-ui-admin-vue3 |
| **文档版本** | v1.0 |
| **编写日期** | 2024-12-19 |
| **文档状态** | ✅ 已完成 |

## 目录
- [接口概述](#接口概述)
- [外部接口](#外部接口)
- [内部接口](#内部接口)
- [接口标准](#接口标准)

## 接口概述

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

### 接口设计原则

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

### RESTful API规范

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

#### 资源命名

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

#### HTTP方法

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

#### 状态码

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

#### 响应格式

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

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

分页查询响应格式：

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

### 接口文档

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

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

## 外部接口

### 银行接口对接

#### 银行代扣接口

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

**接口详情**：
- **接口方式**：文件交换（FTP/SFTP）
- **数据格式**：定长文本文件
- **交换频率**：每日凌晨2:00
- **文件编码**：GBK

**代扣文件格式**：
```text
记录类型(1位) + 客户号(12位) + 户名(30位) + 银行账号(20位) + 扣款金额(12位,含2位小数) + 账期(6位) + 保留字段(19位)
```

**代扣文件示例**：
```text
1C00000000001张三                          62172511001234567890000009180202412          
1C00000000002李四                          62172511001234567891000015460202412          
```

**回盘文件格式**：
```text
记录类型(1位) + 客户号(12位) + 银行账号(20位) + 扣款金额(12位) + 处理状态(1位) + 银行流水号(20位) + 处理时间(14位) + 失败原因(20位)
```

**代扣文件生成流程**：
1. 每日凌晨2点自动生成代扣文件
2. 查询当日待代扣账单数据
3. 按银行要求格式生成文件内容
4. 通过SFTP上传至银行服务器
5. 记录文件生成和上传日志

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

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

**接口详情**：
- **接口方式**：HTTP POST
- **请求URL**：`https://bank.api.com/payment/water-fee`
- **数据格式**：JSON
- **认证方式**：API Key + 签名

**请求参数**：

```json
{
  "merchantId": "WATER001",
  "customerCode": "C001",
  "billCodes": ["B202412190001"],
  "totalAmount": 91.80,
  "bankAccount": "6217251100123456789",
  "customerName": "张三",
  "timestamp": "20241219103000",
  "signature": "ABC123DEF456..."
}
```

**响应参数**：
```json
{
  "resultCode": "0000",
  "resultMsg": "交易成功",
  "data": {
    "transactionId": "TXN20241219001",
    "paymentTime": "20241219103001",
    "bankSerial": "BNK20241219001234"
  }
}
```

### 支付宝接口对接

**功能描述**：用户通过支付宝缴纳水费，支持扫码支付和H5支付。

**接口详情**：
- **接口方式**：HTTP POST
- **支付方式**：统一收单交易预创建（alipay.trade.precreate）
- **数据格式**：JSON
- **认证方式**：RSA2签名

**预创建支付请求参数**：

```json
{
  "app_id": "2021001234567890",
  "method": "alipay.trade.precreate", 
  "charset": "UTF-8",
  "sign_type": "RSA2",
  "timestamp": "2024-12-19 10:30:00",
  "version": "1.0",
  "notify_url": "https://water.example.com/api/payment/alipay/notify",
  "biz_content": {
    "out_trade_no": "P202412190002",
    "total_amount": "91.80",
    "subject": "水费缴费",
    "body": "2024年12月水费-客户编号:C001",
    "store_id": "WATER_STORE_001",
    "timeout_express": "30m"
  }
}
```

**支付宝响应参数**：
```json
{
  "alipay_trade_precreate_response": {
    "code": "10000",
    "msg": "Success",
    "out_trade_no": "P202412190002",
    "qr_code": "https://qr.alipay.com/bax08945xtdnfwgqmwi200b4"
  },
  "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}
```

**支付宝支付集成流程**：
1. 调用支付宝预创建接口生成支付二维码
2. 前端展示二维码供用户扫码支付
3. 支付完成后支付宝发送异步通知
4. 系统验证通知签名并更新订单状态
5. 记录支付日志和账务处理

### 微信支付接口对接

**功能描述**：用户通过微信支付缴纳水费，支持扫码支付和小程序支付。

**接口详情**：
- **接口方式**：HTTP POST
- **支付方式**：Native支付（扫码）/ JSAPI支付（小程序）
- **请求URL**：`https://api.mch.weixin.qq.com/v3/pay/transactions/native`
- **数据格式**：JSON
- **认证方式**：微信支付V3签名

**统一下单请求参数**：

```json
{
  "appid": "wx8888888888888888",
  "mchid": "1900000109", 
  "description": "水费缴费-2024年12月",
  "out_trade_no": "P202412190003",
  "notify_url": "https://water.example.com/api/payment/wechat/notify",
  "amount": {
    "total": 9180,
    "currency": "CNY"
  },
  "attach": "客户编号:C001,账单号:B202412190001",
  "goods_tag": "WATER_FEE",
  "time_expire": "2024-12-19T11:00:00+08:00"
}
```

**微信支付响应参数**：
```json
{
  "code_url": "weixin://wxpay/bizpayurl?pr=HuaLcAKwa"
}
```

**支付结果通知参数**：
```json
{
  "id": "EV-2018022511223320873",
  "create_time": "2024-12-19T10:30:00+08:00",
  "resource_type": "encrypt-resource",
  "event_type": "TRANSACTION.SUCCESS",
  "summary": "支付成功",
  "resource": {
    "original_type": "transaction",
    "algorithm": "AEAD_AES_256_GCM",
    "ciphertext": "...",
    "associated_data": "transaction",
    "nonce": "..."
  }
}
```

### 短信接口

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

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

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

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

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

## 内部接口

### 客户管理API接口

#### 客户信息查询接口

**功能描述**：根据客户ID查询客户详细信息。

**接口详情**：
- **请求方式**：GET
- **请求路径**：`/admin-api/water/customer/{id}`
- **请求头**：`Authorization: Bearer {token}`

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|-------|------|------|------|------|
| id | Long | 是 | 客户ID | 1 |

**响应参数**：
```json
{
  "code": 0,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "customerCode": "C001",
    "customerName": "张三",
    "customerType": "RESIDENT",
    "phone": "13800138000",
    "address": "福建省福州市台江区XX街道XX号",
    "status": 1,
    "createTime": "2024-12-19 10:00:00"
  }
}
```

#### 客户分页查询接口

**功能描述**：分页查询客户列表信息。

**接口详情**：
- **请求方式**：GET
- **请求路径**：`/admin-api/water/customer/page`

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|-------|------|------|------|------|
| pageNo | Integer | 否 | 页码，默认1 | 1 |
| pageSize | Integer | 否 | 每页条数，默认10 | 10 |
| customerName | String | 否 | 客户名称 | 张三 |
| customerCode | String | 否 | 客户编号 | C001 |
| customerType | String | 否 | 客户类型 | RESIDENT |
| phone | String | 否 | 联系电话 | 138 |

**响应参数**：
```json
{
  "code": 0,
  "msg": "操作成功",
  "data": {
    "list": [
      {
        "id": 1,
        "customerCode": "C001",
        "customerName": "张三",
        "customerType": "RESIDENT",
        "phone": "13800138000",
        "address": "福建省福州市台江区XX街道XX号",
        "status": 1,
        "createTime": "2024-12-19 10:00:00"
      }
    ],
    "total": 1
  }
}
```

#### 客户创建接口

**功能描述**：创建新客户记录。

**接口详情**：
- **请求方式**：POST
- **请求路径**：`/admin-api/water/customer/create`

**请求参数**：

```json
{
  "customerCode": "C002",
  "customerName": "李四",
  "customerType": "RESIDENT",
  "idType": "ID_CARD",
  "idNumber": "350103199001011234",
  "phone": "13900139000",
  "address": "福建省福州市鼓楼区XX街道XX号"
}
```

**响应参数**：
```json
{
  "code": 0,
  "msg": "操作成功",
  "data": 2
}
```

### 水表管理API接口

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

**功能描述**：根据水表ID查询水表详细信息。

**接口详情**：
- **请求方式**：GET
- **请求路径**：`/admin-api/water/meter/{id}`
- **请求头**：`Authorization: Bearer {token}`

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|-------|------|------|------|------|
| id | Long | 是 | 水表ID | 1 |

**响应参数**：
```json
{
  "code": 0,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "meterCode": "M001",
    "meterNo": "20241219001",
    "meterType": "SMART",
    "meterModel": "LXSY-15E",
    "meterCaliber": "15mm",
    "installDate": "2024-01-15",
    "installPosition": "1层水表井",
    "initialReading": 0.00,
    "currentReading": 156.32,
    "readingCycle": "MONTHLY",
    "meterStatus": 1,
    "customerId": 1,
    "customerName": "张三"
  }
}
```

#### 抄表记录创建接口

**功能描述**：创建新的抄表记录。

**接口详情**：
- **请求方式**：POST
- **请求路径**：`/admin-api/water/reading/create`

**请求参数**：

```json
{
  "meterId": 1,
  "readingDate": "2024-12-19",
  "readingValue": 156.32,
  "readingType": "MANUAL",
  "readerId": "R001",
  "photoUrl": "https://example.com/photos/reading001.jpg",
  "remark": "正常抄表"
}
```

**响应参数**：
```json
{
  "code": 0,
  "msg": "操作成功", 
  "data": 1
}
```

#### 抄表数据批量导入接口

**功能描述**：批量导入抄表数据，支持Excel文件上传。

**接口详情**：
- **请求方式**：POST
- **请求路径**：`/admin-api/water/reading/import`
- **Content-Type**：`multipart/form-data`

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|-------|------|------|------|------|
| file | MultipartFile | 是 | Excel文件 | reading_data.xlsx |
| updateSupport | Boolean | 否 | 是否更新已有数据 | false |

**响应参数**：
```json
{
  "code": 0,
  "msg": "操作成功",
  "data": {
    "successCount": 95,
    "failureCount": 5,
    "failureList": [
      {
        "lineNumber": 3,
        "meterCode": "M003", 
        "errorMsg": "水表不存在"
      }
    ]
  }
}
```

### 账单管理API接口

#### 账单查询接口

**功能描述**：根据客户ID和查询条件查询账单信息。

**接口详情**：
- **请求方式**：GET
- **请求路径**：`/admin-api/water/bill/page`

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|-------|------|------|------|------|
| pageNo | Integer | 否 | 页码，默认1 | 1 |
| pageSize | Integer | 否 | 每页条数，默认10 | 10 |
| customerId | Long | 否 | 客户ID | 1 |
| billMonth | String | 否 | 账期 | 2024-12 |
| billStatus | Integer | 否 | 账单状态 | 0 |

**响应参数**：
```json
{
  "code": 0,
  "msg": "操作成功",
  "data": {
    "list": [
      {
        "id": 1,
        "billCode": "B202412190001",
        "billMonth": "2024-12",
        "billDate": "2024-12-19",
        "waterUsage": 25.50,
        "waterFee": 76.50,
        "sewageFee": 15.30,
        "totalAmount": 91.80,
        "paidAmount": 0.00,
        "balanceAmount": 91.80,
        "dueDate": "2025-01-19",
        "billStatus": 0,
        "customerName": "张三",
        "meterCode": "M001"
      }
    ],
    "total": 1
  }
}
```

#### 账单生成接口

**功能描述**：根据抄表记录生成水费账单。

**接口详情**：
- **请求方式**：POST
- **请求路径**：`/admin-api/water/bill/generate`

**请求参数**：

```json
{
  "billMonth": "2024-12",
  "customerIds": [1, 2, 3],
  "readingIds": [1, 2, 3],
  "dueDate": "2025-01-19"
}
```

**响应参数**：
```json
{
  "code": 0,
  "msg": "操作成功",
  "data": {
    "generateCount": 3,
    "successList": [
      {
        "customerId": 1,
        "billId": 1,
        "totalAmount": 91.80
      }
    ],
    "failureList": []
  }
}
```

### 缴费管理API接口

#### 缴费处理接口

**功能描述**：处理客户缴费操作。

**接口详情**：
- **请求方式**：POST
- **请求路径**：`/admin-api/water/payment/create`

**请求参数**：

```json
{
  "customerId": 1,
  "billIds": [1, 2],
  "paymentType": "NORMAL",
  "paymentChannel": "CASH",
  "paymentAmount": 183.60,
  "actualAmount": 200.00,
  "operatorId": "OP001",
  "outletCode": "OUT001",
  "remark": "现金缴费"
}
```

**响应参数**：
```json
{
  "code": 0,
  "msg": "操作成功",
  "data": {
    "paymentId": 1,
    "paymentCode": "P202412190001",
    "changeAmount": 16.40,
    "invoiceNo": "INV20241219001"
  }
}
```

#### 在线支付接口

**功能描述**：处理在线支付（微信、支付宝等）。

**接口详情**：
- **请求方式**：POST
- **请求路径**：`/admin-api/water/payment/online-pay`

**请求参数**：

```json
{
  "customerId": 1,
  "billIds": [1],
  "paymentChannel": "WECHAT",
  "paymentAmount": 91.80,
  "returnUrl": "https://water.example.com/payment/callback",
  "notifyUrl": "https://water.example.com/api/payment/notify"
}
```

**响应参数**：
```json
{
  "code": 0,
  "msg": "操作成功",
  "data": {
    "paymentCode": "P202412190002",
    "prepayId": "wx20241219001234567890",
    "payUrl": "weixin://wxpay/bizpayurl?pr=abc123",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  }
}
```

### 工单接口

#### 工单创建接口

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

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

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

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

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

## 接口标准

### 接口协议

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

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

### 数据格式

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

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

### 接口安全设计

接口安全采用多层防护机制：

#### 认证机制

**JWT令牌认证**：
- 验证用户名密码
- 生成JWT Token
- 支持Token刷新机制
- 设置合理的过期时间

**API Key认证**（外部系统）：
- 验证API Key有效性
- 验证请求时间戳（防重放攻击）
- 验证请求签名完整性
- 记录访问日志

#### 数据加密

**敏感数据加密**：
- 个人信息字段AES加密存储
- 数据传输HTTPS加密
- 数据库连接SSL加密
- 密钥定期轮换机制

#### 访问控制

**IP白名单控制**：
- 外部接口限制IP访问
- 内部接口网络隔离
- 访问日志记录和监控
- 异常访问自动阻断

#### 接口限流

**基于Redis的令牌桶限流**：
- 按接口设置不同限流规则
- 支持按用户/IP限流
- 实时监控接口调用频率
- 超限自动熔断保护

### 错误处理机制

#### 统一异常处理

系统采用统一的异常处理机制，包括：
- 业务异常统一处理
- 参数校验异常处理
- 系统异常统一处理
- 异常日志记录和监控

#### 错误码定义

```markdown
# 错误码规范

## 通用错误码 (1-000-000-000)
- 0: 成功
- 400: 请求参数不正确
- 401: 账号未登录
- 403: 没有该操作权限
- 404: 请求未找到
- 405: 请求方法不正确
- 500: 系统异常

## 客户管理错误码 (1-001-000-000)
- 1_001_000_001: 客户不存在
- 1_001_000_002: 客户编号已存在
- 1_001_000_003: 客户状态不正确

## 水表管理错误码 (1-002-000-000)
- 1_002_000_001: 水表不存在
- 1_002_000_002: 水表编号已存在
- 1_002_000_003: 水表读数不正确

## 账单管理错误码 (1-003-000-000)
- 1_003_000_001: 账单不存在
- 1_003_000_002: 账单已缴费
- 1_003_000_003: 账单金额不正确

## 缴费管理错误码 (1-004-000-000)
- 1_004_000_001: 缴费失败
- 1_004_000_002: 缴费金额不足
- 1_004_000_003: 缴费渠道不可用
```

#### 接口调用示例

**成功响应示例**：
```json
{
  "code": 0,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "customerName": "张三"
  }
}
```

**失败响应示例**：
```json
{
  "code": 1001000001,
  "msg": "客户不存在",
  "data": null
}
```

### 前端接口调用规范

#### 接口封装标准

前端接口调用需要遵循以下规范：
- 统一的请求配置和响应处理
- 统一的错误处理和提示机制
- 统一的Loading状态管理
- 统一的数据类型定义

#### 组件使用规范

前端组件使用接口时需要：
- 合理的数据加载状态展示
- 完善的错误处理和用户提示
- 适当的数据缓存和优化
- 规范的分页和查询实现