a
This commit is contained in:
Ubuntu
@@ -0,0 +1,605 @@
|
||||
# API 接口文档
|
||||
|
||||
## 1. 接口规范
|
||||
|
||||
### 1.1 基础信息
|
||||
|
||||
| 项 | 值 |
|
||||
|----|-----|
|
||||
| 基础 URL | `''`（相对路径，通过 Vite 代理转发） |
|
||||
| 后端地址 | `http://localhost:10003` |
|
||||
| 协议 | HTTP/HTTPS |
|
||||
| 数据格式 | JSON |
|
||||
| 字符编码 | UTF-8 |
|
||||
|
||||
**注意：** 前端开发环境使用相对路径调用 API，Vite 代理将 `/api`、`/uploads`、`/storage` 转发到后端服务。生产环境通过 Nginx 统一代理。
|
||||
|
||||
### 1.2 响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
### 1.3 错误码
|
||||
|
||||
| 码 | 说明 |
|
||||
|----|------|
|
||||
| 200 | 成功 |
|
||||
| 400 | 请求参数错误 |
|
||||
| 401 | 未认证/Token过期 |
|
||||
| 403 | 无权限 |
|
||||
| 404 | 资源不存在 |
|
||||
| 500 | 服务器内部错误 |
|
||||
|
||||
### 1.4 认证方式
|
||||
|
||||
管理员接口需要在请求头携带 Token：
|
||||
|
||||
```
|
||||
Authorization: Bearer <jwt_token>
|
||||
```
|
||||
|
||||
## 2. 认证接口
|
||||
|
||||
### 2.1 管理员登录
|
||||
|
||||
```http
|
||||
POST /api/auth/login
|
||||
```
|
||||
|
||||
**请求体：**
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "admin123"
|
||||
}
|
||||
```
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "登录成功",
|
||||
"data": {
|
||||
"token": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"admin": {
|
||||
"id": 1,
|
||||
"username": "admin"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 获取当前管理员信息
|
||||
|
||||
```http
|
||||
GET /api/auth/me
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"id": 1,
|
||||
"username": "admin"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 修改密码
|
||||
|
||||
```http
|
||||
POST /api/auth/change-password
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**请求体：**
|
||||
```json
|
||||
{
|
||||
"old_password": "oldpass",
|
||||
"new_password": "newpass"
|
||||
}
|
||||
```
|
||||
|
||||
## 3. 前台接口（无需认证）
|
||||
|
||||
### 3.1 获取首页模块
|
||||
|
||||
```http
|
||||
GET /api/home/modules
|
||||
```
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "轮播图",
|
||||
"code": "banner",
|
||||
"type": "banner",
|
||||
"title": "",
|
||||
"subtitle": "",
|
||||
"content": {
|
||||
"slides": [
|
||||
{
|
||||
"image": "/uploads/banner1.jpg",
|
||||
"link": "/product",
|
||||
"title": "手机就能做尿检"
|
||||
}
|
||||
]
|
||||
},
|
||||
"style_config": {
|
||||
"backgroundColor": "#ffffff",
|
||||
"paddingTop": "0",
|
||||
"paddingBottom": "0"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 获取导航菜单
|
||||
|
||||
```http
|
||||
GET /api/nav
|
||||
```
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "首页",
|
||||
"link": "/",
|
||||
"is_external": false,
|
||||
"children": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 获取系统设置
|
||||
|
||||
```http
|
||||
GET /api/settings
|
||||
```
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"site_name": "飞点健康",
|
||||
"site_logo": "/logo.png",
|
||||
"company_phone": "400-xxx-xxxx",
|
||||
"icp": "粤ICP备xxxxxxxx号"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 后台管理接口（需要认证）
|
||||
|
||||
### 4.1 首页模块管理
|
||||
|
||||
#### 获取所有模块（后台）
|
||||
|
||||
```http
|
||||
GET /api/admin/home/modules
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应：** 包含未启用的模块
|
||||
|
||||
#### 获取单个模块详情
|
||||
|
||||
```http
|
||||
GET /api/admin/home/modules/:id
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
#### 更新模块
|
||||
|
||||
```http
|
||||
PUT /api/admin/home/modules/:id
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求体：**
|
||||
```json
|
||||
{
|
||||
"title": "新的标题",
|
||||
"subtitle": "副标题",
|
||||
"content": {
|
||||
"slides": [
|
||||
{"image": "/uploads/banner.jpg", "link": "/", "title": "标题"}
|
||||
]
|
||||
},
|
||||
"style_config": {
|
||||
"backgroundColor": "#FEF9E7",
|
||||
"paddingTop": "60px"
|
||||
},
|
||||
"is_enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
#### 更新模块排序
|
||||
|
||||
```http
|
||||
PUT /api/admin/home/modules/sort
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求体：**
|
||||
```json
|
||||
{
|
||||
"orders": [
|
||||
{"id": 1, "sort_order": 1},
|
||||
{"id": 2, "sort_order": 2},
|
||||
{"id": 3, "sort_order": 3}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 切换模块启用状态
|
||||
|
||||
```http
|
||||
PUT /api/admin/home/modules/:id/toggle
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"id": 1,
|
||||
"is_enabled": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 导航菜单管理
|
||||
|
||||
#### 获取菜单列表
|
||||
|
||||
```http
|
||||
GET /api/admin/nav
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
#### 创建菜单
|
||||
|
||||
```http
|
||||
POST /api/admin/nav
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求体：**
|
||||
```json
|
||||
{
|
||||
"name": "新菜单",
|
||||
"link": "/new-page",
|
||||
"sort_order": 6,
|
||||
"is_enabled": true,
|
||||
"is_external": false
|
||||
}
|
||||
```
|
||||
|
||||
#### 更新菜单
|
||||
|
||||
```http
|
||||
PUT /api/admin/nav/:id
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
#### 删除菜单
|
||||
|
||||
```http
|
||||
DELETE /api/admin/nav/:id
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 4.3 系统设置管理
|
||||
|
||||
#### 获取所有设置
|
||||
|
||||
```http
|
||||
GET /api/admin/settings
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
#### 更新设置
|
||||
|
||||
```http
|
||||
PUT /api/admin/settings
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求体：**
|
||||
```json
|
||||
{
|
||||
"site_name": "新名称",
|
||||
"company_phone": "新电话"
|
||||
}
|
||||
```
|
||||
|
||||
### 4.4 图片资源管理
|
||||
|
||||
#### 获取图片列表
|
||||
|
||||
```http
|
||||
GET /api/images?page=1&size=20&module=news
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数：**
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| page | int | 页码，默认 1 |
|
||||
| size | int | 每页数量，默认 20，最大 100 |
|
||||
| module | string | 按模块筛选（可选：news/product/page） |
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"id": 1,
|
||||
"filename": "20260421_182026_df70a127.jpg",
|
||||
"original_name": "photo.jpg",
|
||||
"file_path": "/storage/admin/images/20260421_182026_df70a127.jpg",
|
||||
"thumb_path": "/storage/admin/images/thumbnails/20260421_182026_df70a127.jpg",
|
||||
"description": null,
|
||||
"file_size": 547343,
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"module": "news",
|
||||
"created_at": "2026-04-21T18:20:26"
|
||||
}
|
||||
],
|
||||
"total": 100,
|
||||
"page": 1,
|
||||
"size": 20
|
||||
}
|
||||
```
|
||||
|
||||
#### 上传图片
|
||||
|
||||
```http
|
||||
POST /api/images/upload
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
**表单字段：**
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| file | File | 图片文件（jpg, jpeg, png, gif, webp, bmp，最大 10MB） |
|
||||
| description | string | 图片描述（可选） |
|
||||
| module | string | 所属模块，默认 `news` |
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": 1,
|
||||
"filename": "20260421_182026_df70a127.jpg",
|
||||
"original_name": "photo.jpg",
|
||||
"file_path": "/storage/admin/images/20260421_182026_df70a127.jpg",
|
||||
"thumb_path": "/storage/admin/images/thumbnails/20260421_182026_df70a127.jpg",
|
||||
"file_size": 547343,
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"module": "news",
|
||||
"created_at": "2026-04-21T18:20:26"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**缩略图规则：**
|
||||
- 上传成功后自动创建缩略图
|
||||
- 缩略图尺寸：最大 300x300 像素，等比缩放
|
||||
- 缩略图格式：统一为 JPEG，质量 85%
|
||||
- 缩略图命名：与原图同名，扩展名统一为 `.jpg`
|
||||
- 缩略图路径：`/storage/admin/images/thumbnails/`
|
||||
|
||||
#### 更新图片描述
|
||||
|
||||
```http
|
||||
PUT /api/images/{image_id}
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
**表单字段：**
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| description | string | 新的图片描述 |
|
||||
|
||||
#### 删除图片
|
||||
|
||||
```http
|
||||
DELETE /api/images/{image_id}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**删除规则：**
|
||||
- 删除数据库记录
|
||||
- 同步删除物理文件（原图 + 缩略图）
|
||||
- 外部 URL 跳过删除（仅删除数据库记录）
|
||||
|
||||
#### 批量删除图片
|
||||
|
||||
```http
|
||||
POST /api/images/batch-delete
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求体：**
|
||||
```json
|
||||
[1, 2, 3]
|
||||
```
|
||||
|
||||
#### 获取图片插入信息
|
||||
|
||||
```http
|
||||
GET /api/images/{image_id}/insert?size=original
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数：**
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| size | string | `original` 或 `thumb`，默认 `original` |
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"url": "/storage/admin/images/xxx.jpg",
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"original_name": "photo.jpg"
|
||||
}
|
||||
```
|
||||
|
||||
### 4.5 新闻资讯管理
|
||||
|
||||
#### 栏目管理
|
||||
|
||||
```http
|
||||
GET /api/news/categories # 获取栏目列表
|
||||
POST /api/news/categories # 创建栏目
|
||||
GET /api/news/categories/{id} # 获取栏目详情
|
||||
PUT /api/news/categories/{id} # 更新栏目
|
||||
DELETE /api/news/categories/{id} # 删除栏目
|
||||
```
|
||||
|
||||
**创建栏目请求体：**
|
||||
```json
|
||||
{
|
||||
"name": "公司新闻",
|
||||
"slug": "company-news",
|
||||
"description": "公司动态和新闻",
|
||||
"sort_order": 1,
|
||||
"is_enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
#### 资讯管理
|
||||
|
||||
```http
|
||||
GET /api/news/posts?page=1&size=10&category_id=1&keyword=xxx&status=all # 获取资讯列表
|
||||
POST /api/news/posts # 创建资讯
|
||||
GET /api/news/posts/{post_id} # 获取资讯详情
|
||||
PUT /api/news/posts/{post_id} # 更新资讯
|
||||
DELETE /api/news/posts/{post_id} # 删除资讯
|
||||
POST /api/news/posts/{post_id}/publish # 发布/取消发布
|
||||
```
|
||||
|
||||
**创建资讯请求体：**
|
||||
```json
|
||||
{
|
||||
"title": "文章标题",
|
||||
"slug": "article-slug",
|
||||
"content": "# Markdown 内容\n\n正文...",
|
||||
"content_type": "markdown",
|
||||
"summary": "文章摘要（可选，未提供时自动提取前100字）",
|
||||
"cover_image": "/storage/admin/images/xxx.jpg",
|
||||
"category_id": 1,
|
||||
"is_draft": true
|
||||
}
|
||||
```
|
||||
|
||||
**删除资讯规则：**
|
||||
- 删除数据库记录
|
||||
- 同步删除封面图及其缩略图（如果存在）
|
||||
|
||||
#### 访客端接口（无需认证）
|
||||
|
||||
```http
|
||||
GET /api/news/public/posts?category_slug=xxx&page=1&size=10 # 获取已发布资讯列表
|
||||
GET /api/news/public/posts/{slug} # 通过 slug 获取文章详情
|
||||
GET /api/news/public/categories # 获取启用的栏目列表
|
||||
```
|
||||
|
||||
### 4.6 通用文件上传
|
||||
|
||||
#### 上传图片（兼容旧接口）
|
||||
|
||||
```http
|
||||
POST /api/upload/image
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
**表单字段：**
|
||||
- `file`: 图片文件 (jpg, png, gif, webp, max 5MB)
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "上传成功",
|
||||
"data": {
|
||||
"url": "/storage/admin/images/20260421_xxx.jpg",
|
||||
"filename": "20260421_xxx.jpg",
|
||||
"size": 12345,
|
||||
"thumb_url": "/storage/admin/images/thumbnails/20260421_xxx.jpg"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 图片存储规范
|
||||
|
||||
### 5.1 存储目录结构
|
||||
|
||||
```
|
||||
storage/
|
||||
├── admin/
|
||||
│ └── images/ # 管理员上传的图片
|
||||
│ ├── thumbnails/ # 缩略图目录
|
||||
│ ├── banners/ # 轮播图（手动维护）
|
||||
│ ├── features/ # 特色展示图（手动维护）
|
||||
│ └── 202604/ # 按月分组的旧文件
|
||||
└── public/ # 公开访问的文件（预留）
|
||||
```
|
||||
|
||||
### 5.2 静态文件挂载
|
||||
|
||||
| URL 路径 | 物理路径 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `/uploads` | `storage/admin/images` | 兼容旧路径，与 `/storage/admin/images` 指向同一目录 |
|
||||
| `/storage/admin` | `storage/admin` | 管理员文件根目录 |
|
||||
| `/storage/public` | `storage/public` | 公开文件目录 |
|
||||
|
||||
### 5.3 图片 URL 格式
|
||||
|
||||
| 类型 | URL 格式 | 示例 |
|
||||
|------|----------|------|
|
||||
| 原图 | `/storage/admin/images/{filename}` | `/storage/admin/images/20260421_xxx.jpg` |
|
||||
| 缩略图 | `/storage/admin/images/thumbnails/{filename}.jpg` | `/storage/admin/images/thumbnails/20260421_xxx.jpg` |
|
||||
|
||||
## 6. Swagger 文档
|
||||
|
||||
启动后端后，访问以下地址查看自动生成的 API 文档：
|
||||
|
||||
- Swagger UI: `http://localhost:10003/docs`
|
||||
- ReDoc: `http://localhost:10003/redoc`
|
||||
Reference in New Issue
Block a user