oh-my-muse/design-docs/后端-05-统一API契约-v1.md

后端-05：统一 API(接口) 契约-v1

• 版本：v5
• 更新日期：2026-05-13
• 目标读者：前端/后端/架构/测试
• 阅读时间：35-55 分钟
• 边界说明：本文件只定义外部 API(接口)分组、资源语义、关键请求/响应、错误模型与异步交互；底层表结构看 后端-04-统一数据库Schema-v1.md，生命周期与状态跳转看 架构-04-状态机与约束清单.md。本文描述目标 API，不代表当前代码都已实现。

1. 目标

这份 API 只服务一个原则：管理员(Admin)控制系统能力，普通用户(User)控制作品事实；AI 只能产出待审对象，用户显式决策后才会进入 Canonical(规范数据)。

因此 v1 API 明确拆成三组：

• Admin APIs：管理员控制台(Admin Console)接口，管理元数据、Prompt、Agent、全局知识库、访问策略、New-API 用户同步、评测集、用户和系统日志。
• User Workspace APIs：用户工作区(User Workspace)接口，服务我的作品、作品工作台、写作、规划、局域知识库、授权全局知识检索、导入解析、导出交付和生成候选。
• Personal Center APIs：个人中心(Personal Center)接口，服务个人信息、Token 使用、生成记录总览、配额、套餐和授权摘要。

普通用户不能访问 Admin APIs；管理员接口也不能替普通用户确认单个作品的候选、写正文或做作品知识取舍。

2. 通用约定

2.1 Base URL

• Base URL：/api/v1
• 数据格式：application/json; charset=utf-8
• 文件上传：multipart/form-data

2.2 认证与权限

• 认证授权基座：Sa-Token。
• 访问令牌传输方式仍使用 Authorization: Bearer {accessToken}；令牌签发、校验、续期和失效由 Sa-Token 或 Sa-Token 适配层负责。
• refreshToken 只存 HttpOnly + Secure + SameSite=Strict Cookie
• /auth/refresh 不接受 body 里的 refreshToken
• 现有自研 Bearer Token 能力必须逐步收敛为 Sa-Token 适配层，避免认证、权限、当前用户解析在多个地方重复实现。
• Admin APIs 必须校验管理员角色或等价权限。
• User Workspace APIs 必须先校验登录身份，再校验当前用户对作品、章节、文本块、局域知识库和授权全局知识库的访问权限。
• Personal Center APIs 只能访问当前登录用户自己的资源。
• System Job APIs 或后台任务入口必须使用明确服务身份，不得复用普通用户 token 绕过业务确认。
• 前端隐藏菜单或按钮只做体验优化，不是安全边界。

权限错误统一返回：

{
  "code": "FORBIDDEN",
  "message": "Permission denied",
  "details": {
    "required": "admin",
    "resource": "admin.prompts"
  }
}

2.3 异步模式

• 任何需要外部 AI、批处理、索引、导出或评测的操作，默认返回 202 Accepted。
• 响应体必须包含 jobId 或等价任务 ID。
• 前端轮询对应 job 端点获取结果。
• 例外：Accept Suggestion(接受建议)返回 200 OK，因为用户最关心的正文合并必须在本次提交内完成；如果触发重新提取，响应里附带 extractionJob。

2.4 ID 契约

• API 对外暴露的所有业务 ID 都是字符串 ID，格式和生成规则以 后端-04 的自定义字符串 ID 规则为准。
• API 不暴露迁移前的数字 ID 或 UUID。全量 ID 迁移完成后，路由参数、请求体和响应体一次性切到 string id。
• S0-ID 采用停机清库/重建，不提供双写或公开兼容期。
• 基于当前无重要数据的前提，S0-ID 删除现有 schema，重建 schema，重新执行 migration，并重建最小 smoke 数据；原有 ID 不保留、不映射、不进入公开 API 合同。
• 本地、隔离测试库和当前远程开发库默认允许按 S0-ID 口径清理；执行前必须记录环境标识、数据库连接摘要、操作者和清理范围，不要求快照或备份。

2.5 成功 / 错误响应约定

成功响应可以继续使用领域对象包装；错误响应统一为顶层 code / message / details，不再包在 Result<T> 或 error 节点内。

{
  "code": "REVISION_CONFLICT",
  "message": "Block revision mismatch",
  "details": {
    "currentRevision": 5,
    "blockContent": {
      "type": "doc",
      "content": []
    }
  }
}

