{
  "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": {
        "operationId": "DepartmentsController_tree",
        "parameters": [],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "部门树（两级，含成员数与负责人）",
        "tags": [
          "identity-departments"
        ]
      }
    },
    "/api/v1/departments": {
      "post": {
        "description": "最多两级，在小组下新建返回 42201",
        "operationId": "DepartmentsController_create",
        "parameters": [],
        "responses": {
          "201": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "新建部门 / 小组",
        "tags": [
          "identity-departments"
        ]
      }
    },
    "/api/v1/departments/{id}": {
      "patch": {
        "operationId": "DepartmentsController_rename",
        "parameters": [],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "部门改名",
        "tags": [
          "identity-departments"
        ]
      }
    },
    "/api/v1/roles": {
      "get": {
        "operationId": "RolesController_list",
        "parameters": [],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "角色列表（绑定用）",
        "tags": [
          "identity-roles"
        ]
      }
    },
    "/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
  }
}