{ "openapi": "3.1.0", "paths": { "/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/users/{id}/transfer-customers": { "post": { "description": "A3 客户模块落地前返回 42201", "operationId": "UsersController_transferCustomers", "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" ] } }, "/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" ] } } }, "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": { "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 } }