# MediSettle

**Repository Path**: code_87/medi-settle

## Basic Information

- **Project Name**: MediSettle
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-18
- **Last Updated**: 2026-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MediSettle — 医院体检对公收银台

面向医院体检中心的对公（B2B）收费管理系统。采用 **平台 → 医院 → 企业/个人客户** 三层多租户架构。企业客户可为员工批量下单体检套餐，通过光大银行公缴接口完成对公支付，系统自动开具医疗电子票据，并支持退费申请与审核。

## 系统角色与页面

系统分为四个端，覆盖平台运营、医院管理、客户消费的完整链路：

### 🏢 平台后台 (`/admin`)

Saas 平台超级管理员，管理所有入驻医院和系统全局设置。

| 页面 | 说明 |
|------|------|
| 登录 | 平台管理员账号密码登录 |
| 仪表盘 | 医院数、订单数、销售额等全平台概览 |
| 医院管理 | 审核和管理入驻的医院，查看基本信息、银行账号、票据配置，只读预览医院项目/客户（企业/个人），查看医院账号并重置密码 |
| 订单管理 | 查看全平台订单 |
| 退费单据 | 只读查看各医院退费申请（审核由医院执行） |
| 系统设置 | 全局配置（支付接口、票据平台、短信等） |
| 管理员账号 | 创建平台账号、修改自己密码、重置他人密码 |

### 🏥 医院后台 (`/hospital-admin`)

每家医院独立的管理后台，管理本院体检项目、订单、客户和内部账号。

| 页面 | 说明 |
|------|------|
| 医院入驻 | 医院自助注册，填写基本信息、银行账户、票据配置，提交后待平台审核 |
| 登录 | 医院管理员账号密码登录 |
| 仪表盘 | 本院订单数、企业数、销售额概览 |
| 信息管理 | 编辑医院基本信息、收款银行账号、电子票据配置 |
| 体检项目管理 | 管理本院体检项目（价格、税率、上下架） |
| 订单管理 | 查看本院所有订单，支持状态筛选和金额核算 |
| 企业管理 | 查看本院下属企业客户 |
| 退费审核 | 审核本院退费申请（通过自动冲红发票） |
| 账号管理 | 管理医院内部员工账号（财务、项目管理等角色） |
| 角色管理 | 自定义角色权限（细粒度权限码控制） |
| 页面配置 | 配置医院 H5 首页的主题色、标题、文案、是否公开价格等 |

### 📱 H5 客户端 (`/h/:slug`)

医院面向企业客户和个人客户的 H5 页面，基于手机验证码登录。

| 页面 | 说明 |
|------|------|
| 企业注册 | 企业客户填写统一信用代码、公司名称、联系人等信息，短信验证码验证手机号完成注册 |
| 个人注册 | 个人客户填写姓名、身份证号、手机号，短信验证码验证完成注册 |
| 验证码登录 | 企业或个人均通过"手机号 + 短信验证码"登录，无需记忆密码 |
| 首页 | 医院 H5 首页，浏览全部体检项目并下单 |
| 订单列表 | 查看历史订单，按状态筛选 |
| 订单详情 | 查看订单明细、支付信息、发票信息 |
| 收银台 | 两阶段支付：查询银行缴费信息 → 确认支付 |
| 支付结果 | 支付成功/失败结果展示 |
| 电子发票 | 在线查看医疗电子发票，支持发送到邮箱 |
| 退费申请 | 提交退费申请，填写原因，跟踪审核进度 |
| 我的 | 客户信息管理（企业/个人信息查看） |

> **验证码登录**：企业和个人客户统一使用手机号 + 短信验证码登录。首次登录时自动创建账号（注册即登录）。开发模式下验证码固定为 `123456`。平台/医院管理员仍使用密码登录。

## 技术架构

