37 lines
1.7 KiB
Markdown
37 lines
1.7 KiB
Markdown
# 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 完成证据。
|