更新

2026-03-11 14:33:49 +08:00
parent 38ad60f4bb
commit 08dd9cd307
57 changed files with 9547 additions and 379 deletions
@@ -0,0 +1,310 @@
+# 小程序 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. ✅ 文档和使用指南
+
+小程序现在可以正常加载和展示医生列表。