# 医生预约系统后端安装说明

## 文件清单

已创建以下后端文件：

### 1. 数据库模型
- `server/app/common/model/doctor/Appointment.php` - 预约模型

### 2. 控制器
- `server/app/adminapi/controller/doctor/AppointmentController.php` - 预约控制器

### 3. 业务逻辑层
- `server/app/adminapi/logic/doctor/AppointmentLogic.php` - 预约业务逻辑

### 4. 验证器
- `server/app/adminapi/validate/doctor/AppointmentValidate.php` - 预约数据验证

### 5. 数据列表
- `server/app/adminapi/lists/doctor/AppointmentLists.php` - 预约列表

### 6. 数据库脚本
- `server/sql/doctor_appointment.sql` - 数据库表创建脚本

## 安装步骤

### 1. 创建数据库表

在MySQL中执行以下SQL脚本：

```bash
mysql -u your_username -p your_database < server/sql/doctor_appointment.sql
```

或者在phpMyAdmin中导入 `server/sql/doctor_appointment.sql` 文件。

### 2. 验证文件

确认所有文件已正确创建：

```bash
# 检查模型
ls -la server/app/common/model/doctor/Appointment.php

# 检查控制器
ls -la server/app/adminapi/controller/doctor/AppointmentController.php

# 检查逻辑层
ls -la server/app/adminapi/logic/doctor/AppointmentLogic.php

# 检查验证器
ls -la server/app/adminapi/validate/doctor/AppointmentValidate.php

# 检查列表
ls -la server/app/adminapi/lists/doctor/AppointmentLists.php
```

### 3. 清除缓存

```bash
cd server
php think clear
```

### 4. 测试API接口

#### 4.1 获取可用时间段

```bash
GET /adminapi/doctor.appointment/availableSlots?doctor_id=1&appointment_date=2026-03-04&period=morning
```

预期返回：
```json
{
  "code": 1,
  "msg": "success",
  "data": {
    "slots": [
      {
        "time": "09:00",
        "available": true,
        "quota": 5
      },
      ...
    ]
  }
}
```

#### 4.2 创建预约

```bash
POST /adminapi/doctor.appointment/create
Content-Type: application/json

{
  "patient_id": 1,
  "doctor_id": 1,
  "appointment_date": "2026-03-04",
  "period": "morning",
  "appointment_time": "09:00",
  "appointment_type": "video",
  "remark": "测试预约"
}
```

预期返回：
```json
{
  "code": 1,
  "msg": "预约成功",
  "data": {
    "id": 1
  }
}
```

#### 4.3 获取预约列表

```bash
GET /adminapi/doctor.appointment/lists?page_no=1&page_size=10
```

#### 4.4 取消预约

```bash
POST /adminapi/doctor.appointment/cancel
Content-Type: application/json

{
  "id": 1
}
```

#### 4.5 获取医生可用号源数

```bash
GET /adminapi/doctor.appointment/doctorAvailability?doctor_id=1&date=2026-03-04
```

预期返回：
```json
{
  "code": 1,
  "msg": "success",
  "data": {
    "available_count": 10
  }
}
```

## API接口说明

### 1. 获取可用时间段

**接口地址**: `/adminapi/doctor.appointment/availableSlots`

**请求方式**: GET

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| doctor_id | int | 是 | 医生ID |
| appointment_date | date | 是 | 预约日期 YYYY-MM-DD |
| period | string | 是 | 时段 morning/afternoon |

**返回数据**:
```json
{
  "slots": [
    {
      "time": "09:00",
      "available": true,
      "quota": 5
    }
  ]
}
```

### 2. 创建预约

**接口地址**: `/adminapi/doctor.appointment/create`

**请求方式**: POST

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| patient_id | int | 是 | 患者ID |
| doctor_id | int | 是 | 医生ID |
| appointment_date | date | 是 | 预约日期 |
| period | string | 是 | 时段 morning/afternoon |
| appointment_time | time | 是 | 预约时间 HH:mm |
| appointment_type | string | 否 | 预约类型 video/text/phone |
| remark | string | 否 | 备注 |

**返回数据**:
```json
{
  "id": 1
}
```

### 3. 取消预约

**接口地址**: `/adminapi/doctor.appointment/cancel`

**请求方式**: POST

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 预约ID |

### 4. 预约列表

**接口地址**: `/adminapi/doctor.appointment/lists`

