Initial commit
This commit is contained in:
admin
106
BACKEND_API_DOC.md
Normal file
106
BACKEND_API_DOC.md
Normal file
@@ -0,0 +1,106 @@
|
|||||||
|
# 后端接口文档 (Backend API Documentation)
|
||||||
|
|
||||||
|
## 1. 概述 (Overview)
|
||||||
|
|
||||||
|
本接口文档描述了系统的后端API接口，主要包含 CRM（小程序业务）模块和 System（系统管理）模块。
|
||||||
|
|
||||||
|
- **基础路径 (Base URL)**: `http://localhost:8000/api` (开发环境)
|
||||||
|
- **认证方式 (Authentication)**:
|
||||||
|
- 管理后台：JWT (JSON Web Token)。Header: `Authorization: Bearer <token>`
|
||||||
|
- 小程序：自定义Token。Header: `Authorization: Bearer <token>` (登录后获取)
|
||||||
|
|
||||||
|
## 2. 通用响应格式 (Common Response Format)
|
||||||
|
|
||||||
|
接口通常返回 JSON 格式数据，结构如下：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200, // 状态码，200 表示成功
|
||||||
|
"msg": "success", // 提示信息
|
||||||
|
"data": { ... } // 业务数据
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. CRM 模块 (Mini Program & Business)
|
||||||
|
|
||||||
|
该模块主要用于微信小程序业务及后台对业务数据的管理。
|
||||||
|
路径前缀：`/api/`
|
||||||
|
|
||||||
|
### 3.1 用户认证 (Authentication)
|
||||||
|
|
||||||
|
| 接口路径 | 方法 | 描述 | 参数示例 |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| `/auth/login/` | POST | 小程序登录，换取Token | `{ "code": "js_code" }` |
|
||||||
|
|
||||||
|
### 3.2 用户信息 (User Profile)
|
||||||
|
|
||||||
|
| 接口路径 | 方法 | 描述 | 参数/说明 |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| `/user/` | GET | 获取当前用户信息 | Header需带Token |
|
||||||
|
| `/user/phone/` | POST | 更新/绑定手机号 | `{ "code": "phone_code" }` |
|
||||||
|
| `/user-coupons/` | GET | 获取当前用户的优惠券 | |
|
||||||
|
| `/user-projects/` | GET | 获取当前用户的项目 | |
|
||||||
|
| `/user-honors/` | GET | 获取当前用户的荣誉 | |
|
||||||
|
|
||||||
|
### 3.3 业务资源 (Resources)
|
||||||
|
|
||||||
|
支持标准的 CRUD 操作。
|
||||||
|
|
||||||
|
| 资源名称 | 路径 | 方法 | 描述 |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| **项目 (Projects)** | `/projects/` | GET, POST, PUT, DELETE | 学位项目、活动等 |
|
||||||
|
| **分类 (Categories)** | `/categories/` | GET, POST, PUT, DELETE | 项目分类 |
|
||||||
|
| **教师 (Teachers)** | `/teachers/` | GET, POST, PUT, DELETE | 师资力量 |
|
||||||
|
| **教学中心 (Centers)** | `/teaching-centers/` | GET, POST, PUT, DELETE | 教学点 |
|
||||||
|
| **优惠券 (Coupons)** | `/coupons/` | GET, POST, PUT, DELETE | 优惠券定义 |
|
||||||
|
| **可领优惠券** | `/available-coupons/` | GET | 获取可领取的优惠券列表 |
|
||||||
|
| **轮播图 (Banners)** | `/banners/` | GET, POST, PUT, DELETE | 首页轮播图 |
|
||||||
|
| **学员 (Students)** | `/students/` | GET, POST, PUT, DELETE | 学员信息管理 |
|
||||||
|
| **学员项目** | `/student-projects/` | GET, POST, PUT, DELETE | 学员报名的项目 |
|
||||||
|
| **学员优惠券** | `/student-coupons/` | GET, POST, PUT, DELETE | 学员持有的优惠券 |
|
||||||
|
| **学员荣誉** | `/student-honors/` | GET, POST, PUT, DELETE | 学员获得的荣誉 |
|
||||||
|
| **精彩展示** | `/student-showcases/` | GET, POST, PUT, DELETE | 视频或图片展示 |
|
||||||
|
| **通知 (Notifications)**| `/notifications/` | GET, POST, PUT, DELETE | 系统通知 |
|
||||||
|
|
||||||
|
### 3.4 仪表盘 (Dashboard)
|
||||||
|
|
||||||
|
| 接口路径 | 方法 | 描述 |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| `/dashboard/stats/` | GET | 获取后台首页统计数据 |
|
||||||
|
|
||||||
|
## 4. System 模块 (System Management)
|
||||||
|
|
||||||
|
该模块用于后台系统权限、用户及配置管理。
|
||||||
|
路径前缀：`/api/system/`
|
||||||
|
|
||||||
|
| 资源名称 | 路径 | 方法 | 描述 |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| **系统用户** | `/user/` | GET, POST, PUT, DELETE | 后台管理员 |
|
||||||
|
| **角色** | `/role/` | GET, POST, PUT, DELETE | 角色与权限组 |
|
||||||
|
| **权限** | `/permission/` | GET, POST, PUT, DELETE | 菜单及按钮权限 |
|
||||||
|
| **组织架构** | `/organization/` | GET, POST, PUT, DELETE | 部门管理 |
|
||||||
|
| **岗位** | `/position/` | GET, POST, PUT, DELETE | 岗位管理 |
|
||||||
|
| **字典** | `/dict/` | GET, POST, PUT, DELETE | 数据字典 |
|
||||||
|
| **文件** | `/file/` | POST, DELETE | 文件上传与管理 |
|
||||||
|
|
||||||
|
## 5. 使用示例 (Usage Examples)
|
||||||
|
|
||||||
|
### 获取项目列表 (Get Projects)
|
||||||
|
|
||||||
|
**Request:**
|
||||||
|
```http
|
||||||
|
GET /api/projects/?page=1&size=10 HTTP/1.1
|
||||||
|
Authorization: Bearer <your_token>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"count": 100,
|
||||||
|
"next": "...",
|
||||||
|
"previous": null,
|
||||||
|
"results": [
|
||||||
|
{ "id": 1, "title": "MBA项目", ... }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
158
FRONTEND_API_DOC.md
Normal file
158
FRONTEND_API_DOC.md
Normal file
@@ -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] }`
|
||||||
Reference in New Issue
Block a user