3. Common APIs

POST /auth/register

注册并登录普通用户。创建用户后的 New-API 同步由后台或 Admin 配置链路处理，注册接口不直接暴露 New-API 细节。

请求体：

{
  "email": "user@example.com",
  "password": "plain-text-password",
  "displayName": "作者名"
}

响应：201 Created，返回 accessToken、expiresIn 和当前用户摘要。

错误：400 VALIDATION_ERROR、409 EMAIL_ALREADY_EXISTS

POST /auth/login

登录。响应结构同 register。

POST /auth/refresh

使用 Cookie 中的 refreshToken 续期。请求体为空。

POST /auth/logout

清除 refresh cookie。响应：204 No Content。

GET /auth/me

返回当前登录用户、角色、权限摘要和默认入口。普通用户默认入口是我的作品(My Works)，管理员可以进入管理员控制台(Admin Console)。

响应至少包含：

{
  "user": {
    "id": "string-id",
    "email": "user@example.com",
    "displayName": "作者名"
  },
  "roles": ["user"],
  "permissions": ["workspace:works:read"],
  "defaultEntry": "my_works"
}

/auth/me 不返回密码哈希、Sa-Token 内部状态、New-API token 或系统 Prompt secret。

4. Admin APIs

Admin APIs 只能由管理员访问。普通用户即使知道 URL，也必须得到 403 FORBIDDEN。

4.1 元数据 APIs

方法	路径	说明
GET	/admin/meta-schemas	查询 MetaSchema 列表，支持 domain、scope、targetType、status
POST	/admin/meta-schemas	创建系统级或模板级 MetaSchema
GET	/admin/meta-schemas/{schemaId}	查询 Schema 详情和字段继承结果
PATCH	/admin/meta-schemas/{schemaId}	更新名称、描述、状态、可见性默认值
POST	/admin/meta-schemas/{schemaId}/fields	新增 MetaField
PATCH	/admin/meta-schemas/{schemaId}/fields/{fieldId}	更新字段、校验和可见性

MetaField 可见性字段：

{
  "fieldKey": "motivation",
  "fieldLabel": "角色动机",
  "fieldType": "text",
  "isRequired": false,
  "uiVisible": true,
  "aiContext": true,
  "userEditable": true,
  "userSearchable": true,
  "exportable": true
}

说明：

• uiVisible=false 不代表不能进入 AI 上下文；是否进入上下文看 aiContext。
• 可见性变更必须触发用户可见投影(User-visible Projection)重建或失效标记。

4.2 Prompt APIs

方法	路径	说明
GET	/admin/prompts	查询 Prompt 列表和 active 版本
POST	/admin/prompts/{promptKey}/versions	创建 prompt_versions 新版本
GET	/admin/prompts/{promptKey}/versions/{version}	查询版本详情
POST	/admin/prompts/{promptKey}/versions/{version}/activate	激活版本
POST	/admin/prompts/{promptKey}/versions/{version}/disable	停用版本
POST	/admin/prompts/{promptKey}/versions/{version}/archive	归档版本

激活响应至少返回：

{
  "promptKey": "generation.default",
  "version": 3,
  "status": "active",
  "activatedAt": "ISO8601"
}

4.3 Agent APIs

方法	路径	说明
GET	/admin/agents	查询 Agent 配置
POST	/admin/agents/{agentKey}/configs	创建 agent_configs 新版本
POST	/admin/agents/{agentKey}/configs/{version}/activate	激活配置
POST	/admin/agents/{agentKey}/configs/{version}/disable	停用配置
POST	/admin/agents/{agentKey}/test	连通性、超时、fallback 校验

Agent 配置只保存 Muse 侧编排策略，不保存模型供应商路由和成本策略。

4.4 全局知识库 APIs

方法	路径	说明
GET	/admin/global-knowledge-bases	查询全局知识库(Global Knowledge Base)
POST	/admin/global-knowledge-bases	创建全局知识库
POST	/admin/global-knowledge-bases/{kbId}/import	导入资料或绑定外部 dataset
POST	/admin/global-knowledge-bases/{kbId}/reindex	重建索引
POST	/admin/global-knowledge-bases/{kbId}/activate	启用版本
POST	/admin/global-knowledge-bases/{kbId}/disable	停用版本

