QHD_ZhongYiYuan_YiJiYuYue/AGENTS.md

AGENTS.md - 秦皇岛中医院医技预约系统

项目简介

秦皇岛中医院医技预约系统，用于医院医技检查项目的预约管理，包括科室、设备、号源管理、预约登记等核心功能。系统与HIS系统集成，支持多渠道预约（自助机、H5、管理后台）。

项目结构

QHD_ZhongYiYuan_YiJiYuYue/
├── Laravel/              # PHP后端API服务 (Laravel 8)
│   ├── app/             # 应用核心代码
│   │   ├── Http/Controllers/API/  # API控制器
│   │   ├── Models/               # 数据模型
│   │   ├── Lib/                  # 自定义类库
│   │   └── Middleware/           # 中间件
│   ├── routes/          # 路由定义
│   ├── config/          # 配置文件
│   └── database/        # 数据库相关
│
├── YiJi-admin/          # 管理后台前端 (Vue 3 + Vite + Element Plus)
│   ├── src/
│   │   ├── views/      # 页面组件
│   │   ├── components/ # 公共组件
│   │   ├── router/     # 路由配置
│   │   ├── store/      # Pinia状态管理
│   │   └── api/        # API接口
│   └── vite.config.js  # Vite配置
│
├── ZiZhuJi/            # 自助机前端 (Vue 3 + Vite + Element Plus)
│   ├── src/
│   │   ├── views/      # 页面组件
│   │   ├── tools/      # 工具类
│   │   └── router/     # 路由配置
│   └── vite.config.js
│
├── h5/                 # 移动端H5 (uni-app)
│   ├── pages/          # 页面
│   ├── api/            # API接口
│   ├── static/         # 静态资源
│   └── uni_modules/    # uni-app组件模块
│
├── bot/                # WebSocket服务 (Workerman)
│   └── workerman/      # Workerman框架
│
├── 秦皇岛中医院监听mq/  # HIS消息队列监听服务 (C#)
│   └ MyHosListener/
│       ├── common/
│       │   ├── listener/  # MQ消息监听器
│       │   ├── DBTools.cs # 数据库工具
│       │   └ Tools.cs     # 通用工具
│       └ App.config       # 应用配置
│
└── data.sql            # 数据库结构文件

技术栈

后端

• 框架: Laravel 8
• PHP版本: ^7.4|^8.0
• 数据库: MySQL 5.7+ (数据库名: yiji_qhdzhongyiyuan)
• 认证: Laravel Sanctum
• 关键依赖:
  • barryvdh/laravel-snappy (PDF生成)
  • picqer/php-barcode-generator (条形码生成)

前端

• 管理后台 & 自助机: Vue 3 + Vite + Element Plus + Pinia/Vue Router
• 移动端H5: uni-app (支持多端)
• HTTP客户端: Axios

其他服务

• WebSocket: Workerman (PHP)
• HIS集成: C# Windows服务监听MQ消息

构建与运行命令

Laravel后端

cd Laravel

# 安装依赖
composer install

# 配置环境
cp .env.example .env
php artisan key:generate

# 运行开发服务器
php artisan serve

# 数据库迁移（如有）
php artisan migrate

# 运行测试
php artisan test
# 或
phpunit

YiJi-admin 管理后台

cd YiJi-admin

# 安装依赖
npm install

# 开发模式
npm run dev

# 生产构建
npm run build

# 预览构建结果
npm run preview

# 代码检查
npm run lint

# 代码格式化
npm run format

ZiZhuJi 自助机

cd ZiZhuJi

# 安装依赖
npm install

# 开发模式
npm run dev

# 生产构建
npm run build

# 预览构建结果
npm run preview

h5 移动端

cd h5

# 使用HBuilderX或uni-app CLI
# 开发：通过HBuilderX运行到浏览器或模拟器
# 构建：通过HBuilderX发布为H5/App

Workerman WebSocket

cd bot

# 安装依赖
composer install

# 启动WebSocket服务（Windows）
php workerman/start.php

# Linux下通常使用
php workerman/start.php start
php workerman/start.php stop
php workerman/start.php restart

