From 9af4d15706bd25f2d7db09d2db46a93d52cd8f58 Mon Sep 17 00:00:00 2001 From: zizi Date: Sun, 24 May 2026 14:31:55 +0800 Subject: [PATCH] =?UTF-8?q?feat(api):=20=E8=A1=A5=E9=BD=90=20Content=20?= =?UTF-8?q?=E6=A8=A1=E5=9D=97=E5=85=A8=E9=87=8F=E6=8E=A5=E5=8F=A3=EF=BC=88?= =?UTF-8?q?admin+=E8=A7=84=E5=88=92+=E5=AF=BC=E5=85=A5=E5=AF=BC=E5=87=BA+?= =?UTF-8?q?=E6=9D=A5=E6=BA=90=E5=BD=92=E5=9B=A0=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api-contracts/content/openapi.yaml | 2374 ++++++++++++++++++++++- 1 file changed, 2372 insertions(+), 2 deletions(-) diff --git a/docs/api-contracts/content/openapi.yaml b/docs/api-contracts/content/openapi.yaml index cf3cf581..70c95d99 100644 --- a/docs/api-contracts/content/openapi.yaml +++ b/docs/api-contracts/content/openapi.yaml @@ -512,7 +512,7 @@ paths: '200': description: 合并成功 - # ========== 导出 ========== + # ========== 导出（旧版保留） ========== /app-api/content/works/{workId}/export: post: tags: [Content] @@ -548,8 +548,1076 @@ paths: '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] @@ -672,4 +1740,1306 @@ components: format: date-time updatedAt: type: string - format: date-time \ No newline at end of file + 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