476 lines
11 KiB
Markdown
476 lines
11 KiB
Markdown
# 福建水务营收系统接口设计
|
||
|
||
## 一、接口设计概述
|
||
|
||
福建水务营收系统采用RESTful风格设计API接口，通过HTTP协议提供服务。系统接口分为内部模块间接口和外部系统集成接口两大类，遵循统一的接口规范和安全策略。
|
||
|
||
## 二、接口设计原则
|
||
|
||
### 1. 设计原则
|
||
|
||
- **RESTful风格**: 接口遵循REST架构风格
|
||
- **版本控制**: 在URL中包含版本信息
|
||
- **统一响应**: 统一的响应格式和状态码
|
||
- **参数校验**: 严格的参数校验确保数据有效性
|
||
- **权限控制**: 基于JWT和RBAC的接口权限控制
|
||
- **幂等性**: 确保关键操作的幂等性
|
||
- **文档完善**: 详细的接口文档说明
|
||
|
||
### 2. 接口地址规范
|
||
|
||
```
|
||
https://{domain}/api/v{version}/{module}/{resource}/{action}
|
||
```
|
||
|
||
- **domain**: 系统域名
|
||
- **version**: 接口版本号，如v1
|
||
- **module**: 功能模块，如user、meter
|
||
- **resource**: 资源名称，通常为复数形式
|
||
- **action**: 可选的操作名称
|
||
|
||
### 3. 响应格式规范
|
||
|
||
所有接口统一返回JSON格式数据，基本结构如下：
|
||
|
||
```json
|
||
{
|
||
"code": 0, // 状态码，0表示成功，非0表示失败
|
||
"msg": "success", // 状态描述
|
||
"data": { // 响应数据，可能是对象、数组或null
|
||
// 具体的业务数据
|
||
},
|
||
"timestamp": 1621234567890 // 响应时间戳
|
||
}
|
||
```
|
||
|
||
### 4. 状态码规范
|
||
|
||
| 状态码 | 说明 |
|
||
|-------|------|
|
||
| 0 | 成功 |
|
||
| 1000-1999 | 用户认证相关错误 |
|
||
| 2000-2999 | 权限相关错误 |
|
||
| 3000-3999 | 参数相关错误 |
|
||
| 4000-4999 | 业务相关错误 |
|
||
| 5000-5999 | 系统内部错误 |
|
||
|
||
## 三、内部模块接口
|
||
|
||
### 1. 用户认证模块接口
|
||
|
||
#### 1.1 用户登录
|
||
|
||
- **接口地址**: `/api/v1/auth/login`
|
||
- **请求方式**: POST
|
||
- **接口描述**: 用户登录认证接口
|
||
- **请求参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 说明 |
|
||
|-------|------|---------|-----|
|
||
| username | String | 是 | 用户名 |
|
||
| password | String | 是 | 密码 |
|
||
| captcha | String | 否 | 验证码 |
|
||
| captchaId | String | 否 | 验证码ID |
|
||
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"expireTime": 1621234567890,
|
||
"userInfo": {
|
||
"userId": 1,
|
||
"username": "admin",
|
||
"nickname": "管理员",
|
||
"avatar": "https://example.com/avatar.jpg",
|
||
"permissions": ["sys:user:list", "sys:user:create"]
|
||
}
|
||
},
|
||
"timestamp": 1621234567890
|
||
}
|
||
```
|
||
|
||
#### 1.2 刷新令牌
|
||
|
||
- **接口地址**: `/api/v1/auth/refresh-token`
|
||
- **请求方式**: POST
|
||
- **接口描述**: 刷新访问令牌
|
||
- **请求参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 说明 |
|
||
|-------|------|---------|-----|
|
||
| refreshToken | String | 是 | 刷新令牌 |
|
||
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"expireTime": 1621234567890
|
||
},
|
||
"timestamp": 1621234567890
|
||
}
|
||
```
|
||
|
||
### 2. 水表管理模块接口
|
||
|
||
#### 2.1 水表列表查询
|
||
|
||
- **接口地址**: `/api/v1/meter/meters`
|
||
- **请求方式**: GET
|
||
- **接口描述**: 查询水表信息列表
|
||
- **请求参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 说明 |
|
||
|-------|------|---------|-----|
|
||
| customerId | Long | 否 | 客户ID |
|
||
| meterNo | String | 否 | 水表编号 |
|
||
| meterType | Integer | 否 | 水表类型 |
|
||
| status | Integer | 否 | 水表状态 |
|
||
| pageNo | Integer | 否 | 页码，默认1 |
|
||
| pageSize | Integer | 否 | 每页记录数，默认10 |
|
||
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"total": 100,
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"meterNo": "M20230001",
|
||
"customerName": "张三",
|
||
"meterType": 1,
|
||
"meterTypeName": "普通水表",
|
||
"installAddress": "福建省福州市台江区",
|
||
"currentReading": 120.5,
|
||
"status": 0,
|
||
"statusName": "正常"
|
||
}
|
||
],
|
||
"pageNum": 1,
|
||
"pageSize": 10,
|
||
"totalPages": 10
|
||
},
|
||
"timestamp": 1621234567890
|
||
}
|
||
```
|
||
|
||
#### 2.2 水表详情查询
|
||
|
||
- **接口地址**: `/api/v1/meter/meters/{id}`
|
||
- **请求方式**: GET
|
||
- **接口描述**: 查询水表详细信息
|
||
- **路径参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 说明 |
|
||
|-------|------|---------|-----|
|
||
| id | Long | 是 | 水表ID |
|
||
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"meterNo": "M20230001",
|
||
"customerId": 1,
|
||
"customerName": "张三",
|
||
"meterType": 1,
|
||
"meterTypeName": "普通水表",
|
||
"caliber": "DN20",
|
||
"installDate": "2023-01-15",
|
||
"initialReading": 0,
|
||
"currentReading": 120.5,
|
||
"installAddress": "福建省福州市台江区",
|
||
"status": 0,
|
||
"statusName": "正常",
|
||
"readingCycle": 1,
|
||
"readingCycleName": "月",
|
||
"description": "安装在一楼进水口",
|
||
"createTime": "2023-01-15 10:00:00",
|
||
"updateTime": "2023-05-10 15:30:00"
|
||
},
|
||
"timestamp": 1621234567890
|
||
}
|
||
```
|
||
|
||
### 3. 抄表管理模块接口
|
||
|
||
#### 3.1 提交抄表数据
|
||
|
||
- **接口地址**: `/api/v1/reading/meter-readings`
|
||
- **请求方式**: POST
|
||
- **接口描述**: 提交水表读数
|
||
- **请求参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 说明 |
|
||
|-------|------|---------|-----|
|
||
| meterId | Long | 是 | 水表ID |
|
||
| reading | Decimal | 是 | 本次读数 |
|
||
| readingDate | Date | 是 | 抄表日期 |
|
||
| readingType | Integer | 是 | 抄表类型(1人工,2远传,3用户自报) |
|
||
| photoUrl | String | 否 | 水表照片URL |
|
||
| remark | String | 否 | 备注 |
|
||
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"meterId": 1,
|
||
"meterNo": "M20230001",
|
||
"readingDate": "2023-05-10",
|
||
"reading": 120.5,
|
||
"lastReading": 100.0,
|
||
"waterUsage": 20.5,
|
||
"readingType": 1,
|
||
"readingTypeName": "人工抄表",
|
||
"status": 0,
|
||
"statusName": "正常"
|
||
},
|
||
"timestamp": 1621234567890
|
||
}
|
||
```
|
||
|
||
### 4. 收费管理模块接口
|
||
|
||
#### 4.1 生成水费账单
|
||
|
||
- **接口地址**: `/api/v1/billing/generate-bills`
|
||
- **请求方式**: POST
|
||
- **接口描述**: 根据抄表数据生成水费账单
|
||
- **请求参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 说明 |
|
||
|-------|------|---------|-----|
|
||
| meterReadingIds | Array | 是 | 抄表记录ID数组 |
|
||
| billingPeriod | String | 是 | 账单周期(yyyyMM) |
|
||
| dueDate | Date | 是 | 缴费截止日期 |
|
||
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"successCount": 10,
|
||
"failCount": 0,
|
||
"billIds": [1, 2, 3]
|
||
},
|
||
"timestamp": 1621234567890
|
||
}
|
||
```
|
||
|
||
#### 4.2 缴费处理
|
||
|
||
- **接口地址**: `/api/v1/payment/payments`
|
||
- **请求方式**: POST
|
||
- **接口描述**: 处理用户缴费
|
||
- **请求参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 说明 |
|
||
|-------|------|---------|-----|
|
||
| billId | Long | 是 | 账单ID |
|
||
| paymentAmount | Decimal | 是 | 支付金额 |
|
||
| paymentMethod | Integer | 是 | 支付方式(1现金,2银行卡,3微信,4支付宝) |
|
||
| paymentDate | Date | 是 | 支付日期 |
|
||
| transactionNo | String | 否 | 交易流水号 |
|
||
| remark | String | 否 | 备注 |
|
||
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"billId": 1,
|
||
"billNo": "B20230510001",
|
||
"customerName": "张三",
|
||
"paymentAmount": 100.0,
|
||
"paymentMethod": 1,
|
||
"paymentMethodName": "现金",
|
||
"paymentDate": "2023-05-10",
|
||
"receiptNo": "R20230510001"
|
||
},
|
||
"timestamp": 1621234567890
|
||
}
|
||
```
|
||
|
||
## 四、外部系统接口
|
||
|
||
### 1. 银行支付接口
|
||
|
||
#### 1.1 银行代扣申请
|
||
|
||
- **接口地址**: `/api/v1/external/bank/deduction`
|
||
- **请求方式**: POST
|
||
- **接口描述**: 向银行发起代扣申请
|
||
- **请求参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 说明 |
|
||
|-------|------|---------|-----|
|
||
| bankCode | String | 是 | 银行代码 |
|
||
| billIds | Array | 是 | 账单ID数组 |
|
||
| batchNo | String | 是 | 批次号 |
|
||
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"batchNo": "BK20230510001",
|
||
"totalAmount": 1000.0,
|
||
"totalCount": 10,
|
||
"requestTime": "2023-05-10 10:00:00",
|
||
"status": "PROCESSING"
|
||
},
|
||
"timestamp": 1621234567890
|
||
}
|
||
```
|
||
|
||
### 2. 微信支付接口
|
||
|
||
#### 2.1 发起微信支付
|
||
|
||
- **接口地址**: `/api/v1/external/wechat/create-order`
|
||
- **请求方式**: POST
|
||
- **接口描述**: 创建微信支付订单
|
||
- **请求参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 说明 |
|
||
|-------|------|---------|-----|
|
||
| billId | Long | 是 | 账单ID |
|
||
| openId | String | 是 | 用户微信openId |
|
||
| amount | Decimal | 是 | 支付金额 |
|
||
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"prepayId": "wx2023051010000000000000000000",
|
||
"nonceStr": "ibuaiVcKdpRxkhJA",
|
||
"timeStamp": "1621234567",
|
||
"signType": "MD5",
|
||
"paySign": "70EA570631E4BB79628FBCA90534C63FF7FADD89"
|
||
},
|
||
"timestamp": 1621234567890
|
||
}
|
||
```
|
||
|
||
### 3. 短信通知接口
|
||
|
||
#### 3.1 发送短信通知
|
||
|
||
- **接口地址**: `/api/v1/external/sms/send`
|
||
- **请求方式**: POST
|
||
- **接口描述**: 发送短信通知
|
||
- **请求参数**:
|
||
|
||
| 参数名 | 类型 | 是否必填 | 说明 |
|
||
|-------|------|---------|-----|
|
||
| phone | String | 是 | 手机号 |
|
||
| templateId | String | 是 | 短信模板ID |
|
||
| params | Object | 是 | 短信参数 |
|
||
|
||
- **响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"messageId": "SMS20230510001",
|
||
"sendTime": "2023-05-10 10:00:00",
|
||
"status": "SENT"
|
||
},
|
||
"timestamp": 1621234567890
|
||
}
|
||
```
|
||
|
||
## 五、接口安全设计
|
||
|
||
### 1. 认证机制
|
||
|
||
- **JWT认证**: 使用JWT进行接口认证，访问需要权限的接口时必须在请求头中携带有效的Token
|
||
- **Token刷新**: 提供Token刷新机制，避免频繁登录
|
||
- **多端登录控制**: 支持控制同一账号多端登录策略
|
||
|
||
### 2. 权限控制
|
||
|
||
- **RBAC权限模型**: 基于角色的权限控制，精细化权限管理
|
||
- **接口权限**: 每个接口绑定权限标识，通过注解方式声明
|
||
- **数据权限**: 支持部门级、用户级数据权限控制
|
||
|
||
### 3. 安全防护
|
||
|
||
- **参数验证**: 严格校验请求参数，防止非法参数
|
||
- **SQL注入防护**: 使用参数绑定方式防止SQL注入
|
||
- **XSS防护**: 过滤请求参数中的恶意脚本
|
||
- **CSRF防护**: 使用Token验证防止CSRF攻击
|
||
- **接口限流**: 对关键接口实施限流措施，防止恶意攻击
|
||
- **日志追踪**: 记录接口调用日志，便于安全审计
|
||
|
||
## 六、接口测试策略
|
||
|
||
### 1. 单元测试
|
||
|
||
- 编写接口单元测试，验证接口功能正确性
|
||
- 使用MockMVC进行Controller层测试
|
||
- 使用Mock框架模拟外部依赖
|
||
|
||
### 2. 集成测试
|
||
|
||
- 编写接口集成测试，验证接口与其他组件的交互
|
||
- 使用测试容器进行数据库测试
|
||
- 测试完整业务流程
|
||
|
||
### 3. 性能测试
|
||
|
||
- 使用JMeter等工具进行接口性能测试
|
||
- 测试接口响应时间
|
||
- 测试接口并发处理能力
|
||
- 测试系统在高负载下的稳定性
|
||
|
||
## 七、接口文档管理
|
||
|
||
### 1. 文档生成
|
||
|
||
- 使用Swagger/Knife4j自动生成接口文档
|
||
- 通过API注解提供详细的接口说明
|
||
- 支持在线调试接口
|
||
|
||
### 2. 版本管理
|
||
|
||
- 明确的接口版本控制策略
|
||
- 接口变更记录
|
||
- 兼容性说明
|
||
|
||
### 3. 文档发布
|
||
|
||
- 提供在线接口文档站点
|
||
- 支持导出PDF、HTML等格式
|
||
- 权限控制，限制文档访问范围 |