zyt/APPOINTMENT_MANAGEMENT_COMPLETE.md

# 挂号管理系统开发完成文档

## 完成状态

✅ 挂号管理系统已完成开发，包括：
- 挂号列表查询（支持搜索和筛选）
- 挂号详情查看
- 挂号取消功能
- 挂号完成功能

## 已完成的文件

### 前端文件
1. `admin/src/views/tcm/appointment/list.vue` - 挂号列表页面
2. `admin/src/api/doctor.ts` - API接口（已包含 completeAppointment）

### 后端文件
1. `server/app/adminapi/controller/doctor/AppointmentController.php` - 控制器
2. `server/app/adminapi/logic/doctor/AppointmentLogic.php` - 业务逻辑
3. `server/app/adminapi/lists/doctor/AppointmentLists.php` - 列表查询
4. `server/app/adminapi/validate/doctor/AppointmentValidate.php` - 验证器
5. `server/app/common/model/doctor/Appointment.php` - 数据模型

## 核心功能

### 1. 挂号列表
- 支持按患者姓名模糊搜索
- 支持按医生姓名模糊搜索
- 支持按状态筛选（已预约/已取消/已完成）
- 支持按日期范围筛选
- 分页显示
- 显示患者信息、医生信息、预约时间等

### 2. 挂号详情
- 查看完整的挂号信息
- 包含患者姓名、电话、医生姓名等

### 3. 取消挂号
- 只能取消"已预约"状态的挂号
- 需要二次确认
- 取消后状态变为"已取消"

### 4. 完成挂号
- 只能完成"已预约"状态的挂号
- 需要二次确认
- 完成后状态变为"已完成"

## 后端更新说明

### 数据库查询优化
使用联表查询获取患者和医生信息：

```php
// AppointmentLists.php
Appointment::alias('a')
    ->leftJoin('user u', 'a.patient_id = u.id')
    ->leftJoin('admin ad', 'a.doctor_id = ad.id')
    ->field('a.*, u.nickname as patient_name, u.mobile as patient_phone, ad.name as doctor_name')
```

### 搜索功能
- 患者姓名：模糊匹配 `u.nickname`
- 医生姓名：模糊匹配 `ad.name`
- 日期范围：between 查询
- 状态：精确匹配

### 数据格式化
- 时间戳自动转换为日期时间格式
- 状态自动添加描述文本
- 预约类型自动添加描述文本

## 配置步骤

### 1. 在后台添加菜单

登录后台管理系统，进入"权限管理" -> "菜单管理"，添加新菜单：

**菜单配置：**
- 菜单名称：挂号管理
- 菜单类型：菜单
- 上级菜单：中医诊断（或其他合适的父菜单）
- 菜单路径：tcm/appointment/list
- 组件路径：tcm/appointment/list
- 权限标识：doctor.appointment/lists
- 菜单图标：Calendar（或 el-icon-calendar）
- 排序：根据需要设置
- 是否显示：是
- 是否缓存：是

### 2. 配置权限节点

在"权限管理"中为该菜单添加操作权限：

| 权限名称 | 权限标识 | 说明 |
|---------|---------|------|
| 挂号列表 | doctor.appointment/lists | 查看挂号列表 |
| 挂号详情 | doctor.appointment/detail | 查看挂号详情 |
| 取消挂号 | doctor.appointment/cancel | 取消挂号 |
| 完成挂号 | doctor.appointment/complete | 完成挂号 |

### 3. 分配权限

在"角色管理"中，为相应的角色分配上述权限。

## API接口文档

