{ "openapi": "3.1.0", "paths": { "/api/v1/health/queues": { "get": { "description": "返回 9 个队列的计数、队首等待时长与 worker 心跳；Redis 不可用时返回 503（错误码 50002）。", "operationId": "QueueHealthController_queues", "parameters": [], "responses": { "200": { "description": "队列状态快照（可能为 degraded）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueHealthReportDto" } } } }, "503": { "description": "Redis 不可用（错误码 50002）" } }, "summary": "队列健康检查", "tags": [ "platform" ] } }, "/api/v1/auth/login": { "post": { "description": "返回 accessToken / refreshToken / expiresIn / me", "operationId": "AuthController_login", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "账号密码登录", "tags": [ "identity-auth" ] } }, "/api/v1/auth/refresh": { "post": { "operationId": "AuthController_refresh", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "刷新令牌（旋转，旧 refresh 立即失效）", "tags": [ "identity-auth" ] } }, "/api/v1/auth/logout": { "post": { "description": "吊销 refresh 令牌所在家族", "operationId": "AuthController_logout", "parameters": [], "responses": { "204": { "description": "" } }, "summary": "登出", "tags": [ "identity-auth" ] } }, "/api/v1/auth/change-password": { "post": { "operationId": "AuthController_changePassword", "parameters": [], "responses": { "204": { "description": "" } }, "summary": "修改密码（首登强改）", "tags": [ "identity-auth" ] } }, "/api/v1/me": { "get": { "operationId": "MeController_current", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "当前用户、角色、权限点、数据范围（多角色并集）", "tags": [ "identity-me" ] } }, "/api/v1/users": { "get": { "description": "status 默认 active（停用默认隐藏）；sort/order 走白名单；手机号仅返回掩码", "operationId": "UsersController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "用户列表（游标分页）", "tags": [ "identity-users" ] }, "post": { "description": "初始密码由管理员设定，首登强制修改", "operationId": "UsersController_create", "parameters": [], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "新建用户", "tags": [ "identity-users" ] } }, "/api/v1/users/{id}": { "get": { "description": "仅 user:manage 返回 phone 全号", "operationId": "UsersController_detail", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "用户详情", "tags": [ "identity-users" ] }, "patch": { "operationId": "UsersController_update", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "更新用户（不含账号 / 状态 / 密码）", "tags": [ "identity-users" ] } }, "/api/v1/users/{id}/disable": { "post": { "description": "停用后旧令牌立即失效；可指定客户转交人", "operationId": "UsersController_disable", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "停用用户", "tags": [ "identity-users" ] } }, "/api/v1/users/{id}/enable": { "post": { "operationId": "UsersController_enable", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "启用用户", "tags": [ "identity-users" ] } }, "/api/v1/departments/tree": { "get": { "description": "memberCount 含下级成员、directMemberCount 仅本部门直属成员；默认只返回启用部门，管理页传 include_disabled=true", "operationId": "DepartmentsController_tree", "parameters": [ { "name": "include_disabled", "required": false, "in": "query", "schema": { "enum": [ "true", "false" ], "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "部门树（两级）", "tags": [ "identity-departments" ] } }, "/api/v1/departments": { "post": { "description": "最多两级；父级必须启用；负责人必须是启用用户；同级重名返回 40903", "operationId": "DepartmentsController_create", "parameters": [], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "新建部门 / 小组", "tags": [ "identity-departments" ] } }, "/api/v1/departments/{id}": { "patch": { "description": "上级关系创建后不可移动；负责人必须是启用用户", "operationId": "DepartmentsController_update", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "更新部门（名称 / 负责人 / 排序）", "tags": [ "identity-departments" ] } }, "/api/v1/departments/{id}/disable": { "post": { "description": "本部门仍有在职成员、或一级部门存在启用中的下级小组 / 下级在职成员时返回 42201；已停用返回 40903", "operationId": "DepartmentsController_disable", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "停用部门", "tags": [ "identity-departments" ] } }, "/api/v1/departments/{id}/enable": { "post": { "description": "上级必须启用；已启用返回 40903", "operationId": "DepartmentsController_enable", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "启用部门", "tags": [ "identity-departments" ] } }, "/api/v1/roles": { "get": { "description": "默认 status=active（兼容 A1 用户管理的角色多选）；含权限点统计、用户数与数据范围", "operationId": "RolesController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "角色列表（游标分页 + 筛选 + 排序）", "tags": [ "identity-roles" ] }, "post": { "description": "权限点默认全空、code 自动生成；保存即做 SoD 校验（40304）；特殊权限单独授予", "operationId": "RolesController_create", "parameters": [], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "新建角色", "tags": [ "identity-roles" ] } }, "/api/v1/roles/{id}": { "get": { "operationId": "RolesController_detail", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "角色详情（权限点、特殊权限、数据范围、绑定用户）", "tags": [ "identity-roles" ] }, "patch": { "description": "系统角色仅显示名可改；status=enabled/disabled；返回 affectedUserCount 与软提示", "operationId": "RolesController_update", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "更新角色 / 启停", "tags": [ "identity-roles" ] }, "delete": { "description": "系统角色拒绝；有绑定用户（40903）只能停用", "operationId": "RolesController_remove", "parameters": [], "responses": { "204": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "删除角色", "tags": [ "identity-roles" ] } }, "/api/v1/permissions": { "get": { "description": "模块顺序与 design/a2-ui-v1/brief.md 对齐；特殊权限默认关闭、单独授予", "operationId": "PermissionsController_getTree", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "权限点目录（10 模块树 + 特殊权限 + SoD 对）", "tags": [ "identity-permissions" ] } }, "/api/v1/industries": { "get": { "operationId": "IndustriesController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "两级行业树（一级 → 二级）", "tags": [ "client-industries" ] }, "post": { "operationId": "IndustriesController_create", "parameters": [], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "新建一级 / 二级行业", "tags": [ "client-industries" ] } }, "/api/v1/industries/{id}": { "get": { "operationId": "IndustriesController_detail", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "行业详情与引用（子行业 / 客户 / 资产）", "tags": [ "client-industries" ] }, "patch": { "operationId": "IndustriesController_update", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "更新行业名称 / 排序 / 备注（层级与上级不可变）", "tags": [ "client-industries" ] }, "delete": { "operationId": "IndustriesController_remove", "parameters": [], "responses": { "204": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "删除行业（仅无子行业 / 客户 / 资产时）", "tags": [ "client-industries" ] } }, "/api/v1/industries/{id}/status": { "patch": { "operationId": "IndustriesController_setStatus", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "停用 / 启用行业（有启用子行业时禁止停用）", "tags": [ "client-industries" ] } }, "/api/v1/customers": { "get": { "operationId": "CustomersController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "客户列表（游标分页 + 行业 / 状态 / 负责人 / 客户组筛选）", "tags": [ "client-customers" ] }, "post": { "operationId": "CustomersController_create", "parameters": [], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "新建客户（简称必填；行业必须为末级行业）", "tags": [ "client-customers" ] } }, "/api/v1/customers/{id}": { "get": { "operationId": "CustomersController_detail", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "客户详情（跨客户访问统一 404）", "tags": [ "client-customers" ] }, "patch": { "operationId": "CustomersController_update", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "更新客户档案（所属行业不可改；暂停 / 结束只读）", "tags": [ "client-customers" ] } }, "/api/v1/customers/{id}/status": { "patch": { "operationId": "CustomersController_setStatus", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "客户状态：在服务 ⇄ 暂停 → 结束（结束不可逆）", "tags": [ "client-customers" ] } }, "/api/v1/customers/{id}/transfer": { "post": { "operationId": "CustomersController_transfer", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "变更客户负责人（写审计）", "tags": [ "client-customers" ] } }, "/api/v1/customers/{id}/groups": { "put": { "operationId": "CustomersController_setGroups", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "设置客户所属客户组（覆盖式）", "tags": [ "client-customers" ] } }, "/api/v1/customers/{id}/apply-industry-pack": { "post": { "operationId": "CustomersController_applyIndustryPack", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "套用行业资产包（B0 批次提供；当前返回业务提示）", "tags": [ "client-customers" ] } }, "/api/v1/users/{id}/transfer-customers": { "post": { "operationId": "CustomerTransferController_transfer", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "把用户名下客户转交给另一负责人", "tags": [ "client-customers" ] } }, "/api/v1/customer-groups": { "get": { "operationId": "CustomerGroupsController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "客户组列表（授权与数据范围最小单位）", "tags": [ "client-customer-groups" ] }, "post": { "operationId": "CustomerGroupsController_create", "parameters": [], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "新建客户组", "tags": [ "client-customer-groups" ] } }, "/api/v1/customer-groups/{id}": { "get": { "operationId": "CustomerGroupsController_detail", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "客户组详情与成员", "tags": [ "client-customer-groups" ] }, "patch": { "operationId": "CustomerGroupsController_update", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "更新客户组名称 / 说明", "tags": [ "client-customer-groups" ] }, "delete": { "operationId": "CustomerGroupsController_remove", "parameters": [], "responses": { "204": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "删除客户组（被角色数据范围引用时拒绝）", "tags": [ "client-customer-groups" ] } }, "/api/v1/customer-groups/{id}/members": { "post": { "operationId": "CustomerGroupsController_updateMembers", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "批量添加 / 移除成员（幂等）", "tags": [ "client-customer-groups" ] } }, "/api/v1/customer-fields": { "get": { "operationId": "CustomerFieldsController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "字段审批队列（待审批 / 已生效 / 已驳回）", "tags": [ "client-customer-fields" ] } }, "/api/v1/customer-fields/{id}/approve": { "post": { "operationId": "CustomerFieldsController_approve", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "审批客户级字段（通过 / 驳回；驳回原因必填）", "tags": [ "client-customer-fields" ] } }, "/api/v1/customers/{id}/fields": { "get": { "operationId": "CustomerFieldsOfCustomerController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "客户级字段列表（基础字段在 customers.custom_fields）", "tags": [ "client-customer-fields" ] }, "post": { "operationId": "CustomerFieldsOfCustomerController_apply", "parameters": [], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "申请客户级字段（进入生成字段需审批；每客户 ≤ 5）", "tags": [ "client-customer-fields" ] } }, "/api/v1/dicts": { "get": { "operationId": "DictsController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "字典类型列表（分组顺序 + 排序；含条目 / 行业层统计）", "tags": [ "catalog-dicts" ] }, "post": { "operationId": "DictsController_create", "parameters": [], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "新建字典类型（编码唯一；builtin=false）", "tags": [ "catalog-dicts" ] } }, "/api/v1/dicts/{code}": { "get": { "operationId": "DictsController_detail", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "字典类型详情（不存在 40401）", "tags": [ "catalog-dicts" ] }, "patch": { "operationId": "DictsController_update", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "更新字典类型（编码 / 形态 / 行业作用域不可改）", "tags": [ "catalog-dicts" ] }, "delete": { "operationId": "DictsController_remove", "parameters": [], "responses": { "204": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "删除自定义字典类型（内置 / 有子条目时不可删）", "tags": [ "catalog-dicts" ] } }, "/api/v1/dicts/{code}/status": { "patch": { "operationId": "DictsController_setStatus", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "启用 / 停用字典类型（内置类型允许停用）", "tags": [ "catalog-dicts" ] } }, "/api/v1/dicts/{code}/items": { "get": { "operationId": "DictsController_listItems", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "生效条目列表（industry_id 三层合并；非行业类型忽略该参数）", "tags": [ "catalog-dicts" ] }, "post": { "operationId": "DictsController_createItem", "parameters": [], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "新建字典条目（编码 / 父级 / 行业校验；编码创建后不可改）", "tags": [ "catalog-dicts" ] } }, "/api/v1/dicts/{code}/items/{itemId}": { "patch": { "operationId": "DictsController_updateItem", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "更新字典条目（仅名称 / 排序 / 启停 / 备注）", "tags": [ "catalog-dicts" ] } }, "/api/v1/media-tasks": { "post": { "operationId": "MediaTaskController_submit", "parameters": [], "responses": { "202": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "提交任务（异步 202；M0 仅演练任务；必带 Idempotency-Key，同 key 同请求体 24h 内返回同一任务）", "tags": [ "media-tasks" ] }, "get": { "operationId": "MediaTaskController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "任务列表（类型 / 状态 / 客户 / 时间 / 我的 / 关键字筛选；稳定排序 createdAt DESC, id DESC）", "tags": [ "media-tasks" ] } }, "/api/v1/media-tasks/{id}/events": { "get": { "operationId": "MediaTaskController_events", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "任务 SSE 进度（id 用 task_events.seq；支持 Last-Event-ID / last_event_id 续推，15s 心跳）", "tags": [ "media-tasks" ] } }, "/api/v1/media-tasks/{id}": { "get": { "operationId": "MediaTaskController_detail", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "任务详情（首 100 条任务项 + itemsNextCursor；范围外 404）", "tags": [ "media-tasks" ] } }, "/api/v1/media-tasks/{id}/cancel": { "post": { "operationId": "MediaTaskController_cancel", "parameters": [], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "取消任务（仅排队 / 生成中；只把未开始项置 skipped，已成功项不受影响）", "tags": [ "media-tasks" ] } }, "/api/v1/media-tasks/{id}/retry": { "post": { "operationId": "MediaTaskController_retry", "parameters": [], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "重试任务（仅部分失败；只重置失败项，成功项不动）", "tags": [ "media-tasks" ] } }, "/health": { "get": { "description": "真实检查 PostgreSQL 与 Redis；任一不可用返回 503 与统一错误体。", "operationId": "HealthController_check", "parameters": [], "responses": { "200": { "description": "全部依赖健康", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponseDto" } } } }, "503": { "description": "依赖不可用（错误码 50002），details 内附各依赖检查结果" } }, "summary": "健康检查", "tags": [ "platform" ] } }, "/api/v1/system/configs": { "get": { "operationId": "SystemConfigController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "全量系统配置（定义元数据 + 当前值 / 版本）", "tags": [ "platform-system-configs" ] }, "put": { "operationId": "SystemConfigController_update", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "批量保存配置（乐观锁 expectedVersion；写版本历史与审计）", "tags": [ "platform-system-configs" ] } }, "/api/v1/system/configs/effective": { "get": { "operationId": "SystemConfigController_effective", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "生效配置（仅登录；只返回 public 项，前端上限读取入口）", "tags": [ "platform-system-configs" ] } }, "/api/v1/system/configs/history": { "get": { "operationId": "SystemConfigController_history", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "配置变更记录（按变更时间倒序；操作人为用户姓名）", "tags": [ "platform-system-configs" ] } }, "/api/v1/audit-logs": { "get": { "operationId": "AuditController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "审计日志列表（多条件筛选 + 游标分页，稳定排序 occurred_at DESC, id DESC）", "tags": [ "platform-audit" ] } }, "/api/v1/audit-logs/actions": { "get": { "operationId": "AuditController_actions", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "审计动作目录（中文名 / 分类 / 对象类型，供筛选下拉）", "tags": [ "platform-audit" ] } }, "/api/v1/audit-logs/export": { "post": { "operationId": "AuditController_createExport", "parameters": [], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "创建审计导出任务（异步，立即返回 queued；导出本身写审计）", "tags": [ "platform-audit" ] } }, "/api/v1/audit-logs/exports": { "get": { "operationId": "AuditController_listExports", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "我的审计导出任务（按发起时间倒序）", "tags": [ "platform-audit" ] } }, "/api/v1/audit-logs/exports/{id}": { "get": { "operationId": "AuditController_getExport", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "导出任务进度（status / progress / rowCount / fileSize / expiresAt）", "tags": [ "platform-audit" ] } }, "/api/v1/audit-logs/exports/{id}/download": { "get": { "operationId": "AuditController_download", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "下载审计导出 CSV（短时效 HMAC 签名链接，无需登录）", "tags": [ "platform-audit" ] } }, "/api/v1/audit-logs/{id}": { "get": { "operationId": "AuditController_detail", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "审计日志详情（before / after / changes / diff / trace / ip / ua）", "tags": [ "platform-audit" ] } } }, "info": { "title": "灵犀 API", "description": "信息流广告素材生产平台后端 API。\n\n统一约定：\n- 前缀 /api/v1（健康检查 /health 除外）\n- 错误体 { code, message, details, trace_id }\n- 列表响应 { items, next_cursor }", "version": "0.1.0", "contact": {} }, "tags": [], "servers": [ { "url": "/api/v1", "description": "API v1" } ], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" } }, "schemas": { "QueueCountsDto": { "type": "object", "properties": { "waiting": { "type": "number", "description": "等待中任务数", "example": 0 }, "active": { "type": "number", "description": "执行中任务数", "example": 0 }, "completed": { "type": "number", "description": "已完成任务数（保留窗口内的历史计数）", "example": 12 }, "failed": { "type": "number", "description": "失败任务数（保留窗口内的历史计数）", "example": 1 }, "delayed": { "type": "number", "description": "延迟任务数", "example": 0 } }, "required": [ "waiting", "active", "completed", "failed", "delayed" ] }, "WorkerHeartbeatDto": { "type": "object", "properties": { "present": { "type": "boolean", "description": "最近 30s 内是否有 worker 心跳" }, "ageSeconds": { "type": "number", "nullable": true, "description": "心跳年龄（秒）；心跳缺失或值非法时为 null", "example": 3 } }, "required": [ "present", "ageSeconds" ] }, "QueueHealthEntryDto": { "type": "object", "properties": { "name": { "type": "string", "description": "队列名", "example": "media:verify" }, "group": { "type": "string", "description": "队列组", "example": "verify" }, "counts": { "$ref": "#/components/schemas/QueueCountsDto" }, "oldestWaitingSeconds": { "type": "number", "description": "队首任务等待秒数", "example": 0 }, "workerHeartbeat": { "$ref": "#/components/schemas/WorkerHeartbeatDto" } }, "required": [ "name", "group", "counts", "oldestWaitingSeconds", "workerHeartbeat" ] }, "QueueHealthReportDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ], "example": "ok" }, "redis": { "type": "string", "enum": [ "ok" ], "example": "ok" }, "queues": { "type": "array", "items": { "$ref": "#/components/schemas/QueueHealthEntryDto" } } }, "required": [ "status", "redis", "queues" ] }, "ComponentHealthDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "up", "down" ], "example": "up" }, "latencyMs": { "type": "number", "description": "检查耗时（毫秒）", "example": 3 }, "error": { "type": "string", "description": "失败原因（仅 down 时返回）" } }, "required": [ "status", "latencyMs" ] }, "HealthChecksDto": { "type": "object", "properties": { "database": { "$ref": "#/components/schemas/ComponentHealthDto" }, "redis": { "$ref": "#/components/schemas/ComponentHealthDto" } }, "required": [ "database", "redis" ] }, "HealthResponseDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ], "example": "ok" }, "env": { "type": "string", "example": "development" }, "version": { "type": "string", "example": "0.1.0" }, "uptimeSeconds": { "type": "number", "description": "进程运行秒数", "example": 128 }, "checks": { "$ref": "#/components/schemas/HealthChecksDto" }, "timestamp": { "type": "string", "example": "2026-11-02T08:00:00.000Z" } }, "required": [ "status", "env", "version", "uptimeSeconds", "checks", "timestamp" ] }, "ErrorResponseDto": { "type": "object", "properties": { "code": { "type": "number", "description": "错误码（见 ErrorCode 常量）", "example": 42202 }, "message": { "type": "string", "description": "可直接展示给用户的提示", "example": "内容触发合规拦截" }, "details": { "type": "object", "description": "补充信息（字段错误、命中规则等），结构由错误码决定", "example": { "issues": [ { "path": "name", "message": "Required" } ] } }, "trace_id": { "type": "string", "description": "请求追踪 ID，与日志同源", "example": "01JABCDEF0123456789ABCDEFG" } }, "required": [ "code", "message", "trace_id" ] }, "ErrorCode": { "type": "integer", "description": "业务错误码（只允许使用 @lingxi/shared 中登记的错误码）", "enum": [ 40001, 40101, 40102, 40103, 40301, 40302, 40303, 40304, 40401, 40901, 40902, 40903, 42201, 42202, 42203, 42901, 42902, 50001, 50002, 50003 ] }, "ErrorResponse": { "type": "object", "required": [ "code", "message", "trace_id" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string" }, "details": { "description": "补充信息，结构由错误码决定" }, "trace_id": { "type": "string" } } } } }, "x-error-codes": [ { "code": 40001 }, { "code": 40101 }, { "code": 40102 }, { "code": 40103 }, { "code": 40301 }, { "code": 40302 }, { "code": 40303 }, { "code": 40304 }, { "code": 40401 }, { "code": 40901 }, { "code": 40902 }, { "code": 40903 }, { "code": 42201 }, { "code": 42202 }, { "code": 42203 }, { "code": 42901 }, { "code": 42902 }, { "code": 50001 }, { "code": 50002 }, { "code": 50003 } ], "x-api-config": { "env": "development", "featureVideo": false } }