tangweijie/fujian_water_biz_doc

Fork 0

tangweijie f8b75f7771 docs: import bank api archive and openapi tooling

2026-03-27 10:12:47 +08:00

18 KiB

Raw Blame History

营收系统接口规范设计文档

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 请求头设计

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 错误响应格式

<out>
    <Version>1.0.1</Version>
    <InstId>00001</InstId>
    <TranCode>QueryRes</TranCode>
    <TranDate>20240101</TranDate>
    <TranSeq>123456789012</TranSeq>
    <RespCode>DEF0001</RespCode>
    <RespMessage>无相应记录</RespMessage>
    <ErrorDetail>
        <ErrorCode>DEF0001</ErrorCode>
        <ErrorMsg>用户编号123456不存在</ErrorMsg>
        <ErrorTime>2024-01-01 12:00:00</ErrorTime>
    </ErrorDetail>
</out>

4. 数据模型设计

4.1 核心实体模型

4.1.1 用户实体 (Customer)

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)

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)

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)

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 核心逻辑

@Service
public class BillQueryService {
    
    public QueryResponse queryBill(QueryRequest request) {
        // 1. 参数校验
        validateRequest(request);
        
        // 2. 业务逻辑处理
        List<Bill> 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 事务处理

@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 缓存策略

@Service
public class BillQueryService {
    
    @Cacheable(value = "billCache", key = "#billKey + '_' + #companyId")
    public List<Bill> 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配置

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配置

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 查询接口测试用例

@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 审计日志格式

{
    "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. 总结

本规范设计文档为营收系统接口的设计、开发、测试、部署和运维提供了全面的指导。通过遵循这些规范，可以确保系统的：

可靠性：通过完善的错误处理和事务管理
安全性：通过多层次的安全控制措施
性能：通过合理的架构设计和优化策略
可维护性：通过标准化的代码和文档规范
可扩展性：通过模块化和微服务架构设计

建议在实际项目中根据具体需求对本规范进行适当调整和完善。

18 KiB Raw Blame History Unescape Escape