lili d38260fc51 feat(p1-market): market 写路径整改——member 暴露写端口,消除 market→member.dal BC 违例(BC 门全绿)

market 5 类(MarketAccountProjectionProvider/AdminMarketReviewServiceImpl/MarketInstallServiceImpl/
MarketLicenseServiceImpl/MarketPublishServiceImpl)此前直接构建 member.dal 的 AccountRecordProjectionDO
并经 AccountRecordProjectionMapper upsert 进 member 表——跨 BC 写路径违例(原 BcBoundaryArchTest 单点豁免登记)。

本次整改(ultracode 工作流:设计→实现→对抗验证;JDK21 scoped 实跑验证):
- member-api 新增对外写端口 MuseAccountRecordProjectionApi + MuseAccountRecordProjectionSaveReqDTO;
  member-server MuseAccountRecordProjectionApiImpl 实现,读写 member 自有 DAL,整体平移原 upsert 语义
  (insert/update 分支、update rows!=1 抛 IllegalStateException 防伪成功)。
- 安全边界:DTO 刻意不含 tenantId,由实现侧从 TenantContextHolder 注入,杜绝调用方(他域)伪造租户。
- 事务红线:写端口为进程内 Bean、不加 @Transactional,沿用调用方(market 的 REQUIRES_NEW)事务上下文,
  market 业务回滚则投影一并回滚,原子性与原实现等价。
- market 5 类改消费写端口 + DTO 替代 DO,移除 member.dal 代码依赖;
  BcBoundaryArchTest.KNOWN_VIOLATION_EXEMPTIONS 清空 → 通用 BC 门全绿(0 Architecture Violation)。
- 测试:insert/update/租户隔离语义随实现迁移至 MuseAccountRecordProjectionApiImplTest(4/0F);
  provider 测试改 mock 写端口、保留"失败→写 blocked outbox→上抛 UNAVAILABLE"语义(5/0F);
  market 其余 4 类测试同步(AdminReview 16 / Publish 14 / License 9 / Install 5)。

附带修复 round-2 一处假绿:round-2 把 ContentKnowledgeWorkOwnerFacade 重构为消费 MuseContentWorkOwnerApi 后,
旧测试 KnowledgeWorkOwnerFacadeTest 仍断言旧 WorkMapper 行为(当时验证构建在平台 QiniuSmsClientTest
时区用例处中止、未真正跑到 knowledge 模块,故漏网=假绿)。删除该旧测试,其装配守卫
(@ConditionalOnBean 值应为 MuseContentWorkOwnerApi)与 Unavailable 兜底失败关闭两用例并入
ContentKnowledgeWorkOwnerFacadeTest(3→5/0F),覆盖不丢。

验证(JDK21;-Dtest scoped 避开预存红 + muse-server -am):BUILD SUCCESS,日志无任何 <<< FAILURE/ERROR;
BcBoundaryArchTest 1/0F 且 0 Architecture Violation、AgentsInfraIntegrity 3/0F、ContractFirst 2/0F、
P1rApiCoverage 7/0F、member 4/0F、knowledge 5/0F、content 端口 7/0F、market 5 类全绿,全 reactor 模块 SUCCESS。

注:本仓存在预存红测试(非本轮引入,启用真实测试 + CI 接电后将暴露,已登记 总账/AGENTS 后续):
MuseAiTaskServiceTest 桩 eventPublishOutboxService 缺失致 11 例 NPE、MuseAiEventPublishOutboxMapperTest
需真实 PostgreSQL、平台 QiniuSmsClientTest 硬编码北京时区在非 +8 机器失败。故全量 reactor / CI-on-main
当前仍会因这些预存红呈 RED——本轮只声明 market 整改切片与 BC/契约/loop/覆盖门全绿,不声称全仓全绿。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-14 06:22:09 -07:00

7.1 KiB

Raw Permalink Blame History

AGENTS.md —— oh-my-muse(Muse)· Agent 工作入口

本项目以 AI 驱动开发。 无论你是 AI agent 还是工程师,每个任务都从这里开始。本文件是项目唯一事实源:既答"这是什么项目"(定位/目录),也答"怎么在这里干活"(先读什么、守什么规则、怎么把经验沉淀回去)。能力细节在 .agents/;CLAUDE.md 是 design-docs(设计 SSOT)的写作规范,从属本文件。

1. 项目定位

Muse = AI 驱动的长篇创作工具(Shadow→Canonical 主权:AI 产出经"先审后入"才进入正式正文)。四仓协作,采用 monorepo 承载。

仓	技术栈	职责
muse-cloud	Java 21 + Spring Boot 3 + PostgreSQL + Yudao 框架	后端(9 业务域 muse-module-*)
muse-admin	Vue 3 + Vben Admin + TS	管理端前端
muse-studio	React + Vite + TS	用户端前端
design-docs / docs	Markdown + SQL	设计 SSOT / agent 规格与基建

业务域:account(member) / ai / content / knowledge / market / meta / events + 平台底座。

2. ⚠️ 仓库物理事实(2026-06-14 订正,对抗复盘 A1/R6)

本仓是 monorepo,物理承载实现代码,不是"纯设计文档仓"。

git ls-files muse-cloud = 4468 文件、无 .gitmodules → muse-cloud/、muse-admin/、muse-studio/ 三个实现仓代码就在本工作树里、被本仓版本控制;CI 在 muse-cloud/.github/workflows/。
因此:agent 可以也应当修改这些实现代码(遵循各自规范 + .agents/rules/)。此前"本仓不承载代码/CI"的描述与磁盘矛盾,会让 agent 误判改动边界、绕路产生文档 churn,已订正。
design-docs/、docs/ 是设计/规格 SSOT;实现代码须反向对齐其正式文档。

