zyt/MINI_PROGRAM_API_INTEGRATION.md

# 小程序 API 集成总结

## 概述

已完成小程序与后端 API 的集成，使用 `main.js` 中定义的全局 `apiUrl` 方法进行统一的 API 请求管理。

## 核心文件

### 1. 全局配置 (`main.js`)

**位置**: `TUICallKit-Vue3/main.js`

**功能**:
- 定义全局 `baseUrl`：`http://api.zzzhengyangtang.cn`
- 定义全局 `apiUrl` 方法用于发送 HTTP 请求
- 自动处理 token 和请求头
- 自动处理登录失效（code === -1）

**特点**:
- 支持 Vue2 和 Vue3
- 自动显示/隐藏加载中
- 支持自定义请求头
- 15秒超时设置

### 2. API 服务层 (`utils/api.js`)

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

**功能**:
- 封装 `request()` 方法
- 提供 `get()` 和 `post()` 便捷方法
- 定义医生相关 API (`doctorApi`)
- 降级方案：当全局 `apiUrl` 不可用时，直接使用 `uni.request`

**医生 API**:
```javascript
doctorApi.getDoctorList(params)      // 获取医生列表
doctorApi.getDoctorDetail(id)        // 获取医生详情
doctorApi.getDoctorRoster(id, date)  // 获取医生排班
```

### 3. 首页组件 (`pages/index/index.vue`)

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

**功能**:
- 展示古典卷轴风格幻灯片
- 动态加载医生列表
- 医生卡片点击跳转到挂号页面

**流程**:
1. 页面加载时调用 `onMounted()`
2. `onMounted()` 调用 `fetchDoctors()`
3. `fetchDoctors()` 调用 `doctorApi.getDoctorList()`
4. 获取成功后更新 `doctors` 数据
5. 医生卡片自动渲染

## 后端 API 端点

### 医生列表

**请求**:
```
GET /api/doctor/lists?page_no=1&page_size=10
```

**响应**:
```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
  }
}
```

### 医生详情

**请求**:
```
GET /api/doctor/detail?id=1
```

### 医生排班

**请求**:
```
GET /api/doctor/roster?doctor_id=1&date=2024-03-11
```

## 使用示例

### 在组件中使用

```vue
<script setup>
import { ref, onMounted } from 'vue'
import { doctorApi } from '../utils/api'

const doctors = ref([])

const fetchDoctors = async () => {
  try {
    const response = await doctorApi.getDoctorList({
      page_no: 1,
      page_size: 10
    })
    
    if (response.code === 1) {
      doctors.value = response.data.lists || []
    } else {
      uni.showToast({
        title: response.msg || '获取失败',
        icon: 'none'
      })
    }
  } catch (error) {
    console.error('请求失败:', error)
  }
}

onMounted(() => {
  fetchDoctors()
})
</script>
```

## 请求流程

```
组件调用 doctorApi.getDoctorList()
    ↓
调用 get('/api/doctor/lists', params, false)
    ↓
调用 request('/api/doctor/lists', 'GET', params, false)
    ↓
获取全局 apiUrl 方法
    ↓
调用 apiUrl({ url, method, data, header }, loading)
    ↓
main.js 中的 apiUrl 方法处理请求
    ↓
uni.request 发送 HTTP 请求
    ↓
返回响应数据
```

## 错误处理

### 自动处理

1. **登录失效** (code === -1)
   - 自动清除 token
   - 可选：跳转到登录页

2. **网络错误**
   - 自动显示/隐藏加载中
   - 返回错误信息

### 手动处理

```javascript
try {
  const response = await doctorApi.getDoctorList({ page_no: 1 })
  
  if (response.code === 1) {
    // 成功
    console.log(response.data)
  } else if (response.code === -1) {
    // 登录失效
    uni.redirectTo({ url: '/pages/login/login' })
  } else {
    // 其他错误
    uni.showToast({
      title: response.msg || '请求失败',
      icon: 'none'
    })
  }
} catch (error) {
  // 网络错误
  console.error('网络错误:', error)
}
```

## 配置修改

### 修改 API 基础 URL

编辑 `TUICallKit-Vue3/main.js`：

```javascript
var baseUrl = 'http://your-api-domain/api'
```

### 修改超时时间

编辑 `TUICallKit-Vue3/main.js` 中的 `uni.request`：

```javascript
timeout: 20000  // 改为 20 秒
```

### 修改请求头

编辑 `TUICallKit-Vue3/main.js` 中的 `header` 对象：

```javascript
const header = {
  token: token,
  'content-type': 'application/x-www-form-urlencoded',
  'X-Custom-Header': 'custom-value'
}
```

## 扩展功能

### 添加新的 API 模块

在 `TUICallKit-Vue3/utils/api.js` 中添加：

```javascript
export const appointmentApi = {
  getList: (params) => get('/api/appointment/lists', params, false),
  create: (data) => post('/api/appointment/create', data, true),
  cancel: (id) => post('/api/appointment/cancel', { id }, true)
}
```

### 添加文件上传

```javascript
export const uploadFile = (filePath, url) => {
  return new Promise((resolve, reject) => {
    uni.uploadFile({
      url: baseUrl + url,
      filePath: filePath,
      name: 'file',
      header: {
        token: uni.getStorageSync('token')
      },
      success: (res) => {
        resolve(JSON.parse(res.data))
      },
      fail: (err) => {
        reject(err)
      }
    })
  })
}
```

## 常见问题

### Q: 如何修改 API 地址？

A: 编辑 `TUICallKit-Vue3/main.js` 中的 `baseUrl` 变量。

### Q: 如何添加自定义请求头？

A: 在 `TUICallKit-Vue3/main.js` 中的 `header` 对象中添加。

### Q: 如何处理登录失效？

A: 当 `code === -1` 时，自动清除 token，可选择跳转到登录页。

### Q: 如何取消请求？

A: 小程序不支持直接取消请求，可使用标志位实现。

### Q: 如何处理文件上传？

A: 使用 `uni.uploadFile` 而不是 `uni.request`。

## 相关文件

- 全局配置: `TUICallKit-Vue3/main.js`
- API 服务: `TUICallKit-Vue3/utils/api.js`
- 首页组件: `TUICallKit-Vue3/pages/index/index.vue`
- API 配置: `TUICallKit-Vue3/API_CONFIG.md`
- API 使用指南: `TUICallKit-Vue3/API_USAGE_GUIDE.md`
- 后端控制器: `server/app/api/controller/DoctorController.php`
- 后端逻辑: `server/app/api/logic/DoctorLogic.php`

## 总结

已完成小程序与后端 API 的完整集成：

1. ✅ 后端 API 开发（医生列表、详情、排班）
2. ✅ 前端 API 服务层封装
3. ✅ 首页医生列表展示
4. ✅ 错误处理和加载状态
5. ✅ 文档和使用指南

小程序现在可以正常加载和展示医生列表。