docs(spec): 制定 muse-cloud P1R 真实 API 规格

docs/superpowers/specs/2026-05-25-P1R-muse-cloud-real-api-design.md

@@ -0,0 +1,438 @@
+# P1R：muse-cloud 真实业务 API 完成规格
+
+- 版本：v1
+- 日期：2026-05-25
+- 状态：待用户复核
+- 目标读者：后端执行代理 / 主代理 / 架构评审 / 验收人员
+- 范围：`muse-cloud/`
+- 非范围：`muse-admin/`、`muse-studio/`、`docs/api-contracts/**` 合同修改、Yudao 基座重构
+
+## 1. 背景
+
+原 P1 计划目标是在 `muse-cloud/` 这个 Yudao Cloud fork 上完成 Muse 后端业务模块，覆盖 `docs/api-contracts/**/openapi.yaml` 中的全量 Muse API。
+
+当前 P1 已完成后端可调用基线：DDL、模块入口、Content 核心 API、统一合同路由、幂等审计和部分写命令持久化。但这仍不足以称为真实业务 API 完成，因为 Meta / Knowledge / Market / AI / Account 等模块仍大量依赖合同兜底入口和通用持久化服务，很多接口没有领域 Application Service、Domain 状态机、OpenAPI DTO 组装和真实外部闭环。
+
+P1R 的目标是纠正这个偏差：P1 不再以“接口能被调用”作为完成标准，而以“全量 API 有真实业务行为、真实外部闭环、真实验收证据”作为完成标准。
+
+## 2. 目标
+
+1. 覆盖 `docs/api-contracts/**/openapi.yaml` 中属于 P1 的全部 Muse API。
+2. 每个 API 都必须有真实 Controller / Application Service / Domain 规则 / Persistence / 测试。
+3. 写命令必须真实推进领域事实、状态机、审计、幂等和外部副作用。
+4. 读接口必须返回对应领域读模型 DTO，不允许返回通用 operation record、workflow task 原始行或占位 JSON。
+5. AI、知识解析、导入导出、市场安装绑定、New-API / RAGFlow / 文件服务等外部链路必须跑通真实闭环。
+6. 遇到外部依赖、环境、认证、数据、测试阻塞时，目标是解决阻塞，不是降级为 mock、跳过或伪成功。
+7. 总 spec 只定义共同架构、真实 API 标准、外部服务硬依赖、验收门禁和阶段拆分原则；每个领域的详细实现再通过后续阶段 spec + plan 承接。
+
+## 3. 非目标
+
+1. 不修改 `muse-admin/`、`muse-studio/`。
+2. 不重构 Yudao 基座，不删除保留模块。
+3. 不借 P1R 顺手修改 API 合同。若发现合同与设计 SSOT 冲突，必须单独提出合同变更并先获得确认。
+4. 不用 catch-all shim 扩大完成口径。`MuseApiContractSupport` 和 `MuseContractPersistenceService` 只能作为迁移中间态或未完成保护网，不能作为最终业务实现。
+5. 不用本地替身、controller mock、内存 Map、固定样例数据替代真实外部服务闭环。
+6. 不把前端可见性、按钮隐藏或路由限制当作权限、安全、状态机和功能 gate 的可信边界。
+
+## 4. 当前事实基线
+
+### 4.1 已完成基线
+
+1. `muse-cloud/` 已纳入主仓管理，并完成 P1 后端基础提交。
+2. `muse-cloud/sql/muse/` 已有 V1-V8 Muse 业务 DDL。
+3. Content 核心作品、章节、Block API 已有专用 `ContentAppService`。
+4. Meta / Knowledge / Market / AI / Account 合同入口已从纯占位响应推进到通用持久化层。
+5. 全量 `mvn test` 曾在 P1 收口时通过。
+6. 远端 PG15 已验证可执行 V1-V8；用户已允许以 PG15 推进，不再因 PG16 未就绪阻塞当前进度。
+
+### 4.2 仍未完成的事实
+
+1. 多数非 Content API 仍不是领域 Application Service，而是合同兜底入口。
+2. 多数读接口还不是 OpenAPI DTO 对应的读模型。
+3. Content 扩展 API 如规划、导入、解析、导出、MetaProjection、SuggestionMerge 仍缺专用业务实现。
+4. `muse_domain_workflow_task` 当前只表示任务事实，不等于真实异步执行器、外部副作用和终态闭环。
+5. New-API、RAGFlow、文件服务、导出器、SSE 等真实外部闭环还没有形成全量验收证据。
+6. 原计划中的 Domain 覆盖率、Application 集成测试、ArchUnit、Checkstyle / SpotBugs 等门禁没有完整验收证据。
+
+## 5. 真实 API 标准
+
+P1R 中，一个 API 只有同时满足以下条件，才能标记为完成。
+
+### 5.1 入口标准
+
+1. 每个 OpenAPI operation 有明确 Controller 方法或明确路由映射。
+2. 所有 Muse API 支持并校验 `X-API-Version: 1`。
+3. 响应统一为 Yudao `CommonResult<T>` 形态，对外 JSON 字段为 `code/data/msg`。
+4. 不得返回 `message` 替代 `msg`。
+5. Controller 只做鉴权入口、参数校验、版本头检查、DTO 转换和统一响应，不拼业务规则。
+
+### 5.2 DTO 标准
+
+1. 请求和响应必须使用领域 DTO / VO / assembler。
+2. 读接口必须返回 OpenAPI 合同对应的业务读模型。
+3. 禁止用 `Map<String, Object>`、operation record 原始行、workflow task 原始行、`persisted: true`、`status: accepted` 这类通用结构替代合同 DTO。
+4. 异步任务创建接口可以返回任务摘要，但任务必须能通过后续查询接口进入真实成功、失败、取消或超时终态。
+
+### 5.3 领域 owner 标准
+
+1. 业务事实只能由所属领域模块写入。
+2. `admin-api` 和 `app-api` 只是入口差异，不能形成两套事实。
+3. 跨模块读取必须通过 facade、Application Service、事件投影或读模型，不能直接绕过 owner 写其他模块表。
+4. Market 只负责资产、授权、安装记录、发布申请、申诉、来源侧授权摘要、handoff token 和跳转审计；目标绑定事实必须由目标 owner API 消费授权后写入。
+5. Account 负责个人资料、权益、配额、用量、购买/授权/发布记录聚合和 New-API 调用归因；不得允许请求体任意伪造归因事实。
+6. Meta 负责 MetaSchema、保护节点和功能链治理；保护节点不能被降级为用户可替换槽位。
+
+### 5.4 写命令标准
+
+1. 所有写命令必须有 `commandId` 或合同指定的等价幂等键。
+2. 重复请求必须返回同一业务结果，不重复扣费、不重复安装、不重复发布、不重复外部调用。
+3. 覆盖事实的写命令必须校验 revision / expectedVersion / expectedStatus / expectedActiveVersion。
+4. 所有写命令必须记录审计字段：操作者、入口、请求摘要、业务目标、状态变化、时间、结果。
+5. 写命令不能只落 operation record；必须真实改变领域事实，或创建真实可执行任务并最终进入业务终态。
+
+### 5.5 状态机标准
+
+1. 状态变化必须由领域服务推进。
+2. 状态机前置条件必须在后端强制校验。
+3. 非法状态转移必须返回明确错误码。
+4. 状态字段不能只作为可任意更新的字符串。
+5. 状态机测试必须覆盖成功路径、重复命令、并发冲突、非法转移、外部失败恢复。
+
+### 5.6 安全标准
+
+1. 后端强制登录态、RBAC、owner 校验、tenant 隔离、来源授权和高危动作权限。
+2. 前端隐藏入口不是安全边界。
+3. 敏感操作必须审计；高危治理必须包含 reason、影响预览或校验引用、期望状态或版本。
+4. 用户数据查询必须带 owner 和 tenant 约束。
+5. 外部 URL、导入文件和下载凭证必须有服务端安全校验，包含私网地址阻断、文件大小限制、类型限制、病毒或内容扫描接入点、凭证过期和访问审计。
+
+## 6. 明确禁止事项
+
+1. 禁止用 `MuseApiContractSupport.handle(...)` 的占位结果作为完成。
+2. 禁止用 `MuseContractPersistenceService` 的通用持久化响应替代领域服务。
+3. 禁止将仍由 catch-all 合同入口处理的 operation 标记为完成。
+4. 禁止 controller 层 mock、内存 Map、固定样例数据、伪造外部服务成功。
+5. 禁止只在前端实现权限、状态机或功能 gate。
+6. 禁止为了通过测试跳过安全、审计、幂等、外部服务调用。
+7. 禁止用空列表、accepted task、operation record、通用 JSON 行作为真实读模型完成证据。
+8. 禁止未验证就声明 P1R 完成。
+
+catch-all 入口可以临时保留为 404 / 501 保护网，但不能计入任何 operation 的完成范围。
+
+## 7. 目标架构
+
+```mermaid
+flowchart TD
+    C[Controller] --> A[Application Service]
+    A --> D[Domain Service / Aggregate]
+    A --> Q[Query Service / Assembler]
+    A --> O[Outbox / Job Service]
+    D --> P[Persistence Mapper]
+    O --> E[External Adapter]
+    E --> N[New-API]
+    E --> R[RAGFlow / Knowledge Engine]
+    E --> F[File / Object Storage]
+    E --> S[SSE Event Stream]
+    Q --> V[OpenAPI DTO]
+```
+
+### 7.1 Controller
+
+Controller 只负责入口转换：鉴权、参数校验、`X-API-Version` 校验、请求 DTO、响应封装。Controller 不直接访问数据库，不直接拼业务 JSON，不直接调用外部服务。
+
+### 7.2 Application Service
+
+Application Service 是用例和事务边界。它负责幂等、权限摘要、跨模块 facade、任务创建、外部调用编排、outbox 发布、错误归一和最终响应组装。
+
+### 7.3 Domain
+
+Domain 持有聚合状态机、不变式、版本冲突判断、授权快照消费规则和状态变化决策。Domain 不依赖 Controller、Yudao Web DTO 或外部 API DTO。
+
+### 7.4 Infrastructure
+
+Infrastructure 负责 MyBatis Mapper、Redis、文件服务、New-API client、RAGFlow client、SSE 推送、任务执行器和审计持久化。外部 client 必须暴露超时、错误分类、重试和补偿语义。
+
+### 7.5 Query Service / Assembler
+
+Query Service 负责读模型查询和 DTO 组装。读接口不能由 Controller 直接拼 JSON，也不能把数据库表行原样暴露给前端。
+
+## 8. 外部服务硬依赖
+
+P1R 的外部服务是验收硬门槛，不允许因为复杂而降级为 mock。
+
+| 依赖 | P1R 必须证明的真实能力 |
+|------|------------------------|
+| PostgreSQL | 真实持久化、事务、唯一约束、幂等、状态查询、DDL/Flyway 可执行 |
+| Redis | 幂等辅助、短期锁、SSE/job 状态缓存、限流或任务协调中实际需要的部分 |
+| New-API | AI 调用、调用归因、成本/用量回查、绑定重验 |
+| RAGFlow / 知识引擎 | 文档入库、切片、索引、检索、GraphRAG 或项目确认的图查询能力 |
+| 文件/对象存储 | 导入文件、解析原件、导出产物、下载凭证 |
+| SSE | AI stream、任务事件和统一事件流真实推送 |
+| Yudao 基础能力 | 登录、RBAC、租户、审计、文件、任务、权限菜单 |
+
+## 9. 阻塞处理规则
+
+1. 连接失败、认证失败、版本不符、缺容器、缺账号、缺配置，必须先诊断 root cause。
+2. 能通过服务器 Docker 补齐基础设施的，补齐并记录命令。
+3. 能通过现有远端环境解决的，优先复用远端环境，但必须验证版本、权限、数据隔离和清理策略。
+4. 缺凭据时，只说明需要哪个服务、哪个账号、哪类权限，不输出已有密钥。
+5. 外部服务暂不可用时，相关 API 不能标为完成，只能标为 blocked，并列出下一步验证命令。
+6. 测试可以构造测试数据，但不能绕过真实 adapter。
+7. 测试失败要修服务、配置或代码，不能以跳过测试收尾。
+8. 对不可逆或高危环境操作，如清库、重置远端服务、删除索引，必须先单独确认。
+
+## 10. 阶段拆分
+
+P1R 采用“总 spec + 阶段 spec + 阶段 plan”的执行模型。总 spec 定义硬标准，后续每个阶段必须单独补充领域 spec 和实现计划。
+
+### P1R-0 Baseline Gate
+
+目标：清点全部 operation，建立 API 完成矩阵。
+
+输出：
+
+1. operation 清单，来源为 `docs/api-contracts/**/openapi.yaml`。
+2. 每个 operation 标注 owner、side、HTTP method、路径、是否写命令、是否外部依赖、是否异步。
+3. 每个 operation 标注当前实现状态：真实实现、catch-all、通用持久化、缺实现、阻塞。
+4. 每个 operation 标注目标阶段和验收证据。
+
+### P1R-1 Content Real API
+
+目标：补齐 Content 真实业务 API。
+
+范围：
+
+1. 作品、章节、Block 核心能力回归到 OpenAPI DTO。
+2. 规划、候选、导入解析、导出、动态字段校验、来源归因、Suggestion Merge。
+3. 管理端 content read、risk action、导入导出任务治理。
+
+外部闭环：
+
+1. 文件导入产生真实文件和解析任务。
+2. 导出产生真实产物和下载凭证。
+3. Suggestion Merge 与 AI suggestion、知识草稿、来源归因形成真实链路。
+
+### P1R-2 Meta Real API
+
+目标：实现 MetaSchema 和治理真实 API。
+
+范围：
+
+1. MetaSchema 列表、详情、版本、草稿。
+2. 验证、影响预览、发布、激活、回滚、废弃、灰度规则。
+3. 保护节点和功能链治理。
+
+关键要求：
+
+1. 版本激活必须有唯一 active 约束。
+2. 高危治理必须有 validationResultId、impactPreviewId、reason、expectedVersion 或 expectedActiveVersion。
+3. 保护节点不可被用户替换槽位覆盖。
+
+### P1R-3 Account Real API
+
+目标：实现账户、权益、配额、用量和归因真实 API。
+
+范围：
+
+1. 当前用户、资料、权益、配额、余额快照。
+2. New-API 绑定、绑定重验、调用归因 job、correlation 查询。
+3. 用量、购买记录、授权记录、发布记录、安全事件、导出下载。
+
+外部闭环：
+
+1. New-API 调用产生真实 correlation/call 记录。
+2. Account 归因接口基于真实调用记录校验 user/work/asset/license。
+3. 导出任务生成真实下载凭证。
+
+### P1R-4 AI Real API
+
+目标：实现 AI 编排、任务、智能体和质量治理真实 API。
+
+范围：
+
+1. Prompt、Agent、Tool Grant、Quality Policy。
+2. AI task/job、source event、agent slot、suggestion。
+3. API 访问日志和业务审计。
+
+外部闭环：
+
+1. AI task 调用真实 New-API。
+2. SSE 能推送真实任务事件或流式结果。
+3. 任务支持成功、失败、取消、重试。
+4. runtime 不能自授权，grant/runtime 包隔离由 ArchUnit 验证。
+
+### P1R-5 Knowledge Real API
+
+目标：实现全局知识库、用户知识库、局域知识和 RAG 检索真实 API。
+
+范围：
+
+1. 全局知识库、用户知识库、文档版本、访问策略。
+2. 文档上传、链接抓取、解析、切片、索引、重建。
+3. 实体、关系、知识图谱、知识草稿、绑定预检、发布快照、安装知识库。
+
+外部闭环：
+
+1. 文档能进入 RAGFlow / 知识引擎。
+2. 检索结果能回到 Knowledge API。
+3. 知识草稿确认能真实写入 Canonical 事实。
+4. Market 安装的知识库只能通过授权快照消费。
+
+### P1R-6 Market Real API
+
+目标：实现市场资产、交易、安装、handoff 和治理真实 API。
+
+范围：
+
+1. 资产、分类、推荐、详情、收藏。
+2. 购买、安装、bind-precheck、handoff 查询/取消。
+3. 发布草稿、发布检查、发布申请、撤回。
+4. 管理端审核、驳回、下架、召回、申诉处理。
+
+外部闭环：
+
+1. 购买和安装必须写授权、安装记录和账户聚合。
+2. Handoff 只能产生来源授权摘要和 token，目标 owner 必须重新生成并消费目标 precheck。
+3. 作品资产高阶模式默认关闭，未完成 ADR、Schema/API、来源 lineage 和授权快照前不能开放。
+
+### P1R-7 End-to-End Acceptance
+
+目标：在真实环境中证明全量 P1R 业务闭环。
+
+验收链路：
+
+1. 应用连接真实 PG/Redis 启动。
+2. 用户创建作品、章节、Block，保存正文并生成来源归因。
+3. 用户创建 AI task，真实调用 New-API，SSE 或轮询得到终态。
+4. AI suggestion 被接受或拒绝，正文和审计事实一致。
+5. 文档上传到知识库，RAGFlow / 知识引擎完成索引和检索。
+6. 知识草稿确认后写入 Canonical 知识事实。
+7. 市场发布、审核、购买、安装、handoff、目标绑定形成跨领域闭环。
+8. Account 能查询真实用量、授权、购买、发布、导出和安全事件。
+9. 管理端治理动作能改变状态并留下审计。
+
+## 11. 验收门禁
+
+### 11.1 API 覆盖门禁
+
+从 `docs/api-contracts/**/openapi.yaml` 生成 operation 清单。每个 operation 必须有：
+
+1. owner module。
+2. Controller 方法。
+3. Application Service 方法。
+4. Domain 规则或状态机说明。
+5. 持久化表、读模型或外部服务。
+6. 单元测试、集成测试、API 契约测试。
+7. 真实环境验收记录。
+
+### 11.2 Catch-all 清零门禁
+
+任何仍由 `MuseApiContractSupport.handle(...)` 或通用 `MuseContractPersistenceService` 处理的 operation，不能标记完成。
+
+### 11.3 响应合同门禁
+
+1. 所有接口统一 `code/data/msg`。
+2. 响应 DTO 与 OpenAPI 匹配。
+3. 分页统一使用项目现有分页结构或合同明确结构。
+4. 错误码必须可追踪到领域模块。
+
+### 11.4 写命令门禁
+
+1. 所有写命令校验 `commandId`。
+2. 所有覆盖事实的写命令校验 revision / expectedVersion / expectedStatus。
+3. 重复命令返回同一业务结果。
+4. 所有写命令落审计。
+5. 外部副作用必须有真实调用记录、状态和失败恢复路径。
+
+### 11.5 外部闭环门禁
+
+1. New-API 调用能产生可查询的真实 correlation/call 记录，并被 Account 归因接口校验。
+2. RAGFlow / 知识引擎能完成文档入库、索引、检索，并驱动 Knowledge API 状态变化。
+3. 文件导入、导出和下载凭证能产生真实文件或对象。
+4. AI task 能从创建、执行、流式或轮询查看，到完成、失败或取消形成闭环。
+5. 市场购买、安装、handoff、绑定能跨 Market、AI、Knowledge、Content owner 完成真实授权消费。
+
+### 11.6 测试门禁
+
+1. Domain 层单元测试覆盖状态机、不变式、冲突和非法转移。
+2. Application 层集成测试覆盖事务、幂等、审计、外部调用和失败恢复。
+3. API 契约测试覆盖请求响应、错误码、权限和版本头。
+4. 真实环境冒烟测试覆盖 P1R-7 验收链路。
+5. 若全量 `mvn test` 被非 P1 模块阻断，必须定位并修复或隔离到明确 owner，不能用“基座问题”直接跳过最终验收。
+
+最低命令：
+
+```bash
+cd muse-cloud
+mvn test
+```
+
+阶段命令：
+
+```bash
+cd muse-cloud
+mvn test -pl <领域模块> -am
+mvn test -Dtest=<领域 API 契约测试/集成测试>
+```
+
+真实环境验收必须补充对应 curl、HTTP test、Maven profile、脚本或手工命令记录。
+
+### 11.7 提交门禁
+
+1. 小步提交，每个 commit 只做一件事。
+2. 只提交 P1R 相关文件。
+3. 不提交 `muse-admin/`、`muse-studio/`、`.DS_Store`、并行计划文件或 unrelated SQL。
+4. 提交前必须看 `git status --short`。
+5. 涉及安全扫描或 pre-commit hook 跳过时，必须说明项目约定和原因。
+
+## 12. 完成定义
+
+P1R 只有满足以下条件才能宣称完成：
+
+1. 全部 P1 operation 都从 catch-all 迁移到真实业务实现。
+2. 全部 OpenAPI 响应 DTO 和错误模型有测试证据。
+3. 全部写命令有幂等、审计、权限和状态机测试。
+4. 全部外部闭环在真实服务上验收通过。
+5. 全量 `mvn test` 通过。
+6. DDL/Flyway 在目标 PG 环境执行通过。
+7. API 完成矩阵中没有未完成、阻塞、未验收项。
+
+以下情况不能算完成：
+
+1. 只有入口，没有领域服务。
+2. 只有 accepted task，没有执行器和终态。
+3. 只有 operation record，没有业务事实。
+4. 只有空列表或固定样例。
+5. 只有 controller mock 或测试替身。
+6. 外部服务未跑通。
+7. 全量测试未跑或失败。
+
+## 13. 后续产出要求
+
+本 spec 通过后，不直接进入编码。下一步必须先为 P1R-0 写阶段 spec 和 implementation plan。
+
+建议产出顺序：
+
+1. `docs/superpowers/specs/2026-05-25-P1R-0-baseline-gate-design.md`
+2. `docs/superpowers/plans/2026-05-25-P1R-0-baseline-gate.md`
+3. 完成 P1R-0 API 完成矩阵和验收口径后，再进入 P1R-1 Content。
+
+每个阶段 spec 必须包含：
+
+1. 阶段目标和非目标。
+2. API operation 列表。
+3. 领域 owner 和状态机。
+4. 数据表、读模型和外部服务依赖。
+5. 权限、幂等、审计和错误码。
+6. 测试和真实环境验收命令。
+7. 阻塞处理策略。
+
+每个阶段 plan 必须包含：
+
+1. 任务顺序。
+2. 涉及路径。
+3. 测试先行要求。
+4. 小步提交点。
+5. 回滚策略。
+6. 完成证据。
+