全局知识库停用后，不得进入新的检索或生成上下文；历史记录保留引用来源。

4.5 全局知识访问策略 APIs

方法	路径	说明
GET	/admin/global-knowledge-bases/{kbId}/access-policies	查询访问策略
POST	/admin/global-knowledge-bases/{kbId}/access-policies	创建策略
PATCH	/admin/global-knowledge-access-policies/{policyId}	更新草稿策略
POST	/admin/global-knowledge-access-policies/{policyId}/activate	激活策略
POST	/admin/global-knowledge-access-policies/{policyId}/disable	停用策略

请求体关键字段：

{
  "subjectType": "user_group",
  "subjectId": "vip-authors",
  "defaultBound": true,
  "uiVisible": true,
  "userSearchable": true,
  "aiContext": true,
  "userBindable": false,
  "userUnbindable": false,
  "readonly": true
}

没有 active 策略时，全局知识库不得展示、检索或用于生成。

4.6 New-API 用户同步 APIs

方法	路径	说明
GET	/admin/new-api/user-bindings	查询 newapi_user_bindings
POST	/admin/users/{userId}/new-api/sync	为用户创建或刷新 New-API 绑定
POST	/admin/users/{userId}/new-api/retry	重试失败同步
GET	/admin/new-api/plan-mappings	查询 newapi_plan_mappings
POST	/admin/new-api/plan-mappings	新增 Muse 套餐到 New-API 分组/配额映射
POST	/admin/new-api/plan-mappings/{mappingId}/activate	激活映射

说明：

• 同步必须幂等；失败返回可重试状态和原因。
• New-API 的模型供应商、路由、分组限流、成本策略和消耗日志不迁入 Muse。

4.7 评测集 APIs

方法	路径	说明
GET	/admin/evaluation-datasets	查询评测集(Evaluation Dataset)
POST	/admin/evaluation-datasets	创建固定场景、固定数据集和评分标准
POST	/admin/evaluation-datasets/{datasetId}/activate	激活评测集
POST	/admin/evaluation-datasets/{datasetId}/lock	锁定已用于正式评测的版本
POST	/admin/evaluation-runs	启动评测运行(Evaluation Run)
GET	/admin/evaluation-runs/{runId}	查询评测结果、置信度和风险结论

评测结论用于系统改进，不替代普通用户对正文和作品知识的最终确认。

首批固定评测场景必须覆盖：续写、改写、描写、作品规划、实体一致性、角色一致性、角色弧光、世界事实、大纲一致性、细纲一致性、叙事手法、伏笔与回收、张力曲线、节奏与信息释放、主题表达、文风匹配、全书解析和长程连载。新增评测场景必须绑定固定输入数据、评分标准、模型评审 prompt、聚合算法和版本。

4.8 用户与系统日志 APIs

方法	路径	说明
GET	/admin/users	查询用户
PATCH	/admin/users/{userId}	调整状态或封禁信息
GET	/admin/roles	查询角色
POST	/admin/roles	创建角色
PATCH	/admin/roles/{roleId}	更新角色状态、名称或描述
GET	/admin/permissions	查询权限点
POST	/admin/users/{userId}/roles/{roleId}	给用户分配角色
DELETE	/admin/users/{userId}/roles/{roleId}	移除用户角色
POST	/admin/roles/{roleId}/permissions/{permissionId}	给角色分配权限
DELETE	/admin/roles/{roleId}/permissions/{permissionId}	移除角色权限
GET	/admin/system-service-identities	查询系统任务服务身份
POST	/admin/system-service-identities	创建或登记服务身份
PATCH	/admin/system-service-identities/{serviceIdentityId}	启停或调整服务身份权限范围
GET	/admin/system-logs	查询系统日志、任务失败、同步失败
GET	/admin/audit-logs	查询审计记录

系统日志不得返回正文全文、密钥、New-API token 或 Prompt secret。

管理员调整角色和权限只改变接口和后台能力边界，不替用户确认单作品正文、规划项、知识草稿或 AI 候选。

5. User Workspace APIs

User Workspace APIs 服务普通用户作品流程。所有接口都必须校验当前用户对 workId 的访问权限。

5.1 Works

方法	路径	说明
GET	/works	获取当前用户作品列表，支持搜索、筛选、排序、分页
POST	/works	创建作品
GET	/works/{workId}	获取作品详情、导入解析摘要和待确认数量
PATCH	/works/{workId}	修改标题、简介、状态、作品模板
DELETE	/works/{workId}	删除作品及下游数据