### 1. 获取挂号列表
```
GET /doctor.appointment/lists

请求参数：
{
  page_no: number,          // 页码
  page_size: number,        // 每页数量
  patient_name?: string,    // 患者姓名（模糊搜索）
  doctor_name?: string,     // 医生姓名（模糊搜索）
  status?: number,          // 状态：1=已预约，2=已取消，3=已完成
  start_date?: string,      // 开始日期 YYYY-MM-DD
  end_date?: string         // 结束日期 YYYY-MM-DD
}

返回数据：
{
  code: 1,
  msg: "success",
  data: {
    lists: [
      {
        id: number,
        patient_id: number,
        patient_name: string,
        patient_phone: string,
        doctor_id: number,
        doctor_name: string,
        appointment_date: string,
        appointment_time: string,
        period: string,
        appointment_type: string,
        appointment_type_desc: string,
        status: number,
        status_desc: string,
        remark: string,
        create_time: string,
        update_time: string
      }
    ],
    count: number,
    page_no: number,
    page_size: number
  }
}
```

### 2. 获取挂号详情
```
GET /doctor.appointment/detail

请求参数：
{
  id: number  // 挂号ID
}

返回数据：同列表项结构
```

### 3. 取消挂号
```
POST /doctor.appointment/cancel

请求参数：
{
  id: number  // 挂号ID
}

返回数据：
{
  code: 1,
  msg: "取消成功"
}
```

### 4. 完成挂号
```
POST /doctor.appointment/complete

请求参数：
{
  id: number  // 挂号ID
}

返回数据：
{
  code: 1,
  msg: "操作成功"
}
```

## 测试步骤

1. **配置菜单和权限**
   - 在后台添加"挂号管理"菜单
   - 配置相应的权限节点
   - 为角色分配权限

2. **测试列表功能**
   - 访问挂号管理页面
   - 验证列表数据正常显示
   - 测试分页功能

3. **测试搜索功能**
   - 按患者姓名搜索
   - 按医生姓名搜索
   - 按状态筛选
   - 按日期范围筛选

4. **测试详情功能**
   - 点击"详情"按钮
   - 验证详情信息完整

5. **测试取消功能**
   - 选择"已预约"状态的挂号
   - 点击"取消"按钮
   - 确认操作
   - 验证状态变为"已取消"

6. **测试完成功能**
   - 选择"已预约"状态的挂号
   - 点击"完成"按钮
   - 确认操作
   - 验证状态变为"已完成"

## 数据库表

确保数据库表 `la_doctor_appointment` 已创建：

```sql
CREATE TABLE `la_doctor_appointment` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `patient_id` int(11) NOT NULL COMMENT '患者ID',
  `doctor_id` int(11) NOT NULL COMMENT '医生ID',
  `roster_id` int(11) NOT NULL COMMENT '排班ID',
  `appointment_date` date NOT NULL COMMENT '预约日期',
  `period` varchar(20) NOT NULL COMMENT '时段',
  `appointment_time` time NOT NULL COMMENT '预约时间',
  `appointment_type` varchar(20) DEFAULT 'video' COMMENT '预约类型',
  `status` tinyint(1) DEFAULT '1' COMMENT '状态：1=已预约，2=已取消，3=已完成',
  `remark` varchar(500) DEFAULT NULL COMMENT '备注',
  `create_time` int(10) unsigned DEFAULT NULL,
  `update_time` int(10) unsigned DEFAULT NULL,
  PRIMARY KEY (`id`),
  KEY `idx_patient` (`patient_id`),
  KEY `idx_doctor_date` (`doctor_id`,`appointment_date`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='医生挂号表';
```

## 注意事项

1. **表前缀**：确保使用正确的表前缀 `la_`
2. **关联表**：
   - `la_user` - 患者表
   - `la_admin` - 医生表（管理员表）
3. **权限控制**：确保用户有相应的权限才能访问
4. **状态流转**：
   - 已预约 → 已取消
   - 已预约 → 已完成
   - 已取消和已完成状态不可逆

## 扩展功能建议

1. **导出功能**：导出挂号列表为Excel
2. **统计报表**：每日挂号统计、医生挂号统计
3. **消息通知**：挂号成功、就诊提醒
4. **批量操作**：批量取消、批量完成
5. **挂号改期**：支持修改预约时间

## 相关文档

- `APPOINTMENT_SYSTEM.md` - 挂号系统总体设计
- `APPOINTMENT_COMPLETE.md` - 挂号功能实现说明
- `APPOINTMENT_PERIOD_FIX.md` - 时间段修复说明