From a33560a03b875b2d590a416870bef9a1e920d33b Mon Sep 17 00:00:00 2001
From: zizi <zizi2000mail@gmail.com>
Date: Mon, 25 May 2026 12:29:03 +0800
Subject: [PATCH] =?UTF-8?q?docs(memory):=20=E8=AE=B0=E5=BD=95=20muse-cloud?=
 =?UTF-8?q?=20P1=20=E6=94=B6=E5=8F=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../2026-05-25-muse-cloud后端P1收口.md        | 252 ++++++++++++++++++
 1 file changed, 252 insertions(+)
 create mode 100644 docs/memorys/2026-05-25-muse-cloud后端P1收口.md

diff --git a/docs/memorys/2026-05-25-muse-cloud后端P1收口.md b/docs/memorys/2026-05-25-muse-cloud后端P1收口.md
new file mode 100644
index 00000000..d1283f54
--- /dev/null
+++ b/docs/memorys/2026-05-25-muse-cloud后端P1收口.md
@@ -0,0 +1,252 @@
+# muse-cloud 后端 P1 收口留痕
+
+## 任务背景
+
+执行 `docs/superpowers/plans/2026-05-24-P1-muse-cloud.md` 的 P1 后端搭建任务，目标是在 `muse-cloud/` 这个 Yudao Cloud fork 基础上搭建 Muse 后端业务模块。
+
+本次任务只负责 `muse-cloud/`，不修改 `muse-studio/`、`muse-admin/` 和 `docs/api-contracts/**`。P2、P3 有并行会话执行，提交时必须严格避免带入其他会话文件。
+
+## 已完成内容
+
+### 1. 基础环境与远端基础设施
+
+已确认当前开发环境使用：
+
+- Java 21
+- Spring Boot 3 / Yudao Cloud fork
+- PostgreSQL 连接来自 `~/.config/muse-repo/infra.env`
+- Redis 连接同样来自 `~/.config/muse-repo/infra.env`
+
+用户确认当前远端 PostgreSQL 15 可接受，不强制补 PostgreSQL 16 实例。远端 Redis 已验证 TCP 端口连通。
+
+注意：`~/.config/muse-repo/infra.env` 内有真实凭据，不要输出密码。
+
+### 2. DDL / Flyway SQL
+
+已在 `muse-cloud/sql/muse/` 下形成 V1-V8：
+
+- `V1__init_content_schema.sql`
+- `V2__init_account_schema.sql`
+- `V3__init_meta_schema.sql`
+- `V4__init_ai_schema.sql`
+- `V5__init_knowledge_schema.sql`
+- `V6__init_market_schema.sql`
+- `V7__add_contract_operation_audit.sql`
+- `V8__add_contract_workflow_and_market_interaction.sql`
+
+关键新增：
+
+- `muse_domain_operation_record`：统一操作审计与 `commandId` 幂等记录。
+- `muse_domain_workflow_task`：承载预检、导出、重试、发布准备等异步工作流事实。
+- `muse_market_favorite`：市场收藏状态。
+- `muse_market_purchase`：市场购买事实。
+
+DDL 口径：
+
+- 使用 PostgreSQL 语法。
+- 主键使用 `BIGINT GENERATED ALWAYS AS IDENTITY`。
+- 布尔字段使用 `BOOLEAN`。
+- 大文本使用 `TEXT`。
+- 不使用 MySQL `AUTO_INCREMENT`、`BIT`、`MEDIUMTEXT`。
+
+### 3. 合同入口持久化
+
+新增：
+
+- `muse-cloud/muse-framework/muse-spring-boot-starter-mybatis/src/main/java/cn/iocoder/muse/framework/mybatis/core/muse/MuseContractPersistenceService.java`
+
+用途：
+
+- 统一处理 Meta / Knowledge / Market / AI / Account 合同入口。
+- 先执行 OpenAPI 合同路由和基础字段校验。
+- 写命令先插入 `muse_domain_operation_record` 占用 `commandId`。
+- 再写入领域事实表或统一 workflow task。
+- 最后回写操作记录的 `resource_id` 和响应快照。
+- 重复 `commandId` 返回历史响应，避免重复扣费、重复发布、重复安装。
+
+为了让 framework 包下服务能被 `muse-server` 扫描到，已在：
+
+- `MuseMybatisAutoConfiguration`
+
+中通过 `@Import(MuseContractPersistenceService.class)` 注册。
+
+### 4. 模块接入
+
+以下合同 Controller 已从纯 `MuseApiContractSupport.handle(...)` 占位响应，改为注入 `MuseContractPersistenceService`：
+
+- Meta admin
+- Knowledge admin / app
+- Market admin / app
+- Account admin / app
+- AI admin / app
+
+并为相关模块补齐 `muse-spring-boot-starter-mybatis` 依赖。
+
+Content 的核心作品、章节、Block 已有专用业务 Controller / Service，因此没有强行纳入统一 shim。Content 扩展类 API 仍保留 catch-all 合同入口，后续应继续拆专用业务服务。
+
+### 5. 写命令覆盖口径
+
+通过 `MuseApiContractSupport` 中的 operation 注册表核对：
+
+- 全部合同 operation：233
+- 全部写命令：118
+- Account 写命令：9/9 已接入持久化
+- AI 写命令：19/19 已接入持久化
+- Knowledge 写命令：36/36 已接入持久化
+- Market 写命令：19/19 已接入持久化
+- Meta 写命令：8/8 已接入持久化
+
+Content 写命令不按统一 shim 统计，因为核心 Content 已有专用实现；剩余扩展 Content API 仍需后续继续落专用 Application Service。
+
+## 关键工程实践与避坑
+
+### 1. 不再返回伪成功
+
+早期 Meta / Knowledge / Market / AI / Account 合同入口主要返回占位响应，容易让前端误以为写命令已生效。
+
+当前修正为：
+
+- 已支持的写命令必须落业务表或 workflow task。
+- 未拥有的领域写命令抛 `CONTRACT_NOT_IMPLEMENTED`。
+- Content 写命令由 Content 专用服务负责，不在 `MuseContractPersistenceService` 里伪造成功。
+
+### 2. 幂等记录必须先于业务写入
+
+并发场景下，如果先写业务表再写幂等记录，两个相同 `commandId` 请求可能同时撞业务唯一键。
+
+当前顺序固定为：
+
+1. 查询是否已有 `commandId` 响应。
+2. 插入 `muse_domain_operation_record` 占用 `commandId`。
+3. 执行业务事实落库。
+4. 回写操作记录响应。
+
+### 3. 领域 owner 不能被 admin/app 入口拆散
+
+后端按领域模块拆，不按 admin/app 拆。`admin-api` 和 `app-api` 只是入口不同，领域事实只有一个 owner。
+
+本次实现中：
+
+- App 写命令会对作品、知识库、文档、安装记录等做有限 owner guard。
+- Meta / Market 的 `expectedVersion`、`expectedActiveVersion`、`expectedStatus` 会在后端校验。
+- `commandId`、revision / expectedVersion、审计字段不只依赖前端。
+
+### 4. 统一 workflow task 是 P1 过渡层
+
+预检、导出、重试、发布准备等命令先统一落 `muse_domain_workflow_task`，它解决的是 P1 阶段“必须有后端事实、幂等和审计”的问题。
+
+长期方向仍应按领域继续拆：
+
+- Account quota request / export task
+- AI evaluation run / source event retry
+- Knowledge publish readiness / export / reindex
+- Market bind precheck
+
+## 验证记录
+
+### 1. 目标测试
+
+```bash
+cd muse-cloud
+JAVA_HOME=/Users/qingse/Library/Java/JavaVirtualMachines/corretto-21.0.7/Contents/Home \
+PATH=/Users/qingse/Library/Java/JavaVirtualMachines/corretto-21.0.7/Contents/Home/bin:$PATH \
+mvn -o test \
+  -pl muse-framework/muse-spring-boot-starter-mybatis,muse-server \
+  -am \
+  -Dtest=MuseContractPersistenceServiceTest,MuseApiContractSupportTest \
+  -Dsurefire.failIfNoSpecifiedTests=false
+```
+
+结果：
+
+- `BUILD SUCCESS`
+- `MuseContractPersistenceServiceTest` 8 个测试通过
+- `MuseApiContractSupportTest` 4 个测试通过
+
+### 2. 全量 Maven 测试
+
+```bash
+cd muse-cloud
+JAVA_HOME=/Users/qingse/Library/Java/JavaVirtualMachines/corretto-21.0.7/Contents/Home \
+PATH=/Users/qingse/Library/Java/JavaVirtualMachines/corretto-21.0.7/Contents/Home/bin:$PATH \
+mvn test
+```
+
+最终结果：
+
+- `BUILD SUCCESS`
+- 总耗时约 `01:14 min`
+
+### 3. PostgreSQL DDL 验收
+
+使用远端 PG，通过临时 schema 执行 `V1..V8`，最后 `ROLLBACK`：
+
+```sql
+SELECT current_setting('server_version') AS pg_version,
+       count(*) AS muse_tables,
+       count(*) AS muse_triggers;
+```
+
+结果：
+
+- PostgreSQL `15.17 (Debian 15.17-1.pgdg13+1)`
+- Muse 表数量：`46`
+- Muse trigger 数量：`46`
+- 已回滚临时 schema，不污染数据库。
+
+### 4. Redis 连通性
+
+```bash
+nc -vz "$MUSE_REDIS_HOST" "$MUSE_REDIS_PORT"
+```
+
+结果：
+
+- `Connection to 100.64.0.8 port 6379 succeeded`
+
+本机缺少 `redis-cli`，因此未执行 AUTH/PING。
+
+## 提交记录
+
+本次 P1 相关提交：
+
+- `6410604 feat(muse-cloud): 持久化 Muse 合同入口`
+
+提交只包含 `muse-cloud/` 下 P1 相关文件。
+
+提交后工作树中仍有其他会话文件，不属于 P1：
+
+- `.DS_Store`
+- `muse-admin/**`
+- `docs/memorys/2026-05-25-muse-admin管理端搭建.md`
+- `docs/superpowers/plans/P1-execution-prompt.md`
+- `docs/superpowers/plans/P3-execution-prompt.md`
+- `precommit-scan-oh-my-muse-20260524.md`
+
+后续提交时需要继续避开这些文件，除非对应 owner 明确要求。
+
+## 未完成与后续建议
+
+### 1. DTO 仍需继续精细化
+
+当前读接口很多仍返回通用 JSON 行、操作记录或 workflow task，不等于完全符合 OpenAPI DTO 的最终形态。
+
+后续应按领域补齐 Application Query Service 和 response assembler。
+
+### 2. Content 扩展 API 仍需专用实现
+
+Content 核心作品、章节、Block 已有业务实现；但规划、导入、解析、导出、MetaProjection、SuggestionMerge 等扩展 API 仍应继续拆专用服务。
+
+### 3. Workflow task 需要异步执行器
+
+`muse_domain_workflow_task` 当前只保证命令事实、幂等和审计。后续需要补：
+
+- 任务调度
+- 状态流转
+- 失败重试
+- 结果 payload
+- 领域事件或 outbox
+
+### 4. PG16 最终环境仍未实际验收
+
+用户已确认可使用 PG15 推进。若后续要严格对齐计划中的 PostgreSQL 16，需要重新在 PG16 实例上跑一次 `V1..V8` 和应用启动验收。