tangweijie/fujian_water_biz_doc

Fork 0

tangweijie 60a217da4f 初始化提交：添加福建水务业务系统初步设计文档

2025-05-08 15:07:03 +08:00

11 KiB

Raw Blame History

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

一、接口设计概述

福建水务营收系统采用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格式数据，基本结构如下：

{
  "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

响应示例:

{
  "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	是	刷新令牌

响应示例:

{
  "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

响应示例:

{
  "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

响应示例:

{
  "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	否	备注

响应示例:

{
  "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	是	缴费截止日期

响应示例:

{
  "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	否	备注

响应示例:

{
  "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	是	批次号

响应示例:

{
  "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	是	支付金额

响应示例:

{
  "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	是	短信参数

响应示例:

{
  "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等格式
权限控制，限制文档访问范围

11 KiB Raw Blame History Unescape Escape

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

一、接口设计概述

二、接口设计原则

1. 设计原则

2. 接口地址规范

3. 响应格式规范

4. 状态码规范

三、内部模块接口

1. 用户认证模块接口

1.1 用户登录

1.2 刷新令牌

2. 水表管理模块接口

2.1 水表列表查询

2.2 水表详情查询

3. 抄表管理模块接口

3.1 提交抄表数据

4. 收费管理模块接口

4.1 生成水费账单

4.2 缴费处理

四、外部系统接口

1. 银行支付接口

1.1 银行代扣申请

2. 微信支付接口

2.1 发起微信支付

3. 短信通知接口

3.1 发送短信通知

五、接口安全设计

1. 认证机制

2. 权限控制

3. 安全防护

六、接口测试策略

1. 单元测试

2. 集成测试

3. 性能测试

七、接口文档管理

1. 文档生成

2. 版本管理

3. 文档发布

11 KiB

Raw Blame History