# his_gzyb_server

**Repository Path**: elfbobo_admin_admin/his_gzyb_server

## Basic Information

- **Project Name**: his_gzyb_server
- **Description**: his_gzyb_server 是一个基于 Python 的医保项目后端服务，用于处理 HIS（医院信息系统）与医保系统之间的业务交互，提供标准化的接口调用能力。
- **Primary Language**: Python
- **License**: Zlib
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-25
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 项目需求文档

## 1. 项目概述

### 1.1 项目名称
his_gzyb_server

### 1.2 项目描述
his_gzyb_server 是一个基于 Python 的医保项目后端服务，用于处理 HIS（医院信息系统）与医保系统之间的业务交互，提供标准化的接口调用能力。

### 1.3 技术栈
| 技术 | 版本 | 说明 |
|------|------|------|
| Python | 3.11+ | 编程语言 |
| FastAPI | 0.115.0+ | Web 框架 |
| Pydantic | 2.9.0+ | 数据验证 |
| Pydantic Settings | 2.0+ | 配置管理 |
| httpx | 0.27.0+ | HTTP 客户端 |
| Uvicorn | 0.29.0+ | ASGI 服务器 |

### 1.4 运行环境要求
- Python 3.11 及以上版本
- 医保网络专线支持

---

## 2. 项目架构

### 2.1 架构设计
采用分层架构设计，确保代码的可扩展性和可维护性：

```
┌─────────────────────────────────────────────────────────────┐
│                    路由层 (routes)                          │
│  sign_in_router.py | catalog_router.py | generic_router.py │
├─────────────────────────────────────────────────────────────┤
│                    服务层 (services)                        │
│ sign_in_service.py | catalog_service.py | generic_service.py│
│              | base_service.py                              │
├─────────────────────────────────────────────────────────────┤
│                    模型层 (schemas)                         │
│   sign_in.py | catalog.py | generic.py                     │
├─────────────────────────────────────────────────────────────┤
│                    工具层 (utils)                           │
│          logger.py | message_utils.py                      │
├─────────────────────────────────────────────────────────────┤
│                    配置层 (config)                          │
│                       config.py                            │
└─────────────────────────────────────────────────────────────┘
```

### 2.2 目录结构
```
his_gzyb_server/
├── main.py                    # 应用入口
├── requirements.txt           # 依赖清单
├── .env                       # 环境变量配置
├── 项目需求.md                 # 项目需求文档
└── src/
    ├── __init__.py
    ├── config.py              # 配置管理
    ├── routes/                # 路由定义
    │   ├── __init__.py
    │   ├── sign_in_router.py  # 签到接口路由
    │   ├── catalog_router.py  # 目录接口路由
    │   └── generic_router.py  # 通用接口路由
    ├── services/              # 业务服务
    │   ├── __init__.py
    │   ├── base_service.py    # 基础服务类
    │   ├── sign_in_service.py # 签到服务
    │   ├── catalog_service.py # 目录服务
    │   └── generic_service.py # 通用服务
    ├── schemas/               # 数据模型
    │   ├── __init__.py
    │   ├── sign_in.py         # 签到模型
    │   ├── catalog.py         # 目录模型
    │   └── generic.py         # 通用模型
    └── utils/                 # 工具函数
        ├── __init__.py
        ├── logger.py          # 日志工具
        └── message_utils.py   # 消息工具
```

---

## 3. 接口说明

### 3.1 接口列表

| 接口编号 | 接口名称 | HTTP方法 | 路径 | 描述 |
|---------|---------|----------|------|------|
| 9001 | 签到 | POST | /api/sign-in | 定点医药机构签到 |
| - | 快速签到 | POST | /api/sign-in/quick | 使用默认参数签到 |
| 7043 | 目录信息查询 | POST | /api/catalog | 查询医保目录信息 |
| - | 快速目录查询 | POST | /api/catalog/quick | 使用默认参数查询 |
| 通用 | 通用接口 | POST | /api/generic | 支持所有医保接口调用 |
| - | 健康检查 | GET | / | 服务健康检查 |

### 3.2 通用接口（推荐使用）

**请求格式：**
```json
{
    "info_number": "7043",
    "input": {
        "data": {
            "id": "",
            "fixmedinsCode": "配置值"
        }
    }
}
```

**请求参数说明：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| info_number | string | 是 | 接口编号（如 7043、7044） |
| input | object | 是 | 输入参数包装 |
| input.data | object | 是 | 业务数据，根据接口不同而变化 |

**服务端自动填充的公共字段：**

