openapi.yaml

openapi: 3.0.1
info:
  title: SAST Link v2 API
  description: |
    SAST Link v2 统一认证与用户中心 API。

    - Base URL: `https://link.sast.fun/v2`
    - 认证方式: JWT Bearer Token（`Authorization: Bearer <access_token>`）
    - Content-Type: 标准业务接口使用 `application/json`；OAuth Token/Revoke 使用 `application/x-www-form-urlencoded`
    - OAuth 2.1: 授权端点使用 PKCE-S256，第一方应用无需 client_secret
    - OIDC Provider: 基于 OAuth 2.1 的 OpenID Connect 认证层，scope 含 openid 时返回 ID Token
    - 响应格式: 标准业务接口使用标准化响应信封；OAuth/OIDC/健康检查/公开卡片等协议或直出端点见 StandardEnvelope 注释

    本文件是目标契约，不是已注册路由的清单。
    当前所有路径均已注册；实现对契约的收紧之处以 `docs/API文档.md` 为准。
  version: 2.0.0
  contact:
    name: SAST
    url: https://sast.fun
tags:
  - name: Auth
  - name: OAuth Login
  - name: Profile
  - name: Identities
  - name: OAuth 2.1 Server
  - name: Admin
  - name: Health
  - name: OIDC
  - name: Card
