openapi: 3.1.0
info:
  title: ADCN API 草案
  version: 0.1.0
  summary: 第二階段已實作端點標為已完成，其餘標為尚未開發。
  description: |
    這是文件草案，不是已全部上線的正式 API。
    已完成的路徑以第二階段 MVP（https://adcn-phase2.pages.dev）為準。
    錯誤回應固定為 {"ok":false,"error":"繁體中文說明","code":"…"}。
  license:
    name: UNLICENSED
    identifier: UNLICENSED
servers:
  - url: https://adcn-phase2.pages.dev
    description: 第二階段 MVP（已部署的派單與記時 API）
tags:
  - name: 客戶
    description: 已完成。以客戶密鑰呼叫。
  - name: 裝置
    description: 已完成。以工作密鑰或裝置憑證呼叫。
  - name: 智能體與金流
    description: 尚未開發。
paths:
  /api/v1/jobs:
    post:
      tags: [客戶]
      summary: 送出工作
      description: 狀態：已完成。
      x-adcn-status: 已完成
      security: [{ CustomerKey: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "../schemas/adcn-job.schema.json"
            examples:
              sample:
                value:
                  texts: ["The cat sits on the mat."]
                  model: Xenova/all-MiniLM-L6-v2
      responses:
        "201":
          description: 已建立
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobId: { type: string }
                  status: { type: string }
                  total: { type: integer }
                  model: { type: string }
        "400": { description: 格式錯誤 }
        "401": { description: 密鑰錯誤 }
        "413": { description: 太大或太多 }
        "429": { description: 太頻繁 }
  /api/v1/jobs/{jobId}:
    get:
      tags: [客戶]
      summary: 查詢工作狀態
      description: 狀態：已完成。只能看自己的工作，別人的回 404。
      x-adcn-status: 已完成
      security: [{ CustomerKey: [] }]
      parameters:
        - $ref: "#/components/parameters/jobId"
      responses:
        "200":
          description: 狀態
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, enum: [queued, running, done] }
                  statusText: { type: string }
                  total: { type: integer }
                  done: { type: integer }
                  progress: { type: number }
                  createdAt: { type: string }
                  finishedAt: { type: string, nullable: true }
        "401": { description: 密鑰錯誤 }
        "404": { description: 找不到 }
  /api/v1/jobs/{jobId}/result:
    get:
      tags: [客戶]
      summary: 取回結果
      description: 狀態：已完成。未完成時回 409。JSON 每頁最多 50 筆，b64 最多 500 筆。
      x-adcn-status: 已完成
      security: [{ CustomerKey: [] }]
      parameters:
        - $ref: "#/components/parameters/jobId"
        - name: format
          in: query
          schema: { type: string, enum: [json, b64], default: json }
        - name: offset
          in: query
          schema: { type: integer, minimum: 0, default: 0 }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, default: 50 }
      responses:
        "200":
          description: 結果頁
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        index: { type: integer }
                        verified: { type: boolean }
                        vector: { description: "JSON 為數字陣列，b64 為 Float32 的 base64。" }
                  nextOffset: { type: integer, nullable: true }
        "401": { description: 密鑰錯誤 }
        "404": { description: 找不到 }
        "409": { description: 尚未完成 }
  /api/worker/register:
    post:
      tags: [裝置]
      summary: 登記裝置
      description: 狀態：已完成。憑證只回這一次，伺服器只存雜湊。
      x-adcn-status: 已完成
      security: [{ WorkerKey: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [account, deviceName, b]
              properties:
                account: { type: string }
                deviceName: { type: string }
                b: { type: number, description: 基準速度，每秒推論次數 }
                backend: { type: string }
                models: { type: array, items: { type: string } }
      responses:
        "200":
          description: 登記成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  deviceId: { type: string }
                  deviceToken: { type: string }
  /api/worker/lease:
    post:
      tags: [裝置]
      summary: 領取分片
      description: 狀態：已完成。
      x-adcn-status: 已完成
      security: [{ DeviceToken: [] }]
      responses:
        "200":
          description: 分片
          content:
            application/json:
              schema:
                type: object
                properties:
                  shard:
                    type: object
                    properties:
                      id: { type: string }
                      seq: { type: integer }
                      model: { type: string }
                      texts: { type: array, items: { type: string } }
                      leaseUntil: { type: string }
                      leaseMs: { type: integer }
  /api/worker/submit:
    post:
      tags: [裝置]
      summary: 交回向量
      description: 狀態：已完成。必須帶與分片相同的 model。
      x-adcn-status: 已完成
      security: [{ DeviceToken: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shardId, vectors]
              properties:
                shardId: { type: string }
                model: { type: string }
                vectors:
                  type: array
                  items: { type: string, description: 384 維 Float32 的 base64 }
      responses:
        "200":
          description: 判定
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted: { type: boolean }
                  verdict: { type: string }
        "400": { description: 格式或模型不符 }
        "409": { description: 已逾時或已改派 }
  /api/worker/bench:
    post:
      tags: [裝置]
      summary: 更新基準速度 B
      description: 狀態：已完成。
      x-adcn-status: 已完成
      security: [{ DeviceToken: [] }]
      responses:
        "200": { description: 已更新 }
  /api/worker/me:
    get:
      tags: [裝置]
      summary: 裝置摘要
      description: 狀態：已完成。含今日與本月有效分鐘。settlement 固定為「結算未開放」。
      x-adcn-status: 已完成
      security: [{ DeviceToken: [] }]
      responses:
        "200": { description: 摘要 }
  /api/account-minutes:
    get:
      tags: [裝置]
      summary: 帳號今日有效分鐘（聯集）
      description: 狀態：已完成。
      x-adcn-status: 已完成
      security: [{ WorkerKey: [] }]
      parameters:
        - name: account
          in: query
          required: true
          schema: { type: string }
      responses:
        "200": { description: 分鐘數 }
  /api/health:
    get:
      tags: [客戶]
      summary: 健康檢查
      description: 狀態：已完成。
      x-adcn-status: 已完成
      responses:
        "200": { description: 正常 }
  /api/v1/agents/keys:
    post:
      tags: [智能體與金流]
      summary: 智能體自助建立金鑰
      description: 狀態：尚未開發。
      x-adcn-status: 尚未開發
      responses:
        "501": { description: 尚未開發 }
  /api/v1/agents/budget:
    put:
      tags: [智能體與金流]
      summary: 設定智能體預算上限
      description: 狀態：尚未開發。
      x-adcn-status: 尚未開發
      responses:
        "501": { description: 尚未開發 }
  /api/v1/payments/intents:
    post:
      tags: [智能體與金流]
      summary: 建立付款
      description: 狀態：尚未開發。本草案不定義卡號欄位。
      x-adcn-status: 尚未開發
      responses:
        "501": { description: 尚未開發 }
  /api/v1/earnings:
    get:
      tags: [智能體與金流]
      summary: 查詢已結算金額
      description: 狀態：尚未開發。
      x-adcn-status: 尚未開發
      responses:
        "501": { description: 尚未開發 }
components:
  securitySchemes:
    CustomerKey:
      type: http
      scheme: bearer
      description: 客戶密鑰。狀態：已完成。
    WorkerKey:
      type: apiKey
      in: header
      name: X-ADCN-Worker-Key
      description: 手機工作密鑰。狀態：已完成。
    DeviceToken:
      type: apiKey
      in: header
      name: X-ADCN-Device-Token
      description: 裝置憑證。狀態：已完成。
  parameters:
    jobId:
      name: jobId
      in: path
      required: true
      schema: { type: string }
