openapi: 3.0.0
info:
  title: MarkBase API
  description: Momentry Display Engine - Markdown渲染與檔案樹管理系統
  version: 0.1.0
  contact:
    name: MarkBase Team

servers:
  - url: http://localhost:11438
    description: 本地開發伺服器
  - url: https://gitea.momentry.ddns.net
    description: 生產伺服器

tags:
  - name: Display
    description: 內容顯示與渲染
  - name: File Tree
    description: 檔案樹管理
  - name: Files
    description: 檔案操作
  - name: System
    description: 系統狀態與控制
  - name: Audio
    description: macOS音訊控制

paths:
  # Display相關路由
  /:
    get:
      tags: [Display]
      summary: 主頁顯示
      description: 返回當前顯示的HTML內容
      responses:
        '200':
          description: HTML內容
          content:
            text/html:
              schema:
                type: string

  /display:
    post:
      tags: [Display]
      summary: 更新顯示內容
      description: 根據內容類型更新顯示內容
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum: [md, markdown, json, url, video, image, html]
                  description: 內容類型
                data:
                  type: string
                  description: 內容資料
                file:
                  type: string
                  description:檔案路徑
                url:
                  type: string
                  description: URL地址
                html:
                  type: string
                  description: HTML內容
                step_id:
                  type: string
                step_num:
                  type: integer
                step_total:
                  type: integer
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean

  /version:
    get:
      tags: [System]
      summary: 取得版本號
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  v:
                    type: integer

  /status:
    get:
      tags: [System]
      summary: 取得狀態
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  paused:
                    type: boolean
                  step:
                    type: integer
                  total:
                    type: integer
                  id:
                    type: string
                  label:
                    type: string
                  voice:
                    type: string

  /body:
    get:
      tags: [Display]
      summary: 取得內容body
      responses:
        '200':
          content:
            text/html:
              schema:
                type: string

  /labels:
    get:
      tags: [System]
      summary: 取得標籤列表
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
    post:
      tags: [System]
      summary:更新標籤列表
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean

  # Audio相關路由
  /devices:
    get:
      tags: [Audio]
      summary: 取得音訊裝置
      description: 列出所有音訊輸入/輸出裝置（macOS）
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  output:
                    type: array
                    items:
                      type: string
                  input:
                    type: array
                    items:
                      type: string
                  current_out:
                    type: string
                  current_in:
                    type: string

  /volume:
    get:
      tags: [Audio]
      summary: 取得音量
      description: 取得當前音量級別（macOS）
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  level:
                    type: integer

  # Command相關路由
  /command:
    get:
      tags: [System]
      summary: 取得指令隊列
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    val:
                      type: string
    post:
      tags: [System]
      summary: 提交指令
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                cmd:
                  type: string
                val:
                  type: string
                out:
                  type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean

  # File Tree相關路由
  /api/v2/tree/{user_id}:
    get:
      tags: [File Tree]
      summary: 取得檔案樹
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
        - name: mode
          in: query
          schema:
            type: string
            enum: [tree, list, grid_sm, grid_lg]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  mode:
                    type: string
                  nodes:
                    type: array
                    items:
                      $ref: '#/components/schemas/FileNode'
    delete:
      tags: [File Tree]
      summary: 刪除所有節點
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  deleted:
                    type: integer

  /api/v2/tree/{user_id}/node:
    post:
      tags: [File Tree]
      summary: 建立節點
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNodeRequest'
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  node_id:
                    type: string

  /api/v2/tree/{user_id}/node/{node_id}:
    put:
      tags: [File Tree]
      summary: 更新節點
      parameters:
        - name: user_id
          in: path
          required: true
        - name: node_id
          in: path
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNodeRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
    delete:
      tags: [File Tree]
      summary: 刪除節點
      parameters:
        - name: user_id
          in: path
          required: true
        - name: node_id
          in: path
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean

  /api/v2/tree/{user_id}/node/{node_id}/move:
    put:
      tags: [File Tree]
      summary: 移動節點
      parameters:
        - name: user_id
          in: path
          required: true
        - name: node_id
          in: path
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                parent_id:
                  type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean

  /api/v2/tree/{user_id}/node/{node_id}/alias:
    patch:
      tags: [File Tree]
      summary: 更新別名
      parameters:
        - name: user_id
          in: path
          required: true
        - name: node_id
          in: path
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                lang:
                  type: string
                value:
                  type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean

  /api/v2/tree/{user_id}/restore:
    post:
      tags: [File Tree]
      summary: 從外部API恢復檔案樹
      parameters:
        - name: user_id
          in: path
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  deleted:
                    type: integer
                  imported:
                    type: integer

  /api/v2/modes:
    get:
      tags: [File Tree]
      summary: 取得顯示模式列表
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  modes:
                    type: array
                    items:
                      $ref: '#/components/schemas/DisplayMode'

  # Files相關路由
  /api/v2/dupes/{user_id}:
    get:
      tags: [Files]
      summary: 取得重複檔案
      parameters:
        - name: user_id
          in: path
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object

  /api/v2/unregister/{file_uuid}:
    post:
      tags: [Files]
      summary: 取消註冊檔案
      parameters:
        - name: file_uuid
          in: path
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object

  /api/v2/upload/{user_id}:
    post:
      tags: [Files]
      summary: 上傳檔案
      parameters:
        - name: user_id
          in: path
          required: true
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  filename:
                    type: string
                  file_uuid:
                    type: string
                  sha256:
                    type: string
                  size:
                    type: integer

  /api/v2/render/{file_uuid}:
    get:
      tags: [Files]
      summary: 渲染檔案
      parameters:
        - name: file_uuid
          in: path
          required: true
      responses:
        '200':
          content:
            text/html:
              schema:
                type: string

  /api/v2/render/{file_uuid}/body:
    get:
      tags: [Files]
      summary: 取得檔案渲染內容
      parameters:
        - name: file_uuid
          in: path
          required: true
      responses:
        '200':
          content:
            text/html:
              schema:
                type: string

  /api/v2/files/{file_uuid}/info:
    get:
      tags: [Files]
      summary: 取得檔案資訊
      parameters:
        - name: file_uuid
          in: path
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileInfo'

  /api/v2/files/{file_uuid}/probe:
    get:
      tags: [Files]
      summary: 取得檔案探測資訊
      parameters:
        - name: file_uuid
          in: path
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object

  /api/v2/files/{file_uuid}/stream:
    get:
      tags: [Files]
      summary: 串流檔案
      parameters:
        - name: file_uuid
          in: path
          required: true
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

  /api/v2/files/{file_uuid}/locations:
    post:
      tags: [Files]
      summary: 新增檔案位置
      parameters:
        - name: file_uuid
          in: path
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                location:
                  type: string
                label:
                  type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean

