/** * 系统管理模块 Swagger 文档 * @file swagger-system.js * @description 定义系统管理相关的API文档 */ /** * @swagger * tags: * - name: 系统管理 * description: 系统配置和菜单权限管理 */ /** * @swagger * components: * schemas: * SystemConfig: * type: object * properties: * id: * type: string * description: 配置ID * example: "config_001" * config_key: * type: string * description: 配置键名 * example: "system.max_upload_size" * config_value: * description: 配置值(可以是任意类型) * example: "10MB" * category: * type: string * description: 配置分类 * example: "upload" * description: * type: string * description: 配置描述 * example: "系统最大上传文件大小限制" * is_public: * type: boolean * description: 是否为公开配置 * example: false * is_editable: * type: boolean * description: 是否可编辑 * example: true * default_value: * description: 默认值 * example: "5MB" * value_type: * type: string * enum: [string, number, boolean, json, array] * description: 值类型 * example: "string" * validation_rules: * type: object * description: 验证规则 * properties: * required: * type: boolean * min: * type: number * max: * type: number * pattern: * type: string * created_at: * type: string * format: date-time * description: 创建时间 * example: "2024-01-15T10:30:00Z" * updated_at: * type: string * format: date-time * description: 更新时间 * example: "2024-01-15T10:30:00Z" * * SystemConfigInput: * type: object * required: * - config_key * - config_value * properties: * config_key: * type: string * description: 配置键名 * example: "system.max_upload_size" * config_value: * description: 配置值 * example: "10MB" * category: * type: string * description: 配置分类 * example: "upload" * description: * type: string * description: 配置描述 * example: "系统最大上传文件大小限制" * is_public: * type: boolean * description: 是否为公开配置 * example: false * is_editable: * type: boolean * description: 是否可编辑 * example: true * value_type: * type: string * enum: [string, number, boolean, json, array] * description: 值类型 * example: "string" * validation_rules: * type: object * description: 验证规则 * * ConfigCategory: * type: object * properties: * category: * type: string * description: 分类名称 * example: "upload" * label: * type: string * description: 分类标签 * example: "文件上传" * description: * type: string * description: 分类描述 * example: "文件上传相关配置" * count: * type: integer * description: 该分类下的配置数量 * example: 5 * * MenuPermission: * type: object * properties: * id: * type: string * description: 菜单ID * example: "menu_001" * menu_name: * type: string * description: 菜单名称 * example: "用户管理" * menu_path: * type: string * description: 菜单路径 * example: "/admin/users" * parent_id: * type: string * description: 父菜单ID * example: "menu_admin" * menu_level: * type: integer * description: 菜单层级 * example: 2 * sort_order: * type: integer * description: 排序顺序 * example: 1 * menu_icon: * type: string * description: 菜单图标 * example: "user" * is_active: * type: boolean * description: 是否激活 * example: true * required_roles: * type: array * items: * type: string * description: 所需角色 * example: ["admin", "manager"] * required_permissions: * type: array * items: * type: string * description: 所需权限 * example: ["user.read", "user.write"] * children: * type: array * items: * $ref: '#/components/schemas/MenuPermission' * description: 子菜单 * created_at: * type: string * format: date-time * description: 创建时间 * example: "2024-01-15T10:30:00Z" * updated_at: * type: string * format: date-time * description: 更新时间 * example: "2024-01-15T10:30:00Z" * * SystemStats: * type: object * properties: * system_info: * type: object * properties: * version: * type: string * description: 系统版本 * example: "1.0.0" * uptime: * type: integer * description: 运行时间(秒) * example: 86400 * node_version: * type: string * description: Node.js版本 * example: "18.17.0" * platform: * type: string * description: 运行平台 * example: "linux" * database_info: * type: object * properties: * connection_status: * type: string * description: 数据库连接状态 * example: "connected" * total_tables: * type: integer * description: 总表数 * example: 25 * total_records: * type: integer * description: 总记录数 * example: 100000 * performance_info: * type: object * properties: * memory_usage: * type: object * properties: * used: * type: integer * description: 已使用内存(字节) * total: * type: integer * description: 总内存(字节) * percentage: * type: number * description: 使用百分比 * cpu_usage: * type: number * description: CPU使用率 * example: 0.25 * disk_usage: * type: object * properties: * used: * type: integer * description: 已使用磁盘空间(字节) * total: * type: integer * description: 总磁盘空间(字节) * percentage: * type: number * description: 使用百分比 * * BatchConfigUpdate: * type: object * required: * - configs * properties: * configs: * type: array * items: * type: object * required: * - id * - config_value * properties: * id: * type: string * description: 配置ID * config_value: * description: 新的配置值 * description: 要更新的配置列表 * example: * - id: "config_001" * config_value: "20MB" * - id: "config_002" * config_value: true */ /** * @swagger * /system/configs: * get: * tags: * - 系统管理 * summary: 获取系统配置列表 * description: 获取系统配置列表,支持按分类和公开性筛选(仅限管理员) * security: * - bearerAuth: [] * parameters: * - in: query * name: category * schema: * type: string * description: 配置分类筛选 * example: "upload" * - in: query * name: is_public * schema: * type: boolean * description: 是否公开配置筛选 * example: false * - in: query * name: search * schema: * type: string * description: 搜索关键词(配置键名或描述) * example: "upload" * responses: * 200: * description: 获取配置列表成功 * content: * application/json: * schema: * allOf: * - $ref: '#/components/schemas/ApiResponse' * - type: object * properties: * data: * type: array * items: * $ref: '#/components/schemas/SystemConfig' * 401: * description: 未授权 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 403: * description: 权限不足(仅限管理员) * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 500: * description: 服务器内部错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * * post: * tags: * - 系统管理 * summary: 创建系统配置 * description: 创建新的系统配置项(仅限管理员) * security: * - bearerAuth: [] * requestBody: * required: true * content: * application/json: * schema: * $ref: '#/components/schemas/SystemConfigInput' * responses: * 201: * description: 配置创建成功 * content: * application/json: * schema: * allOf: * - $ref: '#/components/schemas/ApiResponse' * - type: object * properties: * data: * $ref: '#/components/schemas/SystemConfig' * 400: * description: 请求参数错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 401: * description: 未授权 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 403: * description: 权限不足(仅限管理员) * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 409: * description: 配置键名已存在 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 500: * description: 服务器内部错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' */ /** * @swagger * /system/configs/public: * get: * tags: * - 系统管理 * summary: 获取公开系统配置 * description: 获取标记为公开的系统配置 * security: * - bearerAuth: [] * responses: * 200: * description: 获取公开配置成功 * content: * application/json: * schema: * allOf: * - $ref: '#/components/schemas/ApiResponse' * - type: object * properties: * data: * type: array * items: * $ref: '#/components/schemas/SystemConfig' * 401: * description: 未授权 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 500: * description: 服务器内部错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' */ /** * @swagger * /system/configs/categories: * get: * tags: * - 系统管理 * summary: 获取配置分类列表 * description: 获取所有配置分类及其统计信息(仅限管理员) * security: * - bearerAuth: [] * responses: * 200: * description: 获取分类列表成功 * content: * application/json: * schema: * allOf: * - $ref: '#/components/schemas/ApiResponse' * - type: object * properties: * data: * type: array * items: * $ref: '#/components/schemas/ConfigCategory' * 401: * description: 未授权 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 403: * description: 权限不足(仅限管理员) * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 500: * description: 服务器内部错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' */ /** * @swagger * /system/configs/{id}: * put: * tags: * - 系统管理 * summary: 更新系统配置 * description: 更新指定的系统配置项(仅限管理员) * security: * - bearerAuth: [] * parameters: * - in: path * name: id * required: true * schema: * type: string * description: 配置ID * example: "config_001" * requestBody: * required: true * content: * application/json: * schema: * type: object * required: * - config_value * properties: * config_value: * description: 新的配置值 * example: "20MB" * description: * type: string * description: 配置描述 * is_public: * type: boolean * description: 是否为公开配置 * responses: * 200: * description: 配置更新成功 * content: * application/json: * schema: * allOf: * - $ref: '#/components/schemas/ApiResponse' * - type: object * properties: * data: * $ref: '#/components/schemas/SystemConfig' * 400: * description: 请求参数错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 401: * description: 未授权 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 403: * description: 权限不足(仅限管理员) * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 404: * description: 配置不存在 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 500: * description: 服务器内部错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * * delete: * tags: * - 系统管理 * summary: 删除系统配置 * description: 删除指定的系统配置项(仅限管理员) * security: * - bearerAuth: [] * parameters: * - in: path * name: id * required: true * schema: * type: string * description: 配置ID * example: "config_001" * responses: * 200: * description: 配置删除成功 * content: * application/json: * schema: * $ref: '#/components/schemas/ApiResponse' * 401: * description: 未授权 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 403: * description: 权限不足(仅限管理员) * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 404: * description: 配置不存在 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 500: * description: 服务器内部错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' */ /** * @swagger * /system/configs/batch: * put: * tags: * - 系统管理 * summary: 批量更新系统配置 * description: 批量更新多个系统配置项(仅限管理员) * security: * - bearerAuth: [] * requestBody: * required: true * content: * application/json: * schema: * $ref: '#/components/schemas/BatchConfigUpdate' * responses: * 200: * description: 批量更新成功 * content: * application/json: * schema: * allOf: * - $ref: '#/components/schemas/ApiResponse' * - type: object * properties: * data: * type: object * properties: * updated_count: * type: integer * description: 成功更新的配置数量 * example: 5 * failed_count: * type: integer * description: 更新失败的配置数量 * example: 0 * errors: * type: array * items: * type: object * properties: * id: * type: string * error: * type: string * description: 更新失败的配置及错误信息 * 400: * description: 请求参数错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 401: * description: 未授权 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 403: * description: 权限不足(仅限管理员) * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 500: * description: 服务器内部错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' */ /** * @swagger * /system/configs/{id}/reset: * post: * tags: * - 系统管理 * summary: 重置系统配置 * description: 将指定配置重置为默认值(仅限管理员) * security: * - bearerAuth: [] * parameters: * - in: path * name: id * required: true * schema: * type: string * description: 配置ID * example: "config_001" * responses: * 200: * description: 配置重置成功 * content: * application/json: * schema: * allOf: * - $ref: '#/components/schemas/ApiResponse' * - type: object * properties: * data: * $ref: '#/components/schemas/SystemConfig' * 401: * description: 未授权 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 403: * description: 权限不足(仅限管理员) * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 404: * description: 配置不存在或无默认值 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 500: * description: 服务器内部错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' */ /** * @swagger * /system/menus: * get: * tags: * - 系统管理 * summary: 获取菜单权限配置 * description: 获取所有菜单的权限配置(仅限管理员) * security: * - bearerAuth: [] * responses: * 200: * description: 获取菜单权限成功 * content: * application/json: * schema: * allOf: * - $ref: '#/components/schemas/ApiResponse' * - type: object * properties: * data: * type: array * items: * $ref: '#/components/schemas/MenuPermission' * 401: * description: 未授权 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 403: * description: 权限不足(仅限管理员) * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 500: * description: 服务器内部错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' */ /** * @swagger * /system/menus/user: * get: * tags: * - 系统管理 * summary: 获取当前用户可访问的菜单 * description: 根据当前用户的角色和权限获取可访问的菜单列表 * security: * - bearerAuth: [] * responses: * 200: * description: 获取用户菜单成功 * content: * application/json: * schema: * allOf: * - $ref: '#/components/schemas/ApiResponse' * - type: object * properties: * data: * type: array * items: * $ref: '#/components/schemas/MenuPermission' * 401: * description: 未授权 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 500: * description: 服务器内部错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' */ /** * @swagger * /system/menus/{id}: * put: * tags: * - 系统管理 * summary: 更新菜单权限配置 * description: 更新指定菜单的权限配置(仅限管理员) * security: * - bearerAuth: [] * parameters: * - in: path * name: id * required: true * schema: * type: string * description: 菜单ID * example: "menu_001" * requestBody: * required: true * content: * application/json: * schema: * type: object * properties: * menu_name: * type: string * description: 菜单名称 * example: "用户管理" * required_roles: * type: array * items: * type: string * description: 所需角色 * example: ["admin", "manager"] * required_permissions: * type: array * items: * type: string * description: 所需权限 * example: ["user.read", "user.write"] * is_active: * type: boolean * description: 是否激活 * example: true * sort_order: * type: integer * description: 排序顺序 * example: 1 * responses: * 200: * description: 菜单权限更新成功 * content: * application/json: * schema: * allOf: * - $ref: '#/components/schemas/ApiResponse' * - type: object * properties: * data: * $ref: '#/components/schemas/MenuPermission' * 400: * description: 请求参数错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 401: * description: 未授权 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 403: * description: 权限不足(仅限管理员) * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 404: * description: 菜单不存在 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 500: * description: 服务器内部错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' */ /** * @swagger * /system/stats: * get: * tags: * - 系统管理 * summary: 获取系统统计信息 * description: 获取系统运行状态和统计信息(仅限管理员) * security: * - bearerAuth: [] * responses: * 200: * description: 获取系统统计成功 * content: * application/json: * schema: * allOf: * - $ref: '#/components/schemas/ApiResponse' * - type: object * properties: * data: * $ref: '#/components/schemas/SystemStats' * 401: * description: 未授权 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 403: * description: 权限不足(仅限管理员) * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 500: * description: 服务器内部错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' */ /** * @swagger * /system/init: * post: * tags: * - 系统管理 * summary: 初始化系统 * description: 初始化系统配置和基础数据(仅限管理员) * security: * - bearerAuth: [] * requestBody: * required: false * content: * application/json: * schema: * type: object * properties: * force: * type: boolean * description: 是否强制重新初始化 * example: false * modules: * type: array * items: * type: string * description: 要初始化的模块列表 * example: ["configs", "menus", "roles"] * responses: * 200: * description: 系统初始化成功 * content: * application/json: * schema: * allOf: * - $ref: '#/components/schemas/ApiResponse' * - type: object * properties: * data: * type: object * properties: * initialized_modules: * type: array * items: * type: string * description: 已初始化的模块 * example: ["configs", "menus", "roles"] * skipped_modules: * type: array * items: * type: string * description: 跳过的模块 * example: [] * 400: * description: 请求参数错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 401: * description: 未授权 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 403: * description: 权限不足(仅限管理员) * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' * 500: * description: 服务器内部错误 * content: * application/json: * schema: * $ref: '#/components/schemas/ErrorResponse' */ module.exports = {};