# 营收系统接口规范设计文档
## 1. 文档概述
### 1.1 文档信息
- **文档名称**：营收系统接口规范设计文档
- **版本**：1.0
- **编写日期**：2024年12月
- **基于原始文档**：营收系统缴费接口 v1.5
### 1.2 设计目标
本文档旨在为营收系统与银行/第三方支付机构之间的接口交互提供标准化、规范化的设计指导，确保系统的高可用性、安全性和可扩展性。
### 1.3 适用范围
- 公用事业单位（水司、电力等）
- 银行机构
- 第三方支付平台
- 系统集成商
## 2. 系统架构设计
### 2.1 整体架构
```
┌─────────────────┐ HTTP/HTTPS ┌─────────────────┐
│ │<──────────────────>│ │
│ 银行/支付平台 │ │ 营收系统 │
│ │ │ │
└─────────────────┘ └─────────────────┘
│ │
│ │
v v
┌─────────────────┐ ┌─────────────────┐
│ 对账文件处理 │ │ 业务数据库 │
└─────────────────┘ └─────────────────┘
```
### 2.2 接口分层设计
```
┌─────────────────────────────────────────────────────────┐
│ 表示层 (Presentation Layer) │
│ HTTP/HTTPS + XML/JSON │
├─────────────────────────────────────────────────────────┤
│ 业务层 (Business Layer) │
│ 查询服务 | 缴费服务 | 代扣服务 | 对账服务 │
├─────────────────────────────────────────────────────────┤
│ 数据层 (Data Layer) │
│ 用户数据 | 账单数据 | 交易数据 │
└─────────────────────────────────────────────────────────┘
```
## 3. 接口设计规范
### 3.1 RESTful设计原则
虽然原系统使用XML格式，但建议遵循RESTful设计原则：
| 功能模块 | HTTP方法 | 资源路径 | 描述 |
|----------|----------|----------|------|
| 账单查询 | POST | `/api/app/billQuery/query` | 查询用户账单 |
| 账单缴费 | POST | `/api/app/billPay/pay` | 执行缴费操作 |
| 账单红冲 | POST | `/api/app/payInvalid/payInvalid` | 红冲已缴费账单 |
| 代扣签约 | POST | `/api/app/bankWithholding/signing` | 代扣签约 |
| 代扣解约 | POST | `/api/app/bankWithholding/termination` | 代扣解约 |
| 代扣送盘 | POST | `/api/app/bankWithholding/sendDisc` | 代扣送盘 |
| 代扣回盘 | POST | `/api/app/bankWithholding/backDisc` | 代扣回盘 |
### 3.2 数据格式规范
#### 3.2.1 请求格式
- **内容类型**：`application/xml` 或 `application/json`
- **字符编码**：GBK（XML）或 UTF-8（JSON）
- **请求方法**：POST
#### 3.2.2 响应格式
- **状态码**：200 OK（业务成功/失败通过返回码区分）
- **内容类型**：与请求格式保持一致
- **响应结构**：统一的响应格式
### 3.3 安全设计规范
#### 3.3.1 加密策略
```
┌─────────────────┐ 加密传输 ┌─────────────────┐
│ 客户端 │ ──────────────> │ 服务端 │
│ │ │ │
│ 1. 数据加密 │ │ 1. 数据解密 │
│ 2. Base64编码 │ │ 2. Base64解码 │
│ 3. HTTP传输 │ │ 3. 业务处理 │
└─────────────────┘ └─────────────────┘
```
#### 3.3.2 支持的加密算法
| 加密类型 | 加密模式 | 填充方式 | 安全等级 |
|----------|----------|----------|----------|
| 3DES | ECB | PKCS7 | 中等 |
| SM2 | C1C3C2/C1C2C3 | - | 高 |
| SM4 | ECB/CBC | PKCS7 | 高 |
#### 3.3.3 请求头设计
```http
Content-Type: application/xml; charset=GBK
EncryptType: 3DES
EncryptMode: ECB
DataType: XML
```
### 3.4 错误处理规范
#### 3.4.1 统一错误码设计
```
AAAAAAA: 成功
DEF0xxx: 业务错误 (0001-0999)
SYS1xxx: 系统错误 (1000-1999)
SEC2xxx: 安全错误 (2000-2999)
NET3xxx: 网络错误 (3000-3999)
```
#### 3.4.2 错误响应格式
```xml
1.0.1
00001
QueryRes
20240101
123456789012
DEF0001
无相应记录
DEF0001
用户编号123456不存在
2024-01-01 12:00:00
```
## 4. 数据模型设计
### 4.1 核心实体模型
#### 4.1.1 用户实体 (Customer)
```sql
CREATE TABLE customer (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
bill_key VARCHAR(35) NOT NULL UNIQUE COMMENT '客户编号',
customer_name VARCHAR(150) NOT NULL COMMENT '客户姓名',
contract_no VARCHAR(30) COMMENT '合同号',
company_id VARCHAR(30) NOT NULL COMMENT '机构编码',
created_time DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_bill_key (bill_key),
INDEX idx_company_id (company_id)
);
```
#### 4.1.2 账单实体 (Bill)
```sql
CREATE TABLE bill (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
bill_key VARCHAR(35) NOT NULL COMMENT '客户编号',
company_id VARCHAR(30) NOT NULL COMMENT '机构编码',
pay_amount DECIMAL(16,2) NOT NULL COMMENT '缴费金额',
balance DECIMAL(16,2) DEFAULT 0.00 COMMENT '余额',
begin_date DATE COMMENT '账单开始日期',
end_date DATE COMMENT '账单结束日期',
bill_status TINYINT DEFAULT 0 COMMENT '账单状态 0:未缴费 1:已缴费',
created_time DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_bill_key (bill_key),
INDEX idx_company_id (company_id),
INDEX idx_status (bill_status)
);
```
#### 4.1.3 交易记录 (Transaction)
```sql
CREATE TABLE transaction (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
tran_seq VARCHAR(40) NOT NULL UNIQUE COMMENT '交易流水号',
bill_key VARCHAR(35) NOT NULL COMMENT '客户编号',
company_id VARCHAR(30) NOT NULL COMMENT '机构编码',
tran_code VARCHAR(20) NOT NULL COMMENT '交易码',
pay_amount DECIMAL(16,2) NOT NULL COMMENT '交易金额',
pay_date DATETIME NOT NULL COMMENT '交易时间',
sub_channel TINYINT COMMENT '二级渠道 1:支付宝 2:微信 6:其它',
tran_status TINYINT DEFAULT 0 COMMENT '交易状态 0:处理中 1:成功 2:失败',
resp_code VARCHAR(7) COMMENT '返回码',
resp_message VARCHAR(60) COMMENT '返回消息',
created_time DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_tran_seq (tran_seq),
INDEX idx_bill_key (bill_key),
INDEX idx_pay_date (pay_date),
INDEX idx_status (tran_status)
);
```
### 4.2 代扣相关实体
#### 4.2.1 代扣协议 (WithholdingAgreement)
```sql
CREATE TABLE withholding_agreement (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
bill_key VARCHAR(35) NOT NULL COMMENT '客户编号',
company_id VARCHAR(30) NOT NULL COMMENT '机构编码',
account_name VARCHAR(150) NOT NULL COMMENT '开户名',
account_no VARCHAR(30) NOT NULL COMMENT '开户账号',
bank_name VARCHAR(150) COMMENT '银行名称',
contract_no VARCHAR(150) COMMENT '合同号',
agreement_no VARCHAR(150) COMMENT '协议号',
bank_type TINYINT COMMENT '银行类型 0:本行 1:他行',
agreement_status TINYINT DEFAULT 0 COMMENT '协议状态 0:未签约 1:已签约 2:已解约',
signing_date DATE COMMENT '签约日期',
termination_date DATE COMMENT '解约日期',
created_time DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_bill_key (bill_key),
INDEX idx_account_no (account_no),
INDEX idx_status (agreement_status)
);
```
## 5. 接口实现规范
### 5.1 查询接口实现
#### 5.1.1 业务流程
```
Client Request → Parameter Validation → Business Logic → Data Query → Response Format → Client Response
```
#### 5.1.2 核心逻辑
```java
@Service
public class BillQueryService {
public QueryResponse queryBill(QueryRequest request) {
// 1. 参数校验
validateRequest(request);
// 2. 业务逻辑处理
List bills = billRepository.findByBillKeyAndCompanyId(
request.getBillKey(),
request.getCompanyId()
);
// 3. 构造响应
return buildQueryResponse(bills);
}
private void validateRequest(QueryRequest request) {
if (StringUtils.isEmpty(request.getBillKey())) {
throw new BusinessException("DEF0001", "客户编号不能为空");
}
// 其他校验逻辑...
}
}
```
### 5.2 缴费接口实现
#### 5.2.1 业务流程
```
Client Request → Parameter Validation → Balance Check → Payment Processing → Transaction Record → Response
```
#### 5.2.2 事务处理
```java
@Service
@Transactional
public class BillPayService {
public PayResponse payBill(PayRequest request) {
// 1. 参数校验
validatePayRequest(request);
// 2. 账单查询
Bill bill = billRepository.findByBillKeyAndCompanyId(
request.getBillKey(),
request.getCompanyId()
);
// 3. 金额校验
if (bill.getPayAmount().compareTo(request.getPayAmount()) != 0) {
throw new BusinessException("DEF0002", "缴费金额不匹配");
}
// 4. 更新账单状态
bill.setBillStatus(1);
billRepository.save(bill);
// 5. 记录交易
Transaction transaction = createTransaction(request);
transactionRepository.save(transaction);
// 6. 构造响应
return buildPayResponse(request);
}
}
```
## 6. 性能设计规范
### 6.1 性能指标
| 指标类型 | 要求 | 说明 |
|----------|------|------|
| 响应时间 | < 3秒 | 95%的请求在3秒内响应 |
| 并发量 | 1000 TPS | 支持1000笔/秒的交易处理 |
| 可用性 | 99.9% | 年度可用性不低于99.9% |
| 错误率 | < 0.1% | 系统错误率控制在0.1%以内 |
### 6.2 缓存策略
```java
@Service
public class BillQueryService {
@Cacheable(value = "billCache", key = "#billKey + '_' + #companyId")
public List queryBillWithCache(String billKey, String companyId) {
return billRepository.findByBillKeyAndCompanyId(billKey, companyId);
}
}
```
### 6.3 数据库优化
#### 6.3.1 索引设计
- 主要查询字段建立索引
- 复合索引优化多条件查询
- 定期分析索引使用情况
#### 6.3.2 分表策略
- 按时间分表：每月一张交易表
- 按机构分库：不同机构使用不同数据库
## 7. 监控与日志规范
### 7.1 日志规范
#### 7.1.1 日志级别
- ERROR: 系统错误，需要立即处理
- WARN: 业务警告，需要关注
- INFO: 关键业务流程记录
- DEBUG: 调试信息
#### 7.1.2 日志格式
```
[时间戳] [日志级别] [线程名] [类名] [方法名] - [交易流水号] [业务描述] [详细信息]
```
示例：
```
2024-01-01 12:00:00.123 [INFO] [http-thread-1] [BillQueryService] [queryBill] - [TXN123456789012] 查询账单开始 {"billKey":"123456","companyId":"654321"}
```
### 7.2 监控指标
#### 7.2.1 业务监控
- 交易成功率
- 平均响应时间
- 接口调用量
- 错误码分布
#### 7.2.2 系统监控
- CPU使用率
- 内存使用率
- 数据库连接数
- 网络IO
## 8. 部署架构规范
### 8.1 生产环境架构
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 负载均衡器 │────>│ Web服务器1 │ │ 数据库主库 │
│ (Nginx/F5) │ │ (Tomcat) │────>│ (MySQL) │
│ │ └─────────────────┘ │ │
│ │ ┌─────────────────┐ └─────────────────┘
│ │────>│ Web服务器2 │ ┌─────────────────┐
└─────────────────┘ │ (Tomcat) │────>│ 数据库从库 │
└─────────────────┘ │ (MySQL) │
└─────────────────┘
```
### 8.2 容器化部署
#### 8.2.1 Docker配置
```dockerfile
FROM openjdk:8-jre-alpine
VOLUME /tmp
ADD app.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java","-Djava.security.egd=file:/dev/./urandom","-jar","/app.jar"]
```
#### 8.2.2 Kubernetes配置
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: billing-api
spec:
replicas: 3
selector:
matchLabels:
app: billing-api
template:
metadata:
labels:
app: billing-api
spec:
containers:
- name: billing-api
image: billing-api:latest
ports:
- containerPort: 8080
resources:
requests:
memory: "512Mi"
cpu: "500m"
limits:
memory: "1Gi"
cpu: "1"
```
## 9. 测试规范
### 9.1 测试策略
#### 9.1.1 单元测试
- 覆盖率 >= 80%
- 核心业务逻辑 100% 覆盖
- Mock 外部依赖
#### 9.1.2 集成测试
- 接口层面的集成测试
- 数据库集成测试
- 第三方服务集成测试
#### 9.1.3 性能测试
- 压力测试：测试系统极限
- 负载测试：测试正常负载下的性能
- 稳定性测试：长时间运行测试
### 9.2 测试用例设计
#### 9.2.1 查询接口测试用例
```java
@Test
public void testQueryBill_Success() {
// Given
QueryRequest request = new QueryRequest();
request.setBillKey("123456");
request.setCompanyId("654321");
// When
QueryResponse response = billQueryService.queryBill(request);
// Then
assertEquals("AAAAAAA", response.getRespCode());
assertNotNull(response.getData());
}
@Test
public void testQueryBill_NotFound() {
// Given
QueryRequest request = new QueryRequest();
request.setBillKey("999999");
request.setCompanyId("654321");
// When & Then
BusinessException exception = assertThrows(
BusinessException.class,
() -> billQueryService.queryBill(request)
);
assertEquals("DEF0001", exception.getCode());
}
```
## 10. 安全审计规范
### 10.1 安全审计要求
#### 10.1.1 审计内容
- 所有接口调用记录
- 敏感操作日志
- 异常访问记录
- 系统配置变更
#### 10.1.2 审计日志格式
```json
{
"timestamp": "2024-01-01T12:00:00.123Z",
"event_type": "API_CALL",
"user_id": "bank_001",
"ip_address": "192.168.1.100",
"endpoint": "/api/app/billQuery/query",
"request_id": "TXN123456789012",
"response_code": "AAAAAAA",
"execution_time": 1500,
"data_accessed": {
"bill_key": "123456",
"company_id": "654321"
}
}
```
### 10.2 安全控制措施
#### 10.2.1 访问控制
- IP白名单机制
- API密钥认证
- 请求频率限制
#### 10.2.2 数据保护
- 敏感数据加密存储
- 传输过程加密
- 数据脱敏处理
## 11. 运维规范
### 11.1 发布流程
```
开发环境 → 测试环境 → 预生产环境 → 生产环境
↓ ↓ ↓ ↓
单元测试 集成测试 性能测试 灰度发布
```
### 11.2 回滚策略
#### 11.2.1 快速回滚
- 保留前一版本的部署包
- 数据库版本管理
- 配置文件版本控制
#### 11.2.2 回滚触发条件
- 系统错误率超过阈值
- 响应时间超过预期
- 业务功能异常
## 12. 总结
本规范设计文档为营收系统接口的设计、开发、测试、部署和运维提供了全面的指导。通过遵循这些规范，可以确保系统的：
1. **可靠性**：通过完善的错误处理和事务管理
2. **安全性**：通过多层次的安全控制措施
3. **性能**：通过合理的架构设计和优化策略
4. **可维护性**：通过标准化的代码和文档规范
5. **可扩展性**：通过模块化和微服务架构设计
建议在实际项目中根据具体需求对本规范进行适当调整和完善。