GET /works 响应项至少包含：

{
  "id": "string-id",
  "title": "string",
  "status": "writing",
  "wordCount": 45200,
  "chapterCount": 12,
  "parseStatus": "parsed",
  "pendingSuggestionCount": 2,
  "pendingKnowledgeDraftCount": 5,
  "updatedAt": "ISO8601"
}

禁止通过作品接口修改 importedAt、parseStatus、parseProgress、parsedAt 等系统字段。

5.2 Chapters / Blocks

方法	路径	说明
GET	/works/{workId}/chapters	返回作品章节树
POST	/works/{workId}/chapters	创建章节
PATCH	/works/{workId}/chapters/{chapterId}	更新章节标题、摘要、排序
DELETE	/works/{workId}/chapters/{chapterId}	删除章节与下属 Block
GET	/chapters/{chapterId}/blocks	基于 orderIndex 的 cursor 分页
POST	/chapters/{chapterId}/blocks	创建 Block
PUT	/blocks/{blockId}	更新 Block，必须带 expectedRevision
DELETE	/blocks/{blockId}	删除 Block

PUT /blocks/{blockId} 请求体：

{
  "content": {
    "type": "doc",
    "content": []
  },
  "expectedRevision": 3
}

错误：400 EXPECTED_REVISION_MISSING、409 REVISION_CONFLICT

5.3 作品规划 APIs

作品规划台(Planning Desk)面向作品设定、章节大纲、世界设定、角色关系和文风检查。底层优先复用 MetaSchema、narrative_states、knowledge_entities、knowledge_relations、Work、Chapter 和 Block，不为每个 UI 面板建独立事实源。

方法	路径	说明
GET	/works/{workId}/planning	获取当前作品可见规划结构和已确认规划数据
PUT	/works/{workId}/planning/{sectionKey}	保存用户确认后的规划项
POST	/works/{workId}/planning/{sectionKey}/ai-generate	AI 生成、补全、整理、检查或给多组选项
GET	/works/{workId}/planning-candidates	获取待确认规划候选
POST	/works/{workId}/planning-candidates/{candidateId}/accept	确认规划候选
POST	/works/{workId}/planning-candidates/{candidateId}/reject	丢弃规划候选

AI 规划候选仍进入 Shadow(待审层)，确认后才成为后续生成上下文。产品语言可以使用“情节节拍 / 场景推进”，API 不引入独立 Scene 资源。

5.4 AI Generation / Suggestions

方法	路径	说明
POST	/ai/generate	触发续写、改写、描写、检查或规划候选生成
GET	/ai/generation-jobs/{jobId}	轮询生成任务
GET	/works/{workId}/suggestions	获取待审 Suggestion 列表
GET	/works/{workId}/suggestions/{suggestionId}	获取单条待审 Suggestion
POST	/works/{workId}/suggestions/{suggestionId}/accept	接受 Suggestion
POST	/works/{workId}/suggestions/{suggestionId}/reject	丢弃当前建议

POST /ai/generate 请求体：

{
  "workId": "string-id",
  "targetBlockId": "string-id | null",
  "suggestionType": "continuation",
  "requestSource": "writing_desk",
  "contextBlockIds": ["string-id"]
}

POST /works/{workId}/suggestions/{suggestionId}/accept 语义：

1. 校验 Suggestion 仍存在且未过期。
2. 用 expectedRevision 更新目标 Block。
3. 把 Suggestion 迁入 Archive。
4. 原样接受时，可在主事务内确认关联且未 stale 的 Knowledge Draft，并写 outbox。
5. 修改后合并时，旧 Draft 立即作废；事务提交后重新提取。

响应：

{
  "block": {
    "id": "string-id",
    "revision": 4,
    "content": {
      "type": "doc",
      "content": []
    }
  },
  "suggestion": {
    "id": "string-id",
    "disposition": "accepted",
    "archivedAt": "ISO8601"
  },
  "extractionJob": {
    "id": "string-id",
    "status": "queued"
  }
}

extractionJob 只在修改后合并触发重新提取时返回；原样接受场景可以为 null。

5.5 NER Preview

方法	路径	说明
POST	/ai/ner	命名实体识别(NER)预览，只返回高亮结果，不写数据库