| 参数 | 值 | 说明 |
|------|------|------|
| msgid | 自动生成 | 消息唯一标识 |
| mdtrtarea_admvs | 配置值 | 就医地行政区划代码 |
| insuplc_admdvs | 配置值 | 参保地行政区划代码 |
| recer_sys_code | 配置值 | 接收系统代码 |
| cainfo | 配置值 | CA信息 |
| signtype | SM3 | 签名类型 |
| infver | 1.0.0 | 接口版本 |
| opter_type | 1 | 操作员类型 |
| opter | 配置值 | 操作员编号 |
| opter_name | 配置值 | 操作员名称 |
| inf_time | 自动生成 | 请求时间 |
| fixmedins_code | 配置值 | 定点医药机构编号 |
| fixmedins_name | 配置值 | 定点医药机构名称 |
| sign_no | 配置值 | 签到编号 |

> **注意**：以上公共字段的具体值请通过 `.env` 配置文件进行设置，确保敏感信息安全。

**响应格式：**
```json
{
    "output": {
        "code": "0",
        "type": "success",
        "message": "成功",
        "data": {}
    },
    "infcode": 0,
    "warn_msg": null,
    "cainfo": null,
    "err_msg": null,
    "refmsg_time": "20260505152104084",
    "signtype": null,
    "respond_time": "20260505152104113",
    "inf_refmsgid": "522600202605051521042578513330",
    "detail_msg": null
}
```

### 3.3 9001 签到接口

**请求格式：**
```json
{
    "infno": "9001",
    "msgid": "自动生成",
    "insuplc_admdvs": "配置值",
    "mdtrtarea_admvs": "配置值",
    "recer_sys_code": "配置值",
    "dev_no": "",
    "dev_safe_info": "",
    "cainfo": "配置值",
    "infver": "V1.0",
    "opter_type": "1",
    "opter": "配置值",
    "opter_name": "配置值",
    "inf_time": "自动生成",
    "fixmedins_code": "配置值",
    "fixmedins_name": "配置值",
    "app_id": "",
    "enc_type": "",
    "input": {
        "signIn": {
            "opter_no": "操作员编号",
            "mac": "设备MAC地址",
            "ip": "设备IP地址"
        }
    }
}
```

**成功响应：**
```json
{
    "output": {
        "signinoutb": {
            "sign_no": "522600G0000659252158",
            "sign_time": "2026-05-05 00:00:00"
        }
    },
    "infcode": 0,
    "warn_msg": null,
    "cainfo": null,
    "err_msg": "success",
    "refmsg_time": "20260505152104084",
    "signtype": null,
    "respond_time": "20260505152104113",
    "inf_refmsgid": "522600202605051521042578513330"
}
```

### 3.4 7043 目录信息查询接口

**请求格式：**
```json
{
    "infno": "7043",
    "msgid": "自动生成",
    "mdtrtarea_admvs": "配置值",
    "insuplc_admdvs": "配置值",
    "recer_sys_code": "配置值",
    "dev_no": "",
    "dev_safe_info": "",
    "cainfo": "配置值",
    "signtype": "SM3",
    "infver": "1.0.0",
    "opter_type": "1",
    "opter": "配置值",
    "opter_name": "配置值",
    "inf_time": "自动生成",
    "fixmedins_code": "配置值",
    "fixmedins_name": "配置值",
    "sign_no": "配置值",
    "app_id": "",
    "enc_type": "",
    "pw_ecToken": "",
    "input": {
        "data": {
            "id": "",
            "fixmedinsCode": "配置值"
        }
    }
}
```

**成功响应：**
```json
{
    "output": {
        "code": "0",
        "type": "success",
        "message": "成功",
        "data": {
            "pageNum": 1,
            "pageSize": 1000,
            "size": 1000,
            "startRow": 1,
            "endRow": 1000,
            "pages": 5656,
            "recordCounts": 5655626,
            "data": [
                {
                    "id": "A5200000000000000001",
                    "hilistCode": "001101000010000",
                    "hilistName": "挂号费",
                    "updtTime": "2023-02-09 18:11:46",
                    "medChrgitmType": "02",
                    "chrgitmLv": "03",
                    "spec": "次",
                    "trtItemCont": "项目说明:;项目内涵:含门诊、急诊...",
                    "listType": "201"
                }
            ]
        }
    },
    "infcode": 0,
    "warn_msg": null,
    "cainfo": null,
    "err_msg": null,
    "refmsg_time": "20260505153048602",
    "signtype": null,
    "respond_time": "20260505153048604",
    "inf_refmsgid": "522600202605051530482578513330",
    "detail_msg": null
}
```

