TanWenyan/leaudit-platform-frontend

Fork 0

Files

T

LiangShiyong 3d1dbb3f97 all in

2025-12-05 00:09:32 +08:00

10 KiB

Raw Blame History

入口模块管理 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（地区配置）

interface AreaConfig {
  area: string;        // 地区名称（如：梅州、云浮、揭阳、潮州）
  enabled: boolean;    // 是否启用（默认 true）
  sort_order: number;  // 排序号（默认 0）
}

EntryModule（入口模块）

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	否	地区筛选（如：梅州、云浮）

请求示例:

// 获取第1页，每页20条
GET /api/v3/entry-modules?page=1&page_size=20

// 按名称搜索
GET /api/v3/entry-modules?name=合同

// 按地区筛选
GET /api/v3/entry-modules?area=梅州

响应示例:

{
  "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

请求示例:

GET /api/v3/entry-modules/1

响应示例:

{
  "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"
  }
}

错误响应:

{
  "code": 404,
  "message": "入口模块不存在: id=999"
}

3. 创建入口模块

接口: POST /api/v3/entry-modules

权限要求: 管理员（admin）或领导（is_leader）

请求体:

字段	类型	必填	说明
name	string	是	模块名称（最大255字符）
description	string	否	模块描述
path	string	否	图片存储路径（最大255字符）
areas	AreaConfig[]	否	地区配置列表

请求示例:

{
  "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}
  ]
}

响应示例:

{
  "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"
  }
}

错误响应:

// 权限不足
{
  "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[]	否	地区配置列表（会完全替换原有配置）

请求示例:

// 只更新名称
{
  "name": "新的模块名称"
}

// 更新地区配置
{
  "areas": [
    {"area": "梅州", "enabled": true, "sort_order": 1},
    {"area": "云浮", "enabled": false, "sort_order": 2}
  ]
}

// 更新多个字段
{
  "name": "合同审查v2",
  "description": "更新后的描述",
  "path": "/images/new-icon.png"
}

响应示例:

{
  "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"
  }
}

错误响应:

// 模块不存在
{
  "code": 404,
  "message": "入口模块不存在: id=999"
}

// 权限不足
{
  "detail": "权限不足：仅管理员可以更新入口模块"
}

5. 删除入口模块

接口: DELETE /api/v3/entry-modules/{module_id}

权限要求: 管理员（admin）或领导（is_leader）

路径参数:

参数	类型	必填	说明
module_id	int	是	模块ID

请求示例:

DELETE /api/v3/entry-modules/1

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "deleted": true
  }
}

错误响应:

// 模块不存在
{
  "code": 404,
  "message": "入口模块不存在: id=999"
}

// 权限不足
{
  "detail": "权限不足：仅管理员可以删除入口模块"
}

前端调用示例

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 封装示例

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}`)
};

使用示例

// 获取列表
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	服务器错误	联系后端排查

注意事项

地区配置：更新 areas 字段时会完全替换原有配置，不是增量更新
权限要求：创建、更新、删除操作需要管理员（admin）或领导（is_leader）权限
图片路径：path 字段存储的是相对路径，前端需要拼接完整的图片URL
分页：默认每页20条，最大100条

文档版本: v1.0 最后更新: 2025-11-26 维护者: Backend Team

10 KiB Raw Blame History Unescape Escape

入口模块管理 API 文档

文档信息

接口总览

数据结构

AreaConfig（地区配置）

EntryModule（入口模块）

接口详情

1. 获取入口模块列表

2. 获取入口模块详情

3. 创建入口模块

4. 更新入口模块

5. 删除入口模块

前端调用示例

TypeScript 类型定义

API 封装示例

使用示例

错误码说明

注意事项

10 KiB

Raw Blame History