# 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后端
```bash
cd Laravel

# 安装依赖
composer install

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

# 运行开发服务器
php artisan serve

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

# 运行测试
php artisan test
# 或
phpunit
```

### YiJi-admin 管理后台
```bash
cd YiJi-admin

# 安装依赖
npm install

# 开发模式
npm run dev

# 生产构建
npm run build

# 预览构建结果
npm run preview

# 代码检查
npm run lint

# 代码格式化
npm run format
```

### ZiZhuJi 自助机
```bash
cd ZiZhuJi

# 安装依赖
npm install

# 开发模式
npm run dev

# 生产构建
npm run build

# 预览构建结果
npm run preview
```

### h5 移动端
```bash
cd h5

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

### Workerman WebSocket
```bash
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#)
```bash
# 使用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基础路径

## 测试

```bash
# 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`