From 13ef10039c2aaf280791b8555a2751ba2f1767a6 Mon Sep 17 00:00:00 2001 From: admin Date: Fri, 12 Dec 2025 17:26:20 +0800 Subject: [PATCH] Initial commit --- BACKEND_API_DOC.md | 106 +++++++++++++++++++++++++++++ FRONTEND_API_DOC.md | 158 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 264 insertions(+) create mode 100644 BACKEND_API_DOC.md create mode 100644 FRONTEND_API_DOC.md diff --git a/BACKEND_API_DOC.md b/BACKEND_API_DOC.md new file mode 100644 index 0000000..7bdc54b --- /dev/null +++ b/BACKEND_API_DOC.md @@ -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。Header: `Authorization: Bearer ` (登录后获取) + +## 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 +``` + +**Response:** +```json +{ + "count": 100, + "next": "...", + "previous": null, + "results": [ + { "id": 1, "title": "MBA项目", ... } + ] +} +``` diff --git a/FRONTEND_API_DOC.md b/FRONTEND_API_DOC.md new file mode 100644 index 0000000..fb21159 --- /dev/null +++ b/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 + +``` + +### 2.4 请求拦截器 (Interceptors) + +位置：`src/utils/request.js` + +- **Request Interceptor**: 自动添加 `Authorization: Bearer ` +- **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] }`