# 前端接口文档 (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] }`