/ai/ner 不写 Shadow，不生成 Proposal，不进入正式检索。

5.6 Knowledge Draft / Extraction

方法	路径	说明
GET	/works/{workId}/extraction-jobs/{jobId}	轮询提取任务
GET	/works/{workId}/proposals	获取待确认 Knowledge Draft / Proposal
GET	/works/{workId}/proposals/{proposalId}	获取草稿详情和 diff
POST	/works/{workId}/proposals/{proposalId}/accept	单条确认，写入正式作品知识
POST	/works/{workId}/proposals/{proposalId}/reject	忽略或丢弃草稿

确认前必须校验来源快照(Source Snapshot)。来源失效或缺失返回 409 STALE_SOURCE_SNAPSHOT；缺 Source Snapshot 的历史 Draft 在本轮基线下必须作废并重新提取。

5.7 导入解析 APIs

方法	路径	说明
POST	/works/{workId}/import	导入正文，直接写 Canonical 正文
POST	/works/{workId}/parse	对已导入正文触发全书解析
GET	/works/{workId}/parse-progress	查询解析进度
GET	/works/{workId}/parse-jobs/{parseJobId}/chapters	章节级汇总
GET	/works/{workId}/parse-jobs/{parseJobId}/chapters/{chapterId}/proposals	指定章节待确认详情
POST	/works/{workId}/parse-jobs/{parseJobId}/chapters/{chapterId}/confirm	章节级确认
POST	/works/{workId}/parse-jobs/{parseJobId}/chapters/{chapterId}/reject	章节级驳回

章节确认边界固定为 parse_job_id + chapter_id，并且同章节 all-or-nothing。批量选择和“一键确认全部可确认章节”必须拆成章节级提交；后端按章节逐个事务循环执行，某章失败不回滚已成功章节，也不阻塞后续可确认章节，不能变成跨章节不可解释写入。

5.8 局域知识库 APIs

方法	路径	说明
GET	/works/{workId}/knowledge/projection	获取用户可见投影
GET	/works/{workId}/entities	查询当前作品正式实体
POST	/works/{workId}/entities	手动创建实体
GET	/works/{workId}/entities/{entityId}	查询实体快照、关系和变更
PATCH	/works/{workId}/entities/{entityId}	手动更新实体属性
DELETE	/works/{workId}/entities/{entityId}	删除实体与下游关系
GET	/works/{workId}/relations	查询关系
POST	/works/{workId}/entities/search	在当前作品局域知识库中检索

用户可见投影只展示元数据允许展示、编辑、检索和导出的实体、关系、字段和摘要。投影不是事实源。

5.9 全局知识库授权检索 APIs

方法	路径	说明
GET	/works/{workId}/authorized-global-knowledge-bases	查询当前作品/用户可见的授权全局知识库
POST	/works/{workId}/global-knowledge/search	检索被授权全局资料

全局知识库是独立逻辑资料集。检索前必须根据当前用户、作品、套餐和访问策略计算允许使用的 globalKbIds；请求不得包含未授权或已撤销的全局知识库 ID。如果多个全局知识库共用同一个物理索引或数据库，检索条件必须包含 global_kb_id IN allowedIds 或等价过滤条件。异步重建索引不能作为权限边界。

检索响应必须标明来源：

{
  "results": [
    {
      "sourceType": "global_knowledge_base",
      "globalKnowledgeBaseId": "string-id",
      "title": "平台规范摘要",
      "snippet": "string",
      "usableForGeneration": true
    }
  ]
}

全局知识库参与生成不等于成为作品正式知识。

5.10 导出交付 APIs

方法	路径	说明
POST	/works/{workId}/exports	创建导出任务
GET	/works/{workId}/exports/{exportJobId}	查询导出状态和下载信息

导出只读取已确认内容、用户有权访问且 exportable=true 的投影或正式数据。

5.11 作品记录与用量 APIs

方法	路径	说明
GET	/works/{workId}/generation-records	查询单作品生成历史和候选历史
GET	/works/{workId}/tasks	查询单作品任务历史、失败原因和可恢复动作
GET	/works/{workId}/usage	查询单作品 Token 使用和成本提示摘要

Token 消耗明细和成本账本以 New-API 为准；Muse 不提供 usage_logs 本地明细或本地汇总表查询，只返回用户可理解的 New-API 汇总、任务级 usage 摘要、引用或同步结果。

6. Personal Center APIs