**请求方式**: GET

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page_no | int | 否 | 页码 |
| page_size | int | 否 | 每页数量 |
| patient_id | int | 否 | 患者ID |
| doctor_id | int | 否 | 医生ID |
| status | int | 否 | 状态 |
| appointment_date | date | 否 | 预约日期 |

### 5. 预约详情

**接口地址**: `/adminapi/doctor.appointment/detail`

**请求方式**: GET

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 预约ID |

### 6. 医生可用号源数

**接口地址**: `/adminapi/doctor.appointment/doctorAvailability`

**请求方式**: GET

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| doctor_id | int | 是 | 医生ID |
| date | date | 是 | 日期 YYYY-MM-DD |

## 业务逻辑说明

### 1. 时间段生成规则

- 上午时段：09:00 - 11:30（30分钟间隔）
- 下午时段：13:00 - 20:30（30分钟间隔）

### 2. 预约规则

1. 必须有医生排班且状态为"出诊"（status=1）
2. 时间段不能重复预约
3. 预约数量不能超过排班设置的号源数（quota）
4. 使用数据库唯一索引防止并发冲突

### 3. 状态说明

**预约状态**:
- 1: 已预约
- 2: 已取消
- 3: 已完成

**排班状态**:
- 1: 出诊
- 2: 停诊
- 3: 休息
- 4: 请假

## 注意事项

1. **并发控制**: 使用数据库唯一索引 `unique_appointment` 防止重复预约
2. **事务处理**: 创建预约时使用事务确保数据一致性
3. **时间格式**: 
   - 日期格式：YYYY-MM-DD
   - 时间格式：HH:mm
   - 时间戳：整型（秒）
4. **权限控制**: 需要在后台权限管理中添加相应的权限节点

## 权限节点

建议添加以下权限节点：

```
doctor.appointment/availableSlots - 查看可用时间段
doctor.appointment/create - 创建预约
doctor.appointment/cancel - 取消预约
doctor.appointment/lists - 预约列表
doctor.appointment/detail - 预约详情
doctor.appointment/doctorAvailability - 医生可用号源
```

## 故障排查

### 1. 控制器不存在

**错误**: `控制器不存在: app\adminapi\controller\doctor\AppointmentController`

**解决方案**:
```bash
# 清除缓存
cd server
php think clear

# 检查文件是否存在
ls -la server/app/adminapi/controller/doctor/AppointmentController.php

# 检查命名空间是否正确
head -n 5 server/app/adminapi/controller/doctor/AppointmentController.php
```

### 2. 数据库表不存在

**错误**: `Table 'database.la_doctor_appointment' doesn't exist`

**解决方案**:
```bash
# 执行SQL脚本
mysql -u username -p database < server/sql/doctor_appointment.sql

# 或在MySQL中手动执行
mysql> source /path/to/server/sql/doctor_appointment.sql;
```

### 3. 参数验证失败

**错误**: `参数错误`

**解决方案**:
- 检查请求参数是否完整
- 检查参数类型是否正确
- 查看验证器规则是否匹配

## 测试数据

### 创建测试排班

```sql
INSERT INTO `la_doctor_roster` (`doctor_id`, `date`, `period`, `status`, `quota`, `max_patients`, `create_time`, `update_time`)
VALUES
(1, '2026-03-04', 'morning', 1, 10, 15, UNIX_TIMESTAMP(), UNIX_TIMESTAMP()),
(1, '2026-03-04', 'afternoon', 1, 10, 15, UNIX_TIMESTAMP(), UNIX_TIMESTAMP());
```

### 创建测试预约

```sql
INSERT INTO `la_doctor_appointment` (`patient_id`, `doctor_id`, `roster_id`, `appointment_date`, `period`, `appointment_time`, `appointment_type`, `status`, `create_time`, `update_time`)
VALUES
(1, 1, 1, '2026-03-04', 'morning', '09:00:00', 'video', 1, UNIX_TIMESTAMP(), UNIX_TIMESTAMP());
```

## 完成状态

✅ 数据库模型创建完成
✅ 控制器创建完成
✅ 业务逻辑层创建完成
✅ 验证器创建完成
✅ 数据列表创建完成
✅ SQL脚本创建完成
⏳ 等待数据库表创建
⏳ 等待接口测试

---

**创建时间**: 2024-02-26
**最后更新**: 2024-02-26