497 lines
10 KiB
Markdown
497 lines
10 KiB
Markdown
# 入口模块管理 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
|