e181669197
本会话三部分交付,均经 JDK21 真实构建验证(非退出码,读 BUILD SUCCESS + Tests run):
1) Agent 开发基建(机械门禁优先)
- 入口与中枢:AGENTS.md、.agents/{knowledge,rules,skills,workflows}、CLAUDE.md 订正
- 订正 .gitignore:移除对 .agent/.agents 的忽略——它们是版本化 agent 基建,须入库(此前被忽略致克隆即缺)
- 机械门禁:CI 真跑测试(maven.yml JDK21、去 -Dmaven.test.skip)、覆盖台账去硬编码、
BC 边界 ArchUnit 门(BcBoundaryArchTest)、契约先行门(ContractFirstGateTest:Flyway 卫生 + OpenAPI 结构)
- 单一进度源 docs/mvp/进度总账.md + 7 个 BC per-module .agent + mise.toml(锁 JDK21)
- P1 增量:AiSuggestionMergeProjectionFacade(Gap A)、ContentSourceServiceImpl 事务化 outbox 回流(Gap B)
2) 过期历史文档清理(97 份 churn,git 可恢复)
- 删 docs/memorys(34)、agent-specs 审阅/执行版+迁移review(34)、superpowers/plans+specs(25)、
design-docs/临时+memorys(4);保留 superpowers/reports/coverage(门禁依赖)
- 唯一干货蒸馏入 .agents/knowledge/external-deps-and-gotchas.md;订正大纲/映射表/基线悬空引用
3) P1 harness 验证:消除已登记 BC 违例 ContentMuseWorkOwnerFacade
- content-api 新增只读端口 MuseContentWorkOwnerApi + content-server 实现(读自有 DAL);
AI 适配器改消费该端口、移除全部 content.dal 依赖,AI 业务规则与 4 消费者不变
- 删除 ArchUnit 豁免 → 门禁收紧(反向红 31 例 / 正向绿;适配器单测 13/0F、端口实现 7/0F)
注:muse-studio/src(SSE 相关 4 文件)与 muse-module-ai/pom.xml(移除孤儿 contract-server)
为本会话之前已存在的未提交改动,非本次工作,未纳入本提交。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
38 lines
3.1 KiB
Markdown
38 lines
3.1 KiB
Markdown
# skill:黄金旅程纵切 —— “完成”的样板
|
|
|
|
> **类型**:操作手册(skills) · **上位**:[`../rules/verification-and-anti-false-green.md`](../rules/verification-and-anti-false-green.md)
|
|
> **何时用**:声明任何**用户可见功能**“完成”之前;或要把某条旅程从“后端 completed 台账”推进到“真实可用”。
|
|
|
|
---
|
|
|
|
## 一、“完成”的定义(三指标,缺一不可,禁止单一百分比)
|
|
|
|
| 指标 | 含义 | 证据 |
|
|
|---|---|---|
|
|
| 代码存在 | 控制器 / 服务 / 前端组件 / DB 迁移 / 契约 在位 | 文件 + 台账引用 |
|
|
| 自动化验证绿 | 单测 + IT + e2e 真跑通过 | `Tests run / Failures` 行、Playwright 报告 |
|
|
| 端到端可用 | **关 mock**、真后端、真库,一条用户旅程从入口走到 Canonical 落库 | IT / e2e 跑绿截图或日志 |
|
|
|
|
> 后端覆盖台账(`P1rApiCoverageReportTest`)里的 `completed` **只是门禁批准状态**(需 HTTP 入口 + 真 PostgreSQL + Flyway + 证据),**不等于本旅程端到端可用**。不要用它冒充指标三。
|
|
|
|
---
|
|
|
|
## 二、步骤
|
|
|
|
1. **选一条最小纵切旅程**:从 studio 用户入口 → muse-server 接口 → 业务逻辑 → Canonical 落库(例:写正文 → AI 生成候选 → 用户 Accept Suggestion → content 正文写入 + 候选归档)。
|
|
2. **关 mock**:studio 的 MSW 仅在 `import.meta.env.DEV` 启用(见 [`../../muse-studio/src/main.tsx`](../../muse-studio/src/main.tsx) 第 9 行;handlers 在 `muse-studio/src/api/mocks/handlers/*`)。真实验证须 **MSW OFF**——用 `pnpm build && pnpm preview`(生产构建即不启 worker),并让前端指向真实 `muse-server`(**确认点**:`muse-studio/vite.config.ts` 的 proxy / API baseURL 指向真后端)。
|
|
3. **起真实后端**:`muse-server` + 真实 PostgreSQL + Flyway 迁移(`muse-cloud/sql/muse/V*`)到位;JDK21(`mise exec -- ...`)。
|
|
4. **自动化端到端**:
|
|
- 后端:沿用既有 IT 模式 [`muse-cloud/muse-server/src/test/java/cn/iocoder/muse/server/framework/api/`](../../muse-cloud/muse-server/src/test/java/cn/iocoder/muse/server/framework/api/) —— `*FlywayMigrationIT`(真库迁移)、`*EndToEndLiveAcceptanceIT`(真外部依赖)。IT 由 failsafe 运行(非 surefire),用 `mvn verify`(**确认点**:本仓 failsafe 绑定与 PG/外部依赖凭据)。
|
|
- 前端:Playwright [`muse-studio/e2e/*.spec.ts`](../../muse-studio/e2e/) + [`playwright.config.ts`](../../muse-studio/playwright.config.ts),`pnpm test:e2e` 对真实后端。
|
|
5. **跑绿 + 留证据**:保存 IT/Playwright 报告与 `Tests run` 行;无绿证据不得声称“完成”。
|
|
6. **如实三指标报告**:分别给“代码 / 自动化验证 / 端到端可用”三态,而非一个百分比。
|
|
|
|
---
|
|
|
|
## 三、反模式(本项目实证教训)
|
|
- **MSW 假绿**:前端只对 mock handler 通过,误当真实可用(基线:个人中心约 21% 面跑 MSW)。
|
|
- **台账冒充可用**:把 `completed`(门禁批准)说成端到端可用。
|
|
- **只跑 surefire 不跑 IT**:跳过真库 / 真外部就宣称端到端。
|
|
- **跨 BC facade 仍是 `Unavailable` 占位**却标完成(基线:meta 写链路、account 多端面运行期 `*_UNAVAILABLE`)。
|