oh-my-muse/docs/explainers/muse-cloud/README.md

muse-cloud 架构讲解包

本目录是面向初级后端工程师的 HTML-first 架构讲解包，帮助阅读者理解 P1R 阶段的 muse-cloud 目标架构、OpenAPI 合同路径、请求生命周期、领域 owner、阶段地图和排障路径。

阅读入口

• 权威阅读入口：index.html
• 维护备注：content/*.md
• 样式和本地交互：assets/styles.css、assets/app.js

index.html 是完整主阅读面。content/*.md 只作为维护备注和 review 对照，不是权威正文；如果 HTML 与维护备注冲突，应按 P1R spec、OpenAPI 合同和当前代码事实修正 HTML。

来源优先级

1. docs/superpowers/specs/2026-05-25-P1R-muse-cloud-real-api-design.md
2. docs/superpowers/specs/2026-05-25-P1R-0-baseline-gate-design.md
3. docs/api-contracts/**/openapi.yaml
4. 当前 muse-cloud/ 代码事实
5. 本目录 content/*.md 维护备注

关键口径

• OpenAPI paths 已经是完整外部路径，例如 /app-api/muse/works，不要再把它讲成运行时二次拼接。
• admin-api 和 app-api 只是入口差异，不是领域 owner。
• X-API-Version: 1、权限、owner、tenant、DTO、幂等、状态机和真实外部闭环都属于 P1R 验收口径。
• 对外响应统一为 Yudao CommonResult<T> 形态，JSON 字段是 code/data/msg。

不能算 P1R 完成的形态

• catch-all 合同入口兜底。
• 通用持久化响应替代领域服务。
• placeholder SSE 或固定事件。
• 空列表替代真实读模型。
• accepted task 没有进入成功、失败、取消或超时终态。

这些形态可以作为过渡保护网或基线识别结果，但不能作为真实业务 API 完成证据。