openapi.yaml

openapi: 3.1.0
info:
  title: TOMEET API
  version: 1.0.0
  description: TOMEET backend API。Agent routes use Supabase Bearer access tokens; the public WeChat QR flow uses a one-time session token.
servers:
  - url: https://{apiHost}
    description: Railway production
    variables:
      apiHost:
        default: your-api.up.railway.app
security:
  - bearerAuth: []
tags:
  - name: Operations
  - name: Agent
  - name: Uploads
  - name: Users
  - name: Matchmaking
  - name: AdventureX Testing
  - name: Rooms
  - name: Jobs
  - name: Authentication
  - name: WeChat QR
paths:
  /health:
    get:
      tags: [Operations]
      summary: 进程存活检查
      security: []
      responses:
        "200":
          description: API 进程正常
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /ready:
    get:
      tags: [Operations]
      summary: 依赖服务就绪检查
      security: []
      responses:
        "200":
          description: Supabase 可访问
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReadyResponse"
        "503":
          description: 依赖服务暂不可用
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotReadyResponse"
  /agent/messages:
    post:
      tags: [Agent]
      summary: 发送用户消息
      description: 写入用户消息并创建 agent_reply 异步任务。生产环境通常返回 202。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgentMessageInput"
      responses:
        "200":
          description: Demo 内联处理已完成
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentMessageResponse"
        "202":
          description: 已接受，等待 Worker 处理
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentMessageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/RateLimited"
  /agent/messages/{userId}:
    get:
      tags: [Agent]
      summary: 获取最近对话
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "200":
          description: 最近 100 条消息，按时间正序
          content:
            application/json:
              schema:
                type: object
                required: [messages]
                properties:
                  messages:
                    type: array
                    items:
                      $ref: "#/components/schemas/Message"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
  /agent/multimodal-inputs:
    post:
      tags: [Agent]
      summary: 登记多模态输入
      description: 文件应先上传到私有 Bucket；本接口登记文件并创建理解任务。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MultimodalInput"
      responses:
        "200":
          description: Demo 内联处理已完成
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultimodalResponse"
        "202":
          description: 已接受，等待 Worker 处理
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultimodalResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
  /uploads/sign:
    post:
      tags: [Uploads]
      summary: 创建一次性上传凭据
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignUploadInput"
      responses:
        "200":
          description: Supabase signed upload path 与 token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignUploadResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
  /uploads:
    post:
      tags: [Uploads]
      summary: Base64 图片上传兼容接口
      description: 支持 JPG、PNG、WebP，解码后最大 10MB。生产前端优先使用 /uploads/sign。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Base64UploadInput"
      responses:
        "200":
          description: 文件已保存
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
  /users/{userId}/model:
    get:
      tags: [Users]
      summary: 获取公开用户模型
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "200":
          description: 用户模型；不包含内部记忆 profile
          content:
            application/json:
              schema:
                type: object
                required: [userModel]
                properties:
                  userModel:
                    $ref: "#/components/schemas/UserModel"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
  /users/{userId}/adventurex-onboarding/start:
    post:
      tags: [Users]
      summary: 幂等开始 AdventureX 引导
      parameters:
        - $ref: "#/components/parameters/UserId"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                language:
                  type: string
                  enum: [zh, en]
                  default: zh
      responses:
        "200":
          description: 当前引导状态和首次开场消息
          content:
            application/json:
              schema:
                type: object
                required: [state, message, messages]
                properties:
                  state:
                    $ref: "#/components/schemas/AdventurexOnboardingState"
                  message:
                    anyOf:
                      - $ref: "#/components/schemas/Message"
                      - type: "null"
                  messages:
                    type: array
                    maxItems: 1
                    items:
                      $ref: "#/components/schemas/Message"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
  /offline-games:
    get:
      tags: [Matchmaking]
      summary: 获取启用的线下游戏
      responses:
        "200":
          description: 当前游戏目录
          content:
            application/json:
              schema:
                type: object
                required: [games]
                properties:
                  games:
                    type: array
                    items:
                      $ref: "#/components/schemas/OfflineGame"
        "401":
          $ref: "#/components/responses/Unauthenticated"
  /adventurex/test-pool:
    get:
      tags: [AdventureX Testing]
      summary: 读取当前白名单账号的虚拟测试池状态
      responses:
        "200":
          description: 测试池状态
          content:
            application/json:
              schema:
                type: object
                required: [testPool]
                properties:
                  testPool:
                    $ref: "#/components/schemas/AdventurexTestPoolStatus"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
        "503":
          description: 虚拟测试池功能未启用
    post:
      tags: [AdventureX Testing]
      summary: 开关并配置当前白名单账号的隔离虚拟测试池
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [enabled]
              properties:
                enabled:
                  type: boolean
                desiredUserCount:
                  type: integer
                  minimum: 3
                  maximum: 12
                  default: 5
      responses:
        "200":
          description: 更新后的测试池状态
          content:
            application/json:
              schema:
                type: object
                required: [testPool]
                properties:
                  testPool:
                    $ref: "#/components/schemas/AdventurexTestPoolStatus"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
        "503":
          description: 虚拟测试池功能未启用
  /match-requests:
    post:
      tags: [Matchmaking]
      summary: 创建匹配请求
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateMatchRequestInput"
      responses:
        "201":
          description: 请求内已完成匹配
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateMatchRequestResponse"
        "202":
          description: 已进入匹配队列
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateMatchRequestResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
  /match-requests/{id}:
    get:
      tags: [Matchmaking]
      summary: 查询匹配请求
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: 匹配请求
          content:
            application/json:
              schema:
                type: object
                required: [matchRequest]
                properties:
                  matchRequest:
                    $ref: "#/components/schemas/MatchRequest"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "404":
          $ref: "#/components/responses/NotFound"
  /match-requests/{id}/cancel:
    post:
      tags: [Matchmaking]
      summary: 取消等待中的匹配请求
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: 已取消
          content:
            application/json:
              schema:
                type: object
                required: [matchRequest]
                properties:
                  matchRequest:
                    $ref: "#/components/schemas/MatchRequest"
                  canRematch:
                    type: boolean
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /match-requests/{id}/options:
    get:
      tags: [Matchmaking]
      summary: 获取当前公开候选
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: 不包含 hook ID、候选成员 ID 的 1–3 个候选
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicMatchOptions"
        "404":
          $ref: "#/components/responses/NotFound"
  /match-requests/{id}/choices:
    post:
      tags: [Matchmaking]
      summary: 提交结构化候选选择
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MatchChoicesInput"
      responses:
        "200":
          description: 选择已保存，或已加入开放局
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /match-requests/{id}/options/refresh:
    post:
      tags: [Matchmaking]
      summary: 放弃本批候选并进入下一轮
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: 已计划下一轮
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /match-requests/{id}/rematch:
    post:
      tags: [Matchmaking]
      summary: 从已取消或已超时请求创建全新匹配请求
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: 新请求和计划轮次
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /match-requests/{id}/open-room/{roomId}/join:
    post:
      tags: [Matchmaking]
      summary: 使用 offer 版本原子加入开放局
      parameters:
        - $ref: "#/components/parameters/ResourceId"
        - name: roomId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Uuid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [offerId, sourceVersion]
              properties:
                offerId:
                  $ref: "#/components/schemas/Uuid"
                sourceVersion:
                  type: integer
                  minimum: 0
      responses:
        "200":
          description: 已加入开放局
        "409":
          $ref: "#/components/responses/Conflict"
  /match-invites/{id}:
    get:
      tags: [Matchmaking]
      summary: 查询匹配邀请
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: 当前用户参与的匹配邀请
          content:
            application/json:
              schema:
                type: object
                required: [invite]
                properties:
                  invite:
                    $ref: "#/components/schemas/MatchInvite"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "404":
          $ref: "#/components/responses/NotFound"
  /match-invites/{id}/accept:
    post:
      tags: [Matchmaking]
      summary: 接受初始匹配或入房邀请
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserIdBody"
      responses:
        "200":
          description: 邀请接受结果；初始邀请双方接受后才创建房间
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MatchInviteResolution"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
  /match-invites/{id}/decline:
    post:
      tags: [Matchmaking]
      summary: 拒绝初始匹配或入房邀请
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserIdBody"
      responses:
        "200":
          description: 邀请拒绝及重新入队结果
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MatchInviteResolution"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
  /jobs/{id}:
    get:
      tags: [Jobs]
      summary: 查询异步任务
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: 当前用户的任务
          content:
            application/json:
              schema:
                type: object
                required: [job]
                properties:
                  job:
                    $ref: "#/components/schemas/LlmJob"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "404":
          $ref: "#/components/responses/NotFound"
  /rooms/{id}:
    get:
      tags: [Rooms]
      summary: 查询匹配房间
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: 当前用户所在的房间
          content:
            application/json:
              schema:
                type: object
                required: [room]
                properties:
                  room:
                    $ref: "#/components/schemas/MatchRoom"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "404":
          $ref: "#/components/responses/NotFound"
  /rooms/{id}/event-plan:
    patch:
      tags: [Rooms]
      summary: 创建活动清单的新草稿版本
      description: 仅初始两位 founder 可调用；expectedVersion 用于防止并发覆盖。
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateEventPlanInput"
      responses:
        "200":
          description: 新草稿及更新后的房间
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventPlanMutationResult"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
  /rooms/{id}/event-plan/confirm:
    post:
      tags: [Rooms]
      summary: 确认指定活动清单版本
      description: 仅 founder 可确认；两位 founder 确认同一版本后原子发布。
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfirmEventPlanInput"
      responses:
        "200":
          description: 确认进度或发布结果
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventPlanMutationResult"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
  /rooms/{id}/confirm:
    post:
      tags: [Rooms]
      summary: 确认参加房间
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserIdBody"
      responses:
        "200":
          description: 更新后的房间
          content:
            application/json:
              schema:
                type: object
                required: [room]
                properties:
                  room:
                    $ref: "#/components/schemas/MatchRoom"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
  /rooms/{id}/stop-match:
    post:
      tags: [Rooms]
      summary: 停止房间继续匹配新成员
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserIdBody"
      responses:
        "200":
          description: 已停止继续匹配；待处理候选重新入队
          content:
            application/json:
              schema:
                type: object
                required: [room, requeuedRequestIds]
                properties:
                  room:
                    $ref: "#/components/schemas/MatchRoom"
                  requeuedRequestIds:
                    type: array
                    items:
                      $ref: "#/components/schemas/Uuid"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
  /rooms/{id}/complete:
    post:
      tags: [Rooms]
      summary: 标记线下活动完成
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: 已完成的房间
          content:
            application/json:
              schema:
                type: object
                required: [room]
                properties:
                  room:
                    $ref: "#/components/schemas/MatchRoom"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /rooms/{id}/leave:
    post:
      tags: [Rooms]
      summary: 退出已确认房间
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RoomLeaveBody"
      responses:
        "200":
          description: 已退出；响应包含 canRematch=false、最新匹配请求与 watching/ended 意愿状态
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /rooms/{id}/feedback:
    post:
      tags: [Rooms]
      summary: 提交活动反馈
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostEventFeedbackInput"
      responses:
        "200":
          description: Demo 内联更新已完成
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeedbackResponse"
        "202":
          description: 反馈已保存，等待模型更新
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeedbackResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
  /auth/wechat/claim:
    post:
      tags: [Authentication]
      summary: Redeem a one-time WeChat Web registration claim
      description: |
        The registration page reads the claim from the URL fragment and sends it
        in the JSON body. A successful response returns the Supabase anonymous
        session that already owns the WeChat profile. The client must call
        supabase.auth.setSession before upgrading that same user with email and
        password, phone and password, or a linked Google identity. If the browser
        already has a session, send its optional Bearer token; a different account
        receives a non-consuming 409 account-switch response.
      security:
        - {}
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WechatWebClaimInput"
      responses:
        "200":
          description: Claim consumed; continue registration with the returned session
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
            Referrer-Policy:
              schema:
                type: string
                const: no-referrer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatWebClaimResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Claim is invalid, expired, or already consumed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatSessionError"
        "409":
          description: The browser is signed in to a different TOMEET account; the claim is not consumed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatSessionError"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          description: WeChat Web registration is not configured
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatSessionError"
  /wechat/connect/sessions:
    post:
      tags: [WeChat QR]
      summary: Create a one-time WeChat QR connection session
      description: |
        Anonymous kiosk clients should omit Authorization. A signed-in client may
        optionally send a Supabase Bearer token to bind the activated WeChat
        identity to its existing profile. The session token and QR content are
        returned only by this response and must not be logged or persisted.
      security:
        - {}
        - bearerAuth: []
      responses:
        "201":
          description: One-time QR session created
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatQrSessionCreated"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          description: WeChat QR runtime is not configured
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatSessionError"
  /wechat/connect/sessions/{sessionId}:
    get:
      tags: [WeChat QR]
      summary: Read the current QR session state
      security:
        - wechatSessionToken: []
      parameters:
        - $ref: "#/components/parameters/WechatSessionId"
      responses:
        "200":
          description: Current public session state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatQrSession"
        "401":
          description: Missing or invalid one-time session token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatSessionError"
        "404":
          description: Session does not exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatSessionError"
        "409":
          description: Session activation conflicts with an existing profile binding
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatSessionError"
        "503":
          description: WeChat QR runtime is not configured
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatSessionError"
  /wechat/connect/sessions/{sessionId}/events:
    get:
      tags: [WeChat QR]
      summary: Stream QR session state through server-sent events
      description: |
        Use fetch with a readable stream because the native EventSource API
        cannot set X-WeChat-Session-Token. The server immediately emits
        `event: session`, emits state changes, and emits `event: done` before
        closing after active, expired, or failed.
      security:
        - wechatSessionToken: []
      parameters:
        - $ref: "#/components/parameters/WechatSessionId"
      responses:
        "200":
          description: |
            SSE stream whose `session` and `done` data payloads conform to
            WechatQrSession. Creation-only secrets are never included.
          content:
            text/event-stream:
              schema:
                type: string
        "401":
          description: Missing or invalid one-time session token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatSessionError"
        "404":
          description: Session does not exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatSessionError"
        "503":
          description: WeChat QR runtime is not configured
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatSessionError"
  /wechat/connect/sessions/{sessionId}/verify:
    post:
      tags: [WeChat QR]
      summary: Submit the verification code shown by WeChat
      security:
        - wechatSessionToken: []
      parameters:
        - $ref: "#/components/parameters/WechatSessionId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WechatVerificationCodeInput"
      responses:
        "200":
          description: Updated public session state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatQrSession"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Missing or invalid one-time session token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatSessionError"
        "404":
          description: Session does not exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatSessionError"
        "409":
          description: Verification is not allowed in the current session state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatSessionError"
        "503":
          description: WeChat QR runtime is not configured
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WechatSessionError"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Supabase JWT
    wechatSessionToken:
      type: apiKey
      in: header
      name: X-WeChat-Session-Token
  parameters:
    UserId:
      name: userId
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/Uuid"
      description: 必须等于 access token 对应的用户 ID
    ResourceId:
      name: id
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/Uuid"
    WechatSessionId:
      name: sessionId
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/Uuid"
  responses:
    BadRequest:
      description: 请求参数或格式错误
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
    Unauthenticated:
      description: token 缺失、无效或过期
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
    Forbidden:
      description: token 用户与请求用户不一致
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
    NotFound:
      description: 当前用户可见范围内的资源不存在
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
    Conflict:
      description: 当前业务状态不允许操作
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
    PayloadTooLarge:
      description: 请求体过大
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
    RateLimited:
      description: 请求过于频繁
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
  schemas:
    Uuid:
      type: string
      format: uuid
    JsonObject:
      type: object
      additionalProperties: true
    WechatQrSessionStatus:
      type: string
      enum:
        - pending
        - scanned
        - verification_required
        - active
        - expired
        - failed
    WechatQrSession:
      type: object
      additionalProperties: false
      required:
        - sessionId
        - status
        - expiresAt
        - confirmedAt
        - errorCode
        - errorMessage
      properties:
        sessionId:
          $ref: "#/components/schemas/Uuid"
        status:
          $ref: "#/components/schemas/WechatQrSessionStatus"
        expiresAt:
          type: string
          format: date-time
        confirmedAt:
          oneOf:
            - type: string
              format: date-time
            - type: "null"
        errorCode:
          oneOf:
            - type: string
            - type: "null"
        errorMessage:
          oneOf:
            - type: string
            - type: "null"
    WechatQrSessionCreated:
      type: object
      additionalProperties: false
      required:
        - sessionId
        - status
        - expiresAt
        - confirmedAt
        - errorCode
        - errorMessage
        - sessionToken
        - qrCodeContent
      properties:
        sessionId:
          $ref: "#/components/schemas/Uuid"
        status:
          $ref: "#/components/schemas/WechatQrSessionStatus"
        expiresAt:
          type: string
          format: date-time
        confirmedAt:
          oneOf:
            - type: string
              format: date-time
            - type: "null"
        errorCode:
          oneOf:
            - type: string
            - type: "null"
        errorMessage:
          oneOf:
            - type: string
            - type: "null"
        sessionToken:
          type: string
          minLength: 16
          description: One-time secret returned only during creation
        qrCodeContent:
          type: string
          minLength: 1
          description: Content rendered by the external frontend as a QR code
    WechatVerificationCodeInput:
      type: object
      additionalProperties: false
      required: [code]
      properties:
        code:
          type: string
          pattern: '^\d{4,12}$'
    WechatWebClaimInput:
      type: object
      additionalProperties: false
      required: [token]
      properties:
        token:
          type: string
          pattern: '^[A-Za-z0-9_-]{43}$'
    WechatWebClaimResponse:
      type: object
      additionalProperties: false
      required: [userId, session, registrationMethods, accountContinuity]
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
        session:
          type: object
          additionalProperties: false
          required: [accessToken, refreshToken]
          properties:
            accessToken:
              type: string
              minLength: 1
            refreshToken:
              type: string
              minLength: 1
        registrationMethods:
          type: array
          prefixItems:
            - const: email_password
            - const: phone_password
            - const: google
          minItems: 3
          maxItems: 3
        accountContinuity:
          type: object
          additionalProperties: false
          required: [mode, preserves]
          properties:
            mode:
              const: upgrade_existing_wechat_user
            preserves:
              type: array
              prefixItems:
                - const: conversation
                - const: profile
                - const: matching
              minItems: 3
              maxItems: 3
    WechatSessionError:
      type: object
      required: [error, message]
      properties:
        error:
          type: string
        message:
          type: string
        requestId:
          type: string
    HealthResponse:
      type: object
      required: [status, service, time]
      properties:
        status:
          type: string
          const: ok
        service:
          type: string
          const: tomeet-api
        time:
          type: string
          format: date-time
    ReadyResponse:
      type: object
      required: [status]
      properties:
        status:
          type: string
          const: ready
    NotReadyResponse:
      type: object
      required: [status, message]
      properties:
        status:
          type: string
          const: not_ready
        message:
          type: string
    ApiError:
      type: object
      required: [error, message, requestId]
      properties:
        error:
          type: string
          enum:
            - VALIDATION_ERROR
            - UNAUTHENTICATED
            - FORBIDDEN
            - NOT_FOUND
            - CONFLICT
            - PAYLOAD_TOO_LARGE
            - RATE_LIMITED
            - HTTP_ERROR
            - INTERNAL_ERROR
        message:
          type: string
        requestId:
          type: string
        details:
          description: 仅校验错误可能出现
    Message:
      type: object
      required: [id, userId, role, content, createdAt]
      properties:
        id:
          $ref: "#/components/schemas/Uuid"
        userId:
          $ref: "#/components/schemas/Uuid"
        role:
          type: string
          enum: [user, assistant]
        content:
          type: string
          minLength: 1
          maxLength: 20000
        createdAt:
          type: string
          format: date-time
    UserModel:
      type: object
      required:
        - userId
        - vibeNarrative
        - longTermProfile
        - currentIntent
        - socialHistory
        - feedbackMemory
        - multimodalUnderstanding
        - version
        - updatedAt
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
        vibeNarrative:
          type: string
          maxLength: 12000
        longTermProfile:
          $ref: "#/components/schemas/JsonObject"
        currentIntent:
          $ref: "#/components/schemas/JsonObject"
        socialHistory:
          type: array
          items:
            type: string
        feedbackMemory:
          type: array
          items:
            type: string
        multimodalUnderstanding:
          $ref: "#/components/schemas/JsonObject"
        version:
          type: integer
          minimum: 0
        updatedAt:
          type: string
          format: date-time
    LlmJob:
      type: object
      required:
        - id
        - type
        - status
        - payload
        - result
        - error
        - attempts
        - maxAttempts
        - partitionKey
        - runAt
        - createdAt
        - updatedAt
      properties:
        id:
          $ref: "#/components/schemas/Uuid"
        type:
          type: string
          enum:
            - agent_reply
            - agent_event_reply
            - multimodal_understanding
            - matchmaking
            - match_round_generate
            - match_round_settle
            - room_change_notify
            - feedback_update
            - memory_extract
            - memory_consolidate
        status:
          type: string
          enum: [pending, processing, completed, retry, failed]
        payload:
          $ref: "#/components/schemas/JsonObject"
        result:
          oneOf:
            - $ref: "#/components/schemas/JsonObject"
            - type: "null"
        error:
          type: [string, "null"]
        attempts:
          type: integer
          minimum: 0
        maxAttempts:
          type: integer
          minimum: 1
        partitionKey:
          type: [string, "null"]
        runAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    OfflineGame:
      type: object
      required:
        - id
        - name
        - description
        - minPlayers
        - maxPlayers
        - intentTags
        - traits
        - requirements
        - instructions
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        minPlayers:
          type: integer
          minimum: 3
        maxPlayers:
          type: integer
          maximum: 10
        intentTags:
          type: array
          items:
            type: string
        traits:
          type: array
          items:
            type: string
        requirements:
          type: array
          items:
            type: string
        instructions:
          type: array
          items:
            type: string
    AdventurexTestPoolStatus:
      type: object
      required: [ownerUserId, enabled, desiredUserCount, provisionedUserCount, availableRequestCount, updatedAt]
      properties:
        ownerUserId:
          $ref: "#/components/schemas/Uuid"
        enabled:
          type: boolean
        desiredUserCount:
          type: integer
          minimum: 3
          maximum: 12
        provisionedUserCount:
          type: integer
          minimum: 0
        availableRequestCount:
          type: integer
          minimum: 0
        updatedAt:
          type: string
          format: date-time
    MatchRequest:
      type: object
      required: [requestId, userId, intentSnapshot, status, phase, proactivePushEnabled, activeRoundId, optionsExpiresAt, roomId, inviteId, createdAt, updatedAt]
      properties:
        requestId:
          $ref: "#/components/schemas/Uuid"
        userId:
          $ref: "#/components/schemas/Uuid"
        intentSnapshot:
          $ref: "#/components/schemas/JsonObject"
        status:
          type: string
          enum: [matching, invited, matched, cancelled, expired]
        phase:
          type: string
          enum: [waiting, offered, selected, settling, push_consent, watching]
        proactivePushEnabled:
          type: boolean
        activeRoundId:
          type: [string, "null"]
          format: uuid
        optionsExpiresAt:
          type: [string, "null"]
          format: date-time
        roomId:
          type: [string, "null"]
          format: uuid
        inviteId:
          type: [string, "null"]
          format: uuid
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    MatchInviteParticipant:
      type: object
      required: [userId, requestId, displayName, accepted]
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
        requestId:
          $ref: "#/components/schemas/Uuid"
        displayName:
          type: string
        accepted:
          type: boolean
    EventPlanTime:
      type: object
      required: [startsAt, endsAt, timeZone, note]
      properties:
        startsAt:
          type: [string, "null"]
          format: date-time
        endsAt:
          type: [string, "null"]
          format: date-time
        timeZone:
          type: string
        note:
          type: string
    EventPlanLocation:
      type: object
      required: [name, address, url, note]
      properties:
        name:
          type: [string, "null"]
        address:
          type: [string, "null"]
        url:
          type: [string, "null"]
          format: uri
        note:
          type: string
    EventPlanGame:
      type: object
      required: [game, primary, position]
      properties:
        game:
          $ref: "#/components/schemas/OfflineGame"
        primary:
          type: boolean
        position:
          type: integer
          minimum: 0
    EventPlanConfirmation:
      type: object
      required: [userId, displayName, confirmedAt]
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
        displayName:
          type: string
        confirmedAt:
          type: string
          format: date-time
    RoomEventPlan:
      type: object
      required: [planId, roomId, version, status, time, location, games, confirmations, createdBy, createdAt, publishedAt]
      properties:
        planId:
          $ref: "#/components/schemas/Uuid"
        roomId:
          $ref: "#/components/schemas/Uuid"
        version:
          type: integer
          minimum: 1
        status:
          type: string
          enum: [draft, published, superseded]
        time:
          $ref: "#/components/schemas/EventPlanTime"
        location:
          $ref: "#/components/schemas/EventPlanLocation"
        games:
          type: array
          minItems: 1
          maxItems: 5
          items:
            $ref: "#/components/schemas/EventPlanGame"
        confirmations:
          type: array
          maxItems: 2
          items:
            $ref: "#/components/schemas/EventPlanConfirmation"
        createdBy:
          type: [string, "null"]
          format: uuid
        createdAt:
          type: string
          format: date-time
        publishedAt:
          type: [string, "null"]
          format: date-time
    MatchInvite:
      type: object
      required: [inviteId, kind, roomId, participants, offlineGameId, matchSummary, eventPlan, status, createdAt, resolvedAt]
      properties:
        inviteId:
          $ref: "#/components/schemas/Uuid"
        kind:
          type: string
          enum: [initial_pair, room_join]
        roomId:
          type: [string, "null"]
          format: uuid
        participants:
          type: array
          minItems: 1
          maxItems: 2
          items:
            $ref: "#/components/schemas/MatchInviteParticipant"
        offlineGameId:
          type: string
        matchSummary:
          type: string
        eventPlan:
          oneOf:
            - $ref: "#/components/schemas/RoomEventPlan"
            - type: "null"
        status:
          type: string
          enum: [pending, accepted, declined, cancelled]
        createdAt:
          type: string
          format: date-time
        resolvedAt:
          type: [string, "null"]
          format: date-time
    MatchInviteResolution:
      type: object
      required: [invite, room, requeuedRequestIds]
      properties:
        invite:
          $ref: "#/components/schemas/MatchInvite"
        room:
          oneOf:
            - $ref: "#/components/schemas/MatchRoom"
            - type: "null"
        requeuedRequestIds:
          type: array
          items:
            $ref: "#/components/schemas/Uuid"
    RoomMember:
      type: object
      required: [userId, displayName, confirmed, participationStatus, role]
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
        displayName:
          type: string
        confirmed:
          type: boolean
        participationStatus:
          type: string
          enum: [invited, confirmed, withdrawn]
        role:
          type: string
          enum: [founder, member]
    MatchRoom:
      type: object
      required: [roomId, members, offlineGame, matchSummary, status, sourceDraftId, targetPlayers, recruitmentStatus, version, meetingPoint, matchingStatus, capacity, eventPlans, createdAt, completedAt]
      properties:
        roomId:
          $ref: "#/components/schemas/Uuid"
        members:
          type: array
          minItems: 2
          maxItems: 10
          items:
            $ref: "#/components/schemas/RoomMember"
        offlineGame:
          $ref: "#/components/schemas/OfflineGame"
        matchSummary:
          type: string
        status:
          type: string
          enum: [confirming, confirmed, completed]
        sourceDraftId:
          type: [string, "null"]
          format: uuid
        targetPlayers:
          type: [integer, "null"]
          minimum: 3
          maximum: 10
        recruitmentStatus:
          type: string
          enum: [open, full, closed]
        version:
          type: integer
          minimum: 0
        meetingPoint:
          type: [string, "null"]
        matchingStatus:
          type: string
          enum: [active, stopped, full]
        capacity:
          type: integer
          minimum: 2
          maximum: 10
        eventPlans:
          type: object
          required: [draft, published]
          properties:
            draft:
              oneOf:
                - $ref: "#/components/schemas/RoomEventPlan"
                - type: "null"
            published:
              oneOf:
                - $ref: "#/components/schemas/RoomEventPlan"
                - type: "null"
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: [string, "null"]
          format: date-time
    AdventurexOnboardingState:
      type: object
      required: [userId, stage, imageDeclined, preferredLanguage, boundaryPromptedAt, welcomeSentAt, updatedAt]
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
        stage:
          type: string
          enum: [new, awaiting_image_or_text, exploring, ready, matching]
        imageDeclined:
          type: boolean
        preferredLanguage:
          type: string
          enum: [zh, en]
        boundaryPromptedAt:
          type: [string, "null"]
          format: date-time
        welcomeSentAt:
          type: [string, "null"]
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PublicMatchOptions:
      type: object
      required: [requestId, roundId, expiresAt, options]
      properties:
        requestId:
          $ref: "#/components/schemas/Uuid"
        roundId:
          $ref: "#/components/schemas/Uuid"
        expiresAt:
          type: string
          format: date-time
        options:
          type: array
          minItems: 1
          maxItems: 3
          items:
            type: object
            required: [optionNumber, activity, previewText]
            properties:
              optionNumber:
                type: integer
                minimum: 1
                maximum: 3
              activity:
                type: object
                required: [id, name]
                properties:
                  id:
                    type: string
                  name:
                    type: string
              previewText:
                type: string
    MatchChoicesInput:
      type: object
      additionalProperties: false
      required: [preferredOptionNumber, acceptedOptionNumbers]
      properties:
        preferredOptionNumber:
          type: [integer, "null"]
          minimum: 1
          maximum: 3
        acceptedOptionNumbers:
          type: array
          minItems: 1
          maxItems: 3
          items:
            type: integer
            minimum: 1
            maximum: 3
        requiredHookIds:
          type: array
          maxItems: 3
          items:
            $ref: "#/components/schemas/Uuid"
        rawText:
          type: string
          maxLength: 2000
    AgentMessageInput:
      type: object
      additionalProperties: false
      required: [userId, displayName, content, idempotencyKey]
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
        displayName:
          type: string
          minLength: 1
          maxLength: 80
        content:
          type: string
          minLength: 1
          maxLength: 20000
        idempotencyKey:
          type: string
          minLength: 8
          maxLength: 128
    AgentMessageResponse:
      type: object
      required: [userMessage, job]
      properties:
        userMessage:
          $ref: "#/components/schemas/Message"
        job:
          $ref: "#/components/schemas/LlmJob"
    SignUploadInput:
      type: object
      additionalProperties: false
      required: [userId, fileName, mimeType, sizeBytes]
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
        fileName:
          type: string
          minLength: 1
          maxLength: 255
        mimeType:
          $ref: "#/components/schemas/MultimodalMimeType"
        sizeBytes:
          type: integer
          minimum: 1
          maximum: 20971520
    SignUploadResponse:
      type: object
      required: [path, token]
      properties:
        path:
          type: string
        token:
          type: string
    Base64UploadInput:
      type: object
      additionalProperties: false
      required: [userId, fileName, mimeType, dataUrl]
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
        fileName:
          type: string
          minLength: 1
          maxLength: 255
        mimeType:
          type: string
          enum: [image/jpeg, image/png, image/webp]
        dataUrl:
          type: string
          maxLength: 15728640
    UploadResponse:
      type: object
      required: [storagePath, mimeType, sizeBytes]
      properties:
        storagePath:
          type: string
        mimeType:
          type: string
        sizeBytes:
          type: integer
    MultimodalMimeType:
      type: string
      enum:
        - image/jpeg
        - image/png
        - image/webp
        - audio/mpeg
        - audio/mp4
        - audio/webm
    MultimodalInput:
      type: object
      additionalProperties: false
      required: [userId, kind, storagePath, mimeType, sizeBytes]
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
        kind:
          type: string
          enum: [image, audio]
        storagePath:
          type: string
          minLength: 1
          maxLength: 2000
        mimeType:
          $ref: "#/components/schemas/MultimodalMimeType"
        sizeBytes:
          type: integer
          minimum: 1
          maximum: 20971520
        hint:
          type: string
          maxLength: 2000
    MultimodalResponse:
      type: object
      required: [inputId, job]
      properties:
        inputId:
          $ref: "#/components/schemas/Uuid"
        job:
          $ref: "#/components/schemas/LlmJob"
    CreateMatchRequestInput:
      type: object
      additionalProperties: false
      required: [userId]
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
        intent:
          $ref: "#/components/schemas/JsonObject"
        idempotencyKey:
          type: string
          minLength: 8
          maxLength: 128
          description: 当前版本保留字段
    CreateMatchRequestResponse:
      type: object
      required: [matchRequest, invite, job]
      properties:
        matchRequest:
          oneOf:
            - $ref: "#/components/schemas/MatchRequest"
            - type: "null"
        invite:
          oneOf:
            - $ref: "#/components/schemas/MatchInvite"
            - type: "null"
        job:
          $ref: "#/components/schemas/LlmJob"
    UserIdBody:
      type: object
      additionalProperties: false
      required: [userId]
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
    RoomLeaveBody:
      type: object
      additionalProperties: false
      required: [userId]
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
        reason:
          type: string
          minLength: 1
          maxLength: 500
          description: 正式成局后必填的简单理由；确认前可省略。仅内部保存，不发送给其他成员
    EventPlanPatch:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        time:
          type: object
          additionalProperties: false
          properties:
            startsAt:
              type: [string, "null"]
              format: date-time
            endsAt:
              type: [string, "null"]
              format: date-time
            timeZone:
              type: string
            note:
              type: string
        location:
          type: object
          additionalProperties: false
          properties:
            name:
              type: [string, "null"]
            address:
              type: [string, "null"]
            url:
              type: [string, "null"]
              format: uri
            note:
              type: string
        gameIds:
          type: array
          minItems: 1
          maxItems: 5
          uniqueItems: true
          items:
            type: string
    UpdateEventPlanInput:
      type: object
      additionalProperties: false
      required: [userId, expectedVersion, patch]
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
        expectedVersion:
          type: integer
          minimum: 1
        patch:
          $ref: "#/components/schemas/EventPlanPatch"
    ConfirmEventPlanInput:
      type: object
      additionalProperties: false
      required: [userId, version]
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
        version:
          type: integer
          minimum: 1
    EventPlanMutationResult:
      type: object
      required: [room, eventPlan, published]
      properties:
        room:
          $ref: "#/components/schemas/MatchRoom"
        eventPlan:
          $ref: "#/components/schemas/RoomEventPlan"
        published:
          type: boolean
    PostEventFeedbackInput:
      type: object
      additionalProperties: false
      required: [userId, peopleFeedback, gameFeedback, connectionUserIds, nextIntent]
      properties:
        userId:
          $ref: "#/components/schemas/Uuid"
        peopleFeedback:
          type: string
          minLength: 1
          maxLength: 5000
        gameFeedback:
          type: string
          minLength: 1
          maxLength: 5000
        connectionUserIds:
          type: array
          maxItems: 9
          items:
            $ref: "#/components/schemas/Uuid"
        nextIntent:
          type: string
          minLength: 1
          maxLength: 2000
    FeedbackResponse:
      type: object
      required: [feedbackId, job]
      properties:
        feedbackId:
          $ref: "#/components/schemas/Uuid"
        job:
          $ref: "#/components/schemas/LlmJob"