HospitalPay-Go/docs/API接口文档.md

HospitalPay-Go Socket 服务器接口文档

1. 概述

HospitalPay-Go Socket 服务器是一个基于TCP协议的医院支付系统服务器，提供病人入院、出院、消费记录、余额查询等功能。

1.1 服务器信息

• 协议: TCP Socket
• 端口: 配置文件中指定
• 编码: UTF-8
• 数据格式: JSON

1.2 消息格式

所有请求和响应都遵循以下格式：

[长度(4位)][功能码(4位)][医院编码(4位)][时间戳(19位)][JSON数据]

• 长度: 4位数字，表示整个消息的长度
• 功能码: 4位数字，标识请求的功能类型
• 医院编码: 4位字符，医院标识码
• 时间戳: 19位时间戳，格式为 yyyy-MM-dd HH:mm:ss
• JSON数据: 具体的请求或响应数据

1.3 响应格式

所有响应都包含以下基础结构：

{
    "ResultCode": "string",    // 结果代码
    "ResultData": object,      // 响应数据（可选）
    "ResultMsg": "string"      // 结果消息（可选）
}

2. 错误码说明

错误码	说明
0000	成功
0005	未找到病人信息
0006	入院处理失败
0007	病人已入院
0008	系统异常
0009	请求参数错误
1001	出院处理失败
1002	消费额度查询失败
1003	消费记录保存失败
1004	实时余额查询失败
1005	发票同步失败

3. 接口详情

3.1 入院登记

功能码: 0001

功能说明: 病人入院时的登记处理

请求参数:

{
    "FCode": "string"  // 病人编号，必填
}

响应参数:

{
    "ResultCode": "0000",
    "ResultData": {
        "FCode": "string",      // 病人编号
        "FName": "string",      // 病人姓名
        "AmountA": 100.00,      // A类金额
        "AmountB": 50.00,       // B类金额
        "AmountC": 150.00,      // C类金额
        "BankAccNo": "string",  // 银行账号
        "BankAmount": 1000.00,  // 银行余额
        "Fflag": 0,             // 状态标志 (0:正常, 1:已入院)
        "Flimitflag": 0,        // 限制标志
        "Flimitamt": 0.00       // 限制金额
    }
}

示例:

请求: 0001{"FCode":"3516022343"}
响应: {"ResultCode":"0000","ResultData":{"FCode":"3516022343","FName":"测试病人","AmountA":100.00,"AmountB":50.00,"AmountC":150.00,"BankAccNo":"6222021234567890","BankAmount":1000.00,"Fflag":0,"Flimitflag":0,"Flimitamt":0}}

3.2 消费额度查询

功能码: 0002

功能说明: 查询病人当月消费额度信息

请求参数:

{
    "FCode": "string"  // 病人编号，必填
}

响应参数:

{
    "ResultCode": "0000",
    "ResultData": {
        "AmountA": 50.00,       // A类消费金额
        "AmountB": 30.00,       // B类消费金额
        "FreeAmountA": 0.00,    // A类可用金额
        "FreeAmountB": 0.00,    // B类可用金额
        "Checkflag": 0,         // 检查标志
        "FCode": "string",      // 病人编号
        "FCriminal": "string",  // 病人姓名
        "Flag": 0               // 状态标志
    }
}

3.3 出院处理

功能码: 0003

功能说明: 病人出院时的处理

请求参数:

{
    "FCode": "string"  // 病人编号，必填
}

响应参数:

{
    "ResultCode": "0000",
    "ResultMsg": "出院处理成功"
}

3.4 消费记录

功能码: 0004

功能说明: 记录病人消费信息

请求参数:

{
    "FCode": "string",          // 病人编号，必填
    "InvoiceNo": "string",      // 发票号，必填
    "AmountA": 50.00,           // A类金额
    "AmountB": 30.00,           // B类金额
    "Amount": 80.00,            // 总金额
    "FreeAmountA": 0.00,        // A类可用金额
    "FreeAmountB": 0.00,        // B类可用金额
    "CrtDate": "2024-01-01T10:00:00Z",  // 创建日期
    "FCriminal": "string",      // 病人姓名
    "CardCode": "string",       // 卡号
    "OrderId": 123456           // 订单ID
}

响应参数:

{
    "ResultCode": "0000",
    "ResultMsg": "消费记录保存成功"
}

