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

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

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

## 2. 错误码说明

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

## 3. 接口详情

### 3.1 入院登记

**功能码**: `0001`

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

**请求参数**:
```json
{
    "FCode": "string"  // 病人编号，必填
}
```

**响应参数**:
```json
{
    "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`

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

**请求参数**:
```json
{
    "FCode": "string"  // 病人编号，必填
}
```

**响应参数**:
```json
{
    "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`

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

**请求参数**:
```json
{
    "FCode": "string"  // 病人编号，必填
}
```

**响应参数**:
```json
{
    "ResultCode": "0000",
    "ResultMsg": "出院处理成功"
}
```

### 3.4 消费记录

**功能码**: `0004`

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

**请求参数**:
```json
{
    "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
}
```

**响应参数**:
```json
{
    "ResultCode": "0000",
    "ResultMsg": "消费记录保存成功"
}
```

### 3.5 实时余额查询

**功能码**: `0005`

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

**请求参数**:
```json
{
    "FCode": "string"  // 病人编号，必填
}
```

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

### 3.6 发票同步

**功能码**: `0006`

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

**请求参数**:
```json
{
    "InvoiceList": [
        "INV001",
        "INV002",
        "INV003"
    ]
}
```

**响应参数**:
```json
{
    "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 客户端示例

```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 客户端示例

```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. 联系方式

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