```
medi-settle/
├── main.go                    # 入口：加载配置 → 初始化 DB → 注册路由 → 启动服务
├── config.yaml                # 全局配置文件
├── build.sh / build.bat       # 构建脚本（交叉编译 Linux amd64）
│
├── internal/
│   ├── config/                # YAML 配置加载与结构体定义
│   ├── database/              # GORM 数据库初始化、AutoMigrate、系统必需数据
│   ├── model/                 # 数据模型（GORM）
│   │   ├── user.go            #   平台管理员/用户
│   │   ├── hospital.go        #   医院信息
│   │   ├── hospital_user.go   #   医院管理员/员工
│   │   ├── role.go            #   医院角色权限
│   │   ├── permission.go      #   权限码定义
│   │   ├── page_config.go     #   医院 H5 页面配置
│   │   ├── exam_company.go    #   企业客户
│   │   ├── exam_individual.go #   个人客户
│   │   ├── exam_item.go       #   体检项目
│   │   ├── exam_order.go      #   订单 + 订单明细
│   │   ├── exam_invoice.go    #   电子发票记录
│   │   ├── exam_refund.go     #   退费申请
│   │   ├── sms_code.go        #   短信验证码
│   │   └── config.go          #   系统配置（KV 键值表）
│   │
│   ├── handler/               # HTTP 处理器（Gin Handler）
│   │   ├── auth.go            #   平台用户登录/注册
│   │   ├── admin.go           #   平台管理员：医院管理、项目管理
│   │   ├── admin_dashboard.go #   平台仪表盘
│   │   ├── exam.go            #   H5 客户端：注册/登录、下单、支付、发票、退费
│   │   ├── hospital.go        #   医院后台：注册、信息管理
│   │   ├── hospital.go        #   医院后台：注册/入驻、仪表盘、订单、客户、退费、用户、角色、页面配置
│   │   ├── settings.go        #   系统设置（DB 动态配置）
│   │   ├── upload.go          #   文件上传
│   │   └── health.go          #   健康检查
│   │
│   ├── service/               # 业务逻辑编排层
│   │   ├── exam.go            #   订单、支付、开票、退费核心流程
│   │   └── sms.go             #   短信验证码发送与校验
│   │
│   ├── middleware/             # 中间件
│   │   ├── auth.go            #   JWT 认证（平台用户）
│   │   ├── exam_auth.go       #   JWT 认证（企业/个人客户）
│   │   ├── hospital_auth.go   #   JWT 认证（医院管理员）
│   │   ├── cors.go            #   跨域处理
│   │   └── ratelimit.go       #   API 限流
│   │
│   ├── payment/               # 光大银行公缴接口客户端
│   │   ├── client.go          #   XML/GBK 协议，支持 CFCA 双向 TLS
│   │   ├── types.go           #   5660 查询 / 5661 销账 / 5662 结果查询 / 5663 辅助查询
│   │   └── errors.go          #   错误处理
│   │
│   ├── medical/               # 医疗电子票据平台客户端
│   │   ├── client.go          #   JSON/Base64 协议，MD5 签名
│   │   ├── types.go           #   门诊开票 / 住院开票 / 冲红 / 换开纸质 / 作废
│   │   └── sign.go            #   签名计算与验证
│   │
│   ├── email/                 # 邮件发送（SMTP）
│   ├── sms/                   # 短信发送（Mock/阿里云/腾讯云）
│   ├── storage/               # 文件存储（Local/MinIO/COS，可插拔）
│   ├── task/                  # 定时任务调度框架
│   └── router/                # 路由注册（分组、中间件链、前端 SPA 回退）
│
└── web/                       # 前端（Vue 3 + Vite）
    ├── src/
    │   ├── layouts/           # 布局组件
    │   │   ├── AdminLayout.vue      #  平台后台布局
    │   │   ├── HospitalLayout.vue   #  医院后台布局
    │   │   └── CustomerLayout.vue   #  H5 客户端布局
    │   ├── styles/            # 全局样式（variables.css / base.css / components.css）
    │   ├── views/             # 页面组件
    │   │   ├── Home.vue             #  H5 首页（体检项目浏览）
    │   │   ├── Orders.vue           #  订单列表
    │   │   ├── OrderDetail.vue      #  订单详情
    │   │   ├── Cashier.vue          #  收银台（光大银行支付）
    │   │   ├── Result.vue           #  支付结果
    │   │   ├── Invoice.vue          #  电子发票
    │   │   ├── hospital/            #  医院端 H5 页面
    │   │   │   ├── HospitalLogin.vue      #  验证码登录
    │   │   │   ├── HospitalRegister.vue   #  企业/个人注册
    │   │   │   └── Mine.vue               #  我的
    │   │   ├── admin/               #  平台后台页面
    │   │   │   ├── AdminLogin.vue         #  管理员登录
    │   │   │   ├── AdminDashboard.vue      #  仪表盘
    │   │   │   ├── AdminHospitals.vue      #  医院管理（预览/账号重置）
    │   │   │   ├── AdminHospitalPreview.vue #  医院只读预览（项目/客户）
    │   │   │   ├── AdminOrders.vue         #  订单管理
    │   │   │   ├── AdminRefunds.vue        #  退费单据（只读）
    │   │   │   ├── AdminUsers.vue          #  管理员账号（创建/改密/重置）
    │   │   │   └── AdminSettings.vue       #  系统设置
    │   │   └── hospitalAdmin/       #  医院后台页面
    │   │       ├── HospitalAdminLogin.vue       #  登录
    │   │       ├── HospitalAdminDashboard.vue   #  仪表盘
    │   │       ├── HospitalAdminInfo.vue        #  医院信息管理
    │   │       ├── HospitalAdminItems.vue       #  体检项目管理
    │   │       ├── HospitalAdminOrders.vue      #  订单管理
    │   │       ├── HospitalAdminCompanies.vue   #  企业管理
    │   │       ├── HospitalAdminRefunds.vue     #  退费审核
    │   │       ├── HospitalAdminUsers.vue       #  账号管理
    │   │       ├── HospitalAdminRoles.vue       #  角色权限
    │   │       └── HospitalAdminPageConfig.vue  #  页面配置
    │   ├── router/index.js    # 路由（Hash 模式）
    │   ├── utils/api.js       # H5 客户端 API 封装
    │   ├── utils/adminApi.js  # 平台后台 API 封装
    │   └── utils/auth.js      # Token 管理
    └── dist/                  # 构建产物（go:embed 嵌入后端二进制）
```