Personal Center APIs 只能访问当前登录用户自己的信息，不承载单作品深层创作和管理员配置。

方法	路径	说明
GET	/me	当前用户个人信息
PATCH	/me	更新显示名、偏好等个人信息
GET	/me/usage	Token 使用、配额、套餐摘要
GET	/me/generation-records	跨作品生成记录总览
GET	/me/new-api-binding	当前用户 New-API 绑定状态摘要
GET	/me/authorized-global-knowledge-bases	当前用户可见或可用的全局知识库授权摘要

GET /me/usage 响应示例：

{
  "quota": {
    "planKey": "pro",
    "period": "2026-05",
    "remainingTokens": 120000
  },
  "usageSummary": {
    "totalTokens": 380000,
    "generationCount": 142
  },
  "source": "new-api-summary"
}

7. 分页与轮询

7.1 分页

场景	策略
作品、实体、Proposal、Admin 列表	Offset-based(偏移分页)
Block 列表	Cursor-based(游标分页)，按 orderIndex
Suggestion 列表	默认按 createdAt DESC，不做深分页
日志、生成记录、任务记录	Cursor-based，按 createdAt DESC

7.2 轮询

作业	轮询端点	默认间隔
生成	GET /ai/generation-jobs/{jobId}	2 秒
提取	GET /works/{workId}/extraction-jobs/{jobId}	2 秒
导入解析	GET /works/{workId}/parse-progress	2 秒
导出	GET /works/{workId}/exports/{exportJobId}	2 秒
评测	GET /admin/evaluation-runs/{runId}	5 秒

8. 错误码

Code	HTTP	说明
VALIDATION_ERROR	400	参数错误
MISSING_REQUIRED_FIELD	400	缺少必填字段
EXPECTED_REVISION_MISSING	400	缺少 expectedRevision
UNAUTHORIZED	401	未认证
TOKEN_EXPIRED	401	access token 过期
FORBIDDEN	403	无权限；普通用户访问管理员接口也返回此错误
ADMIN_ONLY	403	需要管理员权限
SYSTEM_JOB_ONLY	403	需要系统任务服务身份
WORK_ACCESS_DENIED	403	无权访问该作品
BUILTIN_SCHEMA_IMMUTABLE	403	内置 Schema 不可修改
NOT_FOUND	404	资源不存在
SUGGESTION_NOT_FOUND	404	Suggestion 不存在
SUGGESTION_EXPIRED	404	Suggestion 已过期
PROPOSAL_NOT_FOUND	404	Proposal 不存在
PROPOSAL_EXPIRED	404	Proposal 已过期
WORK_ALREADY_IMPORTED	409	已导入，禁止再次导入
ORDER_INDEX_CONFLICT	409	排序冲突
REVISION_CONFLICT	409	Block revision 不匹配
ENTITY_NAME_CONFLICT	409	同类型同名实体冲突
STALE_SOURCE_SNAPSHOT	409	来源快照已失效
CHAPTER_BATCH_STALE	409	章节批量确认存在过期草稿
CHAPTER_BATCH_CONFLICT	409	章节批量确认存在冲突
GLOBAL_KB_NOT_AUTHORIZED	403	无权访问全局知识库
NEW_API_SYNC_FAILED	502	New-API 同步失败
RATE_LIMITED	429	限流
LLM_UNAVAILABLE	502	外部模型不可用
INTERNAL_ERROR	500	服务器内部错误

9. 非目标

v1 不做：

• Webhook。
• 多人协同写作冲突协商。
• 前端离线同步协议。
• 普通用户直接访问 Prompt、Agent、Pipeline 或系统日志。
• 引入 Yudao / RuoYi 的完整后台系统。
• 引入多租户、工作流、商城、支付、CRM 等通用平台能力。
• Muse 复制 New-API 的模型供应商、路由、成本策略和消耗日志作为新的权威来源。
• 把小说场景(Scene)作为独立一级 API 资源；近程叙事控制归入章节叙事规划。
• 让 Sa-Token 直接决定作品正文、知识草稿、AI 候选是否进入 Canonical(规范数据)。

10. 关联阅读

• 表结构：后端-04-统一数据库Schema-v1.md
• 生命周期与状态机：架构-04-状态机与约束清单.md
• 双轨模型：架构-02-核心数据结构与双轨模型.md
• 模块职责：后端-02-工程结构与模块职责.md