docs/openapi.yaml

openapi: 3.0.0
info:
  title: InterConnect-Server API
  version: 1.0.0
  description: |
    InterConnect-Server 是一个 Minecraft WebSocket API 服务器，提供 API Key 管理、事件广播、服务器命令等功能。
    
    权限说明：
    - **Admin Key**: `mc_admin_` 前缀，拥有完整管理权限。
    - **Regular Key**: `mc_key_` 前缀，可查看/管理关联的 Server Key，发送服务器命令。
    - **Server Key**: `mc_server_` 前缀，仅用于插件/Mod 配置，用于认证和事件上报。

servers:
  - url: http://localhost:8000
    description: 本地服务器

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 使用 API Key 进行认证 (Bearer Token)

  schemas:
    ApiKey:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        keyPrefix:
          type: string
          enum: [mc_admin_, mc_key_, mc_server_]
        keyType:
          type: string
          enum: [admin, regular, server]
        serverId:
          type: string
          nullable: true
        regularKeyId:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        lastUsed:
          type: string
          format: date-time
          nullable: true
        isActive:
          type: boolean
    
    ApiKeyWithSecret:
      allOf:
        - $ref: '#/components/schemas/ApiKey'
        - type: object
          properties:
            key:
              type: string
              description: 原始 API Key，仅在创建时返回一次

    CreateKeyRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
        description:
          type: string
        key_type:
          type: string
          enum: [regular, admin]
          default: regular
        server_id:
          type: string

    CreateServerKeyRequest:
      type: object
      required: [name, regular_key_id]
      properties:
        name:
          type: string
        description:
          type: string
        server_id:
          type: string
        regular_key_id:
          type: string

    Event:
      type: object
      required: [event_type, server_name, timestamp, data]
      properties:
        event_type:
          type: string
          description: 事件类型 (e.g., player_join, player_leave, message, ai_chat)
        server_name:
          type: string
        timestamp:
          type: string
          format: date-time
        data:
          type: object
          description: 事件具体数据

    CommandRequest:
      type: object
      required: [command]
      properties:
        command:
          type: string
        server_id:
          type: string
          description: 仅 Admin Key 需要/可以指定

    AiConfig:
      type: object
      properties:
        apiUrl:
          type: string
        modelId:
          type: string
        apiKey:
          type: string
          description: 部分隐藏的 API Key
        enabled:
          type: boolean
        systemPrompt:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    AiConfigUpdateRequest:
      type: object
      properties:
        api_url:
          type: string
        model_id:
          type: string
        api_key:
          type: string
        enabled:
          type: boolean
        system_prompt:
          type: string

    AiChatRequest:
      type: object
      required: [message]
      properties:
        message:
          type: string
        player_name:
          type: string
        server_id:
          type: string

paths:
  /health:
    get:
      summary: 健康检查
      description: 获取服务器状态和统计信息
      security: []
      responses:
        '200':
          description: 服务器正常
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  timestamp:
                    type: string
                  active_ws:
                    type: integer
                  keys_total:
                    type: integer
                  admin_active:
                    type: integer
                  server_active:
                    type: integer
                  regular_active:
                    type: integer

  /manage/keys:
    get:
      summary: 获取所有 API Key
      description: 获取所有 API Key 列表 (仅 Admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKey'
        '403':
          description: 权限不足
    
    post:
      summary: 创建 API Key
      description: 创建新的 Admin 或 Regular Key (创建 Regular Key 会自动附带一个 Server Key)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKeyRequest'
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ApiKeyWithSecret'
                  - type: object
                    properties:
                      regularKey:
                        $ref: '#/components/schemas/ApiKeyWithSecret'
                      serverKey:
                        $ref: '#/components/schemas/ApiKeyWithSecret'

  /manage/keys/{key_id}:
    get:
      summary: 获取 API Key 详情
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: key_id
          schema:
            type: string
          required: true
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '404':
          description: 未找到
    
    delete:
      summary: 删除 API Key
      description: 仅 Admin 可操作，不能删除自己
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: key_id
          schema:
            type: string
          required: true
      responses:
        '204':
          description: 删除成功
        '400':
          description: 无法删除（如试图删除自己）

  /manage/keys/{key_id}/activate:
    patch:
      summary: 激活 API Key
      description: Admin 可激活任意 Key，Regular 仅可激活关联的 Server Key
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: key_id
          schema:
            type: string
          required: true
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

  /manage/keys/{key_id}/deactivate:
    patch:
      summary: 停用 API Key
      description: Admin 可停用任意 Key，Regular 仅可停用关联的 Server Key
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: key_id
          schema:
            type: string
          required: true
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

  /manage/keys/server-keys:
    get:
      summary: 获取 Server Key 列表
      description: Admin 获取所有 Server Key，Regular 获取关联的 Server Key
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKey'
    
    post:
      summary: 创建 Server Key
      description: 为指定的 Regular Key 创建新的 Server Key (仅 Admin)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServerKeyRequest'
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyWithSecret'
        '400':
          description: 参数错误
        '404':
          description: Regular Key 不存在

  /api/events:
    post:
      summary: 发送事件
      description: 发送 Minecraft 事件并广播给所有 WebSocket 连接
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: 成功广播

  /api/server/info:
    get:
      summary: 获取服务器信息
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: server_id
          schema:
            type: string
          description: 仅 Admin 需要
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  server_id:
                    type: string
                  status:
                    type: string
                  online_players:
                    type: integer

  /api/server/command:
    post:
      summary: 发送服务器命令
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommandRequest'
      responses:
        '200':
          description: 命令发送成功
        '403':
          description: 禁止的命令

  /api/ai/config:
    get:
      summary: 获取 AI 配置 (Admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiConfig'
    
    post:
      summary: 创建 AI 配置 (Admin)
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiConfigUpdateRequest'
      responses:
        '201':
          description: 创建成功
    
    patch:
      summary: 更新 AI 配置 (Admin)
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiConfigUpdateRequest'
      responses:
        '200':
          description: 更新成功
    
    delete:
      summary: 删除 AI 配置 (Admin)
      security:
        - bearerAuth: []
      responses:
        '204':
          description: 删除成功

  /api/ai/config/test:
    post:
      summary: 测试 AI 连接 (Admin)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 连接成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string

  /api/ai/chat:
    post:
      summary: AI 聊天
      description: 发送消息给 AI 并获取回复
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiChatRequest'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  reply:
                    type: string
                  model:
                    type: string