3. 目录导航

oh-my-muse/
├── AGENTS.md                # 本文件:项目入口(唯一事实源)
├── CLAUDE.md                # design-docs 写作规范(从属本文件)
├── .agents/                 # Agent 能力中枢(knowledge/rules/skills/workflows;见 .agents/README.md)
├── muse-cloud/ muse-admin/ muse-studio/   # 三实现仓代码(可改)
├── design-docs/             # 产品/架构/前后端/流程/专题 设计 SSOT + 内容映射表/大纲
└── docs/
    ├── agent-specs/         # 现状基线 + 对抗复盘 + P0 冻结令 + 六砖交付(过程 churn 已清理)
    ├── mvp/进度总账.md       # 进度单一事实源(+ 历史交付时间线)
    ├── api-contracts/       # 各域 OpenAPI = API 契约 SSOT(原地;见 .agents/rules/contract-first.md)
    ├── dev-baseline/        # 既有全局/各仓规范(待收敛进 .agents/rules)
    └── memorys/             # 已归档清理(见 README);进度改用 mvp/进度总账.md

4. 任务前必读

序	文档	作用
1	`.agents/rules/verification-and-anti-false-green.md`	脊柱规则:完成=机械验证、机械门禁优先、反假绿
2	`docs/agent-specs/2026-06-13-项目目标与模块现状基线.md`	项目目标 + 模块真实现状(避免重复探索)
3	`docs/agent-specs/2026-06-13-目标达成对抗复盘.md`	失控根因(假绿)与重定路径
4	`.agents/README.md`	能力中枢导航
5	design-docs(`00-文档大纲.md` 入口 + `架构-01/02`、`后端-01`)	设计事实

5. 工作协议(硬约束)

读后动手:复杂任务先读 .agents/ 与相关 docs/,对齐事实再开工。
机械门禁优先 / 完成=验证:遵守 verification-and-anti-false-green——无自动化绿证据不得声称完成;新规则必配机械门禁,不靠自觉。
复杂/高危先评审:跨模块 / 改用户可见行为 / 触外部服务·支付·数据 → 评审版 → 两轮评审 → 执行版,再写代码。
契约先行:改接口/数据结构先改契约(API=docs/api-contracts/*、DB=新增 sql/muse/V*.sql,均为原地 SSOT)再实现;遵守 contract-first,已有 Flyway 卫生 + OpenAPI 结构机械门禁(openapi-diff 待启用)。
最小改动 + 中文注释:只动相关代码,复用既有模式,不顺手重构;代码全简体中文注释,关键路径可追溯日志。
无孤儿/拼接设计:任何新结构/接口/模型须带入口、使用路径、失败路径、验收标准。
证据规则:区分已验证事实/推断/假设;无证据不声称"完成/修复/通过"。

6. 知识沉淀机制(也是硬约束 —— 复利的来源)

.agents/ 的价值在于复利:让"越往后开发越快越准"。因此:

每次有价值的交付后,把可复用产出回写对应层:新事实→knowledge/;新硬约束(必配门禁)→rules/;新操作手册→skills/;流程改进→workflows/。
先查重再新增;过时即修正/删除;结构性变更同步 .agents/README.md 索引与本文导航。
进度只进 总账 + per-module .agent,不再新增“状态推进”过程文档(过程文档 churn 是失控来源之一)。

无沉淀的任务是"一次性消耗";有沉淀,下一个同类任务在已有成果上更快更准地推进。

7. 当前基建建设状态(随建随更)

✅ 机械门禁地基:CI 真跑测试(JDK21、触发分支已修为 main——此前误配 master 致 CI 从不运行)、门禁去硬编码(含分域计数派生化)、P0 冻结令。
✅ 入口与中枢骨架:本文件 + .agents/README.md + 脊柱规则。
✅ BC 边界 ArchUnit 门(bc-boundaries):通用覆盖全业务 BC 间方向;AI/knowledge 直连 content、market 直写 member 三处违例均已整改消除,豁免清单 KNOWN_VIOLATION_EXEMPTIONS 清空 → 全绿(0 Architecture Violation;遗留:market-server pom 仍依赖 member-server,仅消除了 .dal 代码 import,见该规则 §三)。
✅ 契约先行门(contract-first):Flyway 迁移卫生 + OpenAPI 存在性/结构(注:挡不住语义破坏;openapi-diff CI 已materialize,需首次 CI 运行验证)。
✅ loop 机械牙(AgentsInfraIntegrityTest):每业务 BC 有 .agent、README 索引每篇 .agents 文档、总账在——把写回/索引同步从自觉变机械。
✅ knowledge 蒸馏 / skills / workflow(AI 开发协议)/ 进度总账 + 7 BC .agent。
⏳ 后续:openapi-diff CI 首跑验证、completed=测试证据兜底(testFiles)、dev-baseline 收敛进 rules、跨域 .application 边界、market-server→member-server pom 坐标收口、ai/平台预存红测试整改(CI 接电后暴露,非本轮引入:MuseAiTaskServiceTest 桩缺失、MuseAiEventPublishOutboxMapperTest 需真实 PG、平台 QiniuSmsClientTest 时区)。

进度只进 docs/mvp/进度总账.md + 各模块 .agent,不新增状态过程文档。

7.1 KiB Raw Permalink Blame History