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

## 一、接口设计概述

福建水务营收系统采用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等格式
- 权限控制，限制文档访问范围