839 lines
19 KiB
Markdown
839 lines
19 KiB
Markdown
# 福建水务营收系统接口设计文档
|
||
|
||
## 文档信息
|
||
| 项目信息 | 详情 |
|
||
|---------|------|
|
||
| **项目名称** | 福建水务营收系统 |
|
||
| **文档类型** | 概要设计文档 |
|
||
| **技术框架** | 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状态管理
|
||
- 统一的数据类型定义
|
||
|
||
#### 组件使用规范
|
||
|
||
前端组件使用接口时需要：
|
||
- 合理的数据加载状态展示
|
||
- 完善的错误处理和用户提示
|
||
- 适当的数据缓存和优化
|
||
- 规范的分页和查询实现 |