# 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`)。