### 技术栈

| 层级 | 技术 |
|------|------|
| 后端语言 | Go 1.21+ |
| Web 框架 | [Gin](https://github.com/gin-gonic/gin) v1.9 |
| ORM | [GORM](https://gorm.io) v1.25 |
| 数据库 | MySQL 8.0 |
| 认证 | JWT (golang-jwt v5) |
| 前端框架 | Vue 3 (Composition API) |
| 构建工具 | Vite 6 |
| 前端路由 | Vue Router 4 (Hash 模式) |
| HTTP 客户端 | Axios |
| 银行协议 | HTTP + XML + GBK 编码, CFCA 双向 TLS |
| 医疗票据 | HTTP + JSON + Base64, MD5 签名 |

## 核心业务流程

### 支付流程（两步式）

```
企业下单 → 创建订单 (status=pending)
                │
                ▼
    ① 提交支付 (SubmitPay)
       └─ 调用光大银行 5660 查询缴费单信息
       └─ 返回合同号、客户名称、应缴金额等
                │
                ▼
    ② 确认支付 (ConfirmPay)
       └─ 调用光大银行 5661 销账
       └─ 更新订单 status=paid
       └─ 自动调用医疗票据平台开具电子发票
       └─ 更新订单 status=invoiced
```

### 退费流程

```
企业提交退费申请 (status=pending)
       │
       ▼
管理员审核
   ├─ 通过 ──→ 自动调用冲红接口作废发票
   │          └─ 退费单 status=approved
   │          └─ 订单 status=refunding
   │          └─ 记录红字票信息
   │
   └─ 驳回 ──→ 退费单 status=rejected
```

### 模拟模式

当未配置银行/票据平台接口时，系统自动降级为模拟模式：
- **支付**：生成模拟银行流水号，直接标记已支付
- **开票**：生成模拟票据代码和号码
- **冲红**：生成模拟红字票

无需真实对接即可跑通完整业务流程，方便开发和演示。

## 快速开始

### 前置要求

- Go 1.21+
- Node.js 18+（构建前端）
- MySQL 8.0

### 1. 构建前端

```bash
cd web
npm install
npm run build
```

### 2. 配置

编辑 `config.yaml`，根据需要修改数据库连接、JWT 密钥等：

```yaml
server:
  port: 8779

database:
  driver: mysql
  mysql:
    host: 127.0.0.1
    port: 3306
    username: root
    password: "your-password"
    database: medisettle
    charset: utf8mb4
  auto_migrate: true
  init_data: true            # 首次部署开一次，写入系统必需数据（默认管理员/权限码），无示例业务数据

jwt:
  secret: "your-secret-key"
  expire_hours: 720
```

### 3. 启动后端

```bash
go run main.go
```

服务启动后访问：`http://127.0.0.1:8779`

### 4. 一键构建（Linux 部署）

```bash
# 先构建前端
cd web && npm install && npm run build && cd ..

# 构建后端
bash build.sh

# 部署
./app
```

### 默认账号

| 角色 | 用户名 | 密码 | 说明 |
|------|--------|------|------|
| 平台管理员 | `admin` | `admin123` | 平台后台 `/admin`（`init_data` 首次部署时创建） |
| 医院管理员 | 入驻时自设 | 入驻时自设 | 医院后台 `/hospital`，医院自助入驻时创建 |
| 企业客户 | 手机号 + 验证码登录 | — | H5 客户端 `/h/:slug` |
| 个人客户 | 手机号 + 验证码登录 | — | H5 客户端 `/h/:slug` |

> 企业/个人客户首次验证码登录即自动注册。短信验证码开发模式下通过接口 `data.code` 回显，生产环境真实下发。

## API 接口

### 公开接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/health` | 健康检查 |
| GET | `/api/v1/hospitals` | 医院列表（公开） |
| POST | `/api/v1/auth/login` | 平台用户登录 |
| POST | `/api/v1/auth/register` | 平台用户注册 |
| GET | `/api/v1/admin/check` | 检查管理员是否存在 |
| POST | `/api/v1/admin/init` | 初始化平台管理员 |
| POST | `/api/v1/hospital/register` | 医院入驻申请 |
| POST | `/api/v1/hospital/login` | 医院管理员登录 |
| POST | `/api/v1/exam/company/register` | 企业注册 |
| POST | `/api/v1/exam/company/login` | 企业登录（验证码） |
| POST | `/api/v1/exam/individual/register` | 个人注册 |
| POST | `/api/v1/exam/individual/login` | 个人登录（验证码） |
| POST | `/api/v1/exam/sms/send` | 发送短信验证码 |

### H5 客户端接口（需客户 JWT）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/exam/items` | 体检项目列表 |
| POST | `/api/v1/exam/order/create` | 创建订单 |
| GET | `/api/v1/exam/orders` | 订单列表 |
| GET | `/api/v1/exam/order/:id` | 订单详情 |
| POST | `/api/v1/exam/order/:id/submit-pay` | 查询银行缴费信息 |
| POST | `/api/v1/exam/order/:id/confirm-pay` | 确认支付 |
| GET | `/api/v1/exam/order/:id/invoice` | 获取发票 |
| POST | `/api/v1/exam/order/:id/invoice/send-email` | 发送发票邮件 |
| POST | `/api/v1/exam/order/:id/refund` | 提交退费申请 |
| GET | `/api/v1/exam/refunds` | 退费申请列表 |

### 平台后台接口（需平台 JWT + Admin）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/admin/dashboard` | 全平台仪表盘 |
| GET/POST/PUT/DELETE | `/api/v1/admin/hospitals` | 医院管理 CRUD |
| GET | `/api/v1/admin/hospitals/:id/preview` | 医院只读预览（项目/客户） |
| GET | `/api/v1/admin/hospitals/:id/users` | 医院账号列表 |
| POST | `/api/v1/admin/hospitals/:id/users/:uid/reset-password` | 重置医院账号密码 |
| GET | `/api/v1/admin/hospitals/:id/companies` | 医院企业用户（支持搜索） |
| GET | `/api/v1/admin/hospitals/:id/individuals` | 医院个人用户（支持搜索，身份证脱敏） |
| GET | `/api/v1/admin/all-orders` | 所有订单 |
| GET | `/api/v1/admin/refunds` | 退费单据（平台只读，审核由医院执行） |
| GET/PUT | `/api/v1/admin/settings` | 系统设置 |
| GET/POST/PUT/DELETE | `/api/v1/admin/users` | 平台账号管理（创建/重置密码/删除，不能删自己） |

### 医院后台接口（需医院 JWT）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/hospital/dashboard` | 本院仪表盘 |
| GET/PUT | `/api/v1/hospital/info` | 医院信息查看/编辑 |
| GET/POST/PUT/DELETE | `/api/v1/hospital/items` | 体检项目 CRUD |
| GET | `/api/v1/hospital/orders` | 本院订单列表 |
| GET | `/api/v1/hospital/companies` | 本院企业客户 |
| GET | `/api/v1/hospital/individuals` | 本院个人客户 |
| GET | `/api/v1/hospital/refunds` | 本院退费申请 |
| POST | `/api/v1/hospital/refunds/:id/approve` | 退费审核通过 |
| POST | `/api/v1/hospital/refunds/:id/reject` | 退费驳回 |
| GET/POST/PUT/DELETE | `/api/v1/hospital/users` | 员工账号管理 |
| GET/POST/PUT/DELETE | `/api/v1/hospital/roles` | 角色权限管理 |
| GET/PUT | `/api/v1/hospital/page-config` | H5 页面配置 |

## 配置说明

完整配置见 `config.yaml`，关键配置项：

| 配置块 | 说明 |
|--------|------|
| `server` | 服务端口 |
| `database` | MySQL 数据库连接、自动建表、初始化系统必需数据 |
| `jwt` | JWT 密钥与过期时间 |
| `upload` | 文件上传路径、大小限制、允许类型 |
| `storage` | 存储类型（local/minio/cos） |
| `sms` | 短信服务（mock/aliyun/tencent），开发模式不真实发送 |
| `payment` | 光大银行公缴接口（base_url/inst_id/证书） |
| `medical` | 医疗电子票据平台（base_url/app_id/签名密钥） |
| `email` | SMTP 邮件发送（发票邮件） |
| `cors` | 跨域白名单 |
| `rate_limit` | API 限流配置 |

> **模拟模式**：`payment.base_url` 和 `medical.base_url` 留空时自动启用模拟模式，无需对接外部系统即可完整体验业务流程。

## 外部系统对接

### 光大银行公缴单位统一接口

- 协议：HTTP + XML + GBK 编码
- 安全：可选 CFCA 双向 TLS 证书认证
- 交易码：
  - **5660** — 查询缴费单信息
  - **5661** — 缴费单销账（支付）
  - **5662** — 缴费结果查询
  - **5663** — 辅助查询

### 医疗电子票据管理平台

- 协议：HTTP + JSON + Base64
- 安全：MD5 签名（appid + data + noise + key）
- 接口：
  - 门诊电子票据开具
  - 住院电子票据开具
  - 电子票据冲红（退费时使用）
  - 换开/重新换开纸质票据
  - 作废纸质票据

## 数据模型 ER

```
hospitals ────────────────── 医院信息
  ├── hospital_users ─────── 医院管理员/员工（belongs to hospital, role）
  ├── roles ──────────────── 角色权限（belongs to hospital）
  ├── permissions ────────── 权限码定义
  ├── page_configs ───────── 医院 H5 页面配置（one-to-one with hospital）
  ├── exam_items ─────────── 体检项目（belongs to hospital）
  ├── exam_companies ─────── 企业客户（belongs to hospital）
  ├── exam_individuals ───── 个人客户（belongs to hospital）
  └── exam_orders ────────── 订单（belongs to hospital/company/individual）
        ├── exam_order_items ─ 订单明细（belongs to order, refs item）
        ├── exam_invoice_records ─ 发票（one-to-one with order）
        └── exam_refund_requests ─ 退费申请（belongs to order）
users ────────────────────── 平台管理员
system_configs ──────────── 系统配置（KV）
sms_codes ────────────────── 短信验证码
login_logs ───────────────── 登录日志
```

## License

MIT