Initial commit

FRONTEND_API_DOC.md

@@ -0,0 +1,158 @@
+# 前端接口文档 (Frontend API Documentation)
+
+本文档说明如何在前端项目（微信小程序和Web管理后台）中使用接口。
+
+## 1. 微信小程序 (WeChat Mini Program)
+
+小程序目录：`wechat-mini-program/`
+
+### 1.1 请求工具 (Request Utility)
+
+封装文件：`utils/request.js`
+
+该工具自动处理了：
+- Base URL 拼接
+- Token 注入 (Bearer Token)
+- 响应拦截与错误处理
+- 响应数据解包 (Unwrapping `data` field)
+
+### 1.2 使用方法 (Usage)
+
+在页面或组件中引入 `request` 方法：
+
+```javascript
+const { request } = require('../../utils/request')
+// 或者在某些地方通过 app 获取 (如果挂载了)
+// const app = getApp() 
+```
+
+**示例代码：**
+
+```javascript
+// GET 请求
+request({
+  url: '/projects/',
+  method: 'GET',
+  data: { page: 1, page_size: 10 }
+}).then(res => {
+  console.log('项目列表:', res.results)
+}).catch(err => {
+  console.error('获取失败:', err)
+})
+
+// POST 请求
+request({
+  url: '/student-projects/',
+  method: 'POST',
+  data: {
+    project: 1,
+    status: 'enrolled'
+  }
+}).then(res => {
+  wx.showToast({ title: '报名成功' })
+})
+```
+
+### 1.3 常用接口封装
+
+虽然可以直接使用 `request`，但建议在 `api/` 目录下（如果存在）或各页面 JS 中进行简单封装。
+
+目前主要直接在 `pages/` 对应的 `.js` 文件中调用。例如 `pages/index/index.js` 调用 `/banners/` 和 `/projects/`。
+
+---
+
+## 2. Web 管理后台 (Admin Client)
+
+Web 端目录：`admin/client/`
+技术栈：Vue.js + Element UI
+
+### 2.1 接口目录结构
+
+所有 API 请求定义在 `src/api/` 目录下，按模块划分：
+
+- `src/api/crm.js`: 核心业务接口（项目、学员、教师等）
+- `src/api/system/user.js`: 系统用户接口
+- `src/api/login.js`: 登录相关接口
+
+### 2.2 定义接口 (Defining APIs)
+
+以 `src/api/crm.js` 为例：
+
+```javascript
+import request from '@/utils/request'
+
+// 获取教师列表
+export function getTeachers(query) {
+  return request({
+    url: '/teachers/',
+    method: 'get',
+    params: query
+  })
+}
+
+// 创建教师
+export function createTeacher(data) {
+  return request({
+    url: '/teachers/',
+    method: 'post',
+    data
+  })
+}
+```
+
+### 2.3 在组件中使用 (Usage in Components)
+
+在 Vue 组件中引入并调用：
+
+```vue
+<script>
+import { getTeachers, createTeacher } from '@/api/crm'
+
+export default {
+  data() {
+    return {
+      list: [],
+      query: { page: 1, limit: 20 }
+    }
+  },
+  created() {
+    this.fetchData()
+  },
+  methods: {
+    fetchData() {
+      getTeachers(this.query).then(response => {
+        this.list = response.data.results
+        // 注意：根据后端响应拦截器的配置，response 可能已经是 data 部分，
+        // 或者需要访问 response.data。请参考 src/utils/request.js
+      })
+    },
+    handleAdd() {
+      createTeacher(this.form).then(() => {
+        this.$message.success('创建成功')
+        this.fetchData()
+      })
+    }
+  }
+}
+</script>
+```
+
+### 2.4 请求拦截器 (Interceptors)
+
+位置：`src/utils/request.js`
+
+- **Request Interceptor**: 自动添加 `Authorization: Bearer <token>`
+- **Response Interceptor**: 
+  - 统一处理非 200 状态码
+  - 统一处理业务错误码
+  - 登录过期自动登出
+
+## 3. 注意事项 (Notes)
+
+1. **Base URL 配置**:
+   - 小程序：`wechat-mini-program/config/env.js` (或 `app.js`)
+   - Web 后台：`.env.development` 和 `.env.production` 中的 `VUE_APP_BASE_API`
+
+2. **分页 (Pagination)**:
+   - 默认参数：`page` (页码), `limit` 或 `size` (每页数量)
+   - 响应格式：`{ count: Total, results: [Array] }`