oh-my-muse/docs/api-contracts/content/openapi.yaml

openapi: 3.0.3
info:
  title: Muse Content API
  version: 1.0.0
  license:
    name: Proprietary

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

paths:
  # ========== 作品(Work) ==========
  /app-api/muse/works:
    get:
      tags: [Content]
      summary: 获取作品列表
      operationId: listWorks
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - $ref: '../openapi-base.yaml#/components/parameters/pageNo'
        - $ref: '../openapi-base.yaml#/components/parameters/pageSize'
        - name: status
          in: query
          schema:
            type: string
            enum: [draft, active, archived]
          description: 作品状态过滤
      responses:
        '200':
          description: 作品分页列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        allOf:
                          - $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
                          - type: object
                            properties:
                              list:
                                type: array
                                items:
                                  $ref: '#/components/schemas/WorkSummary'
        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
    post:
      tags: [Content]
      summary: 创建新作品
      operationId: createWork
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 200
                description:
                  type: string
                  maxLength: 2000
                genre:
                  type: string
                coverImageUrl:
                  type: string
                  format: uri
      responses:
        '201':
          description: 作品创建成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Work'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}:
    get:
      tags: [Content]
      summary: 获取作品详情
      operationId: getWork
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 作品详情
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Work'
        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
    put:
      tags: [Content]
      summary: 更新作品
      operationId: updateWork
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  maxLength: 200
                description:
                  type: string
                  maxLength: 2000
                genre:
                  type: string
                coverImageUrl:
                  type: string
                  format: uri
                status:
                  type: string
                  enum: [draft, active, archived]
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
    delete:
      tags: [Content]
      summary: 删除作品
      operationId: deleteWork
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 删除成功
        '404':
          $ref: '../openapi-base.yaml#/components/responses/NotFound'

  # ========== 章节(Chapter) ==========
  /app-api/muse/works/{workId}/chapters:
    get:
      tags: [Content]
      summary: 获取作品章节列表
      operationId: listChapters
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 章节列表（按 sortOrder 排序）
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Chapter'
        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
    post:
      tags: [Content]
      summary: 创建章节
      operationId: createChapter
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 500
                sortOrder:
                  type: integer
                  description: 插入位置，默认追加到末尾
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Chapter'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/chapters/{chapterId}:
    get:
      tags: [Content]
      summary: 获取章节详情
      description: 必须先校验调用方拥有 workId 权限，并校验 chapterId 属于该 workId。
      operationId: getChapter
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: chapterId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 章节详情（含 Block 列表）
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ChapterDetail'
        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
    put:
      tags: [Content]
      summary: 更新章节
      description: 必须校验 work owner、chapterId 从属关系、commandId 幂等和 expectedRevision 乐观锁。
      operationId: updateChapter
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: chapterId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateChapterRequest'
      responses:
        '200':
          description: 更新成功
        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
    delete:
      tags: [Content]
      summary: 删除章节
      description: 必须校验 work owner、chapterId 从属关系、commandId 幂等和 expectedRevision 乐观锁。
      operationId: deleteChapter
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: chapterId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteChapterRequest'
      responses:
        '200':
          description: 删除成功

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/chapters/{chapterId}/reorder:
    put:
      tags: [Content]
      summary: 调整章节排序
      description: 必须校验 work owner、章节从属关系、commandId 幂等、expectedRevision 和重排源快照。
      operationId: reorderChapters
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: chapterId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReorderChapterRequest'
      responses:
        '200':
          description: 排序更新成功

  # ========== Block ==========
        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/chapters/{chapterId}/blocks:
    get:
      tags: [Content]
      summary: 获取章节 Block 列表
      description: 必须先校验调用方拥有 workId 权限，并校验 chapterId 属于该 workId。
      operationId: listBlocks
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: chapterId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Block 列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Block'
        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
    post:
      tags: [Content]
      summary: 创建 Block
      description: 必须校验 work owner、chapterId 从属关系、commandId 幂等和 expectedChapterRevision。
      operationId: createBlock
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: chapterId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBlockRequest'
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Block'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/blocks/{blockId}:
    get:
      tags: [Content]
      summary: 获取 Block 详情
      description: 必须先校验调用方拥有 workId 权限，并校验 blockId 属于该 workId。
      operationId: getBlock
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: blockId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Block 详情
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Block'
        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
    put:
      tags: [Content]
      summary: 保存 Block 正文
      description: 必须校验 work owner、blockId 从属关系、commandId 幂等、expectedRevision 乐观锁和 sourceSnapshot。
      operationId: saveBlock
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: blockId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveBlockRequest'
      responses:
        '200':
          description: 保存成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          revision:
                            type: integer
                            description: 保存后的新 Block revision
        '409':
          description: 版本冲突，需客户端处理
          content:
            application/json:
              schema:
                $ref: '../openapi-base.yaml#/components/schemas/ErrorResponse'
    delete:
      tags: [Content]
      summary: 删除 Block
      description: 必须校验 work owner、blockId 从属关系、commandId 幂等、expectedRevision 和 sourceSnapshot。
      operationId: deleteBlock
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: blockId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteBlockRequest'
      responses:
        '200':
          description: 删除成功

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/blocks/{blockId}/revisions:
    get:
      tags: [Content]
      summary: 查询 Block 正文版本历史
      description: |
        返回指定 Block 已进入 Canonical 的正文 revision 快照，最新 revision 在前。
        仅包含 Content owner 内部写入的正文快照；不提供恢复写入能力，避免绕过当前 Block 的乐观锁与来源归因。
      operationId: listBlockRevisions
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: blockId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Block 正文版本历史
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/BlockRevision'
        '404':
          $ref: '../openapi-base.yaml#/components/responses/NotFound'
  /app-api/muse/works/{workId}/blocks/{blockId}/split:
    post:
      tags: [Content]
      summary: 分割 Block
      description: 必须校验 work owner、blockId 从属关系、commandId 幂等、expectedRevision 和 sourceSnapshot。
      operationId: splitBlock
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: blockId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SplitBlockRequest'
      responses:
        '200':
          description: 分割成功，返回两个新 Block

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/blocks/{blockId}/merge:
    post:
      tags: [Content]
      summary: 合并 Block
      description: 必须校验 work owner、blockId 从属关系、目标相邻 Block、commandId 幂等、expectedRevision 和 sourceSnapshot。
      operationId: mergeBlocks
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: blockId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 与下一个 Block 合并
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MergeBlockRequest'
      responses:
        '200':
          description: 合并成功

  # ========== 导出（旧版保留） ==========
        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/export:
    post:
      tags: [Content]
      summary: 导出作品
      operationId: exportWork
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [format]
              properties:
                format:
                  type: string
                  enum: [txt, epub, docx]
                includeChapters:
                  type: array
                  items:
                    type: integer
                    format: int64
                  description: 指定导出章节，空数组表示导出全部
      responses:
        '200':
          description: 导出任务已创建，返回任务 ID 供轮询
        '202':
          description: 导出文件二进制流（小文件直接返回）

  # ================================================================
  # 以下为 Phase 0 新增接口
  # ================================================================

  # ========== Admin 内容管理 (Section 3.2) ==========
        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /admin-api/muse/content/works:
    get:
      tags: [Content-Admin]
      summary: 查询作品列表和治理摘要
      description: |
        管理员查询作品列表，返回治理摘要信息。
        默认不返回用户私有正文全文，确需查看必须另有合规访问设计。
      operationId: adminListWorks
      security:
        - adminBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - $ref: '../openapi-base.yaml#/components/parameters/pageNo'
        - $ref: '../openapi-base.yaml#/components/parameters/pageSize'
        - name: status
          in: query
          schema:
            type: string
            enum: [draft, active, archived]
          description: 作品状态过滤
        - name: keyword
          in: query
          schema:
            type: string
          description: 标题关键词搜索
        - name: riskFlag
          in: query
          schema:
            type: boolean
          description: 是否只返回有异常标记的作品
      responses:
        '200':
          description: 作品列表与治理摘要
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        allOf:
                          - $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
                          - type: object
                            properties:
                              list:
                                type: array
                                items:
                                  $ref: '#/components/schemas/AdminWorkSummary'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /admin-api/muse/content/works/{workId}:
    get:
      tags: [Content-Admin]
      summary: 查看作品元信息、章节摘要、异常摘要
      description: |
        管理员查看作品元信息。默认不返回用户私有正文全文，
        确需查看必须另有合规访问设计、审计和最小化字段。
      operationId: adminGetWork
      security:
        - adminBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 作品元信息、章节摘要、异常摘要
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/AdminWorkDetail'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /admin-api/muse/content/works/{workId}/chapters:
    get:
      tags: [Content-Admin]
      summary: 查看章节列表
      description: 管理员查看作品的章节列表，不含正文全文。
      operationId: adminListChapters
      security:
        - adminBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 章节列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/AdminChapterSummary'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /admin-api/muse/content/import-tasks:
    get:
      tags: [Content-Admin]
      summary: 查询导入任务
      operationId: adminListImportTasks
      security:
        - adminBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - $ref: '../openapi-base.yaml#/components/parameters/pageNo'
        - $ref: '../openapi-base.yaml#/components/parameters/pageSize'
        - name: status
          in: query
          schema:
            type: string
            enum: [queued, processing, completed, failed]
          description: 任务状态过滤
        - name: workId
          in: query
          schema:
            type: integer
            format: int64
          description: 按作品过滤
      responses:
        '200':
          description: 导入任务列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        allOf:
                          - $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
                          - type: object
                            properties:
                              list:
                                type: array
                                items:
                                  $ref: '#/components/schemas/ImportTaskSummary'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /admin-api/muse/content/export-tasks:
    get:
      tags: [Content-Admin]
      summary: 查询导出任务
      operationId: adminListExportTasks
      security:
        - adminBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - $ref: '../openapi-base.yaml#/components/parameters/pageNo'
        - $ref: '../openapi-base.yaml#/components/parameters/pageSize'
        - name: status
          in: query
          schema:
            type: string
            enum: [queued, processing, completed, failed]
          description: 任务状态过滤
        - name: workId
          in: query
          schema:
            type: integer
            format: int64
          description: 按作品过滤
      responses:
        '200':
          description: 导出任务列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        allOf:
                          - $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
                          - type: object
                            properties:
                              list:
                                type: array
                                items:
                                  $ref: '#/components/schemas/ExportTaskSummary'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /admin-api/muse/content/works/{workId}/risk-actions:
    post:
      tags: [Content-Admin]
      summary: 异常内容治理动作
      description: |
        管理员对异常内容执行治理动作。必须带 commandId、操作者、权限点、变更理由和审计字段。
        高危治理进入业务审计。
      operationId: adminRiskAction
      security:
        - adminBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RiskActionRequest'
      responses:
        '200':
          description: 治理动作执行成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/RiskActionResult'

  # ========== App 来源归因 (Section 4.3) ==========
        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/blocks/{blockId}/source-attribution:
    get:
      tags: [Content]
      summary: 查看当前 Block revision 来源归因
      description: |
        返回 Block 当前 revision 的来源归因信息，包含来源对象、来源版本、
        授权快照和许可限制。前端可据此展示内容来源标签和合规提示。
        必须先校验调用方拥有 workId 权限，并校验 blockId 属于该 workId。
      operationId: getBlockSourceAttribution
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: blockId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Block 来源归因信息
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/SourceAttribution'
        '404':
          $ref: '../openapi-base.yaml#/components/responses/NotFound'

  /app-api/muse/works/{workId}/blocks/{blockId}/suggestion-merges:
    post:
      tags: [Content]
      summary: 接受或修改后合并 AI 候选到 Canonical Block
      description: |
        Content/Work owner 的最终写入命令，用于承接 AI Orchestration 产生的 suggestion 投影并写入 Canonical Block。
        AI Orchestration 仍拥有候选运行事实；Content 只在提交时查询/校验 suggestionId、来源状态、授权快照、
        质量结果版本、输出合规结果、静态检查结果、work owner、blockId 从属关系、expectedBlockRevision 和 commandId 幂等。
      operationId: mergeBlockSuggestion
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: blockId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MergeBlockSuggestionRequest'
      responses:
        '200':
          description: 候选已写入 Canonical Block
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/MergeBlockSuggestionResult'
        '409':
          description: 目标 Block revision、候选版本、来源状态或授权快照已变化
          content:
            application/json:
              schema:
                $ref: '../openapi-base.yaml#/components/schemas/ErrorResponse'

  # ========== App Meta 投影 (Section 4.3) ==========
  /app-api/muse/works/{workId}/meta-projections:
    get:
      tags: [Content-Meta]
      summary: 查询作品维度用户可见 MetaSchema 投影
      description: |
        返回作品维度用户可见的 MetaSchema 投影列表。
        投影不是事实源，只是 MetaSchema、用户权限、来源状态和目标对象版本计算后的 read model。
      operationId: listMetaProjections
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 作品维度 MetaSchema 投影列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/MetaProjectionSummary'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/meta-projections/{projectionKey}:
    get:
      tags: [Content-Meta]
      summary: 查询指定投影结构、字段数据和版本
      description: |
        返回指定投影的结构、字段数据和版本信息。
        包含 schemaVersion、projectionVersion、dataRevision、sourceSnapshot 和可见字段列表。
      operationId: getMetaProjection
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: projectionKey
          in: path
          required: true
          schema:
            type: string
          description: 投影标识，如 setting、worldview、character 等
      responses:
        '200':
          description: 投影详情
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/MetaProjectionDetail'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/dynamic-fields/validate:
    post:
      tags: [Content-Meta]
      summary: 校验动态字段数据，不写入
      description: |
        只做校验和路由建议，不写入任何 Canonical fact。
        正式写入必须回到目标 owner API。Schema 过期返回 SCHEMA_STALE；
        字段已废弃返回 FIELD_DEPRECATED；投影过期返回 PROJECTION_STALE。
      operationId: validateDynamicFields
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DynamicFieldValidationRequest'
      responses:
        '200':
          description: 校验结果
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/DynamicFieldValidationResult'

  # ========== App 作品规划 (Section 4.4) ==========
        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/planning:
    get:
      tags: [Content-Planning]
      summary: 查询当前作品可见规划结构
      description: |
        返回作品可见规划结构、已确认规划数据、revision 和来源摘要。
        规划正式数据由用户确认后进入 content owner；AI 只能产生 Planning Candidate，不直接写正式规划。
      operationId: getPlanning
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 作品规划结构
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/PlanningStructure'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/planning/{sectionKey}:
    put:
      tags: [Content-Planning]
      summary: 保存规划项
      description: |
        保存规划项，必须带 commandId 和 expectedRevision。
        涉及 MetaSchema 管控的动态字段写入时，expectedSchemaVersion 和 expectedProjectionVersion 必须校验。
      operationId: savePlanningItem
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: sectionKey
          in: path
          required: true
          schema:
            type: string
          description: 规划项标识，如 setting、worldview、character、plot-beat 等
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavePlanningItemRequest'
      responses:
        '200':
          description: 保存成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/PlanningItemSaveResult'
        '409':
          description: 版本冲突或 Schema/投影过期
          content:
            application/json:
              schema:
                $ref: '../openapi-base.yaml#/components/schemas/ErrorResponse'

  /app-api/muse/works/{workId}/planning/candidates:
    post:
      tags: [Content-Planning]
      summary: 请求 AI 生成规划候选
      description: |
        通过 Content/Work 上下文请求 AI Orchestration 生成规划候选，支持生成、补全、整理和多组选项。
        AI Orchestration 拥有生成任务、候选运行事实和评测结果；Content 只提供 work 上下文引用，
        并在用户确认时把候选内容写入 Canonical 规划。
      operationId: createPlanningCandidate
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlanningCandidateRequest'
      responses:
        '202':
          description: 规划候选任务已创建
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          jobId:
                            type: string
                            description: 异步任务 ID，供轮询
                          status:
                            type: string
                            enum: [queued, processing]
                          pollUrl:
                            type: string
                            description: 轮询地址
        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
    get:
      tags: [Content-Planning]
      summary: 查询规划候选
      description: 查询 AI Orchestration owner 提供的规划候选投影；Content 不拥有候选运行事实。
      operationId: listPlanningCandidates
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, confirmed, discarded]
          description: 候选状态过滤
        - name: sectionKey
          in: query
          schema:
            type: string
          description: 按规划项过滤
      responses:
        '200':
          description: 规划候选列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/PlanningCandidateSummary'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/planning/candidates/{candidateId}:
    get:
      tags: [Content-Planning]
      summary: 查询候选详情
      description: 返回 AI Orchestration owner 提供的候选详情、来源、质量结果和 diff 投影。
      operationId: getPlanningCandidate
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: candidateId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 规划候选详情
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/PlanningCandidateDetail'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/planning/candidates/{candidateId}/confirm:
    post:
      tags: [Content-Planning]
      summary: 确认候选进入正式规划
      description: |
        Content/Work owner 的最终写入命令：确认 AI 候选进入正式规划，必须带 commandId 和 expectedRevision。
        确认时目标 owner 必须重验 work 权限、候选状态、来源状态、授权快照、
        质量结果和目标 revision。确认成功只写正式规划项和业务审计，
        不写正文或 Local KB，也不接管 AI 候选运行事实。
      operationId: confirmPlanningCandidate
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: candidateId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmPlanningCandidateRequest'
      responses:
        '200':
          description: 确认成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/PlanningCandidateDecisionResult'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/planning/candidates/{candidateId}/discard:
    post:
      tags: [Content-Planning]
      summary: 丢弃候选
      description: 丢弃候选，必须带 commandId 和原因。
      operationId: discardPlanningCandidate
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: candidateId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscardPlanningCandidateRequest'
      responses:
        '200':
          description: 丢弃成功
          content:
            application/json:
              schema:
                $ref: '../openapi-base.yaml#/components/schemas/CommonResult'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/planning/style-checks:
    post:
      tags: [Content-Planning]
      summary: 请求 AI 文风检查
      description: |
        通过 Content/Work 上下文请求 AI Orchestration 执行文风检查，返回 jobId 供轮询。
        AI Orchestration 拥有运行事实和评测结果；Content 只暴露作品维度结果投影。
      operationId: createStyleCheck
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStyleCheckRequest'
      responses:
        '202':
          description: 文风检查任务已创建
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          jobId:
                            type: string
                            description: 异步任务 ID
                          status:
                            type: string
                            enum: [queued, processing]
                          pollUrl:
                            type: string

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/planning/style-checks/{jobId}:
    get:
      tags: [Content-Planning]
      summary: 查询文风检查结果
      description: 查询 AI Orchestration owner 提供的文风检查结果、风险标记和建议入口投影。
      operationId: getStyleCheckResult
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: jobId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 文风检查结果
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/StyleCheckResult'

  # ========== App 导入导出 (Section 4.9) ==========
        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/import-tasks:
    post:
      tags: [Content-ImportExport]
      summary: 上传并创建导入任务
      description: |
        上传文件并创建导入任务。导入上传必须绑定 owner、用途、大小、MIME、hash、
        扫描状态、source snapshot、authorization snapshot、保留期和清理策略；
        扫描 blocked/failed 的文件不得创建 Parse Job。
      operationId: createImportTask
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateImportTaskRequest'
      responses:
        '202':
          description: 导入任务已创建
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ImportTaskDetail'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/import-tasks/{taskId}:
    get:
      tags: [Content-ImportExport]
      summary: 查询导入任务
      operationId: getImportTask
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: taskId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 导入任务详情
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ImportTaskDetail'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/parse-jobs:
    post:
      tags: [Content-ImportExport]
      summary: 请求 AI 全书解析任务
      description: |
        基于 Content 拥有的导入任务/导入上下文引用，请求 AI Orchestration 创建全书解析任务。
        AI Orchestration 拥有 Parse Job、章节解析结果、评测和重试运行事实；Content 只保存导入上下文引用、
        导入文件安全状态和最终被确认写入 Canonical 的结果。
        Parse Job 必须绑定 workId、发起人、Content 上下文引用、source snapshot、
        authorization snapshot、解析配置版本、Runtime Permission Envelope 和重试组。
      operationId: createParseJob
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateParseJobRequest'
      responses:
        '202':
          description: AI 解析任务已创建
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ParseJobDetail'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/parse-jobs/{jobId}:
    get:
      tags: [Content-ImportExport]
      summary: 查询 AI 解析任务投影
      description: Content 只查询 AI Orchestration owner 的 Parse Job 投影，不拥有解析运行事实。
      operationId: getParseJob
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: jobId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: AI 解析任务详情
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ParseJobDetail'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/parse-jobs/{jobId}/retry:
    post:
      tags: [Content-ImportExport]
      summary: 重试解析任务
      description: 通过 Content 导入上下文引用向 AI Orchestration 请求重试；重试状态和运行事实仍由 AI owner 负责。
      operationId: retryParseJob
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: jobId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [commandId]
              properties:
                commandId:
                  type: string
                  description: 幂等键
                retryStage:
                  type: string
                  description: 指定重试的失败阶段，不传则重试整个任务
      responses:
        '200':
          description: 重试已发起
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          jobId:
                            type: string
                          status:
                            type: string
                            enum: [queued, processing]
                          pollUrl:
                            type: string

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/parse-jobs/{jobId}/chapters:
    get:
      tags: [Content-ImportExport]
      summary: AI 章节解析结果
      description: 返回 AI Orchestration owner 在 Parse Job 下产生的章节解析结果投影。
      operationId: listParseJobChapters
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: jobId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 章节解析结果列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ChapterParseResult'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/chapter-parse-results/{resultId}/confirm:
    post:
      tags: [Content-ImportExport]
      summary: 章节审阅确认
      description: |
        章节审阅确认是对 AI Orchestration owner 章节解析结果的用户决策投影确认。
        Content 不拥有 Chapter Parse Result 或 Review 运行事实；确认后只把导入上下文引用和用户决策交给
        Knowledge owner 生成或刷新 Knowledge Draft，不写正式知识。
      operationId: confirmChapterParseResult
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: resultId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmChapterParseResultRequest'
      responses:
        '200':
          description: 确认成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          draftId:
                            type: string
                            description: 生成的知识草稿 ID
                          status:
                            type: string
                            enum: [confirmed, draft_created]

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/chapter-parse-results/{resultId}/reject:
    post:
      tags: [Content-ImportExport]
      summary: 章节驳回
      description: |
        章节驳回是对 AI Orchestration owner 章节解析结果的用户决策。
        Content 不拥有或删除 AI Shadow 运行事实，只传递驳回原因和导入上下文引用。
        不删除原始导入文件。
      operationId: rejectChapterParseResult
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: resultId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RejectChapterParseResultRequest'
      responses:
        '200':
          description: 驳回成功
          content:
            application/json:
              schema:
                $ref: '../openapi-base.yaml#/components/schemas/CommonResult'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/parse-jobs/{jobId}/chapters/batch-confirm:
    post:
      tags: [Content-ImportExport]
      summary: 批量确认章节
      description: |
        批量确认 AI Orchestration owner 的章节解析结果投影，返回逐章成功、失败和部分失败摘要。
        以章节为事务边界，允许部分失败；某章失败不得回滚已成功章节。
        Content 只保存导入上下文和最终进入 Canonical 的结果引用，不拥有 AI 解析运行事实。
      operationId: batchConfirmChapters
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: jobId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchConfirmChaptersRequest'
      responses:
        '200':
          description: 批量确认结果
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/BatchConfirmChaptersResult'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/works/{workId}/export-tasks:
    post:
      tags: [Content-ImportExport]
      summary: 创建导出任务
      description: |
        创建导出任务，必须带 commandId 幂等键。
        下载凭证必须携带来源传播版本和授权快照。
      operationId: createExportTask
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: workId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExportTaskRequest'
      responses:
        '202':
          description: 导出任务已创建
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ExportTaskDetail'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/export-tasks/{taskId}:
    get:
      tags: [Content-ImportExport]
      summary: 查询导出任务
      operationId: getExportTask
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: taskId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 导出任务详情
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ExportTaskDetail'

        '400':
          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
  /app-api/muse/downloads/{credentialId}:
    get:
      tags: [Content-ImportExport]
      summary: 下载导出包
      description: |
        使用下载凭证下载导出包。来源 revoked/recalled/blocked/unauthorized
        或授权过期时返回 SOURCE_BLOCKED、SOURCE_NEEDS_RECHECK 或 PRECHECK_EXPIRED，
        不能继续下载。
      operationId: downloadExportPackage
      security:
        - appBearerAuth: []
      parameters:
        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
        - name: credentialId
          in: path
          required: true
          schema:
            type: string
          description: 下载凭证 ID
      responses:
        '200':
          description: 导出文件二进制流
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          $ref: '../openapi-base.yaml#/components/responses/NotFound'
        '410':
          description: 下载凭证已过期或已消费
          content:
            application/json:
              schema:
                $ref: '../openapi-base.yaml#/components/schemas/ErrorResponse'

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 不互通。
  schemas:
    # ========== 原有 Schema ==========
    Work:
      type: object
      required: [id, title, status, createdAt, updatedAt]
      properties:
        id:
          type: integer
          format: int64
        title:
          type: string
        description:
          type: string
        genre:
          type: string
        coverImageUrl:
          type: string
          format: uri
        status:
          type: string
          enum: [draft, active, archived]
        wordCount:
          type: integer
          description: 总字数
        chapterCount:
          type: integer
          description: 章节数
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    WorkSummary:
      type: object
      required: [id, title, status, updatedAt]
      properties:
        id:
          type: integer
          format: int64
        title:
          type: string
        genre:
          type: string
        status:
          type: string
          enum: [draft, active, archived]
        wordCount:
          type: integer
        chapterCount:
          type: integer
        updatedAt:
          type: string
          format: date-time

    Chapter:
      type: object
      required: [id, workId, title, sortOrder, status, createdAt, updatedAt]
      properties:
        id:
          type: integer
          format: int64
        workId:
          type: integer
          format: int64
        title:
          type: string
        sortOrder:
          type: integer
        status:
          type: string
          enum: [draft, completed]
        wordCount:
          type: integer
        blockCount:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    ChapterDetail:
      allOf:
        - $ref: '#/components/schemas/Chapter'
        - type: object
          properties:
            blocks:
              type: array
              items:
                $ref: '#/components/schemas/Block'

    Block:
      type: object
      required: [id, workId, chapterId, blockType, content, sortOrder, revision, createdAt, updatedAt]
      properties:
        id:
          type: integer
          format: int64
        workId:
          type: integer
          format: int64
        chapterId:
          type: integer
          format: int64
        blockType:
          type: string
          enum: [scene, section, note]
        title:
          type: string
        content:
          type: string
          description: ProseMirror JSON 格式的正文内容
        sortOrder:
          type: integer
        revision:
          type: integer
          description: 乐观锁版本号，每次保存 +1
        wordCount:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    ContentSourceSnapshot:
      type: object
      description: |
        Content/Work 写命令的来源快照。用于在写入 Canonical 前校验调用方看到的内容版本、
        来源状态、授权快照和目标 owner 边界，避免只凭 chapterId/blockId 裸写。
      properties:
        sourceType:
          type: string
          description: 来源类型，如 user_original、ai_suggestion、imported_content
        sourceId:
          type: string
          description: 来源对象 ID
        sourceVersion:
          type: integer
          description: 调用方看到的来源版本
        authorizationSnapshotId:
          type: string
          description: 授权快照 ID
        contentRevision:
          type: integer
          description: 调用方看到的目标内容 revision

    BlockRevision:
      type: object
      required: [blockId, revision, content, wordCount, commandId, commandType, createdAt]
      properties:
        blockId:
          type: integer
          format: int64
        revision:
          type: integer
          description: Block revision
        content:
          type: string
          description: 该 revision 的正文快照
        wordCount:
          type: integer
          description: 该 revision 的字数
        commandId:
          type: string
          description: 触发该 revision 的命令 ID
        commandType:
          type: string
          enum: [save_block, mergeBlockSuggestion]
          description: 触发该 revision 的命令类型
        sourceType:
          type: string
          description: 来源类型
        sourceId:
          type: string
          description: 来源对象 ID
        sourceVersion:
          type: integer
          description: 来源对象版本
        sourceStatus:
          type: string
          description: 来源状态
        authorizationSnapshotId:
          type: string
          description: 授权快照 ID
        auditReason:
          type: string
          description: 审计原因
        createdAt:
          type: string
          format: date-time

    UpdateChapterRequest:
      type: object
      description: 更新章节请求；服务端必须校验 work owner、chapterId 从属关系、commandId 幂等和 expectedRevision。
      required: [commandId, expectedRevision]
      properties:
        commandId:
          type: string
          description: 幂等键
        expectedRevision:
          type: integer
          description: 章节当前 revision（乐观锁）
        title:
          type: string
          maxLength: 500
        sortOrder:
          type: integer
        status:
          type: string
          enum: [draft, completed]
        sourceSnapshot:
          $ref: '#/components/schemas/ContentSourceSnapshot'
        auditReason:
          type: string
          description: 用户修改原因

    DeleteChapterRequest:
      type: object
      description: 删除章节请求；服务端必须校验 work owner、chapterId 从属关系、commandId 幂等和 expectedRevision。
      required: [commandId, expectedRevision]
      properties:
        commandId:
          type: string
          description: 幂等键
        expectedRevision:
          type: integer
          description: 章节当前 revision（乐观锁）
        sourceSnapshot:
          $ref: '#/components/schemas/ContentSourceSnapshot'
        reason:
          type: string
          description: 删除原因

    ReorderChapterRequest:
      type: object
      description: 章节重排请求；服务端必须校验 work owner、章节从属关系、commandId 幂等、expectedRevision 和 sourceSnapshot。
      required: [commandId, expectedRevision, newSortOrder, sourceSnapshot]
      properties:
        commandId:
          type: string
          description: 幂等键
        expectedRevision:
          type: integer
          description: 作品章节排序 revision 或目标章节 revision（乐观锁）
        newSortOrder:
          type: integer
          minimum: 0
        sourceSnapshot:
          $ref: '#/components/schemas/ContentSourceSnapshot'

    CreateBlockRequest:
      type: object
      description: 创建 Block 请求；服务端必须校验 work owner、chapterId 从属关系、commandId 幂等和 expectedChapterRevision。
      required: [commandId, content, blockType, expectedChapterRevision]
      properties:
        commandId:
          type: string
          description: 幂等键
        content:
          type: string
          description: Block 正文内容（JSON 格式的 ProseMirror 文档）
        blockType:
          type: string
          enum: [scene, section, note]
          description: Block 类型
        expectedChapterRevision:
          type: integer
          description: 章节当前 revision（乐观锁）
        sortOrder:
          type: integer
        title:
          type: string
          maxLength: 500
        sourceSnapshot:
          $ref: '#/components/schemas/ContentSourceSnapshot'

    SaveBlockRequest:
      type: object
      description: 保存 Block 正文请求；服务端必须校验 work owner、blockId 从属关系、commandId 幂等、expectedRevision 和 sourceSnapshot。
      required: [commandId, content, expectedRevision, sourceSnapshot]
      properties:
        commandId:
          type: string
          description: 幂等键
        content:
          type: string
          description: Block 正文（ProseMirror JSON）
        expectedRevision:
          type: integer
          description: Block 当前 revision（乐观锁）
        sourceSnapshot:
          $ref: '#/components/schemas/ContentSourceSnapshot'
        auditReason:
          type: string
          description: 用户保存或覆盖原因

    DeleteBlockRequest:
      type: object
      description: 删除 Block 请求；服务端必须校验 work owner、blockId 从属关系、commandId 幂等、expectedRevision 和 sourceSnapshot。
      required: [commandId, expectedRevision, sourceSnapshot]
      properties:
        commandId:
          type: string
          description: 幂等键
        expectedRevision:
          type: integer
          description: Block 当前 revision（乐观锁）
        sourceSnapshot:
          $ref: '#/components/schemas/ContentSourceSnapshot'
        reason:
          type: string
          description: 删除原因

    SplitBlockRequest:
      type: object
      description: 分割 Block 请求；服务端必须校验 work owner、blockId 从属关系、commandId 幂等、expectedRevision 和 sourceSnapshot。
      required: [commandId, splitPosition, expectedRevision, sourceSnapshot]
      properties:
        commandId:
          type: string
          description: 幂等键
        splitPosition:
          type: integer
          description: 分割位置（字符偏移量）
        expectedRevision:
          type: integer
          description: Block 当前 revision（乐观锁）
        sourceSnapshot:
          $ref: '#/components/schemas/ContentSourceSnapshot'

    MergeBlockRequest:
      type: object
      description: 合并 Block 请求；服务端必须校验 work owner、blockId/targetBlockId 从属关系、commandId 幂等、expectedRevision 和 sourceSnapshot。
      required: [commandId, expectedRevision, sourceSnapshot]
      properties:
        commandId:
          type: string
          description: 幂等键
        expectedRevision:
          type: integer
          description: 源 Block 当前 revision（乐观锁）
        targetBlockId:
          type: integer
          format: int64
          description: 目标相邻 Block ID；不传时默认与下一个 Block 合并
        sourceSnapshot:
          $ref: '#/components/schemas/ContentSourceSnapshot'

    MergeBlockSuggestionRequest:
      type: object
      description: |
        接受或修改后合并 AI suggestion 的 Content owner 写入请求。
        服务端必须实时查询/校验 AI owner 的 suggestion 投影和来源状态，再写 Canonical Block。
      required: [suggestionId, commandId, expectedBlockRevision, decisionType, mergeMode, sourceSnapshot]
      properties:
        suggestionId:
          type: integer
          format: int64
          description: AI Orchestration owner 产生的候选 ID
        commandId:
          type: string
          description: 幂等键
        expectedBlockRevision:
          type: integer
          description: 目标 Block 当前 revision（乐观锁）
        decisionType:
          type: string
          enum: [accept, modify_then_merge]
          description: 用户决策类型
        mergeMode:
          type: string
          enum: [accept_as_is, merge_after_edit]
          description: 写入方式：原样接受或修改后合并
        finalContent:
          type: string
          description: 修改后合并时的最终 Block 正文（mergeMode=merge_after_edit 时必填）
        qualityResultVersion:
          type: integer
          description: 候选质量结果版本
        outputComplianceResultId:
          type: string
          description: 输出合规结果 ID
        staticCheckResultId:
          type: string
          description: 静态检查结果 ID
        sourceSnapshot:
          $ref: '#/components/schemas/ContentSourceSnapshot'
        auditReason:
          type: string
          description: 用户接受或修改合并原因

    MergeBlockSuggestionResult:
      type: object
      description: AI suggestion 写入 Canonical Block 的结果
      required: [blockId, suggestionId, newRevision, decisionType]
      properties:
        blockId:
          type: integer
          format: int64
        suggestionId:
          type: integer
          format: int64
        newRevision:
          type: integer
          description: Block 保存成功后的新 revision
        decisionType:
          type: string
          enum: [accept, modify_then_merge]
        sourceAttribution:
          $ref: '#/components/schemas/SourceAttribution'

    # ========== Admin 内容管理 Schema ==========
    AdminWorkSummary:
      type: object
      description: 管理员视角的作品列表项，含治理摘要
      required: [id, title, status, ownerId, updatedAt]
      properties:
        id:
          type: integer
          format: int64
        title:
          type: string
        genre:
          type: string
        status:
          type: string
          enum: [draft, active, archived]
        ownerId:
          type: string
          description: 作品所有者用户 ID
        wordCount:
          type: integer
        chapterCount:
          type: integer
        riskFlags:
          type: array
          description: 异常标记列表
          items:
            type: object
            properties:
              riskType:
                type: string
                description: 异常类型，如 content_violation、copyright_issue
              severity:
                type: string
                enum: [low, medium, high, critical]
              description:
                type: string
                description: 异常描述摘要
        lastGovernanceActionAt:
          type: string
          format: date-time
          description: 最近一次治理动作时间
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    AdminWorkDetail:
      type: object
      description: 管理员视角的作品详情，含章节摘要和异常摘要
      required: [id, title, status, ownerId, createdAt, updatedAt]
      properties:
        id:
          type: integer
          format: int64
        title:
          type: string
        description:
          type: string
        genre:
          type: string
        status:
          type: string
          enum: [draft, active, archived]
        ownerId:
          type: string
          description: 作品所有者用户 ID
        wordCount:
          type: integer
        chapterCount:
          type: integer
        chapterSummaries:
          type: array
          description: 章节摘要列表（不含正文全文）
          items:
            $ref: '#/components/schemas/AdminChapterSummary'
        exceptionSummary:
          type: object
          description: 异常摘要
          properties:
            totalRiskFlags:
              type: integer
              description: 总异常标记数
            criticalCount:
              type: integer
              description: 严重异常数
            activeGovernanceActions:
              type: integer
              description: 进行中的治理动作数
            latestRiskType:
              type: string
              description: 最近异常类型
        governanceHistory:
          type: array
          description: 治理操作历史摘要
          items:
            type: object
            properties:
              action:
                type: string
                description: 治理动作类型
              operatorId:
                type: string
                description: 操作者 ID
              reason:
                type: string
              operatedAt:
                type: string
                format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    AdminChapterSummary:
      type: object
      description: 管理员视角的章节摘要，不含正文全文
      required: [id, title, sortOrder, status]
      properties:
        id:
          type: integer
          format: int64
        title:
          type: string
        sortOrder:
          type: integer
        status:
          type: string
          enum: [draft, completed]
        wordCount:
          type: integer
        blockCount:
          type: integer
        riskFlags:
          type: array
          items:
            type: object
            properties:
              riskType:
                type: string
              severity:
                type: string
                enum: [low, medium, high, critical]

    RiskActionRequest:
      type: object
      description: 异常内容治理动作请求
      required: [commandId, action, reason, expectedVersion]
      properties:
        commandId:
          type: string
          description: 幂等键
        action:
          type: string
          enum: [warn, restrict, block_content, force_archive, notify_owner]
          description: |
            治理动作类型：
            warn - 发出警告通知
            restrict - 限制部分功能
            block_content - 阻断内容访问
            force_archive - 强制归档作品
            notify_owner - 通知作品所有者
        reason:
          type: string
          description: 治理原因，必须填写
        targetScope:
          type: string
          enum: [work, chapter, block]
          description: 治理范围粒度，默认 work
        targetIds:
          type: array
          items:
            type: integer
            format: int64
          description: 指定治理的章节或 Block ID（粒度非 work 时必填）
        expectedVersion:
          type: integer
          description: 作品当前版本号，用于乐观锁
        duration:
          type: string
          description: 限制时长，如 P7D（7 天），仅 restrict 动作适用

    RiskActionResult:
      type: object
      description: 治理动作执行结果
      properties:
        actionId:
          type: string
          description: 治理动作记录 ID
        status:
          type: string
          enum: [executed, pending_notification]
        affectedScope:
          type: string
          description: 实际影响的范围描述
        auditLogId:
          type: string
          description: 审计日志 ID

    ImportTaskSummary:
      type: object
      description: 导入任务摘要（管理端列表用）
      required: [id, workId, status, createdAt]
      properties:
        id:
          type: integer
          format: int64
        workId:
          type: integer
          format: int64
        workTitle:
          type: string
        fileName:
          type: string
        fileSize:
          type: integer
          format: int64
        format:
          type: string
          enum: [txt, epub, docx, markdown]
        status:
          type: string
          enum: [queued, processing, completed, failed]
        ownerId:
          type: string
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time

    ExportTaskSummary:
      type: object
      description: 导出任务摘要（管理端列表用）
      required: [id, workId, status, createdAt]
      properties:
        id:
          type: integer
          format: int64
        workId:
          type: integer
          format: int64
        workTitle:
          type: string
        format:
          type: string
          enum: [txt, epub, docx]
        status:
          type: string
          enum: [queued, processing, completed, failed]
        ownerId:
          type: string
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time

    # ========== 来源归因 Schema ==========
    SourceAttribution:
      type: object
      description: Block 当前 revision 的来源归因信息
      required: [blockId, revision]
      properties:
        blockId:
          type: integer
          format: int64
        revision:
          type: integer
          description: Block 当前 revision 号
        sources:
          type: array
          description: 来源归因列表
          items:
            type: object
            required: [sourceType, sourceId, contributionType]
            properties:
              sourceType:
                type: string
                enum: [user_original, ai_suggestion, knowledge_reference, market_asset, imported_content]
                description: 来源类型
              sourceId:
                type: string
                description: 来源对象 ID
              sourceName:
                type: string
                description: 来源对象名称
              contributionType:
                type: string
                enum: [full, partial, reference, context]
                description: 贡献类型
              authorizationSnapshotId:
                type: string
                description: 授权快照 ID
              sourceVersion:
                type: integer
                description: 来源版本号
              licenseRestrictions:
                type: array
                description: 许可限制列表
                items:
                  type: string
        lineage:
          type: object
          description: 来源谱系信息
          properties:
            parentSuggestionId:
              type: string
              description: 关联的 AI 候选 ID
            acceptedAt:
              type: string
              format: date-time
            acceptMode:
              type: string
              enum: [accept_as_is, merge_after_edit]

    # ========== Meta 投影 Schema ==========
    MetaProjectionSummary:
      type: object
      description: 作品维度 MetaSchema 投影摘要
      required: [projectionKey, schemaVersion, projectionVersion]
      properties:
        projectionKey:
          type: string
          description: 投影标识，如 setting、worldview、character
        projectionName:
          type: string
          description: 投影名称
        schemaVersion:
          type: integer
          description: 本次投影使用的 MetaSchema 版本
        projectionVersion:
          type: integer
          description: 可见投影版本，用于判断前端缓存是否过期
        dataRevision:
          type: integer
          description: 目标对象动态字段数据 revision
        fieldCount:
          type: integer
          description: 可见字段数量

    MetaProjectionDetail:
      type: object
      description: 投影详情，含结构和字段数据
      required: [projectionKey, schemaVersion, projectionVersion, dataRevision, fields]
      properties:
        projectionKey:
          type: string
        projectionName:
          type: string
        schemaVersion:
          type: integer
          description: 使用的 MetaSchema active 或灰度版本
        projectionVersion:
          type: integer
          description: 可见投影版本
        dataRevision:
          type: integer
          description: 目标对象动态字段数据 revision
        sourceSnapshot:
          type: object
          description: 来源对象、来源版本、授权快照和来源状态摘要
          properties:
            sourceType:
              type: string
            sourceId:
              type: string
            sourceVersion:
              type: integer
            authorizationSnapshotId:
              type: string
            sourceStatus:
              type: string
              enum: [active, stale, revoked, recalled, blocked, owner_missing, unauthorized]
        fields:
          type: array
          description: 仅包含当前用户可见、可编辑、可搜索或可导出的字段
          items:
            type: object
            required: [fieldKey, fieldType, uiVisible]
            properties:
              fieldKey:
                type: string
              fieldName:
                type: string
              fieldType:
                type: string
                enum: [text, number, boolean, enum, reference, structured, date]
              required:
                type: boolean
              uiVisible:
                type: boolean
                description: 是否进入用户可见投影
              aiContext:
                type: boolean
                description: 是否允许进入 AI 上下文组装
              userEditable:
                type: boolean
                description: 用户端是否允许保存该动态字段
              userSearchable:
                type: boolean
                description: 是否允许用户搜索或筛选
              exportable:
                type: boolean
                description: 是否可被导出预检纳入
              deprecated:
                type: boolean
                description: 字段是否已废弃
              migrationHint:
                type: string
                description: 废弃时的迁移提示
              writeOwner:
                type: string
                description: 写入 owner 标识
              ownerCommand:
                type: string
                description: owner 写入命令路径
              value:
                description: 当前字段值
              enumValues:
                type: array
                description: 枚举可选值（fieldType=enum 时）
                items:
                  type: string

    DynamicFieldValidationRequest:
      type: object
      description: 动态字段校验请求
      required: [fields, schemaVersion, projectionVersion]
      properties:
        fields:
          type: array
          description: 待校验的动态字段数据
          items:
            type: object
            required: [fieldKey, value]
            properties:
              fieldKey:
                type: string
              value:
                description: 字段值
        schemaVersion:
          type: integer
          description: 调用方持有的 MetaSchema 版本
        projectionVersion:
          type: integer
          description: 调用方持有的投影版本
        dataRevision:
          type: integer
          description: 调用方持有的数据 revision

    DynamicFieldValidationResult:
      type: object
      description: 动态字段校验结果
      properties:
        valid:
          type: boolean
          description: 整体是否合法
        fieldResults:
          type: array
          items:
            type: object
            properties:
              fieldKey:
                type: string
              valid:
                type: boolean
              errors:
                type: array
                items:
                  type: object
                  properties:
                    errorCode:
                      type: string
                      enum: [REQUIRED_MISSING, TYPE_MISMATCH, ENUM_INVALID, REFERENCE_INVALID, FIELD_DEPRECATED, VALUE_OUT_OF_RANGE]
                    message:
                      type: string
        schemaStale:
          type: boolean
          description: Schema 是否已过期
        projectionStale:
          type: boolean
          description: 投影是否已过期
        currentSchemaVersion:
          type: integer
        currentProjectionVersion:
          type: integer
        currentDataRevision:
          type: integer
        routeSuggestions:
          type: array
          description: 写入路由建议，指引前端到正确的 owner 命令
          items:
            type: object
            properties:
              fieldKey:
                type: string
              writeOwner:
                type: string
              ownerCommand:
                type: string
                description: 建议的 owner 命令路径

    # ========== 规划 Schema ==========
    PlanningStructure:
      type: object
      description: 作品规划结构
      required: [workId, revision]
      properties:
        workId:
          type: integer
          format: int64
        revision:
          type: integer
          description: 规划数据 revision
        sections:
          type: array
          description: 已确认的规划项列表
          items:
            $ref: '#/components/schemas/PlanningSection'
        sourceSnapshot:
          type: object
          description: 来源摘要
          properties:
            sourceType:
              type: string
            sourceVersion:
              type: integer
            authorizationSnapshotId:
              type: string

    PlanningSection:
      type: object
      description: 规划项数据
      required: [sectionKey, revision]
      properties:
        sectionKey:
          type: string
          description: 规划项标识，如 setting、worldview、character、plot-beat
        sectionName:
          type: string
        content:
          type: object
          description: 规划项内容（结构化 JSON）
        revision:
          type: integer
          description: 该规划项的 revision
        schemaVersion:
          type: integer
          description: 使用的 MetaSchema 版本
        projectionVersion:
          type: integer
          description: 使用的投影版本
        updatedAt:
          type: string
          format: date-time

    SavePlanningItemRequest:
      type: object
      description: 保存规划项请求
      required: [commandId, content, expectedRevision]
      properties:
        commandId:
          type: string
          description: 幂等键
        content:
          type: object
          description: 规划项内容（结构化 JSON）
        expectedRevision:
          type: integer
          description: 目标规划 section 的当前 revision
        expectedSchemaVersion:
          type: integer
          description: 调用方持有的 MetaSchema 版本（涉及动态字段时必须）
        expectedProjectionVersion:
          type: integer
          description: 调用方持有的投影版本（涉及动态字段时必须）
        sourceSnapshot:
          type: object
          description: 来源快照摘要
          properties:
            sourceType:
              type: string
            sourceVersion:
              type: integer
            authorizationSnapshotId:
              type: string
        auditReason:
          type: string
          description: 用户保存或覆盖原因

    PlanningItemSaveResult:
      type: object
      description: 规划项保存结果
      properties:
        sectionKey:
          type: string
        newRevision:
          type: integer
        updatedAt:
          type: string
          format: date-time

    CreatePlanningCandidateRequest:
      type: object
      description: 请求 AI Orchestration 生成规划候选的上下文引用；Content 不拥有候选运行事实。
      required: [sectionKey, taskType]
      properties:
        sectionKey:
          type: string
          description: 目标规划项标识
        taskType:
          type: string
          enum: [generate, supplement, organize, multi_option]
          description: |
            任务类型：
            generate - 生成新内容
            supplement - 补全已有内容
            organize - 整理已有内容
            multi_option - 生成多组选项
        context:
          type: object
          description: 生成上下文，如已有规划内容、用户指令等
        commandId:
          type: string
          description: 幂等键
        sourceSnapshot:
          type: object
          properties:
            sourceType:
              type: string
            sourceVersion:
              type: integer
            authorizationSnapshotId:
              type: string

    PlanningCandidateSummary:
      type: object
      description: AI Orchestration owner 提供给 Content/Work 的规划候选投影摘要
      required: [id, sectionKey, status, createdAt]
      properties:
        id:
          type: integer
          format: int64
        sectionKey:
          type: string
        taskType:
          type: string
          enum: [generate, supplement, organize, multi_option]
        status:
          type: string
          enum: [pending, confirmed, discarded]
        revision:
          type: integer
        qualityScore:
          type: number
          description: 质量评分
        createdAt:
          type: string
          format: date-time
        confirmedAt:
          type: string
          format: date-time

    PlanningCandidateDetail:
      type: object
      description: AI Orchestration owner 提供给 Content/Work 的规划候选详情投影
      required: [id, sectionKey, status, content, revision, createdAt]
      properties:
        id:
          type: integer
          format: int64
        sectionKey:
          type: string
        taskType:
          type: string
          enum: [generate, supplement, organize, multi_option]
        status:
          type: string
          enum: [pending, confirmed, discarded]
        content:
          type: object
          description: 候选内容（结构化 JSON）
        revision:
          type: integer
        qualityResult:
          type: object
          description: 质量检查结果
          properties:
            score:
              type: number
            passed:
              type: boolean
            issues:
              type: array
              items:
                type: object
                properties:
                  severity:
                    type: string
                    enum: [info, warning, critical]
                  code:
                    type: string
                  message:
                    type: string
        diff:
          type: object
          description: 与当前正式规划的差异
          properties:
            hasChanges:
              type: boolean
            summary:
              type: string
            additions:
              type: integer
            deletions:
              type: integer
            modifications:
              type: integer
        sourceSnapshot:
          type: object
          properties:
            sourceType:
              type: string
            sourceId:
              type: string
            sourceVersion:
              type: integer
            authorizationSnapshotId:
              type: string
        createdAt:
          type: string
          format: date-time
        confirmedAt:
          type: string
          format: date-time

    ConfirmPlanningCandidateRequest:
      type: object
      description: 确认规划候选请求
      required: [commandId, expectedRevision]
      properties:
        commandId:
          type: string
          description: 幂等键
        expectedRevision:
          type: integer
          description: 目标规划 section 的当前 revision
        expectedSchemaVersion:
          type: integer
          description: MetaSchema 版本（涉及动态字段时必须）
        expectedProjectionVersion:
          type: integer
          description: 投影版本（涉及动态字段时必须）
        sourceSnapshot:
          type: object
          properties:
            sourceType:
              type: string
            sourceVersion:
              type: integer
            authorizationSnapshotId:
              type: string
        auditReason:
          type: string
          description: 用户确认原因

    PlanningCandidateDecisionResult:
      type: object
      description: 候选确认结果
      properties:
        candidateId:
          type: string
        newRevision:
          type: integer
          description: 规划项新 revision
        sectionKey:
          type: string
        auditLogId:
          type: string

    DiscardPlanningCandidateRequest:
      type: object
      description: 丢弃规划候选请求
      required: [commandId, reason]
      properties:
        commandId:
          type: string
          description: 幂等键
        reason:
          type: string
          description: 丢弃原因

    CreateStyleCheckRequest:
      type: object
      description: 请求 AI Orchestration 执行文风检查的作品上下文引用
      required: [commandId]
      properties:
        commandId:
          type: string
          description: 幂等键
        checkScope:
          type: string
          enum: [full_work, selected_chapters, selected_blocks]
          description: 检查范围，默认 full_work
        targetIds:
          type: array
          items:
            type: integer
            format: int64
          description: 指定检查的章节或 Block ID（checkScope 非 full_work 时必填）
        styleRules:
          type: object
          description: 自定义文风规则（可选，不传则使用作品设定）
        sourceSnapshot:
          type: object
          properties:
            sourceType:
              type: string
            sourceVersion:
              type: integer
            authorizationSnapshotId:
              type: string

    StyleCheckResult:
      type: object
      description: AI Orchestration owner 提供给 Content/Work 的文风检查结果投影
      required: [jobId, status]
      properties:
        jobId:
          type: integer
          format: int64
        status:
          type: string
          enum: [queued, processing, completed, failed]
        riskMarkers:
          type: array
          description: 风险标记列表
          items:
            type: object
            properties:
              markerType:
                type: string
                enum: [consistency, tone_shift, pacing, vocabulary, repetition]
              severity:
                type: string
                enum: [info, warning, critical]
              location:
                type: object
                properties:
                  chapterId:
                    type: string
                  blockId:
                    type: string
                  position:
                    type: string
              description:
                type: string
        summary:
          type: object
          properties:
            overallScore:
              type: number
            consistencyScore:
              type: number
            checkedWordCount:
              type: integer
            markerCount:
              type: integer
        suggestions:
          type: array
          description: 建议入口
          items:
            type: object
            properties:
              suggestionType:
                type: string
                enum: [rewrite, adjust, review]
              targetSectionKey:
                type: string
              description:
                type: string
        completedAt:
          type: string
          format: date-time

    # ========== 导入导出 Schema ==========
    CreateImportTaskRequest:
      type: object
      description: 创建导入任务请求
      required: [commandId, fileName, fileSize, fileHash]
      properties:
        commandId:
          type: string
          description: 幂等键
        fileName:
          type: string
          description: 文件名
        fileSize:
          type: integer
          format: int64
          description: 文件大小（字节）
        fileHash:
          type: string
          description: 文件哈希值
        mimeType:
          type: string
          description: 文件 MIME 类型
        format:
          type: string
          enum: [txt, epub, docx, markdown]
          description: 导入文件格式
        uploadUrl:
          type: string
          format: uri
          description: 已上传文件的存储引用
        sourceSnapshot:
          type: object
          description: 来源快照
          properties:
            sourceType:
              type: string
            sourceVersion:
              type: integer
            authorizationSnapshotId:
              type: string

    ImportTaskDetail:
      type: object
      description: 导入任务详情
      required: [id, workId, status, createdAt]
      properties:
        id:
          type: integer
          format: int64
        workId:
          type: integer
          format: int64
        fileName:
          type: string
        fileSize:
          type: integer
          format: int64
        format:
          type: string
          enum: [txt, epub, docx, markdown]
        status:
          type: string
          enum: [queued, processing, completed, failed]
        scanStatus:
          type: string
          enum: [pending, passed, blocked, failed]
          description: 文件扫描状态
        progress:
          type: integer
          description: 处理进度百分比（0-100）
        errorMessage:
          type: string
          description: 失败时的错误信息
        failedStage:
          type: string
          description: 失败阶段
        retryable:
          type: boolean
          description: 是否可重试
        nextActions:
          type: array
          description: 下一步建议动作
          items:
            type: string
        sourceSnapshot:
          type: object
          properties:
            sourceType:
              type: string
            sourceVersion:
              type: integer
            authorizationSnapshotId:
              type: string
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time

    CreateParseJobRequest:
      type: object
      description: 基于 Content 导入上下文请求 AI Orchestration 创建全书解析任务；Content 不拥有 Parse Job 运行事实。
      required: [commandId, importTaskId]
      properties:
        commandId:
          type: string
          description: 幂等键
        importTaskId:
          type: integer
          format: int64
          description: 关联的导入任务 ID
        parseConfig:
          type: object
          description: 解析配置
          properties:
            chapterDetectionMode:
              type: string
              enum: [auto, manual_outline, hybrid]
              description: 章节检测模式
            languageHint:
              type: string
              description: 语言提示
            customInstructions:
              type: string
              description: 自定义解析指令
        sourceSnapshot:
          type: object
          properties:
            sourceType:
              type: string
            sourceVersion:
              type: integer
            authorizationSnapshotId:
              type: string

    ParseJobDetail:
      type: object
      description: AI Orchestration owner 提供给 Content/Work 的解析任务投影
      required: [id, workId, status, createdAt]
      properties:
        id:
          type: integer
          format: int64
        workId:
          type: integer
          format: int64
        importTaskId:
          type: integer
          format: int64
        status:
          type: string
          enum: [queued, processing, completed, failed]
        progress:
          type: integer
          description: 处理进度百分比（0-100）
        totalChapters:
          type: integer
          description: 检测到的总章节数
        confirmedChapters:
          type: integer
          description: 已确认章节数
        pendingChapters:
          type: integer
          description: 待审阅章节数
        errorMessage:
          type: string
        failedStage:
          type: string
        retryable:
          type: boolean
        nextActions:
          type: array
          items:
            type: string
        parseConfigVersion:
          type: integer
          description: 解析配置版本
        sourceSnapshot:
          type: object
          properties:
            sourceType:
              type: string
            sourceVersion:
              type: integer
            authorizationSnapshotId:
              type: string
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time

    ChapterParseResult:
      type: object
      description: AI Orchestration owner 提供给 Content/Work 的章节解析结果投影
      required: [id, jobId, title, status, revision]
      properties:
        id:
          type: integer
          format: int64
        jobId:
          type: integer
          format: int64
        title:
          type: string
          description: AI 检测到的章节标题
        sortOrder:
          type: integer
        contentPreview:
          type: string
          description: 内容预览（截取摘要，非全文）
        wordCount:
          type: integer
        status:
          type: string
          enum: [pending_review, confirmed, rejected]
          description: |
            审阅状态：
            pending_review - 待审阅
            confirmed - 已确认
            rejected - 已驳回
        revision:
          type: integer
        qualityResult:
          type: object
          properties:
            score:
              type: number
            issues:
              type: array
              items:
                type: object
                properties:
                  severity:
                    type: string
                  code:
                    type: string
                  message:
                    type: string

    ConfirmChapterParseResultRequest:
      type: object
      description: 章节解析结果投影确认请求；AI 运行事实仍归 AI Orchestration。
      required: [commandId, expectedRevision]
      properties:
        commandId:
          type: string
          description: 幂等键
        expectedRevision:
          type: integer
          description: 当前 parse result revision

    RejectChapterParseResultRequest:
      type: object
      description: 章节解析结果投影驳回请求；AI 运行事实仍归 AI Orchestration。
      required: [commandId, reason]
      properties:
        commandId:
          type: string
          description: 幂等键
        reason:
          type: string
          description: 驳回原因
        expectedRevision:
          type: integer
          description: 当前 parse result revision

    BatchConfirmChaptersRequest:
      type: object
      description: 批量确认章节解析结果投影请求；Content 只传递导入上下文和用户决策。
      required: [commandId, resultIds]
      properties:
        commandId:
          type: string
          description: 幂等键
        resultIds:
          type: array
          description: 待确认的 chapter parse result ID 列表
          items:
            type: integer
            format: int64

    BatchConfirmChaptersResult:
      type: object
      description: 批量确认章节结果
      properties:
        confirmedChapterResultIds:
          type: array
          description: 成功确认的章节 result ID 列表
          items:
            type: integer
            format: int64
        createdDraftIds:
          type: array
          description: 生成的知识草稿 ID 列表
          items:
            type: integer
            format: int64
        failedChapters:
          type: array
          description: 失败章节列表
          items:
            type: object
            properties:
              resultId:
                type: integer
                format: int64
              errorCode:
                type: string
              errorMessage:
                type: string
        skippedChapters:
          type: array
          description: 跳过章节列表
          items:
            type: object
            properties:
              resultId:
                type: integer
                format: int64
              reason:
                type: string
        partialFailure:
          type: boolean
          description: 是否存在部分失败

    CreateExportTaskRequest:
      type: object
      description: 创建导出任务请求
      required: [commandId, format]
      properties:
        commandId:
          type: string
          description: 幂等键
        format:
          type: string
          enum: [txt, epub, docx]
          description: 导出格式
        includeChapters:
          type: array
          description: 指定导出章节 ID，空数组表示导出全部
          items:
            type: integer
            format: int64
        includeMetadata:
          type: boolean
          default: true
          description: 是否包含元数据
        includePlanning:
          type: boolean
          default: false
          description: 是否包含规划数据
        sourceSnapshot:
          type: object
          description: 来源快照
          properties:
            sourceType:
              type: string
            sourceVersion:
              type: integer
            authorizationSnapshotId:
              type: string

    ExportTaskDetail:
      type: object
      description: 导出任务详情
      required: [id, workId, format, status, createdAt]
      properties:
        id:
          type: integer
          format: int64
        workId:
          type: integer
          format: int64
        format:
          type: string
          enum: [txt, epub, docx]
        status:
          type: string
          enum: [queued, processing, completed, failed]
        progress:
          type: integer
          description: 处理进度百分比（0-100）
        downloadCredentialId:
          type: string
          description: 完成后的下载凭证 ID
        downloadExpiresAt:
          type: string
          format: date-time
          description: 下载凭证过期时间
        errorMessage:
          type: string
        sourceSnapshot:
          type: object
          properties:
            sourceType:
              type: string
            sourceVersion:
              type: integer
            authorizationSnapshotId:
              type: string
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time