3046 lines
89 KiB
YAML
3046 lines
89 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: Muse Content API
|
||
version: 1.0.0
|
||
|
||
paths:
|
||
# ========== 作品(Work) ==========
|
||
/app-api/content/works:
|
||
get:
|
||
tags: [Content]
|
||
summary: 获取作品列表
|
||
operationId: listWorks
|
||
parameters:
|
||
- $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/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/WorkSummary'
|
||
post:
|
||
tags: [Content]
|
||
summary: 创建新作品
|
||
operationId: createWork
|
||
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'
|
||
|
||
/app-api/content/works/{workId}:
|
||
get:
|
||
tags: [Content]
|
||
summary: 获取作品详情
|
||
operationId: getWork
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: 作品详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/Work'
|
||
put:
|
||
tags: [Content]
|
||
summary: 更新作品
|
||
operationId: updateWork
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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'
|
||
delete:
|
||
tags: [Content]
|
||
summary: 删除作品
|
||
operationId: deleteWork
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: 删除成功
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
# ========== 章节(Chapter) ==========
|
||
/app-api/content/works/{workId}/chapters:
|
||
get:
|
||
tags: [Content]
|
||
summary: 获取作品章节列表
|
||
operationId: listChapters
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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'
|
||
post:
|
||
tags: [Content]
|
||
summary: 创建章节
|
||
operationId: createChapter
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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'
|
||
|
||
/app-api/content/chapters/{chapterId}:
|
||
get:
|
||
tags: [Content]
|
||
summary: 获取章节详情
|
||
operationId: getChapter
|
||
parameters:
|
||
- name: chapterId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: 章节详情（含 Block 列表）
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/ChapterDetail'
|
||
put:
|
||
tags: [Content]
|
||
summary: 更新章节
|
||
operationId: updateChapter
|
||
parameters:
|
||
- name: chapterId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
title:
|
||
type: string
|
||
maxLength: 500
|
||
sortOrder:
|
||
type: integer
|
||
status:
|
||
type: string
|
||
enum: [draft, completed]
|
||
responses:
|
||
'200':
|
||
description: 更新成功
|
||
delete:
|
||
tags: [Content]
|
||
summary: 删除章节
|
||
operationId: deleteChapter
|
||
parameters:
|
||
- name: chapterId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: 删除成功
|
||
|
||
/app-api/content/chapters/{chapterId}/reorder:
|
||
put:
|
||
tags: [Content]
|
||
summary: 调整章节排序
|
||
operationId: reorderChapters
|
||
parameters:
|
||
- name: chapterId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [newSortOrder]
|
||
properties:
|
||
newSortOrder:
|
||
type: integer
|
||
minimum: 0
|
||
responses:
|
||
'200':
|
||
description: 排序更新成功
|
||
|
||
# ========== Block ==========
|
||
/app-api/content/chapters/{chapterId}/blocks:
|
||
get:
|
||
tags: [Content]
|
||
summary: 获取章节 Block 列表
|
||
operationId: listBlocks
|
||
parameters:
|
||
- name: chapterId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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'
|
||
post:
|
||
tags: [Content]
|
||
summary: 创建 Block
|
||
operationId: createBlock
|
||
parameters:
|
||
- name: chapterId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [content, blockType]
|
||
properties:
|
||
content:
|
||
type: string
|
||
description: Block 正文内容（JSON 格式的 ProseMirror 文档）
|
||
blockType:
|
||
type: string
|
||
enum: [scene, section, note]
|
||
description: Block 类型
|
||
sortOrder:
|
||
type: integer
|
||
title:
|
||
type: string
|
||
maxLength: 500
|
||
responses:
|
||
'201':
|
||
description: 创建成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/Block'
|
||
|
||
/app-api/content/blocks/{blockId}:
|
||
get:
|
||
tags: [Content]
|
||
summary: 获取 Block 详情
|
||
operationId: getBlock
|
||
parameters:
|
||
- name: blockId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: Block 详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/Block'
|
||
put:
|
||
tags: [Content]
|
||
summary: 保存 Block 正文
|
||
operationId: saveBlock
|
||
parameters:
|
||
- name: blockId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [content, sourceVersion]
|
||
properties:
|
||
content:
|
||
type: string
|
||
description: Block 正文（ProseMirror JSON）
|
||
sourceVersion:
|
||
type: integer
|
||
description: 客户端持有的版本号，用于乐观锁冲突检测
|
||
responses:
|
||
'200':
|
||
description: 保存成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
newVersion:
|
||
type: integer
|
||
description: 保存后的新版本号
|
||
'409':
|
||
description: 版本冲突，需客户端处理
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '../openapi-base.yaml#/components/schemas/ErrorResponse'
|
||
delete:
|
||
tags: [Content]
|
||
summary: 删除 Block
|
||
operationId: deleteBlock
|
||
parameters:
|
||
- name: blockId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: 删除成功
|
||
|
||
/app-api/content/blocks/{blockId}/split:
|
||
post:
|
||
tags: [Content]
|
||
summary: 分割 Block
|
||
operationId: splitBlock
|
||
parameters:
|
||
- name: blockId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [splitPosition]
|
||
properties:
|
||
splitPosition:
|
||
type: integer
|
||
description: 分割位置（字符偏移量）
|
||
responses:
|
||
'200':
|
||
description: 分割成功，返回两个新 Block
|
||
|
||
/app-api/content/blocks/{blockId}/merge:
|
||
post:
|
||
tags: [Content]
|
||
summary: 合并 Block
|
||
operationId: mergeBlocks
|
||
parameters:
|
||
- name: blockId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
description: 与下一个 Block 合并
|
||
responses:
|
||
'200':
|
||
description: 合并成功
|
||
|
||
# ========== 导出（旧版保留） ==========
|
||
/app-api/content/works/{workId}/export:
|
||
post:
|
||
tags: [Content]
|
||
summary: 导出作品
|
||
operationId: exportWork
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [format]
|
||
properties:
|
||
format:
|
||
type: string
|
||
enum: [txt, epub, docx]
|
||
includeChapters:
|
||
type: array
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
description: 指定导出章节，空数组表示导出全部
|
||
responses:
|
||
'200':
|
||
description: 导出任务已创建，返回任务 ID 供轮询
|
||
'202':
|
||
description: 导出文件二进制流（小文件直接返回）
|
||
|
||
# ================================================================
|
||
# 以下为 Phase 0 新增接口
|
||
# ================================================================
|
||
|
||
# ========== Admin 内容管理 (Section 3.2) ==========
|
||
/admin-api/muse/content/works:
|
||
get:
|
||
tags: [Content-Admin]
|
||
summary: 查询作品列表和治理摘要
|
||
description: |
|
||
管理员查询作品列表，返回治理摘要信息。
|
||
默认不返回用户私有正文全文，确需查看必须另有合规访问设计。
|
||
operationId: adminListWorks
|
||
parameters:
|
||
- $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/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/AdminWorkSummary'
|
||
|
||
/admin-api/muse/content/works/{workId}:
|
||
get:
|
||
tags: [Content-Admin]
|
||
summary: 查看作品元信息、章节摘要、异常摘要
|
||
description: |
|
||
管理员查看作品元信息。默认不返回用户私有正文全文，
|
||
确需查看必须另有合规访问设计、审计和最小化字段。
|
||
operationId: adminGetWork
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: 作品元信息、章节摘要、异常摘要
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/AdminWorkDetail'
|
||
|
||
/admin-api/muse/content/works/{workId}/chapters:
|
||
get:
|
||
tags: [Content-Admin]
|
||
summary: 查看章节列表
|
||
description: 管理员查看作品的章节列表，不含正文全文。
|
||
operationId: adminListChapters
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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'
|
||
|
||
/admin-api/muse/content/import-tasks:
|
||
get:
|
||
tags: [Content-Admin]
|
||
summary: 查询导入任务
|
||
operationId: adminListImportTasks
|
||
parameters:
|
||
- $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: string
|
||
format: uuid
|
||
description: 按作品过滤
|
||
responses:
|
||
'200':
|
||
description: 导入任务列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ImportTaskSummary'
|
||
|
||
/admin-api/muse/content/export-tasks:
|
||
get:
|
||
tags: [Content-Admin]
|
||
summary: 查询导出任务
|
||
operationId: adminListExportTasks
|
||
parameters:
|
||
- $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: string
|
||
format: uuid
|
||
description: 按作品过滤
|
||
responses:
|
||
'200':
|
||
description: 导出任务列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ExportTaskSummary'
|
||
|
||
/admin-api/muse/content/works/{workId}/risk-actions:
|
||
post:
|
||
tags: [Content-Admin]
|
||
summary: 异常内容治理动作
|
||
description: |
|
||
管理员对异常内容执行治理动作。必须带 commandId、操作者、权限点、变更理由和审计字段。
|
||
高危治理进入业务审计。
|
||
operationId: adminRiskAction
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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) ==========
|
||
/app-api/muse/blocks/{blockId}/source-attribution:
|
||
get:
|
||
tags: [Content]
|
||
summary: 查看当前 Block revision 来源归因
|
||
description: |
|
||
返回 Block 当前 revision 的来源归因信息，包含来源对象、来源版本、
|
||
授权快照和许可限制。前端可据此展示内容来源标签和合规提示。
|
||
operationId: getBlockSourceAttribution
|
||
parameters:
|
||
- name: blockId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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 Meta 投影 (Section 4.3) ==========
|
||
/app-api/muse/works/{workId}/meta-projections:
|
||
get:
|
||
tags: [Content-Meta]
|
||
summary: 查询作品维度用户可见 MetaSchema 投影
|
||
description: |
|
||
返回作品维度用户可见的 MetaSchema 投影列表。
|
||
投影不是事实源，只是 MetaSchema、用户权限、来源状态和目标对象版本计算后的 read model。
|
||
operationId: listMetaProjections
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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'
|
||
|
||
/app-api/muse/works/{workId}/meta-projections/{projectionKey}:
|
||
get:
|
||
tags: [Content-Meta]
|
||
summary: 查询指定投影结构、字段数据和版本
|
||
description: |
|
||
返回指定投影的结构、字段数据和版本信息。
|
||
包含 schemaVersion、projectionVersion、dataRevision、sourceSnapshot 和可见字段列表。
|
||
operationId: getMetaProjection
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- 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'
|
||
|
||
/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
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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) ==========
|
||
/app-api/muse/works/{workId}/planning:
|
||
get:
|
||
tags: [Content-Planning]
|
||
summary: 查询当前作品可见规划结构
|
||
description: |
|
||
返回作品可见规划结构、已确认规划数据、revision 和来源摘要。
|
||
规划正式数据由用户确认后进入 content owner；AI 只能产生 Planning Candidate，不直接写正式规划。
|
||
operationId: getPlanning
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: 作品规划结构
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/PlanningStructure'
|
||
|
||
/app-api/muse/works/{workId}/planning/{sectionKey}:
|
||
put:
|
||
tags: [Content-Planning]
|
||
summary: 保存规划项
|
||
description: |
|
||
保存规划项，必须带 commandId 和 expectedRevision。
|
||
涉及 MetaSchema 管控的动态字段写入时，expectedSchemaVersion 和 expectedProjectionVersion 必须校验。
|
||
operationId: savePlanningItem
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- 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: 创建规划候选任务
|
||
description: |
|
||
创建规划候选任务，支持生成、补全、整理和多组选项。
|
||
返回异步任务 ID 供轮询。Planning Candidate 是 Shadow 对象。
|
||
operationId: createPlanningCandidate
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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: 轮询地址
|
||
get:
|
||
tags: [Content-Planning]
|
||
summary: 查询规划候选
|
||
description: 查询待确认、已确认和已丢弃的规划候选列表。
|
||
operationId: listPlanningCandidates
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- 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'
|
||
|
||
/app-api/muse/works/{workId}/planning/candidates/{candidateId}:
|
||
get:
|
||
tags: [Content-Planning]
|
||
summary: 查询候选详情
|
||
description: 返回候选详情、来源、质量结果和 diff。
|
||
operationId: getPlanningCandidate
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: candidateId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: 规划候选详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/PlanningCandidateDetail'
|
||
|
||
/app-api/muse/works/{workId}/planning/candidates/{candidateId}/confirm:
|
||
post:
|
||
tags: [Content-Planning]
|
||
summary: 确认候选进入正式规划
|
||
description: |
|
||
确认候选进入正式规划，必须带 commandId 和 expectedRevision。
|
||
确认时目标 owner 必须重验 work 权限、候选状态、来源状态、授权快照、
|
||
质量结果和目标 revision。确认成功只写正式规划项和业务审计，
|
||
不写正文或 Local KB。
|
||
operationId: confirmPlanningCandidate
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: candidateId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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'
|
||
|
||
/app-api/muse/works/{workId}/planning/candidates/{candidateId}/discard:
|
||
post:
|
||
tags: [Content-Planning]
|
||
summary: 丢弃候选
|
||
description: 丢弃候选，必须带 commandId 和原因。
|
||
operationId: discardPlanningCandidate
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: candidateId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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'
|
||
|
||
/app-api/muse/works/{workId}/planning/style-checks:
|
||
post:
|
||
tags: [Content-Planning]
|
||
summary: 创建文风检查任务
|
||
description: 创建文风检查任务，返回 jobId 供轮询。
|
||
operationId: createStyleCheck
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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
|
||
|
||
/app-api/muse/works/{workId}/planning/style-checks/{jobId}:
|
||
get:
|
||
tags: [Content-Planning]
|
||
summary: 查询文风检查结果
|
||
description: 查询文风检查结果、风险标记和建议入口。
|
||
operationId: getStyleCheckResult
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: jobId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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) ==========
|
||
/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
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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'
|
||
|
||
/app-api/muse/import-tasks/{taskId}:
|
||
get:
|
||
tags: [Content-ImportExport]
|
||
summary: 查询导入任务
|
||
operationId: getImportTask
|
||
parameters:
|
||
- name: taskId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: 导入任务详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/ImportTaskDetail'
|
||
|
||
/app-api/muse/works/{workId}/parse-jobs:
|
||
post:
|
||
tags: [Content-ImportExport]
|
||
summary: 创建 AI 全书解析任务
|
||
description: |
|
||
创建 AI 全书解析任务，读取 Content 导入文件或章节上下文。
|
||
Parse Job 必须绑定 workId、发起人、Content 上下文引用、source snapshot、
|
||
authorization snapshot、解析配置版本、Runtime Permission Envelope 和重试组。
|
||
operationId: createParseJob
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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'
|
||
|
||
/app-api/muse/parse-jobs/{jobId}:
|
||
get:
|
||
tags: [Content-ImportExport]
|
||
summary: 查询 AI 解析任务
|
||
operationId: getParseJob
|
||
parameters:
|
||
- name: jobId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: AI 解析任务详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/ParseJobDetail'
|
||
|
||
/app-api/muse/parse-jobs/{jobId}/retry:
|
||
post:
|
||
tags: [Content-ImportExport]
|
||
summary: 重试解析任务
|
||
description: 重试可重试解析任务或失败阶段。
|
||
operationId: retryParseJob
|
||
parameters:
|
||
- name: jobId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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
|
||
|
||
/app-api/muse/parse-jobs/{jobId}/chapters:
|
||
get:
|
||
tags: [Content-ImportExport]
|
||
summary: AI 章节解析结果
|
||
description: 返回 Parse Job 下所有章节的 AI 解析结果列表。
|
||
operationId: listParseJobChapters
|
||
parameters:
|
||
- name: jobId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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'
|
||
|
||
/app-api/muse/chapter-parse-results/{resultId}/confirm:
|
||
post:
|
||
tags: [Content-ImportExport]
|
||
summary: 章节审阅确认
|
||
description: |
|
||
章节审阅确认，通知 Knowledge 生成或刷新知识草稿。
|
||
章节确认只表示 AI Chapter Parse Result 审阅通过并进入 Knowledge Draft 处理，不写正式知识。
|
||
operationId: confirmChapterParseResult
|
||
parameters:
|
||
- name: resultId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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]
|
||
|
||
/app-api/muse/chapter-parse-results/{resultId}/reject:
|
||
post:
|
||
tags: [Content-ImportExport]
|
||
summary: 章节驳回
|
||
description: |
|
||
章节驳回，记录原因并作废对应 AI Shadow 结果。
|
||
不删除原始导入文件。
|
||
operationId: rejectChapterParseResult
|
||
parameters:
|
||
- name: resultId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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'
|
||
|
||
/app-api/muse/parse-jobs/{jobId}/chapters/batch-confirm:
|
||
post:
|
||
tags: [Content-ImportExport]
|
||
summary: 批量确认章节
|
||
description: |
|
||
批量确认章节，返回逐章成功、失败和部分失败摘要。
|
||
以章节为事务边界，允许部分失败；某章失败不得回滚已成功章节。
|
||
operationId: batchConfirmChapters
|
||
parameters:
|
||
- name: jobId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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'
|
||
|
||
/app-api/muse/works/{workId}/export-tasks:
|
||
post:
|
||
tags: [Content-ImportExport]
|
||
summary: 创建导出任务
|
||
description: |
|
||
创建导出任务，必须带 commandId 幂等键。
|
||
下载凭证必须携带来源传播版本和授权快照。
|
||
operationId: createExportTask
|
||
parameters:
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
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'
|
||
|
||
/app-api/muse/export-tasks/{taskId}:
|
||
get:
|
||
tags: [Content-ImportExport]
|
||
summary: 查询导出任务
|
||
operationId: getExportTask
|
||
parameters:
|
||
- name: taskId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: 导出任务详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/ExportTaskDetail'
|
||
|
||
/app-api/muse/downloads/{credentialId}:
|
||
get:
|
||
tags: [Content-ImportExport]
|
||
summary: 下载导出包
|
||
description: |
|
||
使用下载凭证下载导出包。来源 revoked/recalled/blocked/unauthorized
|
||
或授权过期时返回 SOURCE_BLOCKED、SOURCE_NEEDS_RECHECK 或 PRECHECK_EXPIRED，
|
||
不能继续下载。
|
||
operationId: downloadExportPackage
|
||
parameters:
|
||
- 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:
|
||
schemas:
|
||
# ========== 原有 Schema ==========
|
||
Work:
|
||
type: object
|
||
required: [id, title, status, createdAt, updatedAt]
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
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: string
|
||
format: uuid
|
||
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: string
|
||
format: uuid
|
||
workId:
|
||
type: string
|
||
format: uuid
|
||
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, chapterId, blockType, content, sortOrder, version, createdAt, updatedAt]
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
chapterId:
|
||
type: string
|
||
format: uuid
|
||
blockType:
|
||
type: string
|
||
enum: [scene, section, note]
|
||
title:
|
||
type: string
|
||
content:
|
||
type: string
|
||
description: ProseMirror JSON 格式的正文内容
|
||
sortOrder:
|
||
type: integer
|
||
version:
|
||
type: integer
|
||
description: 乐观锁版本号，每次保存 +1
|
||
wordCount:
|
||
type: integer
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
# ========== Admin 内容管理 Schema ==========
|
||
AdminWorkSummary:
|
||
type: object
|
||
description: 管理员视角的作品列表项，含治理摘要
|
||
required: [id, title, status, ownerId, updatedAt]
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
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: string
|
||
format: uuid
|
||
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: string
|
||
format: uuid
|
||
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]
|
||
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: string
|
||
format: uuid
|
||
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: string
|
||
format: uuid
|
||
workId:
|
||
type: string
|
||
format: uuid
|
||
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: string
|
||
format: uuid
|
||
workId:
|
||
type: string
|
||
format: uuid
|
||
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: string
|
||
format: uuid
|
||
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: string
|
||
format: uuid
|
||
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: 创建规划候选任务请求
|
||
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: 规划候选摘要
|
||
required: [id, sectionKey, status, createdAt]
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
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: 规划候选详情
|
||
required: [id, sectionKey, status, content, revision, createdAt]
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
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: 创建文风检查任务请求
|
||
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: string
|
||
format: uuid
|
||
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: 文风检查结果
|
||
required: [jobId, status]
|
||
properties:
|
||
jobId:
|
||
type: string
|
||
format: uuid
|
||
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: string
|
||
format: uuid
|
||
workId:
|
||
type: string
|
||
format: uuid
|
||
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: 创建 AI 全书解析任务请求
|
||
required: [commandId, importTaskId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
importTaskId:
|
||
type: string
|
||
format: uuid
|
||
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 解析任务详情
|
||
required: [id, workId, status, createdAt]
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
workId:
|
||
type: string
|
||
format: uuid
|
||
importTaskId:
|
||
type: string
|
||
format: uuid
|
||
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 章节解析结果
|
||
required: [id, jobId, title, status, revision]
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
jobId:
|
||
type: string
|
||
format: uuid
|
||
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: 章节审阅确认请求
|
||
required: [commandId, expectedRevision]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
expectedRevision:
|
||
type: integer
|
||
description: 当前 parse result revision
|
||
|
||
RejectChapterParseResultRequest:
|
||
type: object
|
||
description: 章节驳回请求
|
||
required: [commandId, reason]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 驳回原因
|
||
expectedRevision:
|
||
type: integer
|
||
description: 当前 parse result revision
|
||
|
||
BatchConfirmChaptersRequest:
|
||
type: object
|
||
description: 批量确认章节请求
|
||
required: [commandId, resultIds]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
resultIds:
|
||
type: array
|
||
description: 待确认的 chapter parse result ID 列表
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
|
||
BatchConfirmChaptersResult:
|
||
type: object
|
||
description: 批量确认章节结果
|
||
properties:
|
||
confirmedChapterResultIds:
|
||
type: array
|
||
description: 成功确认的章节 result ID 列表
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
createdDraftIds:
|
||
type: array
|
||
description: 生成的知识草稿 ID 列表
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
failedChapters:
|
||
type: array
|
||
description: 失败章节列表
|
||
items:
|
||
type: object
|
||
properties:
|
||
resultId:
|
||
type: string
|
||
format: uuid
|
||
errorCode:
|
||
type: string
|
||
errorMessage:
|
||
type: string
|
||
skippedChapters:
|
||
type: array
|
||
description: 跳过章节列表
|
||
items:
|
||
type: object
|
||
properties:
|
||
resultId:
|
||
type: string
|
||
format: uuid
|
||
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: string
|
||
format: uuid
|
||
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: string
|
||
format: uuid
|
||
workId:
|
||
type: string
|
||
format: uuid
|
||
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
|