HIS监听服务 (C#)

# 使用Visual Studio编译运行
# 或通过已编译的exe文件启动

数据库核心表结构

权限与用户管理

• users - 系统用户表
• group - 用户分组
• group_menu - 分组菜单关联
• menu - 系统菜单

业务核心表

• s_department - 科室表
• s_department_resources - 科室资源（检查室/机房）
• s_devices - 设备表
• s_check_item - 检查项目表
• s_check_item_class - 检查项目分类
• s_check_item_device - 检查项目-设备绑定关系

预约管理

• s_appointment_type - 预约类型（住院/门诊/急诊/体检等渠道）
• s_appointment_type_ratio - 预约类型比例配置
• s_period - 预约时间段配置
• s_source_roster - 预约计划模板
• s_source_roster_count - 模板各渠道号源数量
• s_source_roster_detail - 预约计划明细（每日号源）
• s_source_roster_detail_count - 明细各渠道号源数量（含乐观锁version）
• s_holiday - 节假日配置

预约记录

• s_list - 预约主表（核心业务表，包含患者信息、医嘱、预约状态等）
  • 主要状态字段 list_status: 0-正在申请, 1-预约, 2-登记, 3-结束
  • 患者类型 patient_type: 0-住院, 1-门诊, 2-急诊, 3-体检
• s_list_log - 预约状态变更日志

其他

• configs - 系统配置
• s_huchi - 检查项目互斥配置
• s_inpatient_ward - 病区表
• outside_user - 第三方对接用户表
• institutional_calendar - 体检机构日历（如用于体检预约）

API路由规范

API基础路径: /api/v1/ (需携带token认证)

认证相关

• POST /api/admin/login - 登录
• POST /api/tokenRefresh - 刷新token

系统管理

• POST /api/v1/admin/getBaseMenuList - 获取用户菜单
• POST /api/v1/admin/getUserList - 用户列表
• POST /api/v1/admin/getGroupList - 分组列表
• POST /api/v1/admin/GetConfigInfo - 获取配置

业务管理

• POST /api/v1/admin/GetDepartmentList - 科室列表
• POST /api/v1/admin/GetCheckItemList - 检查项目列表
• POST /api/v1/admin/GetDeviceList - 设备列表
• POST /api/v1/admin/PlanModelGetList - 预约计划模板
• POST /api/v1/admin/PlanListGetList - 预约计划明细
• POST /api/v1/admin/GetMainList - 预约记录列表
• POST /api/v1/admin/CancelYuYue - 取消预约

命名规范: 控制器位于 App\Http\Controllers\API\Admin\ 目录，按业务模块分子目录（如 YeWu\）

HIS集成消息类型

C#监听服务处理以下MQ消息类型（位于 秦皇岛中医院监听mq\MyHosListener\common\listener\）：

• MI0150Listener - 医嘱信息
• MI0164Listener - 医嘱状态变更
• MU0165Listener - 医嘱更新
• CI0047Listener - 检查信息
• CI0054Listener / CI0055Listener - 检查相关
• CD0050Listener - 检查确认
• OI0083Listener - 医嘱订单
• OD0084Listener - 订单更新
• MU0151Listener - 其他更新

消息处理后写入 s_list 表及相关业务表。

代码规范

Laravel

• 遵循PSR-12编码规范
• 控制器命名: XxxController
• 模型命名: 单数形式，对应表名前缀通常为 s_
• 使用Eloquent ORM操作数据库
• 复杂业务逻辑封装在 app/Lib/ 或Service层

Vue前端

• 组件命名: PascalCase (如 CheckItemMainList.vue)
• 使用Composition API或Options API
• Element Plus组件库统一UI风格
• API调用统一通过 src/api/ 模块

通用规范

• 时间字段命名: created_at, updated_at
• 状态字段: status (0-关闭/禁用, 1-开启/正常)
• 删除标记: is_del (0-未删除, 1-已删除)
• 注意软删除和状态区分

开发注意事项

1. 号源管理

   • 使用乐观锁（s_source_roster_detail_count.version）防止并发预约冲突
   • 预约时需检查项目互斥（s_huchi表）
   • 预约需在 end_reservation_time 前完成

2. HIS数据同步

   • HIS通过MQ推送医嘱数据，监听服务接收并写入数据库
   • entrust_id 为HIS医嘱唯一标识，需确保唯一性
   • 注意门诊缴费状态同步（is_pay字段）

3. 预约状态流转

   • 正常流程: 申请(0) → 预约(1) → 登记(2) → 结束(3)
   • 支持取消预约（记录取消时间 canel_time）
   • 所有状态变更记录到 s_list_log

4. 安全与认证

   • 所有业务API需通过 checktoken 中间件验证
   • Token使用Laravel Sanctum管理
   • 密码需加密存储

5. 环境配置

   • Laravel .env 配置数据库、应用URL等
   • C#监听服务 App.config 配置MQ连接、数据库连接
   • 前端需配置API基础路径

测试

# Laravel测试
cd Laravel
php artisan test

# 或使用PHPUnit直接运行
phpunit

前端项目暂无测试脚本配置，建议补充单元测试和E2E测试。

常见问题

1. 数据库导入: 使用 data.sql 初始化数据库结构
2. 跨域配置: Laravel已配置 fruitcake/laravel-cors
3. PDF生成: 需安装wkhtmltopdf（laravel-snappy依赖）
4. 条形码生成: 使用 picqer/php-barcode-generator

相关文档

• 项目需求规范示例.md - 需求与设计文档模板参考
• 数据库详细结构见 data.sql