3.5 实时余额查询

功能码: 0005

功能说明: 查询病人实时余额信息

请求参数:

{
    "FCode": "string"  // 病人编号，必填
}

响应参数: 与入院登记响应格式相同

3.6 发票同步

功能码: 0006

功能说明: 同步发票信息到系统

请求参数:

{
    "InvoiceList": [
        "INV001",
        "INV002",
        "INV003"
    ]
}

响应参数:

{
    "ResultCode": "0000",
    "ResultData": [
        {
            "BankFlag": 2,                      // 银行标志
            "CAmount": 100.00,                  // 金额
            "FCode": "3516022343",              // 病人编号
            "Origid": "INV001",                 // 原始发票号
            "SendDate": "2024-01-01T10:00:00Z"  // 发送日期
        }
    ]
}

4. 连接管理

4.1 连接限制

• 最大并发连接数：配置文件中指定
• 连接超时时间：配置文件中指定
• 读取超时时间：配置文件中指定
• 写入超时时间：配置文件中指定

4.2 连接流程

1. 客户端建立TCP连接
2. 发送请求消息（按照消息格式）
3. 服务器验证医院编码
4. 处理业务逻辑
5. 返回响应消息
6. 关闭连接

5. 安全说明

5.1 医院编码验证

所有请求必须包含正确的医院编码，否则返回"无效的医院编码"错误。

5.2 超时控制

• 连接建立后有读取超时限制
• 响应发送有写入超时限制
• 业务处理有上下文超时控制（10秒）

6. 监控指标

系统提供以下监控指标：

• 活跃连接数
• 请求计数（按功能码分类）
• 请求处理时间（按功能码分类）
• 错误计数（按功能码和错误码分类）

7. 示例代码

7.1 Go 客户端示例

package main

import (
    "fmt"
    "net"
    "time"
)

func main() {
    conn, err := net.Dial("tcp", "localhost:8080")
    if err != nil {
        panic(err)
    }
    defer conn.Close()

    // 构造请求消息
    functionCode := "0001"
    hospitalCode := "H001"
    timestamp := time.Now().Format("2006-01-02 15:04:05")
    data := `{"FCode":"3516022343"}`
    
    message := fmt.Sprintf("%s%s%s%s", functionCode, hospitalCode, timestamp, data)
    fullMessage := fmt.Sprintf("%04d%s", len(message), message)

    // 发送请求
    _, err = conn.Write([]byte(fullMessage))
    if err != nil {
        panic(err)
    }

    // 读取响应
    buffer := make([]byte, 4096)
    n, err := conn.Read(buffer)
    if err != nil {
        panic(err)
    }

    response := string(buffer[:n])
    fmt.Printf("Response: %s\n", response)
}

7.2 Python 客户端示例

import socket
import json
import time

def send_request(host, port, function_code, hospital_code, data):
    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    try:
        sock.connect((host, port))
        
        # 构造消息
        timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
        json_data = json.dumps(data)
        message = f"{function_code}{hospital_code}{timestamp}{json_data}"
        full_message = f"{len(message):04d}{message}"
        
        # 发送请求
        sock.send(full_message.encode('utf-8'))
        
        # 接收响应
        response = sock.recv(4096).decode('utf-8')
        
        # 解析响应
        length = int(response[:4])
        json_response = response[4:4+length]
        
        return json.loads(json_response)
        
    finally:
        sock.close()

# 使用示例
if __name__ == "__main__":
    result = send_request(
        "localhost", 8080, 
        "0001", "H001", 
        {"FCode": "3516022343"}
    )
    print(json.dumps(result, indent=2, ensure_ascii=False))

8. 常见问题

8.1 连接被拒绝

• 检查服务器是否启动
• 检查端口是否正确
• 检查是否达到最大连接数限制

8.2 医院编码错误

• 确认医院编码配置正确
• 检查请求消息格式是否正确

8.3 请求超时

• 检查网络连接
• 确认服务器负载情况
• 检查请求数据格式是否正确

8.4 数据格式错误

• 确认JSON格式正确
• 检查必填字段是否完整
• 验证数据类型是否匹配

9. 版本历史

版本	日期	说明
1.0.0	2024-01-01	初始版本，支持基础的6个功能接口

10. 联系方式

如有问题请联系开发团队。