zizi-al/oh-my-muse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
oh-my-muse/docs/memorys/2026-05-25-muse-cloud后端P1收口.md

8.2 KiB
Raw Blame History

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. 目标测试

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 测试

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：

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 连通性

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 和应用启动验收。