# 入口模块管理 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('/entry-modules', { params }), // 获取详情 get: (id: number) => api.get(`/entry-modules/${id}`), // 创建 create: (data: EntryModuleCreate) => api.post('/entry-modules', data), // 更新 update: (id: number, data: EntryModuleUpdate) => api.put(`/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