components:
  schemas:
    FileNode:
      type: object
      properties:
        node_id:
          type: string
        label:
          type: string
        aliases:
          type: object
        file_uuid:
          type: string
        sha256:
          type: string
        parent_id:
          type: string
        node_type:
          type: string
          enum: [folder, file]
        icon:
          type: string
        color:
          type: string
        bg_color:
          type: string
        file_size:
          type: integer
        registered_at:
          type: string
        children:
          type: array
          items:
            type: string

    CreateNodeRequest:
      type: object
      required: [label]
      properties:
        label:
          type: string
        node_type:
          type: string
          enum: [folder, file]
        parent_id:
          type: string
        file_uuid:
          type: string
        sha256:
          type: string
        file_size:
          type: integer
        file_type:
          type: string

    UpdateNodeRequest:
      type: object
      properties:
        label:
          type: string
        icon:
          type: string
        color:
          type: string
        bg_color:
          type: string

    DisplayMode:
      type: object
      properties:
        name:
          type: string
        sort_options:
          type: array
          items:
            $ref: '#/components/schemas/SortOption'
        filter_options:
          type: array
          items:
            $ref: '#/components/schemas/FilterOption'

    SortOption:
      type: object
      properties:
        key:
          type: string
        label:
          type: string

    FilterOption:
      type: object
      properties:
        key:
          type: string
        label:
          type: string

    FileInfo:
      type: object
      properties:
        file_uuid:
          type: string
        original_name:
          type: string
        file_size:
          type: integer
        file_type:
          type: string
        registered_at:
          type: string
        status:
          type: string