openapi: 3.0.3
info:
  title: Muse API
  description: |
    Muse AI 驱动长篇创作平台统一 API 契约。
    所有接口通过 X-API-Version Header 进行版本控制。
  version: 1.0.0
  license:
    name: Proprietary
  contact:
    name: Muse Team

servers:
  - url: /
    description: 同源 API 网关

paths: {}

components:
  securitySchemes:
    adminBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        管理后台认证 scheme，仅用于 /admin-api/** 接口。
        admin-api token 与 app-api token 不互通，接口必须按入口显式选择认证域。
    appBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        用户端认证 scheme，仅用于 /app-api/** 接口。
        app-api token 与 admin-api token 不互通，接口必须按入口显式选择认证域。
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        兼容旧生成器和旧引用的 bearer 认证别名。
        新增或维护接口应优先使用 adminBearerAuth 或 appBearerAuth，避免把两类 token 误判为同一认证域。

  parameters:
    XApiVersion:
      name: X-API-Version
      in: header
      required: true
      schema:
        type: string
        enum: ["1"]
        example: "1"
      description: |
        API 版本号，当前版本为 1。
        未传时网关可兼容最新稳定版本，但前端 SDK 和 API 客户端必须显式传递该 header。

    pageNo:
      name: pageNo
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
      description: 页码，从 1 开始

    pageSize:
      name: pageSize
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      description: 每页条数，上限 100

  schemas:
    CommonResult:
      type: object
      required: [code, msg]
      properties:
        code:
          type: integer
          description: 业务状态码，0 表示成功
          example: 0
        data:
          description: 响应数据，类型视具体接口而定
        msg:
          type: string
          description: 提示信息
          example: "success"

    PaginatedResult:
      type: object
      required: [total, pageNo, pageSize, list]
      properties:
        total:
          type: integer
          description: 总记录数
          example: 150
        pageNo:
          type: integer
          description: 当前页码
          example: 1
        pageSize:
          type: integer
          description: 每页条数
          example: 20
        list:
          type: array
          items: {}
          description: 当前页数据列表

    ErrorResponse:
      type: object
      required: [code, msg]
      properties:
        code:
          type: string
          description: |
            错误码格式: {system}-{module}-{category}-{sequence}
            示例: MUSE-CONTENT-001-0001
          example: "MUSE-CONTENT-001-0001"
        msg:
          type: string
          description: 人类可读的错误描述
        detail:
          type: string
          description: 详细错误信息（仅开发环境返回）

    # 通用时间戳字段
    TimestampMixin:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          description: 创建时间
        updatedAt:
          type: string
          format: date-time
          description: 最后更新时间

  responses:
    BadRequest:
      description: 请求参数有误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: 未认证或 token 过期
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: 无权限
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: 资源不存在
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: 资源冲突
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: 服务器内部错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

tags:
  - name: Content
    description: 作品、章节、Block、导出
  - name: AI
    description: AI 生成、候选管理、智能体、质量门控
  - name: Knowledge
    description: 知识实体、关系、草稿、确认
  - name: Market
    description: 资产发布、安装绑定、审核
  - name: Account
    description: 权益、配额、用量、安全事件
  - name: Meta
    description: MetaSchema 字段定义、版本、scope