paths:
  /auth/register/send-code:
    post:
      summary: 发送注册验证码
      deprecated: false
      description: 向指定邮箱发送注册验证码。邮箱域名必须为 `@njupt.edu.cn` 或 `@sast.fun`。
      operationId: authSendRegisterCode
      tags:
        - Auth
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - login_email
              properties:
                login_email:
                  type: string
                  format: email
                  description: 注册邮箱
                  example: b2404****@njupt.edu.cn
            examples: {}
        required: true
      responses:
        "200":
          description: 验证码已发送
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendCodeResponse"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: 参数错误（400xx）
        "429":
          $ref: "#/components/responses/TooManyRequests"
          description: 频率限制（429xx）
      security: []
  /auth/register/verify-code:
    post:
      summary: 验证注册验证码
      deprecated: false
      description: 注册第一步。验证邮箱验证码，返回 Register-Ticket（Redis，5 分钟，一次性）。
      operationId: authVerifyRegisterCode
      tags:
        - Auth
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - login_email
                - code
              properties:
                login_email:
                  type: string
                  format: email
                  description: 注册邮箱
                code:
                  type: string
                  description: 邮箱验证码
                  example: "123456"
            examples: {}
        required: true
      responses:
        "200":
          description: 验证成功，返回 Register-Ticket
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RegisterTicketResponse"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: 参数错误（400xx）
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
      security: []
  /auth/register:
    post:
      summary: 完成注册
      deprecated: false
      description: >-
        注册第二步。凭 Register-Ticket + 补充信息完成注册，成功后自动签发 Token。
        registration_state / oauth_state 服务第三方 OAuth（GitHub / 飞书）回调的无绑定分支，
        两者必须同时提供或同时省略，只给一半返回 40000。传入双值时 GetDel 一次性消费
        registration_state，比对其中暂存的 oauth_state 与请求传入值，匹配后在同一事务内
        创建账号、资料、identities 绑定与首个会话。registration_state 只能用于新建账号，
        不可用于给已存在账号追加绑定——后者只能走 POST /user/identities/{github,lark}。
        未配置任何第三方 provider 时传入这对字段返回 40000；Redis 不可用返回 50300，
        不降级为无绑定注册。
      operationId: authCompleteRegister
      tags:
        - Auth
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - register_ticket
                - password
                - name
                - phone_number
                - qq_number
                - college
                - major
                - student_id
              properties:
                register_ticket:
                  type: string
                  description: 验证码验证后下发的 Register-Ticket
                password:
                  type: string
                  minLength: 8
                  description: 登录密码，最短 8 位
                  example: your_password
                name:
                  type: string
                  description: 真实姓名
                  example: 张三
                phone_number:
                  type: string
                  description: 手机号
                  example: "13800138000"
                qq_number:
                  type: string
                  description: QQ 号
                  example: "1234567890"
                registration_state:
                  type: string
                  description: 第三方 OAuth 回调下发的注册暂存令牌（可选，需与 oauth_state 配套使用）
                oauth_state:
                  type: string
                  description: 原始 OAuth CSRF state 参数（可选，与 registration_state 配套校验）
                college:
                  $ref: "#/components/schemas/College"
                  description: 学院
                major:
                  type: string
                  description: 专业
                student_id:
                  type: string
                  maxLength: 50
                  description: 学号
            examples: {}
        required: true
      responses:
        "201":
          description: 注册成功并返回 Token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthResultResponse"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: 参数错误（400xx）
        "409":
          $ref: "#/components/responses/Conflict"
          description: 资源冲突（409xx）
        "429":
          $ref: "#/components/responses/TooManyRequests"
          description: >-
            注册过于频繁（42900，带 Retry-After）。按 Register-Ticket 限流而非按 IP，
            默认 5 次/5 分钟（RATE_LIMIT_REGISTER_ATTEMPTS）：每个被接受的请求执行一次
            argon2id 派生（默认 m=19456KiB/t2），ticket 即该成本应计量的「一个已验证邮箱」；按 IP 限流会让
            校园网 NAT 后整栋楼共享一个桶。检查排在全部廉价校验之后（填错表单不计费）、
            registration_state 消费之前，故被限流的请求既不消费 Register-Ticket 也不消费
            registration_state，可在窗口恢复后用同一 ticket 重试——窗口不得超过 ticket 的
            5 分钟 TTL，服务启动时校验。
      security: []
  /user/login:
    post:
      summary: 密码登录
      deprecated: false
      description: 支持教育邮箱和第三方邮箱密码登录。
      operationId: authPasswordLogin
      tags:
        - Auth
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - login_email
                - password
              properties:
                login_email:
                  type: string
                  format: email
                  description: 登录邮箱
                password:
                  type: string
                  description: 登录密码
              additionalProperties: false
            examples: {}
        required: true
      responses:
        "200":
          description: 登录成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthResultResponse"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: 参数错误（400xx）
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 账号已注销（40301）
        "429":
          $ref: "#/components/responses/TooManyRequests"
          description: 登录限流或失败锁定（42900）
        "500":
          $ref: "#/components/responses/InternalError"
          description: 服务端错误（50000）
      security: []
  /auth/refresh:
    post:
      summary: 刷新 Token（内部登录用）
      deprecated: false
      description: >-
        Refresh Token 旋转机制，每次使用后旧 token 撤销，下发新 token。OAuth 客户端请用 `POST
        /oauth/token`（grant_type=refresh_token）。
      operationId: authRefreshToken
      tags:
        - Auth
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - refresh_token
              properties:
                refresh_token:
                  type: string
                  description: 刷新令牌
                  example: rt_abc123...
              additionalProperties: false
            examples: {}
        required: true
      responses:
        "200":
          description: Token 刷新成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenRefreshResponse"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: 参数错误（400xx）
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: Refresh Token 无效、过期或被撤销（40102）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 账号已注销（40301）
        "429":
          $ref: "#/components/responses/TooManyRequests"
          description: >-
            `42900`（带 Retry-After）—— 按调用方 IP 限流，默认 100 次/60s
            （`RATE_LIMIT_REFRESH_RPM` / `RATE_LIMIT_REFRESH_WINDOW`）。检查排在
            token 查库之前。限流器故障时 fail-open。
        "500":
          $ref: "#/components/responses/InternalError"
          description: 服务端错误（50000）
      security: []
  /auth/logout:
    post:
      summary: 登出
      deprecated: false
      description: 撤销当前 access_token（jti）及整条 refresh_token family。
      operationId: authLogout
      tags:
        - Auth
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - refresh_token
              properties:
                refresh_token:
                  type: string
                  description: 刷新令牌
              additionalProperties: false
        required: true
      responses:
        "200":
          description: 登出成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: 参数错误（400xx）
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: Access/Refresh Token 无效（401xx）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 账号已注销（40301）
        "500":
          $ref: "#/components/responses/InternalError"
          description: 服务端错误（50000）
      security:
        - bearerAuth: []
  /auth/change-password:
    post:
      summary: 修改密码
      deprecated: false
      description: 新密码最短 8 位，修改成功后撤销该用户所有 token family。
      operationId: authChangePassword
      tags:
        - Auth
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - old_password
                - new_password
              properties:
                old_password:
                  type: string
                  description: 旧密码
                new_password:
                  type: string
                  minLength: 8
                  description: 新密码，最短 8 位
        required: true
      responses:
        "200":
          description: 密码修改成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: 参数错误（400xx）
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "422":
          $ref: "#/components/responses/Unprocessable"
          description: 业务校验失败（422xx）
      security:
        - bearerAuth: []
  /auth/forgot-password/send-code:
    post:
      summary: 发送重置密码验证码
      deprecated: false
      description: 对格式合法且未触发限流的邮箱统一受理。响应不表示账号存在，也不保证邮件已经送达；服务端通过有界内存队列异步处理。
      operationId: authSendForgotPasswordCode
      tags:
        - Auth
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - login_email
              properties:
                login_email:
                  type: string
                  format: email
                  description: 注册邮箱
            examples: {}
        required: true
      responses:
        "200":
          description: 请求已受理；不表示账号存在或邮件已送达
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendCodeResponse"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: 参数错误（400xx）
        "429":
          $ref: "#/components/responses/TooManyRequests"
          description: 频率限制（429xx）
      security: []
  /auth/reset-password:
    post:
      summary: 重置密码
      deprecated: false
      description: 新密码最短 8 位。
      operationId: authResetPassword
      tags:
        - Auth
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - login_email
                - code
                - new_password
              properties:
                login_email:
                  type: string
                  format: email
                  description: 注册邮箱
                code:
                  type: string
                  description: 邮箱验证码
                new_password:
                  type: string
                  minLength: 8
                  description: 新密码，最短 8 位
            examples: {}
        required: true
      responses:
        "200":
          description: 密码重置成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: 参数错误（400xx）
        "422":
          $ref: "#/components/responses/Unprocessable"
          description: 业务校验失败（422xx）
      security: []
  /oauth/github:
    get:
      summary: GitHub 登录
      deprecated: false
      description: >
        重定向至 GitHub OAuth 授权页，并在 Redis 写入一次性 `oauth_state`（10min）。

        `redirect` 按精确匹配校验 `OAUTH_LOGIN_REDIRECTS` 白名单，不支持前缀匹配：
        回调会把 `login_code` 交给它重定向到的地址，前缀规则会让
        `https://link.sast.fun.evil.test` 也通过。省略时使用白名单首项。

        未启用该 provider（`OAUTH_GITHUB_ENABLED=false`）时路由仍然存在，返回 `40000`。
      operationId: oauthLoginGithub
      tags:
        - OAuth Login
      parameters:
        - name: redirect
          in: query
          required: false
          description: 登录完成后返回的前端地址，必须在 OAUTH_LOGIN_REDIRECTS 白名单内。
          schema:
            type: string
            format: uri
      responses:
        "302":
          description: 重定向至 GitHub OAuth 授权页
          headers: {}
        "400":
          description: >-
            `40000` —— redirect 不在允许列表中，或该 provider 未启用
        "429":
          $ref: "#/components/responses/TooManyRequests"
          description: >-
            `42900`（带 Retry-After）—— 按调用方 IP 限流，默认 100 次/60s
            （RATE_LIMIT_OAUTH_LOGIN_RPM）。与 /oauth/authorize 形状相同：
            无认证且每次调用写一个 oauth_state 键。限流在解析 provider 之前生效，
            因此未启用的 provider 那条返回 40000 的路由也不是无成本探测面。
        "503":
          description: >-
            `50300` —— Redis 不可用，无法写入 oauth_state。fail-closed：
            没有已存储的 state 就无法校验回调，因此登录不予开始
      security: []
  /oauth/github/callback:
    get:
      summary: GitHub 回调
      deprecated: false
      description: >
        处理 GitHub OAuth 回调。

        - 已有绑定 → 签发一次性 login_code，302 重定向至前端 `?code=<login_code>`

        - 无绑定 → 生成 registration_state（Redis，15min），302 重定向至注册补全页
        `?registration_state=<registration_state>&oauth_state=<oauth_state>&provider=github&name=<login>&avatar=<url>`
      operationId: oauthGithubCallback
      tags:
        - OAuth Login
      parameters:
        - name: code
          in: query
          description: GitHub 授权码
          required: true
          schema:
            type: string
        - name: state
          in: query
          description: CSRF 状态值
          required: true
          schema:
            type: string
      responses:
        "302":
          description: 重定向至前端
          headers: {}
      security: []
  /oauth/lark:
    get:
      summary: 飞书登录
      deprecated: false
      description: >
        重定向至飞书 OAuth 授权页，并在 Redis 写入一次性 `oauth_state`（10min）。

        `redirect` 的白名单校验与 `/oauth/github` 相同。未启用该 provider
        （`OAUTH_FEISHU_ENABLED=false`）时路由仍然存在，返回 `40000`。
      operationId: oauthLoginLark
      tags:
        - OAuth Login
      parameters:
        - name: redirect
          in: query
          required: false
          description: 登录完成后返回的前端地址，必须在 OAUTH_LOGIN_REDIRECTS 白名单内。
          schema:
            type: string
            format: uri
      responses:
        "302":
          description: 重定向至飞书 OAuth 授权页
          headers: {}
        "400":
          description: >-
            `40000` —— redirect 不在允许列表中，或该 provider 未启用
        "429":
          $ref: "#/components/responses/TooManyRequests"
          description: >-
            `42900`（带 Retry-After）—— 按调用方 IP 限流，默认 100 次/60s
            （RATE_LIMIT_OAUTH_LOGIN_RPM），与 GitHub 授权端点共用同一档配额与
            同一 Redis 计数域（endpoint 名 oauth_login）。
        "503":
          description: "`50300` —— Redis 不可用，无法写入 oauth_state（fail-closed）"
      security: []
  /oauth/lark/callback:
    get:
      summary: 飞书回调
      deprecated: false
      description: >
        处理飞书 OAuth 回调，仅限 SAST 企业内飞书用户。

        - 已有绑定 → 签发一次性 login_code，302 重定向至前端

        - 无绑定 → 生成 registration_state（Redis，15min），302 重定向至注册补全页
        `?registration_state=<registration_state>&oauth_state=<oauth_state>&provider=lark&name=<name>&avatar=<url>`

        - 非 SAST 企业用户 → 拒绝
      operationId: oauthLarkCallback
      tags:
        - OAuth Login
      parameters:
        - name: code
          in: query
          description: 飞书授权码
          required: true
          schema:
            type: string
        - name: state
          in: query
          description: CSRF 状态值
          required: true
          schema:
            type: string
      responses:
        "302":
          description: 重定向至前端
          headers: {}
      security: []
  /oauth/exchange-code:
    post:
      summary: 交换登录码
      deprecated: false
      description: 用 OAuth 回调中的一次性 login_code（Redis，60 秒）换取 token。
      operationId: authExchangeLoginCode
      tags:
        - OAuth Login
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - code
              properties:
                code:
                  type: string
                  description: 一次性登录码
                  example: lc_abc123...
            examples: {}
        required: true
      responses:
        "200":
          description: 交换成功，返回 Token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthResultResponse"
          headers: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "429":
          $ref: "#/components/responses/TooManyRequests"
          description: >-
            `42900`（带 Retry-After）—— 按调用方 IP 限流，默认 100 次/60s
            （RATE_LIMIT_EXCHANGE_CODE_RPM）。本端点按设计免认证——兑换 login_code
            正是取得会话的方式——故配额是约束无成本探测的唯一手段。限流检查排在
            空 code 校验之前：调用方控制输入，先直接拒空会让每次猜测一次
            Redis GetDel 的昂贵路径保持敞开。被限流的请求不消费 login_code。
      security: []
  /user/profile:
    get:
      summary: 获取当前用户信息
      deprecated: false
      description: ""
      operationId: userGetProfile
      tags:
        - Profile
      parameters: []
      responses:
        "200":
          description: 用户信息
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserProfileResponse"
          headers: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 账号已注销（40301）
        "500":
          $ref: "#/components/responses/InternalError"
          description: 服务端错误（50000）
      security:
        - bearerAuth: []
    put:
      summary: 更新用户资料
      deprecated: false
      description: |
        更新当前登录用户可自助维护的个人信息。允许更新 user 表中的基础信息
        （真实姓名、手机号、QQ 号、学院、专业、学号）以及 profile 表中的展示资料。
        登录邮箱、角色、状态、邮箱类型等身份与权限字段不可通过此接口修改，传入未知字段返回 40000。

        未传的字段保持不变；传 null 等同于未传，不表示清空。profile 侧的可空展示字段
        （nickname、intro、email、blog_url、github_url、department）传空字符串表示
        清空为 null；user 侧字段 NOT NULL，传空字符串或纯空白返回 40000。
        所有文本字段拒绝控制字符（含 NUL、CR、LF、Tab），返回 40000。
        blog_url / github_url 必须是 http/https 绝对 URL。
        college 必须是 college_enum 完整枚举值，department 必须是 software / media 或空字符串。
      operationId: userUpdateProfile
      tags:
        - Profile
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              properties:
                name:
                  type: string
                  nullable: true
                  maxLength: 255
                  description: 真实姓名
                  example: 张三
                phone_number:
                  type: string
                  nullable: true
                  maxLength: 20
                  description: 手机号
                  example: "13800138000"
                qq_number:
                  type: string
                  nullable: true
                  maxLength: 20
                  description: QQ 号
                  example: "1234567890"
                college:
                  allOf:
                    - $ref: "#/components/schemas/College"
                  nullable: true
                  description: 学院。NOT NULL 字段，传空字符串或空白返回 40000；传 null 表示不修改
                major:
                  type: string
                  nullable: true
                  maxLength: 50
                  description: 专业
                  example: 软件工程
                student_id:
                  type: string
                  nullable: true
                  maxLength: 50
                  description: 学号
                  example: B2404****
                nickname:
                  type: string
                  nullable: true
                  maxLength: 255
                  description: 昵称
                  example: 新昵称
                department:
                  type: string
                  nullable: true
                  enum: [software, media, ""]
                  description: 部门。传空字符串清空为 NULL，传 null 表示不修改
                intro:
                  type: string
                  nullable: true
                  maxLength: 255
                  description: 自我介绍
                  example: 新的自我介绍
                email:
                  type: string
                  nullable: true
                  format: email
                  maxLength: 255
                  description: 对外展示邮箱
                  example: display@example.com
                blog_url:
                  type: string
                  nullable: true
                  format: uri
                  maxLength: 512
                  description: 个人博客链接
                  example: https://blog.example.com
                github_url:
                  type: string
                  nullable: true
                  format: uri
                  maxLength: 512
                  description: GitHub 主页链接
                  example: https://github.com/example
        required: true
      responses:
        "200":
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProfileUpdateResponse"
          headers: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "400":
          $ref: "#/components/responses/BadRequest"
          description: 参数错误、未知字段、枚举/长度/链接校验失败（40000）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 账号已注销（40301）
        "409":
          $ref: "#/components/responses/Conflict"
          description: 学号已被占用（40902）
        "500":
          $ref: "#/components/responses/InternalError"
      security:
        - bearerAuth: []
  /user/avatar:
    put:
      summary: 上传头像
      deprecated: false
      description: >-
        上传头像至对象存储（腾讯云 COS），经内容审核后写入 profile.avatar。
        依赖 STORAGE_* 配置；未配置时返回 50002。
        图片限制 5MB，格式 jpg/png/webp。
      operationId: userUploadAvatar
      tags:
        - Profile
      parameters: []
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: 图片文件（限制 5MB，格式 jpg/png/webp）
                  example: ""
              required:
                - file
        required: true
      responses:
        "200":
          description: 上传成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AvatarUploadResponse"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: 参数错误（400xx）
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "422":
          description: >-
            头像未通过内容审核（42203）
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
          description: 请求过于频繁（42900）
        "500":
          $ref: "#/components/responses/InternalError"
          description: 服务端错误（500xx，含 50002 对象存储失败）
        "503":
          description: 内容审核服务不可用（50300，fail-closed）
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      security:
        - bearerAuth: []
  /card/{id}:
    get:
      summary: 获取个人卡片
      deprecated: true
      description: |
        已下线（路由注释，暂不响应）。顺序 ID 的公开 URL 可枚举全站成员名单，隐私重设计中。
        重开后为 owner-only + 不可枚举标识，不会原样启用。
      operationId: cardGetCard
      tags:
        - Card
      parameters:
        - name: id
          in: path
          description: 用户 ID，正整数；非正整数或含非数字字符返回 404
          required: true
          example: 12
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        "200":
          description: 个人卡片数据
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CardResponse"
          headers: {}
        "404":
          $ref: "#/components/responses/NotFound"
          description: 用户不存在或已注销
        "429":
          $ref: "#/components/responses/TooManyRequests"
          description: >-
            请求过于频繁（42900，带 Retry-After）。按调用方 IP 限流，默认 300 次/60s
            （RATE_LIMIT_CARD_RPM）：本端点无认证且路径参数是连续用户 ID，
            不限流即等于开放全站公开卡片的抓取。限流在 ID 校验之前生效，
            因此无效 ID 同样消耗配额——它得到的 404 正是枚举者要读的信号。
            配额按共享出口 IP 下的成员墙定档，只能减缓而非阻止抓取；
            公开卡片的批量读取应交由反向代理缓存承担。
        "500":
          $ref: "#/components/responses/InternalError"
      security: []
  /user/identities:
    get:
      summary: 获取绑定列表
      deprecated: false
      description: ""
      operationId: userListIdentities
      tags:
        - Identities
      parameters: []
      responses:
        "200":
          description: 绑定列表
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentitiesListResponse"
          headers: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 账号已注销（40301）
        "500":
          $ref: "#/components/responses/InternalError"
      security:
        - bearerAuth: []
  /user/identities/lark:
    post:
      summary: 绑定飞书
      deprecated: false
      description: >
        每个用户只能绑定一个飞书账号，每个飞书账号只能绑定一个用户。

        绑定与登录使用**不同的回调地址**，两条都要登记进飞书应用的重定向白名单。
        登录回调（`OAUTH_FEISHU_REDIRECT_URI`）指向本后端的
        `/oauth/lark/callback`；绑定回调是前端页面，由它拿到 provider code 后
        调用本接口。

        本接口不接受 `registration_state`：该值只证明有人完成了一次第三方回调，
        不证明是哪个 SAST 账号在操作，因此调用者一律由 Bearer token 认定。
      operationId: userBindLark
      tags:
        - Identities
      parameters:
        - name: code
          in: query
          description: 飞书 OAuth 授权码
          required: true
          schema:
            type: string
        - name: redirect_uri
          in: query
          required: false
          description: >
            签发该 code 时使用的回调地址（前端的绑定回调页）。RFC 6749 §4.1.3
            要求 token 交换重复这个值；飞书注册了多条回调时，不一致会以
            invalid_grant 拒绝。省略时回退到 OAUTH_FEISHU_REDIRECT_URI，仅在
            绑定与登录共用同一回调地址时适用。
          schema:
            type: string
            format: uri
      responses:
        "200":
          description: 绑定成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityBindResponse"
          headers: {}
        "409":
          $ref: "#/components/responses/Conflict"
          description: 资源冲突（409xx）
      security:
        - bearerAuth: []
  /user/identities/github:
    post:
      summary: 绑定 GitHub
      deprecated: false
      description: >
        每个用户只能绑定一个 GitHub 账号，每个 GitHub 账号只能绑定一个用户。

        绑定回调与登录回调不同，但 GitHub OAuth App 只能注册一条 callback URL，
        且要求 host 与端口精确匹配、path 必须位于已注册路径之下。因此两条回调必须
        共享一个已注册的父路径：生产上绑定页放在 /v2/oauth/bind/github，与登录回调
        同处 /v2/oauth 之下并注册该前缀；本地利用 loopback 免端口匹配的例外注册
        http://127.0.0.1/oauth。详见 docs/runbooks/caddy-reverse-proxy.md。

        为绑定单独开一个 OAuth App 行不通：Bind() 用 OAUTH_GITHUB_CLIENT_ID/SECRET
        交换 code，另一个 App 签发的 code 会被拒绝。

        本接口不接受 `registration_state`，调用者一律由 Bearer token 认定。
      operationId: userBindGithub
      tags:
        - Identities
      parameters:
        - name: code
          in: query
          description: GitHub OAuth 授权码
          required: true
          schema:
            type: string
        - name: redirect_uri
          in: query
          required: false
          description: >
            签发该 code 时使用的回调地址（前端的绑定回调页）。GitHub 在 token
            交换阶段用它校验与签发 code 时是否一致。省略时回退到
            OAUTH_GITHUB_REDIRECT_URI。
          schema:
            type: string
            format: uri
      responses:
        "200":
          description: 绑定成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityBindResponse"
          headers: {}
        "409":
          $ref: "#/components/responses/Conflict"
          description: 资源冲突（409xx）
      security:
        - bearerAuth: []
  /user/identities/email:
    post:
      summary: 绑定其他邮箱（第一步）
      deprecated: false
      description: 返回 Bind-Ticket（Redis，5 分钟，一次性），内部携带待绑定邮箱地址。
      operationId: userRequestBindEmail
      tags:
        - Identities
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: 待绑定的第三方邮箱
                  example: myemail@qq.com
        required: true
      responses:
        "200":
          description: 返回 Bind-Ticket
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BindTicketResponse"
          headers: {}
        "409":
          $ref: "#/components/responses/Conflict"
          description: 资源冲突（409xx）
      security:
        - bearerAuth: []
  /user/identities/email/verify:
    post:
      summary: 确认绑定其他邮箱（第二步）
      deprecated: false
      description: 凭 Bind-Ticket + 验证码完成绑定。每个用户最多绑定 2 个第三方邮箱。
      operationId: userVerifyBindEmail
      tags:
        - Identities
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - bind_ticket
                - code
              properties:
                bind_ticket:
                  type: string
                  description: 绑定票据
                code:
                  type: string
                  description: 邮箱验证码
        required: true
      responses:
        "200":
          description: 绑定成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityBindResponse"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: 参数错误（400xx）
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "409":
          $ref: "#/components/responses/Conflict"
          description: 资源冲突（409xx）
      security:
        - bearerAuth: []
  /user/identities/{id}:
    delete:
      summary: 解绑第三方账号
      deprecated: false
      description: >-
        必须输入当前密码进行二次确认。主邮箱（user.login_email）不在 identities 中，不可通过此接口解绑。
        不属于当前用户的绑定 ID 与不存在的 ID 均返回 40400，不区分两者。
        解绑后若无其他登录方式则拒绝（42200）。按调用者限流，60s 内最多 3 次（42900，带 Retry-After）；限流在密码校验之前生效，密码错误同样消耗配额。
      operationId: userUnbindIdentity
      tags:
        - Identities
      parameters:
        - name: id
          in: path
          description: 绑定记录 ID，正整数
          required: true
          example: 12
          schema:
            type: integer
            format: int64
            minimum: 1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
                  description: 当前密码，用于二次确认
              required:
                - password
            examples: {}
        required: true
      responses:
        "200":
          description: 解绑成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
          headers: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 账号已注销（40301）
        "404":
          $ref: "#/components/responses/NotFound"
          description: 绑定记录不存在或不属于当前用户（40400）
        "422":
          $ref: "#/components/responses/Unprocessable"
          description: 不能解绑唯一的登录方式（42200）
        "429":
          $ref: "#/components/responses/TooManyRequests"
          description: 解绑过于频繁（42900），60s 内最多 3 次，按调用者限流
        "400":
          $ref: "#/components/responses/BadRequest"
          description: password 缺失、未知字段或 Content-Type 非 JSON（40000）
        "500":
          $ref: "#/components/responses/InternalError"
      security:
        - bearerAuth: []
  /user/devices:
    get:
      summary: 设备列表
      deprecated: false
      description: >-
        返回当前用户的已登录设备列表，按最近登录时间倒序（最新在前）。
        设备 ID 即 token family_id：一次登录（或注册）即一台设备，最多 5 台，超出淘汰最旧。
        Redis 不可用时降级返回空列表（fail-open），不影响登录能力。
      operationId: userListDevices
      tags:
        - Devices
      parameters: []
      responses:
        "200":
          description: 设备列表
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DevicesListResponse"
          headers: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 账号已注销（40301）
        "500":
          $ref: "#/components/responses/InternalError"
      security:
        - bearerAuth: []
  /user/devices/{id}:
    delete:
      summary: 登出指定设备
      deprecated: false
      description: >-
        登出指定设备：校验设备归属当前用户（Redis 归属校验，fail-closed）→ 撤销该设备
        所属 token family 的全部令牌 → 删除设备记录 → 审计 logout_device。
        设备不存在或不属于当前用户均返回 40400，不区分两者。按用户限流，60s 内最多 3 次
        （42900，带 Retry-After）。当前设备请使用 POST /auth/logout。
      operationId: userLogoutDevice
      tags:
        - Devices
      parameters:
        - name: id
          in: path
          description: 设备 ID（token family_id，UUID）
          required: true
          example: 6da1d5dd-02ec-4fc6-840e-67dc0dae52ac
          schema:
            type: string
      responses:
        "200":
          description: 登出成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeviceLogoutResponse"
          headers: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 账号已注销（40301）
        "404":
          $ref: "#/components/responses/NotFound"
          description: >-
            设备不存在或不属于当前用户（40400）。空/空白的 id 也走这一条：
            handler 先 trim 再判断，区分 40000 与 40400 对调用方没有可确认的信息，
            反而可能帮助探测他人的会话，所以本端点不产生 40000。
        "429":
          $ref: "#/components/responses/TooManyRequests"
          description: 操作过于频繁（42900），60s 内最多 3 次，按用户限流
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          description: 设备服务暂不可用（50300，fail-closed：无法校验归属时不执行撤销）
      security:
        - bearerAuth: []
  /oauth/authorize:
    get:
      summary: 授权端点
      deprecated: false
      description: |
        授权流程的第一段，**无需认证**——从第三方跳转来的浏览器不携带 Authorization header。

        校验参数后将请求暂存 10 分钟，302 重定向至前端授权页
        `{OAUTH_CONSENT_URL}?request_id=ar_xxx&client_name=..&scope=..&expires_in=600`。
        用户决定由第二段 `POST /oauth/authorize/consent` 提交。

        使用 PKCE-S256，仅接受 code_challenge_method=S256。
        redirect_uri 必须与客户端注册值精确字符串相等，不做前缀匹配。

        错误分两条重定向路径：
        - client_id / redirect_uri 校验通过之前的错误（invalid_request、invalid_client）
          重定向至授权页，携带 error / error_description，不携带 state。
          RFC 6749 §4.1.2.1 禁止将错误重定向至未校验的 redirect_uri，否则本端点
          会退化为 open redirector。
        - 校验通过之后的错误（unsupported_response_type、invalid_scope、
          unauthorized_client、invalid_request）重定向至客户端 redirect_uri，
          携带 error / error_description / state。

        按调用方 IP 限流（默认 100 次/60s）：本端点无认证且每次调用写一个 Redis 暂存键。
      operationId: oauthAuthorize
      tags:
        - OAuth 2.1 Server
      parameters:
        - name: response_type
          in: query
          description: 固定值 `code`
          required: true
          schema:
            type: string
            enum:
              - code
        - name: client_id
          in: query
          description: 客户端标识
          required: true
          schema:
            type: string
        - name: redirect_uri
          in: query
          description: 回调地址
          required: true
          schema:
            type: string
            format: uri
        - name: scope
          in: query
          description: 授权范围，空格分隔（如 `openid profile`）。OAuth 线协议字段为单数 `scope`，数据库列保留 `scopes`
          required: true
          schema:
            type: string
        - name: state
          in: query
          description: CSRF 防护，客户端生成随机字符串，回调时原样返回
          required: true
          schema:
            type: string
        - name: code_challenge
          in: query
          description: PKCE code challenge
          required: true
          schema:
            type: string
        - name: code_challenge_method
          in: query
          description: PKCE 挑战方法，仅支持 S256
          required: true
          schema:
            type: string
            enum:
              - S256
        - name: nonce
          in: query
          description: OIDC nonce（可选参数）
          required: false
          schema:
            type: string
      responses:
        "302":
          description: >-
            成功时重定向至前端授权页，携带 request_id / client_name / scope /
            expires_in（暂存剩余秒数，供页面显示截止时间）。
            错误时按可重定向性重定向至授权页或客户端 redirect_uri，携带
            error / error_description。除参数校验类错误外，限流与 Redis 暂存失败
            会以 temporarily_unavailable、查库失败会以 server_error 重定向回授权页。
          headers:
            Location:
              description: 授权页或客户端回调地址
              schema:
                type: string
                format: uri
      security: []
  /oauth/authorize/consent:
    post:
      summary: 授权确认
      deprecated: false
      description: |
        授权流程的第二段。SAST Link 自有端点而非 RFC 定义端点，因此使用标准响应信封。

        用户身份取自校验过的 access token，不从请求体读取。授权码的
        client / scope / PKCE challenge / nonce 全部取自暂存内容，不采信请求体回传值——
        否则调用方可以确认一个请求而为另一个客户端或另一组 scope 签发授权码。

        暂存内容以 Redis GetDel 原子消费，一个 request_id 最多产出一个授权码；
        并发重复提交只有一个成功。

        approve=false 同样返回 200 与一个 redirect_uri，其中携带
        error=access_denied 与原始 state（RFC 6749 §4.1.2.1 要求把拒绝告知客户端）。

        返回 JSON 而非 302，因为调用方是授权页自身的 fetch——302 会被 fetch 跟随，
        浏览器不会跳转。
      operationId: oauthAuthorizeConsent
      tags:
        - OAuth 2.1 Server
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - request_id
                - approve
              properties:
                request_id:
                  type: string
                  description: GET /oauth/authorize 重定向携带的暂存标识
                  example: ar_3f2a1b4c5d6e7f8a9b0c1d2e3f4a5b6c
                approve:
                  type: boolean
                  description: 用户决定。字段缺失返回 40000，不默认为拒绝
                  example: true
        required: true
      responses:
        "200":
          description: 授权决定已记录，返回浏览器应跳转的地址
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/StandardEnvelope"
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          redirect_uri:
                            type: string
                            format: uri
                            example: https://app.example.com/callback?code=ac_abc123&state=xyz
          headers: {}
        "400":
          description: request_id / approve 缺失、未知字段、暂存已过期或已消费
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardEnvelope"
          headers: {}
        "401":
          description: 未登录或 Access Token 无效
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardEnvelope"
          headers: {}
        "403":
          description: 账号已注销
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardEnvelope"
          headers: {}
        "404":
          description: 两段之间客户端被停用
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardEnvelope"
          headers: {}
        "503":
          description: Redis 暂存不可读（fail-closed）
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardEnvelope"
          headers: {}
      security:
        - bearerAuth: []
  /oauth/token:
    post:
      summary: Token 端点
      deprecated: false
      description: |
        支持 grant_type: `authorization_code` 和 `refresh_token`。
        第一方应用使用 PKCE 无需 client_secret，第三方应用需提供 client_secret。
        此端点不遵循标准响应信封，请求体必须使用 application/x-www-form-urlencoded，成功和错误均使用 RFC 6749 格式。
        scope 包含 `openid` 时，响应额外返回 `id_token`（EdDSA / Ed25519 签名 JWT）。
      operationId: oauthToken
      tags:
        - OAuth 2.1 Server
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/OAuthTokenRequest"
            examples:
              auth_code_first_party:
                value:
                  grant_type: authorization_code
                  code: auth_code_abc123...
                  redirect_uri: https://app.example.com/callback
                  client_id: 9f3a1c7d2e5b40a8c6d1f4b7a2e9c3d5
                  code_verifier: pkce_verifier_raw_string...
                summary: 第一方应用 - 授权码模式
              auth_code_third_party:
                value:
                  grant_type: authorization_code
                  code: auth_code_abc123...
                  redirect_uri: https://app.example.com/callback
                  client_id: 9f3a1c7d2e5b40a8c6d1f4b7a2e9c3d5
                  client_secret: 3K7mDzX434GbFm9YAePJ9FXQNjT6MF0U
                  code_verifier: pkce_verifier_raw_string...
                summary: 第三方应用 - 授权码模式
              refresh_token_first_party:
                value:
                  grant_type: refresh_token
                  refresh_token: rt_abc123...
                  client_id: 9f3a1c7d2e5b40a8c6d1f4b7a2e9c3d5
                summary: 第一方应用 - 刷新 Token
              refresh_token_third_party:
                value:
                  grant_type: refresh_token
                  refresh_token: rt_abc123...
                  client_id: 9f3a1c7d2e5b40a8c6d1f4b7a2e9c3d5
                  client_secret: 3K7mDzX434GbFm9YAePJ9FXQNjT6MF0U
                summary: 第三方应用 - 刷新 Token
        required: true
      responses:
        "200":
          description: Token 签发成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthTokenResponse"
          headers: {}
        "400":
          description: |
            OAuth 错误（RFC 6749 格式）：invalid_request / invalid_grant /
            unsupported_grant_type / unauthorized_client。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthError"
          headers: {}
        "401":
          description: |
            `invalid_client` —— 客户端认证失败。RFC 6749 §5.2 单独规定此项为 401，
            其余皆为 400。不携带 `WWW-Authenticate`：本服务只从表单体读取
            `client_secret`（discovery 通告 `none` 与 `client_secret_post`），
            通告一个未实现的认证方案会让客户端反复用 Basic 重试并始终失败。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthError"
          headers: {}
        "429":
          description: |
            `temporarily_unavailable` —— 按调用方 IP 限流
            （`RATE_LIMIT_TOKEN_RPM`，默认 100 次/60s），附带 `Retry-After`。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthError"
          headers: {}
        "500":
          description: "`server_error` —— 服务器内部错误"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthError"
          headers: {}
      security: []
  /oauth/revoke:
    post:
      summary: Token 撤销
      deprecated: false
      description: |
        撤销整条 token family。请求体必须使用 application/x-www-form-urlencoded。
        遵循 RFC 7009，成功固定返回 200 OK 且响应体为空。
      operationId: oauthRevokeToken
      tags:
        - OAuth 2.1 Server
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - token
                - client_id
              properties:
                token:
                  type: string
                  description: 待撤销的 token
                  example: rt_abc123...
                token_type_hint:
                  type: string
                  enum:
                    - access_token
                    - refresh_token
                  description: Token 类型提示
                client_id:
                  type: string
                  description: 客户端标识
                client_secret:
                  type: string
                  description: |
                    机密客户端（`third_party`）必填；公开客户端不得携带，
                    携带则返回 `invalid_client`。
        required: true
      responses:
        "200":
          description: |
            撤销成功，RFC 7009 要求返回 200 OK 且响应体为空。未知 token 同样返回 200。
            注意：仅在撤销确实提交后才返回 200；撤销事务失败返回 500，
            以免客户端以为会话已终止而不再重试。
            撤销为 family 级：已过期的 access token 也会被解析并撤销其整条 family，
            因为它自身失效不代表同族 refresh token 失效（默认可存活 720h）。
            此时只放宽 exp 校验，签名 / kid / iss / aud / nbf 仍全部强制，
            归属以数据库行的 client_id 判定。
          headers: {}
        "400":
          description: OAuth 错误（RFC 6749 / RFC 7009 格式）
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthError"
          headers: {}
        "401":
          description: |
            `invalid_client` —— 客户端认证失败。不携带 `WWW-Authenticate`，
            理由同 `/oauth/token`。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthError"
          headers: {}
        "429":
          description: |
            `temporarily_unavailable` —— 与 `/oauth/token` 共用同一个按 IP 限流器，
            附带 `Retry-After`。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthError"
          headers: {}
        "500":
          description: "`server_error` —— 撤销事务失败，会话仍然有效，客户端应重试"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthError"
          headers: {}
      security: []
  /.well-known/openid-configuration:
    get:
      summary: OIDC Discovery
      deprecated: false
      description: |
        返回 OpenID Connect Discovery 文档，描述 OIDC Provider 的端点、支持的作用域、签名算法等元数据。
        符合 [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) 规范。
      operationId: oidcDiscovery
      tags:
        - OIDC
      parameters: []
      responses:
        "200":
          description: OIDC Discovery 文档
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenIDConfiguration"
          headers: {}
      security: []
  /.well-known/jwks.json:
    get:
      summary: JWKS 公钥集
      deprecated: false
      description: |
        返回 EdDSA（Ed25519）签名公钥集（JSON Web Key Set，RFC 8037 OKP），用于验证 ID Token 和 Access Token 的签名。
      operationId: oidcJwks
      tags:
        - OIDC
      parameters: []
      responses:
        "200":
          description: JWK Set
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JWKS"
          headers: {}
      security: []
  /userinfo:
    get:
      summary: UserInfo 端点（GET）
      deprecated: false
      description: |
        返回当前认证用户的身份信息。响应内容根据 Token 的 scope 决定：
        - `openid` 至少返回 `sub`
        - `profile` 额外返回 name / picture / preferred_username / updated_at 等
        - `email` 额外返回 email / email_verified

        符合 [OpenID Connect Core 1.0 — UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 规范。
      operationId: oidcUserInfoGet
      tags:
        - OIDC
      parameters: []
      responses:
        "200":
          description: 用户信息
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserInfoResponse"
          headers: {}
        "401":
          description: >-
            未认证或 Token 无效。签名无效、已过期、已撤销、token_version 不匹配、
            账号已注销统一归为 invalid_token——RFC 6750 对「token 被拒」只有此一个错误码。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthError"
          headers:
            WWW-Authenticate:
              description: >-
                RFC 6750 §3 Bearer 挑战头。符合规范的 OIDC 客户端读取此 header
                判断是否需要刷新 token。
              schema:
                type: string
                example: 'Bearer realm="sast-link", error="invalid_token"'
      security:
        - bearerAuth: []
    post:
      summary: UserInfo 端点（POST）
      deprecated: false
      description: |
        UserInfo 端点的 POST 变体，功能与 GET 完全一致。
        部分 OIDC 客户端偏好 POST 以避免 Token 出现在服务器日志中。
      operationId: oidcUserInfoPost
      tags:
        - OIDC
      parameters: []
      responses:
        "200":
          description: 用户信息
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserInfoResponse"
          headers: {}
        "401":
          description: >-
            未认证或 Token 无效。签名无效、已过期、已撤销、token_version 不匹配、
            账号已注销统一归为 invalid_token——RFC 6750 对「token 被拒」只有此一个错误码。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthError"
          headers:
            WWW-Authenticate:
              description: >-
                RFC 6750 §3 Bearer 挑战头。符合规范的 OIDC 客户端读取此 header
                判断是否需要刷新 token。
              schema:
                type: string
                example: 'Bearer realm="sast-link", error="invalid_token"'
      security:
        - bearerAuth: []
  /admin/users:
    get:
      summary: 用户列表
      deprecated: false
      description: 需 admin 或 lecturer 角色。
      operationId: adminListUsers
      tags:
        - Admin
      parameters:
        - name: page
          in: query
          description: 页码，默认 1
          required: false
          schema:
            type: integer
            default: 1
        - name: page_size
          in: query
          description: 每页条数，默认 20，最大 100（超出按 100 截断）
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: role
          in: query
          description: 筛选角色
          required: false
          schema:
            $ref: "#/components/schemas/UserRole"
        - name: state
          in: query
          description: 筛选状态
          required: false
          schema:
            $ref: "#/components/schemas/UserState"
        - name: department
          in: query
          description: 筛选部门
          required: false
          schema:
            $ref: "#/components/schemas/Department"
        - name: student_id
          in: query
          description: 筛选学号
          required: false
          schema:
            type: string
        - name: keyword
          in: query
          description: |
            搜索关键词，对姓名/学号/登录邮箱做大小写不敏感的模糊匹配。
            `%`、`_`、`\` 按字面量处理，不作为通配符。
          required: false
          schema:
            type: string
      responses:
        "200":
          description: |
            分页用户列表。不带 state 筛选时包含已注销用户（state = is_deleted），
            否则无法找到并恢复它们。department 走 profile 的 LEFT JOIN，
            因此无 profile 行的用户仍会出现，department 为 null。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdminUsersListResponse"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: 分页参数或枚举筛选值非法（400xx）
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 无权限（403xx）
      security:
        - bearerAuth: []
  /admin/users/{id}:
    get:
      summary: 用户详情
      deprecated: false
      description: 需 admin 或 lecturer 角色。
      operationId: adminGetUserDetail
      tags:
        - Admin
      parameters:
        - name: id
          in: path
          description: 用户 ID
          required: true
          example: 0
          schema:
            type: integer
      responses:
        "200":
          description: 用户详情
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserProfileResponse"
          headers: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 无权限（403xx）
        "404":
          $ref: "#/components/responses/NotFound"
          description: 资源不存在（404xx）
      security:
        - bearerAuth: []
    put:
      summary: 更新用户
      deprecated: false
      description: 需 admin 角色。
      operationId: adminUpdateUser
      tags:
        - Admin
      parameters:
        - name: id
          in: path
          description: 用户 ID
          required: true
          example: 0
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              additionalProperties: false
              description: |
                至少传一个字段。未知字段（含 password、token_version、id、profile）
                返回 400 而非静默忽略。长度按 V001 列宽校验，中文按字符数计。
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: 真实姓名（列为 NOT NULL，不可传空串）
                phone_number:
                  type: string
                  minLength: 1
                  maxLength: 20
                  description: 手机号（不可传空串）
                qq_number:
                  type: string
                  minLength: 1
                  maxLength: 20
                  description: QQ 号（不可传空串）
                college:
                  $ref: "#/components/schemas/College"
                  description: 学院
                major:
                  type: string
                  maxLength: 50
                  description: 专业（可置为空串）
                student_id:
                  type: string
                  minLength: 1
                  maxLength: 50
                  description: 学号（不可传空串）
                role:
                  $ref: "#/components/schemas/UserRole"
                  description: |
                    用户角色。实际发生变化时同一事务内递增 token_version 并撤销该用户全部 Token。
                    不可修改自己的 role，也不可降权系统中最后一名活跃管理员（均 403）。
                state:
                  $ref: "#/components/schemas/UserState"
                  description: |
                    用户状态。仅接受 njupter / on_sast / retired_sast，三者之间可任意修改以供纠错。
                    不接受 is_deleted（422）——注销必须走 DELETE，它才会在同一事务内撤销 Token。
                    对已注销用户调用本接口同样返回 422，需先恢复。
                email_type:
                  $ref: "#/components/schemas/EmailType"
                  description: |
                    注册邮箱类型。只能与 login_email 一同提交且必须与其域名一致，否则 400：
                    触发器 auto_set_email_type 仅在 login_email 出现在 UPDATE 列中时才重算该字段，
                    单独提交会写入与邮箱矛盾的值。
                login_email:
                  type: string
                  format: email
                  maxLength: 255
                  description: |
                    登录邮箱。域名限 @njupt.edu.cn / @sast.fun，会被规范化为小写；
                    修改后触发器 auto_set_email_type 自动重算 email_type。
        required: true
      responses:
        "200":
          description: |
            更新成功。role 实际变化时 message 为
            「用户信息更新成功，已撤销该用户的全部 Token」。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: 字段校验失败、未知字段或无可更新字段（400xx）
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 无权限，或改自己的 role / 降权最后一名管理员（403xx）
        "404":
          $ref: "#/components/responses/NotFound"
          description: 资源不存在（404xx）
        "409":
          $ref: "#/components/responses/Conflict"
          description: 学号或邮箱已被占用（40901 / 40902）
        "422":
          $ref: "#/components/responses/Unprocessable"
          description: state 为 is_deleted，或目标用户已注销（42200）
      security:
        - bearerAuth: []
    delete:
      summary: 注销用户（软删除）
      deprecated: false
      description: |
        需 admin 角色。将 user.state 设为 is_deleted，保留数据；同一事务内递增
        token_version 并撤销该用户全部 Access / Refresh Token（应用层逐个撤销，
        非 DB 级联删除），撤销的 JTI 写入 outbox，由 worker 失效对应 auth-state 缓存。

        不可注销自己的账号，也不可注销系统中最后一名活跃管理员（均 403）。
      operationId: adminDeleteUser
      tags:
        - Admin
      parameters:
        - name: id
          in: path
          description: 用户 ID
          required: true
          example: 0
          schema:
            type: integer
      responses:
        "200":
          description: 注销成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
          headers: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 无权限，或注销自己 / 最后一名管理员（403xx）
        "404":
          $ref: "#/components/responses/NotFound"
          description: 资源不存在（404xx）
        "422":
          $ref: "#/components/responses/Unprocessable"
          description: 用户已注销（42200）
      security:
        - bearerAuth: []
  /admin/users/{id}/restore:
    put:
      summary: 恢复已注销用户
      deprecated: false
      description: |
        需 admin 角色。将 user.state 从 is_deleted 恢复至 njupter。不记忆注销前的状态 ——
        原 on_sast 成员恢复后为 njupter，需管理员另行调整。已撤销的 token 不恢复，
        用户需重新登录。
      operationId: adminRestoreUser
      tags:
        - Admin
      parameters:
        - name: id
          in: path
          description: 用户 ID
          required: true
          example: 0
          schema:
            type: integer
      responses:
        "200":
          description: 恢复成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
          headers: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 无权限（403xx）
        "404":
          $ref: "#/components/responses/NotFound"
          description: 资源不存在（404xx）
        "422":
          $ref: "#/components/responses/Unprocessable"
          description: 用户未被注销，无需恢复（42200）
      security:
        - bearerAuth: []
  /admin/oauth-clients:
    get:
      summary: OAuth 客户端列表
      deprecated: false
      description: 需 admin 角色。
      operationId: adminListOAuthClients
      tags:
        - Admin
      parameters: []
      responses:
        "200":
          description: 客户端列表
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdminOAuthClientsListResponse"
          headers: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 无权限（403xx）
      security:
        - bearerAuth: []
    post:
      summary: 注册 OAuth 客户端
      deprecated: false
      description: 需 admin 角色。第一方应用不返回 client_secret。
      operationId: adminCreateOAuthClient
      tags:
        - Admin
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - client_name
                - client_type
                - redirect_uris
                - grant_types
                - scopes
              properties:
                client_name:
                  type: string
                  description: 应用名称
                  example: 新应用
                client_type:
                  $ref: "#/components/schemas/ClientType"
                redirect_uris:
                  type: array
                  items:
                    type: string
                    format: uri
                  minItems: 1
                  description: 允许的回调地址列表
                  example:
                    - https://app.example.com/callback
                grant_types:
                  type: array
                  items:
                    type: string
                    enum:
                      - authorization_code
                      - refresh_token
                  minItems: 1
                  description: 授权模式
                  example:
                    - authorization_code
                    - refresh_token
                scopes:
                  type: array
                  items:
                    type: string
                  description: 授权范围
                  example:
                    - openid
                    - profile
        required: true
      responses:
        "201":
          description: 客户端创建成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthClientCreateResponse"
          headers: {}
        "400":
          description: |
            校验失败（40000）。包括：`redirect_uris` 违反注册规则（非 https 且非
            loopback、含 fragment 或 userinfo、非绝对 URI、含首尾空白、超过 10 条、
            单条超 2048 字符、重复）；`grant_types` 含不支持的值或缺少
            `authorization_code`；`scopes` 为空、缺少 `openid` 或含不支持的值；
            `client_type` 非法；请求体传入 `client_id` / `client_secret` / `id`。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardEnvelope"
          headers: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 无权限（403xx）
        "500":
          description: |
            服务器内部错误（50000）。`client_id` 由服务端以 16 随机字节生成，因此
            唯一键冲突不是调用方可修正的冲突，不返回 409：要么是不会复现的碰撞，
            要么是真实故障，两种情况下管理员都应重试而非改名。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardEnvelope"
          headers: {}
      security:
        - bearerAuth: []
  /admin/oauth-clients/{id}:
    put:
      summary: 更新 OAuth 客户端
      deprecated: false
      description: 需 admin 角色。
      operationId: adminUpdateOAuthClient
      tags:
        - Admin
      parameters:
        - name: id
          in: path
          description: 客户端内部 ID
          required: true
          example: 0
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client_name:
                  type: string
                  description: 应用名称
                redirect_uris:
                  type: array
                  items:
                    type: string
                    format: uri
                  description: 回调地址列表
                is_active:
                  type: boolean
                  description: 是否启用
        required: true
      responses:
        "200":
          description: |
            更新成功。停用客户端（`is_active` 由 true 改为 false）会在同一事务内
            撤销该客户端的全部活跃 token。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
          headers: {}
        "400":
          description: |
            校验失败（40000）：请求体为空（未提交任何可更新字段）、未知字段，
            或 `redirect_uris` 违反注册规则（与创建时同一套校验）。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardEnvelope"
          headers: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "403":
          description: |
            无权限（403xx）。除角色不足外，还包括针对内置客户端
            （`INTERNAL_OAUTH_CLIENT_ID`，默认 `sast-link-web`）的受保护操作：
            停用它会使 `findInternalClient` 解析失败，令全站登录/刷新/注册立即中断
            且管理员自己也无法登录回来恢复，因此一律拒绝；改写它的 `redirect_uris`
            同样拒绝。改名允许。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardEnvelope"
          headers: {}
        "404":
          $ref: "#/components/responses/NotFound"
          description: 资源不存在（404xx）
      security:
        - bearerAuth: []
  /admin/audit-logs:
    get:
      summary: 查询审计日志
      deprecated: false
      description: 需 admin 角色。
      operationId: adminListAuditLogs
      tags:
        - Admin
      parameters:
        - name: page
          in: query
          description: 页码，默认 1
          required: false
          schema:
            type: integer
            default: 1
        - name: page_size
          in: query
          description: 每页条数，默认 50，最大 100（超出按 100 截断）
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
        - name: user_id
          in: query
          description: 按用户筛选
          required: false
          schema:
            type: integer
            minimum: 1
        - name: action
          in: query
          description: 按操作类型筛选（精确匹配）
          required: false
          schema:
            type: string
        - name: resource
          in: query
          description: 按资源类型筛选（精确匹配）
          required: false
          schema:
            type: string
        - name: success
          in: query
          description: 是否成功。仅接受 true / false，其他写法返回 400
          required: false
          schema:
            type: boolean
        - name: start_time
          in: query
          description: |
            开始时间（RFC 3339，必须带时区偏移），含该时刻。
            不带偏移返回 400：created_at 是 timestamptz，按 UTC 猜测会使窗口偏移数小时。
          required: false
          schema:
            type: string
            format: date-time
        - name: end_time
          in: query
          description: 结束时间（RFC 3339，必须带时区偏移），不含该时刻
          required: false
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: 分页审计日志
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditLogsListResponse"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: 参数格式非法或时间窗口倒置（400xx）
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: 未认证（401xx）
        "403":
          $ref: "#/components/responses/Forbidden"
          description: 无权限（403xx）
      security:
        - bearerAuth: []
  /health:
    get:
      summary: 健康检查
      deprecated: false
      description: ""
      operationId: healthCheck
      tags:
        - Health
      parameters: []
      responses:
        "200":
          description: 服务正常
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
          headers: {}
      security: []
components:
  schemas:
    UserRole:
      type: string
      enum:
        - freshman
        - member
        - lecturer
        - admin
      description: 用户角色 — freshman（大一新生）/ member（正式成员）/ lecturer（讲师）/ admin（管理员）
    OAuthScope:
      type: string
      enum:
        - openid
        - profile
        - email
      description: OAuth 2.1 授权范围 — openid（用户标识，必选）/ profile（个人资料）/ email（邮箱）
    UserState:
      type: string
      enum:
        - njupter
        - on_sast
        - retired_sast
        - is_deleted
      description: 用户状态 — njupter（在校未加入）/ on_sast（现任成员）/ retired_sast（已离开）/ is_deleted（已注销）
    Department:
      type: string
      enum:
        - software
        - media
      description: 部门 — software（软件部）/ media（媒体部）
    EmailType:
      type: string
      enum:
        - njupt_email
        - sast_email
      description: 注册邮箱类型 — njupt_email（@njupt.edu.cn）/ sast_email（@sast.fun）
    LoginMethod:
      type: string
      enum:
        - github
        - lark
        - other_mail
      description: 第三方登录方式
    ClientType:
      type: string
      enum:
        - first_party
        - third_party
      description: OAuth 客户端类型 — first_party（SAST 内部应用）/ third_party（外部接入应用）
    College:
      type: string
      enum:
        - 贝尔英才学院
        - 通信与信息工程学院
        - 电光柔学院
        - 集成电路科学与工程学院（产教融合学院）
        - 计算机学院、软件学院、网络空间安全学院
        - 自动化学院
        - 人工智能学院
        - 材料科学与工程学院
        - 化学与生命科学学院
        - 物联网学院
        - 理学院
        - 现代邮政学院、智慧交通学院
        - 数字媒体与设计艺术学院
        - 管理学院
        - 经济学院
        - 社会与人口学院、社会工作学院
        - 外国语学院
        - 教育科学与技术学院
        - 波特兰学院
        - 其他
      description: 学院枚举
    AuthUser:
      type: object
      properties:
        id:
          type: integer
          description: 用户 ID
        login_email:
          type: string
          format: email
          description: 登录邮箱
        name:
          type: string
          description: 真实姓名
        role:
          $ref: "#/components/schemas/UserRole"
        state:
          $ref: "#/components/schemas/UserState"
        email_type:
          $ref: "#/components/schemas/EmailType"
        created_at:
          type: string
          format: date-time
          description: 创建时间
    Profile:
      type: object
      properties:
        nickname:
          type: string
          description: 昵称
          nullable: true
        department:
          allOf:
            - $ref: "#/components/schemas/Department"
          nullable: true
        intro:
          type: string
          description: 自我介绍
          nullable: true
        email:
          type: string
          format: email
          description: 对外展示邮箱
          nullable: true
        avatar:
          type: string
          format: uri
          description: 头像 URL
          nullable: true
        blog_url:
          type: string
          format: uri
          description: 个人博客链接
          nullable: true
        github_url:
          type: string
          format: uri
          description: GitHub 主页链接
          nullable: true
        created_at:
          type: string
          format: date-time
          description: 首次创建时间
        updated_at:
          type: string
          format: date-time
          description: 最后更新时间
    Identity:
      type: object
      properties:
        id:
          type: integer
          description: 绑定记录 ID
        provider:
          $ref: "#/components/schemas/LoginMethod"
        provider_id:
          type: string
          description: |
            第三方平台唯一标识：
            - `github` → GitHub 用户 ID
            - `lark` → 飞书 union_id（非 open_id，union_id 在同一租户下跨应用一致）
            - `other_mail` → 绑定邮箱地址
        identity_data:
          type: object
          description: 第三方平台资料（JSONB），结构随 provider 不同而变化
          properties: {}
          nullable: true
        token_expires_at:
          type: string
          format: date-time
          description: 第三方 access_token 过期时间
          nullable: true
        created_at:
          type: string
          format: date-time
          description: 绑定时间
        updated_at:
          type: string
          format: date-time
          description: 更新时间
    AdminUserItem:
      type: object
      properties:
        id:
          type: integer
          description: 用户 ID
        name:
          type: string
          description: 真实姓名
        student_id:
          type: string
          description: 学号
        login_email:
          type: string
          format: email
          description: 登录邮箱
        role:
          $ref: "#/components/schemas/UserRole"
        state:
          $ref: "#/components/schemas/UserState"
        email_type:
          $ref: "#/components/schemas/EmailType"
        phone_number:
          type: string
          description: 手机号
        qq_number:
          type: string
          description: QQ 号
        college:
          $ref: "#/components/schemas/College"
        major:
          type: string
          description: 专业
        department:
          allOf:
            - $ref: "#/components/schemas/Department"
          nullable: true
          description: 部门，用户尚无 profile 行时为 null
        created_at:
          type: string
          format: date-time
          description: 注册时间
        updated_at:
          type: string
          format: date-time
          description: 最后更新时间
    OAuthClient:
      type: object
      properties:
        id:
          type: integer
          description: 内部主键
        client_id:
          type: string
          description: |
            公开客户端标识符：服务端生成的 32 位小写十六进制字符串（16 随机字节），
            不是 UUID，不含连字符。内置客户端为固定值 `sast-link-web`。
            请勿按 UUID 格式校验。
        client_name:
          type: string
          description: 应用名称
        client_type:
          $ref: "#/components/schemas/ClientType"
        redirect_uris:
          type: array
          items:
            type: string
            format: uri
          description: 允许的重定向 URI 列表
        grant_types:
          type: array
          items:
            type: string
          description: 授权模式
        scopes:
          type: array
          items:
            $ref: "#/components/schemas/OAuthScope"
          description: 授权范围
        is_active:
          type: boolean
          description: 是否启用
        created_at:
          type: string
          format: date-time
          description: 创建时间
        updated_at:
          type: string
          format: date-time
          description: 更新时间
    OAuthClientWithSecret:
      type: object
      properties:
        id:
          type: integer
          description: 内部主键
        client_id:
          type: string
          description: |
            公开客户端标识符：服务端生成的 32 位小写十六进制字符串（16 随机字节），
            不是 UUID，不含连字符。内置客户端为固定值 `sast-link-web`。
            请勿按 UUID 格式校验。
        client_secret:
          type: string
          description: 密钥（第三方应用返回，第一方应用不返回）
        client_name:
          type: string
          description: 应用名称
        client_type:
          $ref: "#/components/schemas/ClientType"
        redirect_uris:
          type: array
          items:
            type: string
            format: uri
          description: 允许的重定向 URI 列表
        grant_types:
          type: array
          items:
            type: string
          description: 授权模式
        scopes:
          type: array
          items:
            $ref: "#/components/schemas/OAuthScope"
          description: 授权范围
        is_active:
          type: boolean
          description: 是否启用
        created_at:
          type: string
          format: date-time
          description: 创建时间
        updated_at:
          type: string
          format: date-time
          description: 更新时间
    AuditLog:
      type: object
      properties:
        id:
          type: integer
          description: 日志 ID
        user_id:
          type: integer
          description: 操作用户 ID
          nullable: true
        action:
          type: string
          description: 操作类型
          example: login
        resource:
          type: string
          description: 操作对象类型
          example: user
        resource_id:
          type: string
          description: 操作对象 ID
        detail:
          type: object
          description: 操作详情（JSONB），结构因 action 类型而异
          properties: {}
          example:
            method: password
        client_ip:
          type: string
          description: 客户端 IP
        user_agent:
          type: string
          description: User-Agent
        success:
          type: boolean
          description: 是否成功
        err_code:
          type: integer
          description: 错误码（成功时为 null）
          nullable: true
        created_at:
          type: string
          format: date-time
          description: 操作时间
    OAuthTokenRequest:
      type: object
      required:
        - grant_type
        - client_id
      properties:
        grant_type:
          type: string
          enum:
            - authorization_code
            - refresh_token
          description: 授权模式
        code:
          type: string
          description: 授权码（authorization_code 模式必填）
        redirect_uri:
          type: string
          format: uri
          description: 回调地址（authorization_code 模式必填）
        client_id:
          type: string
          description: 客户端标识（必填）
        client_secret:
          type: string
          description: 客户端密钥（第三方应用必填，第一方应用不使用）
        code_verifier:
          type: string
          description: PKCE code verifier 原始值（authorization_code 模式必填）
        refresh_token:
          type: string
          description: 刷新令牌（refresh_token 模式必填）
    OAuthError:
      type: object
      properties:
        error:
          type: string
          enum:
            - invalid_request
            - invalid_client
            - invalid_grant
            - unauthorized_client
            - unsupported_grant_type
            - unsupported_response_type
            - invalid_scope
            - access_denied
            - invalid_token
            - temporarily_unavailable
            - server_error
          description: >-
            RFC 6749 §4.1.2.1 / §5.2、RFC 6750 §3.1 错误代码。
            invalid_client 对应 401，但**不附带** WWW-Authenticate（本服务只从表单体
            读取 client_secret，通告未实现的 Basic 方案会让客户端反复重试并始终失败）；
            invalid_token 仅出现在 /userinfo，附带 Bearer 挑战头；
            temporarily_unavailable 用于限流（429）与依赖不可用（503）。
        error_description:
          type: string
          description: 错误描述
    # === 通用响应信封（标准端点） ===
    # 所有标准端点使用 { code: int, message: string, data: object|array|null } 响应信封。
    # 以下 StandardEnvelope 为通用模板，各端点的 data schema 在内嵌中各自定义。
    #
    # 不使用信封的例外：
    #   - /oauth/authorize → 成功/错误均为 redirect response，query 携带 request_id 或 error/error_description
    #   - /oauth/token → application/x-www-form-urlencoded 请求；成功/错误均为 OAuth JSON，字段名使用 scope（单数）；
    #     成功响应携带 Cache-Control: no-store 与 Pragma: no-cache（RFC 6749 §5.1）
    #   - /oauth/revoke → application/x-www-form-urlencoded 请求；RFC 7009 成功为 200 空响应体，错误为 OAuth JSON
    #
    # 使用信封的 OAuth 端点：
    #   - /oauth/authorize/consent → SAST Link 自有端点而非 RFC 定义端点，沿用标准信封
    #   - /userinfo → 成功为 OIDC UserInfo claims；错误为 RFC 6750 Bearer Token 格式
    #   - /health → 直接 {status, db, redis}
    #   - /card/{id} → 已下线（隐私重设计中），暂不响应
    #   - /.well-known/openid-configuration → OIDC Discovery JSON
    #   - /.well-known/jwks.json → JWKS JSON
    StandardEnvelope:
      type: object
      description: SAST Link v2 标准响应信封模板
      properties:
        code:
          type: integer
          description: 业务状态码，0 表示成功，非 0 表示错误
          example: 0
        message:
          type: string
          description: 可读的描述信息，成功时为 "ok"
          example: ok
        data:
          description: 业务数据载荷，错误时为 null
    # === 具体响应 schema ===
    SendCodeResponse:
      type: object
      description: 发送验证码响应
      properties:
        code:
          type: integer
          description: 业务状态码，0 表示成功
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          type: object
          properties:
            message:
              type: string
              description: 提示信息
              example: 验证码已发送至邮箱
            expires_in:
              type: integer
              description: 验证码有效期（秒）
              example: 300
    RegisterTicketResponse:
      type: object
      description: 验证注册验证码响应
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          type: object
          properties:
            register_ticket:
              type: string
              description: Register-Ticket，有效期 5 分钟，一次性使用
              example: reg_abc123def456...
            expires_in:
              type: integer
              description: Ticket 有效期（秒）
              example: 300
    AuthResultResponse:
      type: object
      description: 登录/注册成功响应（含 Token + 用户信息）
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          type: object
          properties:
            access_token:
              type: string
              description: JWT Access Token，有效期 1 小时
            refresh_token:
              type: string
              description: Refresh Token，有效期 30 天，旋转机制
            token_type:
              type: string
              enum:
                - Bearer
              description: Token 类型
            expires_in:
              type: integer
              description: Access Token 有效期（秒）
              example: 3600
            user:
              $ref: "#/components/schemas/AuthUser"
    TokenRefreshResponse:
      type: object
      description: Token 刷新响应
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          type: object
          properties:
            access_token:
              type: string
              description: 新的 JWT Access Token
            refresh_token:
              type: string
              description: 新的 Refresh Token（旋转机制）
            token_type:
              type: string
              enum:
                - Bearer
              description: Token 类型
            expires_in:
              type: integer
              description: Access Token 有效期（秒）
              example: 3600
    MessageResponse:
      type: object
      description: 通用消息响应（登出、修改密码、解绑等）
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          type: object
          properties:
            message:
              type: string
              description: 操作结果信息
              example: 操作成功
    UserProfileData:
      type: object
      description: 用户完整资料
      properties:
        id:
          type: integer
          description: 用户 ID
        name:
          type: string
          description: 真实姓名
        login_email:
          type: string
          format: email
          description: 登录邮箱
        role:
          $ref: "#/components/schemas/UserRole"
        state:
          $ref: "#/components/schemas/UserState"
        email_type:
          $ref: "#/components/schemas/EmailType"
        phone_number:
          type: string
          description: 手机号
        qq_number:
          type: string
          description: QQ 号
        student_id:
          type: string
          description: 学号
        college:
          $ref: "#/components/schemas/College"
        major:
          type: string
          description: 专业
        profile:
          allOf:
            - $ref: "#/components/schemas/Profile"
          nullable: true
          description: 用户尚无 profile 行时为 null
        identities:
          type: array
          description: 第三方账号绑定列表
          items:
            $ref: "#/components/schemas/Identity"
        created_at:
          type: string
          format: date-time
          description: 注册时间
        updated_at:
          type: string
          format: date-time
          description: 最后更新时间
    UserProfileResponse:
      type: object
      description: 用户资料响应
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          $ref: "#/components/schemas/UserProfileData"
    ProfileUpdateResponse:
      type: object
      description: 当前用户个人信息更新响应
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          type: object
          properties:
            message:
              type: string
              description: 操作结果
              example: 个人信息更新成功
            user:
              $ref: "#/components/schemas/UserProfileData"
    AvatarUploadResponse:
      type: object
      description: 头像上传响应
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          type: object
          properties:
            avatar_url:
              type: string
              format: uri
              description: 头像 URL
              example: https://cos.example.com/avatar/1.jpg
    IdentitiesListResponse:
      type: object
      description: 绑定列表响应
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          type: object
          properties:
            identities:
              type: array
              description: 第三方账号绑定列表
              items:
                $ref: "#/components/schemas/Identity"
    Device:
      type: object
      description: 已登录设备
      properties:
        device_id:
          type: string
          description: 设备 ID（token family_id，UUID）
        ua:
          type: string
          description: 登录时的 User-Agent
        ip:
          type: string
          description: 登录时的 IP
        login_time:
          type: string
          format: date-time
          description: 登录时间
        last_seen:
          type: string
          format: date-time
          description: 最近一次刷新 Token 的时间（有效记录刷新不续期 TTL；记录过期后再次刷新会重新登记，受 5 台上限约束，超出时淘汰最旧设备并撤销其会话）
    DevicesListResponse:
      type: object
      description: 设备列表响应
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          type: object
          properties:
            devices:
              type: array
              description: 已登录设备列表（按最近登录倒序；Redis 不可用时为空数组）
              items:
                $ref: "#/components/schemas/Device"
    DeviceLogoutResponse:
      type: object
      description: 登出指定设备响应
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          type: object
          properties:
            message:
              type: string
              description: 登出结果描述
              example: 该设备已登出
    IdentityBindResponse:
      type: object
      description: 第三方账号绑定响应
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          type: object
          properties:
            message:
              type: string
              description: 绑定结果描述
              example: 绑定成功
            identity:
              $ref: "#/components/schemas/Identity"
    BindTicketResponse:
      type: object
      description: 获取绑定票据响应
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          type: object
          properties:
            bind_ticket:
              type: string
              description: Bind-Ticket，有效期 5 分钟，一次性使用
              example: be_abc123def456...
            expires_in:
              type: integer
              description: Ticket 有效期（秒）
              example: 300
    AdminUsersListResponse:
      type: object
      description: 管理后台用户列表响应
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          type: object
          properties:
            users:
              type: array
              description: 用户列表
              items:
                $ref: "#/components/schemas/AdminUserItem"
            total:
              type: integer
              description: 总记录数
              example: 500
            page:
              type: integer
              description: 当前页码
              example: 1
            page_size:
              type: integer
              description: 每页条数
              example: 20
    AdminOAuthClientsListResponse:
      type: object
      description: OAuth 客户端列表响应
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          type: object
          properties:
            clients:
              type: array
              description: 客户端列表
              items:
                $ref: "#/components/schemas/OAuthClient"
    OAuthClientCreateResponse:
      type: object
      description: OAuth 客户端创建响应
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          $ref: "#/components/schemas/OAuthClientWithSecret"
    AuditLogsListResponse:
      type: object
      description: 审计日志列表响应
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 0
        message:
          type: string
          description: 可读描述信息
          example: ok
        data:
          type: object
          properties:
            logs:
              type: array
              description: 日志列表
              items:
                $ref: "#/components/schemas/AuditLog"
            total:
              type: integer
              description: 总记录数
            page:
              type: integer
              description: 当前页码
            page_size:
              type: integer
              description: 每页条数
    OAuthTokenResponse:
      type: object
      description: |
        OAuth 2.1 Token 响应（RFC 6749 格式，不使用 SAST Link 标准响应信封）。
        固定额外返回 OIDC ID Token：本服务强制所有 scope 均包含 `openid`，
        不支持纯 OAuth2（非 OIDC）模式。
        字段名 `scope` 为 OAuth 线协议标准单数字段；数据库列仍保留 `scopes`。
      properties:
        access_token:
          type: string
          description: JWT Access Token
        refresh_token:
          type: string
          description: Refresh Token
        token_type:
          type: string
          enum:
            - Bearer
          description: Token 类型
        expires_in:
          type: integer
          description: Access Token 有效期（秒）
          example: 3600
        id_token:
          type: string
          description: |
            OIDC ID Token（EdDSA / Ed25519 签名 JWT）。仅在 scope 包含 `openid` 时返回。
            ID Token 包含以下 OIDC 标准 claims，具体内容取决于授权 scope。
          example: eyJhbGciOiJFZERTQSIs...
        scope:
          type: string
          description: 授权范围，空格分隔，取值见 OAuthScope 枚举（openid / profile / email）
          example: openid profile
    HealthResponse:
      type: object
      description: |
        健康检查响应（不使用标准信封）。
        只有 PostgreSQL 是必需依赖：Redis 不可用时返回 200 且 redis 为 degraded。
      properties:
        status:
          type: string
          description: 服务状态，仅由必需依赖（db）决定
          enum:
            - ok
            - error
          example: ok
        db:
          type: string
          description: 数据库状态（必需依赖，error 时 HTTP 500）
          enum:
            - ok
            - error
          example: ok
        redis:
          type: string
          description: Redis 状态（可选依赖，故障时为 degraded，不影响 status）
          enum:
            - ok
            - degraded
          example: ok
    CardResponse:
      type: object
      description: 个人卡片响应（公开端点，不使用标准信封）
      properties:
        id:
          type: integer
          description: 用户 ID
          example: 1
        nickname:
          type: string
          nullable: true
          description: 昵称
          example: 张三
        department:
          allOf:
            - $ref: "#/components/schemas/Department"
          nullable: true
        intro:
          type: string
          nullable: true
          description: 自我介绍
          example: 自我介绍
        avatar:
          type: string
          nullable: true
          format: uri
          description: 头像 URL
          example: https://cos.example.com/avatar/1.jpg
        blog_url:
          type: string
          nullable: true
          format: uri
          description: 个人博客链接
          example: https://blog.example.com
        github_url:
          type: string
          nullable: true
          format: uri
          description: GitHub 主页链接
          example: https://github.com/example
    OpenIDConfiguration:
      type: object
      description: |
        OIDC Discovery 文档，符合 [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) 规范。
      properties:
        issuer:
          type: string
          description: OIDC Provider 唯一标识，与 ID Token 中的 iss 一致
          example: https://link.sast.fun/v2
        authorization_endpoint:
          type: string
          description: OAuth 2.0 授权端点
          example: https://link.sast.fun/v2/oauth/authorize
        token_endpoint:
          type: string
          description: OAuth 2.0 Token 端点
          example: https://link.sast.fun/v2/oauth/token
        userinfo_endpoint:
          type: string
          description: UserInfo 端点
          example: https://link.sast.fun/v2/userinfo
        jwks_uri:
          type: string
          description: JWKS 公钥集端点
          example: https://link.sast.fun/v2/.well-known/jwks.json
        revocation_endpoint:
          type: string
          description: Token 撤销端点
          example: https://link.sast.fun/v2/oauth/revoke
        scopes_supported:
          type: array
          items:
            type: string
          description: 支持的 scope
          example:
            - openid
            - profile
            - email
        response_types_supported:
          type: array
          items:
            type: string
          description: 支持的 response_type
          example:
            - code
        grant_types_supported:
          type: array
          items:
            type: string
          description: 支持的 grant_type
          example:
            - authorization_code
            - refresh_token
        subject_types_supported:
          type: array
          items:
            type: string
          description: 支持的 subject 类型
          example:
            - public
        id_token_signing_alg_values_supported:
          type: array
          items:
            type: string
          description: ID Token 签名算法
          example:
            - EdDSA
        token_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
          description: Token 端点客户端认证方式
          example:
            - none
            - client_secret_post
        claims_supported:
          type: array
          items:
            type: string
          description: |
            支持的 claims。注意 `auth_time` **会在 ID Token 中签发但不在此列表中**：
            当前可得的值是授权确认时刻而非真实认证时刻，会高报认证新鲜度，
            通告它等于邀请 RP 依赖一个本服务尚无法正确产出的值。
            待持久化真实认证时刻后再加回。
          example:
            - sub
            - iss
            - aud
            - exp
            - iat
            - nonce
            - name
            - picture
            - preferred_username
            - profile
            - email
            - email_verified
            - updated_at
        code_challenge_methods_supported:
          type: array
          items:
            type: string
          description: 支持的 PKCE 挑战方法（S256-only；V001 数据库历史约束曾允许 plain，V002 收紧）
          example:
            - S256
        request_parameter_supported:
          type: boolean
          description: 是否支持 request 参数
          example: false
        request_uri_parameter_supported:
          type: boolean
          description: 是否支持 request_uri 参数
          example: false
        claims_parameter_supported:
          type: boolean
          description: 是否支持 claims 参数
          example: false
        response_modes_supported:
          type: array
          items:
            type: string
          description: 支持的 response_mode
          example:
            - query
        claim_types_supported:
          type: array
          items:
            type: string
          description: 支持的 claim 类型
          example:
            - normal
    JWKS:
      type: object
      description: JSON Web Key Set，符合 [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517) 规范
      properties:
        keys:
          type: array
          description: 公钥列表
          items:
            $ref: "#/components/schemas/JWK"
    JWK:
      type: object
      description: JSON Web Key，Ed25519 公钥（RFC 8037 OKP）
      properties:
        kty:
          type: string
          description: 密钥类型
          example: OKP
        use:
          type: string
          description: 用途
          example: sig
        kid:
          type: string
          description: 密钥 ID，用于匹配 JWT 头中的 kid
          example: link-v2-active
        crv:
          type: string
          description: 曲线名
          example: Ed25519
        alg:
          type: string
          description: 签名算法
          example: EdDSA
        x:
          type: string
          description: Ed25519 公钥坐标（Base64URL，32 字节）
          example: 11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo
    UserInfoResponse:
      type: object
      description: |
        OIDC UserInfo 端点响应。返回的 claims 取决于 Access Token 的 scope：
        - `openid` → sub（必返）
        - `profile` → name, picture, preferred_username, updated_at
        - `email` → email, email_verified

        未授权或用户未填写的 claim 一律**不出现在响应中**，而不是返回 `null`
        或空值——所有字段均为 `omitempty`。客户端应按「键是否存在」判断，
        不要依赖 `null`。
      properties:
        sub:
          type: string
          description: 用户唯一标识（user.id 字符串）。openid scope 时必返
          example: "1"
        name:
          type: string
          description: 真实姓名。需 profile scope
          example: 张三
        picture:
          type: string
          format: uri
          description: 头像 URL。需 profile scope
          example: https://cos.example.com/avatar/1.jpg
        preferred_username:
          type: string
          description: 昵称（fallback 至姓名）。需 profile scope
          example: 张三
        email:
          type: string
          format: email
          description: 注册邮箱。需 email scope
          example: b2404****@njupt.edu.cn
        email_verified:
          type: boolean
          description: 邮箱是否已验证。需 email scope。SAST Link 注册时已校验邮箱，固定为 true
          example: true
        updated_at:
          type: integer
          description: 用户信息最后修改时间（Unix timestamp）。需 profile scope
          example: 1717396400
    IDTokenClaims:
      type: object
      description: |
        ID Token claims 说明（仅供文档参考，非实际返回结构）。
        ID Token 是一个 EdDSA（Ed25519）签名的 JWT，当 scope 包含 `openid` 时在 token 端点响应中返回。
        其 Header 包含 `alg=EdDSA` 和 `kid`，Payload 包含以下 claims。
      properties:
        iss:
          type: string
          description: Issuer，OIDC Provider 标识
          example: https://link.sast.fun/v2
        sub:
          type: string
          description: Subject，用户唯一标识（user.id 字符串）
          example: "1"
        aud:
          type: string
          description: Audience，客户端 client_id
          example: 9f3a1c7d2e5b40a8c6d1f4b7a2e9c3d5
        exp:
          type: integer
          description: 过期时间（Unix timestamp）
          example: 1717400000
        iat:
          type: integer
          description: 签发时间（Unix timestamp）
          example: 1717396400
        auth_time:
          type: integer
          description: |
            **授权确认时间，不是 OIDC 定义的认证时间**（Unix timestamp）。服务端尚未持久化
            真实认证时刻，因此闲置多日后再授权会把该值报成今天，高报认证新鲜度。
            该 claim 因此不在 `claims_supported` 中通告，`max_age` / `prompt` 也未实现，
            请勿依赖它判断认证新鲜度。
          example: 1717396400
        nonce:
          type: string
          description: 防重放值，与授权请求中的 nonce 一致
          example: n-0S6_WzA2Mj
        name:
          type: string
          description: 真实姓名（需 profile scope）
          example: 张三
        picture:
          type: string
          format: uri
          description: 头像 URL（需 profile scope）
          example: https://cos.example.com/avatar/1.jpg
          nullable: true
        preferred_username:
          type: string
          description: 昵称 / 常用用户名（需 profile scope）
          example: 张三
          nullable: true
        email:
          type: string
          format: email
          description: 注册邮箱（需 email scope）
          example: b2404****@njupt.edu.cn
        email_verified:
          type: boolean
          description: 邮箱已验证（需 email scope，SAST Link 固定为 true）
          example: true
        updated_at:
          type: integer
          description: 用户信息最后修改时间，Unix timestamp（需 profile scope）
          example: 1717396400
          nullable: true
  responses:
    BadRequest:
      description: 参数错误（400xx）
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                description: 业务状态码
              message:
                type: string
                description: 错误描述
              data:
                nullable: true
            required:
              - code
              - message
              - data
          examples:
            invalid_params:
              summary: invalid_params
              value:
                code: 40000
                message: 请求参数错误
                data: null
            missing_params:
              summary: missing_params
              value:
                code: 40001
                message: 缺少必要参数
                data: null
            invalid_email_domain:
              summary: invalid_email_domain
              value:
                code: 40020
                message: 邮箱域名不允许（仅限 @njupt.edu.cn / @sast.fun）
                data: null
    Unauthorized:
      description: 未认证（401xx）
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              message:
                type: string
              data:
                nullable: true
            required:
              - code
              - message
              - data
          examples:
            not_logged_in:
              summary: not_logged_in
              value:
                code: 40100
                message: 未登录（缺少或无效 Authorization Header）
                data: null
            wrong_password:
              summary: wrong_password
              value:
                code: 40105
                message: 密码错误
                data: null
            email_not_found:
              summary: email_not_found
              value:
                code: 40106
                message: 登录邮箱不存在
                data: null
            token_expired:
              summary: token_expired
              value:
                code: 40101
                message: Access Token 已过期
                data: null
            invalid_token:
              summary: invalid_token
              value:
                code: 40102
                message: Access Token 无效或已被撤销
                data: null
    Forbidden:
      description: 无权限（403xx）
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              message:
                type: string
              data:
                nullable: true
            required:
              - code
              - message
              - data
          examples:
            no_permission:
              summary: no_permission
              value:
                code: 40300
                message: 无权限（需 admin / lecturer 角色）
                data: null
            account_deleted:
              summary: account_deleted
              value:
                code: 40301
                message: 账号已注销
                data: null
    NotFound:
      description: 资源不存在（404xx）
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              message:
                type: string
              data:
                nullable: true
            required:
              - code
              - message
              - data
          examples:
            not_found:
              summary: not_found
              value:
                code: 40400
                message: 资源不存在
                data: null
            user_not_found:
              summary: user_not_found
              value:
                code: 40401
                message: 用户不存在
                data: null
    Conflict:
      description: 资源冲突（409xx）
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              message:
                type: string
              data:
                nullable: true
            required:
              - code
              - message
              - data
          examples:
            email_registered:
              summary: email_registered
              value:
                code: 40901
                message: 邮箱已被注册
                data: null
            identity_bound:
              summary: identity_bound
              value:
                code: 40903
                message: 第三方账号已被其他用户绑定
                data: null
            too_many_emails:
              summary: too_many_emails
              value:
                code: 40905
                message: 第三方邮箱绑定数量已达上限（2 个）
                data: null
    Unprocessable:
      description: 业务校验失败（422xx）
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              message:
                type: string
              data:
                nullable: true
            required:
              - code
              - message
              - data
          examples:
            short_password:
              summary: short_password
              value:
                code: 42201
                message: 密码长度不足（最短 8 位）
                data: null

    TooManyRequests:
      description: 频率限制（429xx）
      headers:
        Retry-After:
          description: >-
            建议等待的整数秒，由剩余限流窗口或账号锁定剩余时间向上取整（最小 1）。剩余时间无法确定时不返回该头。
          required: false
          schema:
            type: integer
            minimum: 1
            example: 900
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              message:
                type: string
              data:
                nullable: true
            required:
              - code
              - message
              - data
          examples:
            rate_limited:
              summary: rate_limited
              value:
                code: 42900
                message: 请求过于频繁，请稍后再试
                data: null
    InternalError:
      description: 服务端错误（500xx）
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              message:
                type: string
              data:
                nullable: true
            required:
              - code
              - message
              - data
          examples:
            internal:
              summary: internal
              value:
                code: 50000
                message: 服务器内部错误
                data: null
            email_fail:
              summary: email_fail
              value:
                code: 50001
                message: 邮件发送失败
                data: null
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer Token。Access Token 有效期 1 小时。
servers: []
security: []