# 医生API接口文档

## 概述

本文档描述了医生相关的API接口，用于小程序首页展示医生列表和医生详情。

## 后端实现

### 1. 医生逻辑层 (DoctorLogic)

**文件位置**: `server/app/api/logic/DoctorLogic.php`

主要方法：
- `getDoctorList($params)` - 获取医生列表
- `getDoctorDetail($doctorId)` - 获取医生详情
- `getDoctorRoster($doctorId, $date)` - 获取医生排班

### 2. 医生控制器 (DoctorController)

**文件位置**: `server/app/api/controller/DoctorController.php`

提供以下API端点：
- `GET /api/doctor/lists` - 获取医生列表
- `GET /api/doctor/detail` - 获取医生详情
- `GET /api/doctor/roster` - 获取医生排班

### 3. 数据来源

医生数据来自 `zyt_admin` 表，筛选条件：
- `role_id = 1`（医生角色）
- `disable = 0`（未禁用）

## API 接口详情

### 1. 获取医生列表

**请求**:
```
GET /api/doctor/lists
```

**参数**:
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| page_no | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认10 |
| keyword | string | 否 | 搜索关键词（医生名字或账号） |

**响应示例**:
```json
{
  "code": 1,
  "msg": "success",
  "data": {
    "lists": [
      {
        "id": 1,
        "name": "张医生",
        "account": "doctor1",
        "avatar": "http://example.com/avatar.jpg",
        "mobile": "13800138000",
        "email": "doctor@example.com",
        "specialty": "医生",
        "title": "医生",
        "rating": "4.8"
      }
    ],
    "count": 10,
    "page_no": 1,
    "page_size": 10
  }
}
```

### 2. 获取医生详情

**请求**:
```
GET /api/doctor/detail
```

**参数**:
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| id | int | 是 | 医生ID |

**响应示例**:
```json
{
  "code": 1,
  "msg": "success",
  "data": {
    "id": 1,
    "name": "张医生",
    "account": "doctor1",
    "avatar": "http://example.com/avatar.jpg",
    "mobile": "13800138000",
    "email": "doctor@example.com",
    "specialty": "医生",
    "title": "医生",
    "rating": "4.8"
  }
}
```

### 3. 获取医生排班

**请求**:
```
GET /api/doctor/roster
```

**参数**:
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| doctor_id | int | 是 | 医生ID |
| date | string | 是 | 日期（YYYY-MM-DD格式） |

**响应示例**:
```json
{
  "code": 1,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "doctor_id": 1,
      "date": "2024-03-11",
      "period": "morning",
      "status": 1,
      "quota": 20,
      "max_patients": 30,
      "remark": ""
    }
  ]
}
```

## 前端实现

### 1. API 服务文件

**文件位置**: `TUICallKit-Vue3/utils/api.js`

提供了便捷的API调用方法：
```javascript
import { doctorApi } from '@/utils/api'

// 获取医生列表
const response = await doctorApi.getDoctorList({
  page_no: 1,
  page_size: 10
})

// 获取医生详情
const doctor = await doctorApi.getDoctorDetail(1)

// 获取医生排班
const roster = await doctorApi.getDoctorRoster(1, '2024-03-11')
```

### 2. 小程序首页

**文件位置**: `TUICallKit-Vue3/pages/index/index.vue`

首页会自动加载医生列表并展示：
- 古典卷轴风格幻灯片
- 医生团队卡片（从后端动态加载）
- 点击医生卡片可跳转到挂号页面

## 使用流程

### 后端配置

1. 确保 `zyt_admin` 表中有 `role_id = 1` 的医生记录
2. 医生的 `disable` 字段应为 0（未禁用）
3. 医生的 `avatar` 字段应包含头像URL

### 前端配置

1. 在 `TUICallKit-Vue3/.env` 中配置API基础URL：
```
VUE_APP_API_URL=http://your-api-domain/api
```

2. 首页会自动调用 `doctorApi.getDoctorList()` 获取医生列表

## 扩展功能

### 1. 添加医生专科和职位

修改 `DoctorLogic.php` 中的 `getDoctorList()` 方法，从其他表获取医生的专科和职位信息：

```php
// 可以添加关联查询
$doctor['specialty'] = '内科'; // 从科室表获取
$doctor['title'] = '主任医师'; // 从职位表获取
```

### 2. 添加医生评分

可以从预约或评价表中计算医生的平均评分：

```php
$doctor['rating'] = DoctorRating::where('doctor_id', $doctor['id'])->avg('rating');
```

### 3. 添加医生搜索功能

前端可以调用 `getDoctorList()` 时传入 `keyword` 参数进行搜索。

## 常见问题

### Q: 医生列表为空？
A: 检查 `zyt_admin` 表中是否有 `role_id = 1` 且 `disable = 0` 的记录。

### Q: 头像无法显示？
A: 确保 `avatar` 字段包含完整的URL，或者在 `FileService::getFileUrl()` 中正确处理相对路径。

### Q: 如何添加医生的其他信息？
A: 修改 `DoctorLogic.php` 中的数据处理逻辑，从其他表关联查询所需信息。

## 相关文件

- 后端逻辑: `server/app/api/logic/DoctorLogic.php`
- 后端控制器: `server/app/api/controller/DoctorController.php`
- 前端API服务: `TUICallKit-Vue3/utils/api.js`
- 前端首页: `TUICallKit-Vue3/pages/index/index.vue`
- 医生模型: `server/app/common/model/auth/Admin.php`
- 医生排班模型: `server/app/common/model/doctor/Roster.php`