all in
This commit is contained in:
@@ -0,0 +1,496 @@
|
||||
# 入口模块管理 API 文档
|
||||
|
||||
## 文档信息
|
||||
|
||||
- **版本**: v1.0
|
||||
- **更新日期**: 2025-11-26
|
||||
- **基础路径**: `/api/v3/entry-modules`
|
||||
- **认证方式**: JWT Bearer Token
|
||||
|
||||
---
|
||||
|
||||
## 接口总览
|
||||
|
||||
| 方法 | 路径 | 说明 | 权限要求 |
|
||||
|------|------|------|---------|
|
||||
| GET | `/entry-modules` | 获取入口模块列表 | 登录用户 |
|
||||
| GET | `/entry-modules/{module_id}` | 获取入口模块详情 | 登录用户 |
|
||||
| POST | `/entry-modules` | 创建入口模块 | 管理员/领导 |
|
||||
| PUT | `/entry-modules/{module_id}` | 更新入口模块 | 管理员/领导 |
|
||||
| DELETE | `/entry-modules/{module_id}` | 删除入口模块 | 管理员/领导 |
|
||||
|
||||
---
|
||||
|
||||
## 数据结构
|
||||
|
||||
### AreaConfig（地区配置）
|
||||
|
||||
```typescript
|
||||
interface AreaConfig {
|
||||
area: string; // 地区名称（如：梅州、云浮、揭阳、潮州）
|
||||
enabled: boolean; // 是否启用（默认 true）
|
||||
sort_order: number; // 排序号（默认 0）
|
||||
}
|
||||
```
|
||||
|
||||
### EntryModule（入口模块）
|
||||
|
||||
```typescript
|
||||
interface EntryModule {
|
||||
id: number; // 模块ID
|
||||
name: string; // 模块名称
|
||||
description: string | null; // 模块描述
|
||||
path: string | null; // 图片存储路径
|
||||
areas: AreaConfig[] | null; // 地区配置列表
|
||||
created_at: string; // 创建时间（ISO 8601格式）
|
||||
updated_at: string; // 更新时间（ISO 8601格式）
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 接口详情
|
||||
|
||||
### 1. 获取入口模块列表
|
||||
|
||||
**接口**: `GET /api/v3/entry-modules`
|
||||
|
||||
**Query参数**:
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| page | int | 否 | 页码（默认1，最小1） |
|
||||
| page_size | int | 否 | 每页数量（默认20，最小1，最大100） |
|
||||
| name | string | 否 | 模块名称（模糊搜索） |
|
||||
| area | string | 否 | 地区筛选（如：梅州、云浮） |
|
||||
|
||||
**请求示例**:
|
||||
```javascript
|
||||
// 获取第1页，每页20条
|
||||
GET /api/v3/entry-modules?page=1&page_size=20
|
||||
|
||||
// 按名称搜索
|
||||
GET /api/v3/entry-modules?name=合同
|
||||
|
||||
// 按地区筛选
|
||||
GET /api/v3/entry-modules?area=梅州
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"total": 10,
|
||||
"page": 1,
|
||||
"page_size": 20,
|
||||
"items": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "合同审查",
|
||||
"description": "合同文档审查入口",
|
||||
"path": "/images/contract-review.png",
|
||||
"areas": [
|
||||
{"area": "梅州", "enabled": true, "sort_order": 1},
|
||||
{"area": "云浮", "enabled": true, "sort_order": 2},
|
||||
{"area": "揭阳", "enabled": false, "sort_order": 3}
|
||||
],
|
||||
"created_at": "2025-01-01T00:00:00",
|
||||
"updated_at": "2025-01-01T00:00:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 获取入口模块详情
|
||||
|
||||
**接口**: `GET /api/v3/entry-modules/{module_id}`
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| module_id | int | 是 | 模块ID |
|
||||
|
||||
**请求示例**:
|
||||
```javascript
|
||||
GET /api/v3/entry-modules/1
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"name": "合同审查",
|
||||
"description": "合同文档审查入口",
|
||||
"path": "/images/contract-review.png",
|
||||
"areas": [
|
||||
{"area": "梅州", "enabled": true, "sort_order": 1},
|
||||
{"area": "云浮", "enabled": true, "sort_order": 2}
|
||||
],
|
||||
"created_at": "2025-01-01T00:00:00",
|
||||
"updated_at": "2025-01-01T00:00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应**:
|
||||
```json
|
||||
{
|
||||
"code": 404,
|
||||
"message": "入口模块不存在: id=999"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 创建入口模块
|
||||
|
||||
**接口**: `POST /api/v3/entry-modules`
|
||||
|
||||
**权限要求**: 管理员（admin）或领导（is_leader）
|
||||
|
||||
**请求体**:
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| name | string | 是 | 模块名称（最大255字符） |
|
||||
| description | string | 否 | 模块描述 |
|
||||
| path | string | 否 | 图片存储路径（最大255字符） |
|
||||
| areas | AreaConfig[] | 否 | 地区配置列表 |
|
||||
|
||||
**请求示例**:
|
||||
```json
|
||||
{
|
||||
"name": "合同审查",
|
||||
"description": "合同文档审查入口",
|
||||
"path": "/images/contract-review.png",
|
||||
"areas": [
|
||||
{"area": "梅州", "enabled": true, "sort_order": 1},
|
||||
{"area": "云浮", "enabled": true, "sort_order": 2},
|
||||
{"area": "揭阳", "enabled": false, "sort_order": 3},
|
||||
{"area": "潮州", "enabled": true, "sort_order": 4}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"name": "合同审查",
|
||||
"description": "合同文档审查入口",
|
||||
"path": "/images/contract-review.png",
|
||||
"areas": [
|
||||
{"area": "梅州", "enabled": true, "sort_order": 1},
|
||||
{"area": "云浮", "enabled": true, "sort_order": 2},
|
||||
{"area": "揭阳", "enabled": false, "sort_order": 3},
|
||||
{"area": "潮州", "enabled": true, "sort_order": 4}
|
||||
],
|
||||
"created_at": "2025-01-01T00:00:00",
|
||||
"updated_at": "2025-01-01T00:00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应**:
|
||||
```json
|
||||
// 权限不足
|
||||
{
|
||||
"detail": "权限不足：仅管理员可以创建入口模块"
|
||||
}
|
||||
|
||||
// 名称重复
|
||||
{
|
||||
"code": 400,
|
||||
"message": "入口模块名称已存在: 合同审查"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 更新入口模块
|
||||
|
||||
**接口**: `PUT /api/v3/entry-modules/{module_id}`
|
||||
|
||||
**权限要求**: 管理员（admin）或领导（is_leader）
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| module_id | int | 是 | 模块ID |
|
||||
|
||||
**请求体**（所有字段可选，只传需要更新的字段）:
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| name | string | 否 | 模块名称（最大255字符） |
|
||||
| description | string | 否 | 模块描述 |
|
||||
| path | string | 否 | 图片存储路径（最大255字符） |
|
||||
| areas | AreaConfig[] | 否 | 地区配置列表（会完全替换原有配置） |
|
||||
|
||||
**请求示例**:
|
||||
```json
|
||||
// 只更新名称
|
||||
{
|
||||
"name": "新的模块名称"
|
||||
}
|
||||
|
||||
// 更新地区配置
|
||||
{
|
||||
"areas": [
|
||||
{"area": "梅州", "enabled": true, "sort_order": 1},
|
||||
{"area": "云浮", "enabled": false, "sort_order": 2}
|
||||
]
|
||||
}
|
||||
|
||||
// 更新多个字段
|
||||
{
|
||||
"name": "合同审查v2",
|
||||
"description": "更新后的描述",
|
||||
"path": "/images/new-icon.png"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"name": "合同审查v2",
|
||||
"description": "更新后的描述",
|
||||
"path": "/images/new-icon.png",
|
||||
"areas": [
|
||||
{"area": "梅州", "enabled": true, "sort_order": 1},
|
||||
{"area": "云浮", "enabled": false, "sort_order": 2}
|
||||
],
|
||||
"created_at": "2025-01-01T00:00:00",
|
||||
"updated_at": "2025-01-02T10:30:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应**:
|
||||
```json
|
||||
// 模块不存在
|
||||
{
|
||||
"code": 404,
|
||||
"message": "入口模块不存在: id=999"
|
||||
}
|
||||
|
||||
// 权限不足
|
||||
{
|
||||
"detail": "权限不足：仅管理员可以更新入口模块"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 删除入口模块
|
||||
|
||||
**接口**: `DELETE /api/v3/entry-modules/{module_id}`
|
||||
|
||||
**权限要求**: 管理员（admin）或领导（is_leader）
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| module_id | int | 是 | 模块ID |
|
||||
|
||||
**请求示例**:
|
||||
```javascript
|
||||
DELETE /api/v3/entry-modules/1
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"deleted": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应**:
|
||||
```json
|
||||
// 模块不存在
|
||||
{
|
||||
"code": 404,
|
||||
"message": "入口模块不存在: id=999"
|
||||
}
|
||||
|
||||
// 权限不足
|
||||
{
|
||||
"detail": "权限不足：仅管理员可以删除入口模块"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 前端调用示例
|
||||
|
||||
### TypeScript 类型定义
|
||||
|
||||
```typescript
|
||||
// 地区配置
|
||||
interface AreaConfig {
|
||||
area: string;
|
||||
enabled: boolean;
|
||||
sort_order: number;
|
||||
}
|
||||
|
||||
// 入口模块
|
||||
interface EntryModule {
|
||||
id: number;
|
||||
name: string;
|
||||
description: string | null;
|
||||
path: string | null;
|
||||
areas: AreaConfig[] | null;
|
||||
created_at: string;
|
||||
updated_at: string;
|
||||
}
|
||||
|
||||
// 列表响应
|
||||
interface EntryModuleListResponse {
|
||||
total: number;
|
||||
page: number;
|
||||
page_size: number;
|
||||
items: EntryModule[];
|
||||
}
|
||||
|
||||
// 创建请求
|
||||
interface EntryModuleCreate {
|
||||
name: string;
|
||||
description?: string;
|
||||
path?: string;
|
||||
areas?: AreaConfig[];
|
||||
}
|
||||
|
||||
// 更新请求
|
||||
interface EntryModuleUpdate {
|
||||
name?: string;
|
||||
description?: string;
|
||||
path?: string;
|
||||
areas?: AreaConfig[];
|
||||
}
|
||||
```
|
||||
|
||||
### API 封装示例
|
||||
|
||||
```typescript
|
||||
import axios from 'axios';
|
||||
|
||||
const api = axios.create({
|
||||
baseURL: '/api/v3',
|
||||
headers: {
|
||||
'Content-Type': 'application/json'
|
||||
}
|
||||
});
|
||||
|
||||
// 请求拦截器 - 添加 Token
|
||||
api.interceptors.request.use((config) => {
|
||||
const token = localStorage.getItem('token');
|
||||
if (token) {
|
||||
config.headers.Authorization = `Bearer ${token}`;
|
||||
}
|
||||
return config;
|
||||
});
|
||||
|
||||
// 入口模块 API
|
||||
export const entryModuleApi = {
|
||||
// 获取列表
|
||||
list: (params?: {
|
||||
page?: number;
|
||||
page_size?: number;
|
||||
name?: string;
|
||||
area?: string;
|
||||
}) => api.get<EntryModuleListResponse>('/entry-modules', { params }),
|
||||
|
||||
// 获取详情
|
||||
get: (id: number) => api.get<EntryModule>(`/entry-modules/${id}`),
|
||||
|
||||
// 创建
|
||||
create: (data: EntryModuleCreate) => api.post<EntryModule>('/entry-modules', data),
|
||||
|
||||
// 更新
|
||||
update: (id: number, data: EntryModuleUpdate) =>
|
||||
api.put<EntryModule>(`/entry-modules/${id}`, data),
|
||||
|
||||
// 删除
|
||||
delete: (id: number) => api.delete(`/entry-modules/${id}`)
|
||||
};
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
// 获取列表
|
||||
const { data } = await entryModuleApi.list({ page: 1, page_size: 20 });
|
||||
console.log(data.data.items);
|
||||
|
||||
// 创建模块
|
||||
const newModule = await entryModuleApi.create({
|
||||
name: '合同审查',
|
||||
description: '合同文档审查入口',
|
||||
areas: [
|
||||
{ area: '梅州', enabled: true, sort_order: 1 },
|
||||
{ area: '云浮', enabled: true, sort_order: 2 }
|
||||
]
|
||||
});
|
||||
|
||||
// 更新模块
|
||||
await entryModuleApi.update(1, {
|
||||
name: '新名称',
|
||||
areas: [
|
||||
{ area: '梅州', enabled: false, sort_order: 1 }
|
||||
]
|
||||
});
|
||||
|
||||
// 删除模块
|
||||
await entryModuleApi.delete(1);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误码说明
|
||||
|
||||
| HTTP状态码 | 说明 | 处理建议 |
|
||||
|-----------|------|---------|
|
||||
| 200 | 成功 | - |
|
||||
| 400 | 请求参数错误 | 检查请求体格式 |
|
||||
| 401 | 未认证 | Token过期，需重新登录 |
|
||||
| 403 | 无权限 | 当前用户不是管理员/领导 |
|
||||
| 404 | 资源不存在 | 检查模块ID是否正确 |
|
||||
| 500 | 服务器错误 | 联系后端排查 |
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **地区配置**：更新 `areas` 字段时会**完全替换**原有配置，不是增量更新
|
||||
2. **权限要求**：创建、更新、删除操作需要管理员（admin）或领导（is_leader）权限
|
||||
3. **图片路径**：`path` 字段存储的是相对路径，前端需要拼接完整的图片URL
|
||||
4. **分页**：默认每页20条，最大100条
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.0
|
||||
**最后更新**: 2025-11-26
|
||||
**维护者**: Backend Team
|
||||
Reference in New Issue
Block a user