---

## 4. 配置说明

### 4.1 配置文件

配置文件位于 `src/config.py`，支持通过 `.env` 文件覆盖默认配置：

```python
# 默认配置
host: str = "0.0.0.0"          # 服务绑定地址
port: int = 8000               # 服务端口
debug: bool = True             # 调试模式（热部署）
base_url: str = ""             # 医保接口地址（通过.env配置）
apikey: str = ""               # API密钥（通过.env配置）
default_fixmedins_code: str = ""  # 默认机构编号
default_fixmedins_name: str = ""   # 默认机构名称
timeout: int = 30              # 请求超时时间（秒）
log_level: str = "INFO"        # 日志级别
```

### 4.2 .env 文件格式

```env
# 服务配置
HOST=0.0.0.0
PORT=8000
DEBUG=true

# 医保接口配置（生产环境请妥善保管）
BASE_URL=http://your-medicare-api-host:port/path
APIKEY=your-secret-api-key

# 默认机构配置
DEFAULT_FIXMEDINS_CODE=
DEFAULT_FIXMEDINS_NAME=

# 请求超时配置
TIMEOUT=30

# 日志配置
LOG_LEVEL=INFO
```

**注意**：`BASE_URL` 和 `APIKEY` 为敏感配置信息，请通过 `.env` 文件进行配置，不要硬编码到代码中，确保生产环境的安全性。

---

## 5. 日志功能

### 5.1 日志级别

| 级别 | 说明 |
|------|------|
| DEBUG | 调试信息，包含请求/响应详细数据 |
| INFO | 常规信息，记录接口调用开始/完成 |
| WARNING | 警告信息 |
| ERROR | 错误信息 |
| CRITICAL | 严重错误信息 |

### 5.2 日志输出示例

```
2026-05-06 10:30:00 - his_gzyb_server - INFO - 开始调用医保接口: infno=7043
2026-05-06 10:30:00 - his_gzyb_server - DEBUG - 生成消息ID: [自动生成的消息ID]
2026-05-06 10:30:00 - his_gzyb_server - INFO - 发送请求到医保接口: [配置的医保接口地址]
2026-05-06 10:30:01 - his_gzyb_server - INFO - 医保接口调用完成: infno=7043, success=True
```

---

## 6. 部署说明

### 6.1 依赖安装

```bash
pip install -r requirements.txt
```

### 6.2 服务启动

**开发模式（热部署）：**
```bash
python main.py
```

**生产模式：**
```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
```

### 6.3 访问地址

| 地址 | 说明 |
|------|------|
| http://localhost:8000/ | 健康检查 |
| http://localhost:8000/docs | Swagger API 文档 |
| http://localhost:8000/redoc | ReDoc API 文档 |

---

## 7. 接口扩展指南

### 7.1 添加新接口

1. **使用通用接口（推荐）**：只需传入 `info_number` 和 `input.data` 即可调用任意医保接口
   
   ```json
   {
       "info_number": "新接口编号",
       "input": {
           "data": {
               "字段1": "值1",
               "字段2": "值2"
           }
       }
   }
   ```

2. **创建专用接口**（如需自定义逻辑）：
   - 在 `src/schemas/` 中创建数据模型
   - 在 `src/services/` 中创建服务类
   - 在 `src/routes/` 中创建路由

### 7.2 扩展示例

**调用 7044 接口（假设存在）：**
```json
{
    "info_number": "7044",
    "input": {
        "data": {
            "id": "",
            "fixmedinsCode": "",
            "otherParam": "value"
        }
    }
}
```

---

## 8. 错误处理

### 8.1 错误响应格式

```json
{
    "output": null,
    "infcode": -1,
    "warn_msg": null,
    "cainfo": null,
    "err_msg": "错误描述信息",
    "refmsg_time": "20260505153048602",
    "signtype": null,
    "respond_time": "20260505153048604",
    "inf_refmsgid": null,
    "detail_msg": null
}
```

### 8.2 常见错误码

| 错误码 | 说明 |
|--------|------|
| 0 | 成功 |
| -1 | 失败 |
| 401 | 未授权（API密钥错误） |
| 404 | 接口未找到 |

---

## 9. 版本历史

| 版本 | 日期 | 修改内容 |
|------|------|----------|
| 1.0.0 | 2026-05-06 | 初始版本，包含签到、目录查询和通用接口 |
4.  新建 Pull Request


#### 特技

1.  使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
2.  Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
3.  你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
4.  [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
5.  Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
6.  Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)