# Appointment · 预约挂号

## 接口表

| Method | Path | 鉴权 | 说明 |
|---|---|---|---|
| GET | `/api/v1/appointments` | - | 预约列表 |
| GET | `/api/v1/appointments/stats` | ✅ | 统计 |
| GET | `/api/v1/appointments/:id` | - | 详情 |
| POST | `/api/v1/appointments` | - | 创建 |
| PUT | `/api/v1/appointments/:id/cancel` | - | 取消 |
| PUT | `/api/v1/appointments/:id/confirm` | ✅ | 确认（管理后台） |
| PUT | `/api/v1/appointments/:id/complete` | ✅ | 完成（管理后台） |
| PUT | `/api/v1/appointments/:id` | ✅ | 更新备注 |
| DELETE | `/api/v1/appointments/admin/:id` | ✅ | 删除（管理后台） |

## GET /api/v1/appointments

**Query**
- `phone` - 按手机号过滤
- `status` - 'pending' / 'confirmed' / 'completed' / 'cancelled'

## POST /api/v1/appointments

**请求体**
```json
{
  "patientName": "张三",
  "patientAge": 30,
  "patientPhone": "13800138000",
  "date": "2026-06-14",
  "departmentName": "肛肠",
  "doctorId": "doc-001",
  "doctorName": "李医生",
  "timeSlot": "上午",
  "symptom": "便血"
}
```

**校验规则**
- `patientName` 必填，长度 1-20
- `patientAge` 必填，1-149
- `patientPhone` 必填，匹配 `^1[3-9]\d{9}$`
- `date` 必填，ISO 日期 `YYYY-MM-DD`
- `departmentName` 必填，仅支持 `肛肠` / `胃肠`
- `doctorId` / `doctorName` / `timeSlot` / `symptom` 可选

**错误码**
- 400 缺少必填参数
- 400 手机号格式不正确
- 400 年龄参数错误
- 400 科室参数仅支持：肛肠 / 胃肠
- 500 服务器内部错误

## 状态机

```
pending  ──confirm──►  confirmed  ──complete──►  completed
   │                       │
   └─cancel──► cancelled  └─cancel──► cancelled
```

completed 状态不可取消；cancelled 状态不可确认/完成。