jiapuapp/docs/superpowers/plans/2026-07-14-g03-create-flow-consolidation.md

# G03 创建家谱流程收敛实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 把 G04 始祖录入收敛为 G03 的第二步，保留创建/录入的真实数据行为，使独立路由由 57 条降到 56 条。

**Architecture:** `pages/genealogy/g03-create-genealogy.vue` 是创建家谱流程的唯一所有者；默认 `step=create` 创建家谱，`step=ancestor&genealogyId=…` 录入首代。成功创建后使用同一 G03 URL 进入第二步；首代创建成功后才进入 T01。G04 路由与页面彻底删除，不保留兼容入口。

**Tech Stack:** uni-app Vue 3、Vue Composition API、uni-app 生命周期、既有 `appApi`/`genealogyContext`、PowerShell 契约测试、Chrome DevTools 运行时冒烟、ImageGen 位图资产。

## Global Constraints

- 不触碰已验收 A01、A02、A04、A05、A06、G01 默认态和 G01 空状态的可见效果。
- 完整页头、表单面板、主按钮均使用完整位图资产；CSS 只负责布局、文字、字段状态与交互。
- 路由/状态/行为变化先写失败契约；无 G04 兼容路由、重定向或重复页面。
- 不执行 `git add`、`git commit`、`git push`、`git reset` 或 worktree 操作。

---

### Task 1: 固化唯一 G03 创建流程合同

**Files:**
- Create: `tests/g03-create-flow-contract.ps1`
- Modify: `tests/full-page-visual-contract.ps1`
- Modify: `tests/a03-route-removal-contract.ps1`
- Test: `tests/g03-create-flow-contract.ps1`

**Interfaces:**
- Consumes: `pages.json`、当前 G03/G04 页面、`appApi`、`genealogyContext`。
- Produces: 证明 G03 是唯一创建流程入口、G04 不存在、`step=create|ancestor` 是唯一状态合同、位图表面不可被 CSS 伪造的静态守卫。

- [x] **Step 1: 写失败契约**

```powershell
Assert-RoutePresent 'pages/genealogy/g03-create-genealogy'
Assert-RouteAbsent 'pages/genealogy/g04-first-ancestor'
Assert-FileAbsent 'pages/genealogy/g04-first-ancestor.vue'
Assert-Contains $g03 'step=ancestor&genealogyId='
Assert-Contains $g03 'appApi.createGenealogy'
Assert-Contains $g03 'appApi.createPerson'
Assert-Contains $g03 'g03-create-flow-panel.png'
Assert-NoCssSurface $g03 'create-flow-panel'
Assert-NoCssSurface $g03 'flow-primary-action'
```

- [x] **Step 2: 运行并确认失败**

Run: `powershell -ExecutionPolicy Bypass -File tests/g03-create-flow-contract.ps1`

Expected: FAIL，指出 G04 路由和文件仍存在，且 G03 还没有祖先步骤与位图面板。

### Task 2: 生成并审视创建流程位图面板

**Files:**
- Create: `static/assets/modules/genealogy/opaque/g03-create-flow-panel.png`
- Modify: `docs/design/P00_页面结构与资产清单.md`
- Test: `tests/g03-create-flow-contract.ps1`

**Interfaces:**
- Consumes: G01 的暖宣纸、古金、淡墨山水视觉语言与 G03 约 656rpx 宽、876rpx 高的面板槽位。
- Produces: 1122×1500 的不透明表单面板位图，供 G03 两个流程状态共用。

- [x] **Step 1: 用 ImageGen 生成单一最终候选**

Use case: `ui-mockup`。生成暖宣纸全画布、不透明、古金双线框、回纹角饰、极淡右上云纹和底沿淡墨山水的竖向面板；禁止文字、按钮、Logo、人物、黑角、透明区域。

- [x] **Step 2: 将候选移入项目并验证位图**

最终文件为 `g03-create-flow-panel.png`；检查 1122×1500、四角 alpha=255、没有黑角，并在 P00 标注其只服务 G03 的 `create|ancestor` 两个状态。

### Task 3: 实现 G03 的两个真实步骤并移除 G04

**Files:**
- Modify: `pages/genealogy/g03-create-genealogy.vue`
- Modify: `pages.json`
- Delete: `pages/genealogy/g04-first-ancestor.vue`
- Test: `tests/g03-create-flow-contract.ps1`

**Interfaces:**
- Consumes: 查询参数 `step`、`genealogyId`；`appApi.createGenealogy`、`appApi.createPerson`；`genealogyContext`。
- Produces: G03 默认创建态、G03 首代录入态、两个状态各自校验和真实跳转。

- [x] **Step 1: 添加明确路由状态同步**

在 `onLoad`/`onShow` 同步当前查询参数。缺失或非 `ancestor` 的 `step` 一律为 `create`；祖先步骤从 `genealogyId` 或 `genealogyContext` 读取家谱 ID。

- [x] **Step 2: 保留创建行为并改为同路由下一步**

`submitCreate()` 继续验证姓氏与谱名、调用 `appApi.createGenealogy()` 和设置上下文；成功后：

```js
uni.redirectTo({
  url: `/pages/genealogy/g03-create-genealogy?step=ancestor&genealogyId=${created.id}`,
})
```

- [x] **Step 3: 内嵌祖先录入行为**

`submitAncestor()` 保留首代姓名校验和 `appApi.createPerson()`；成功后仍跳转 T01。祖先步骤的返回动作回 G03 默认创建态；默认创建态使用 `uni.navigateBack()`。

- [x] **Step 4: 替换通用 CSS 视觉面**

采用 G01 的纸纹、下沿山水和 `root-header-cinnabar.jpg`，在本页构建位图页头；两个步骤共用 `g03-create-flow-panel.png`；按钮引用 `a01-primary-button.png`。`create-flow-panel` 与 `flow-primary-action` 不能有 CSS `border`、`background` 或 `border-radius`。

- [x] **Step 5: 删除 G04 并运行静态合同**

从 `pages.json` 删除 G04，删除其 Vue 文件；`full-page-visual-contract` 与 A03 路由测试的总数改为 56。运行：

```powershell
powershell -ExecutionPolicy Bypass -File tests/g03-create-flow-contract.ps1
powershell -ExecutionPolicy Bypass -File tests/full-page-visual-contract.ps1
powershell -ExecutionPolicy Bypass -File tests/a03-route-removal-contract.ps1
```

Expected: 全部 PASS。

### Task 4: 真实流程、截图、清理和交接

**Files:**
- Create: `tests/g03-create-flow-runtime-smoke.js`
- Create: `docs/design/screens/runtime/2026-07-14/G03-create-after-360x800.png`
- Create: `docs/design/screens/runtime/2026-07-14/G03-ancestor-after-360x800.png`
- Create: `docs/design/screens/runtime/2026-07-14/G03-ancestor-after-412x915.png`
- Modify: `docs/交接记录.md`
- Modify: `docs/规划.md`
- Modify: `docs/design/视觉设计交接手册.md`
- Modify: `docs/design/2026-07-14_页面与状态合并审计.md`

**Interfaces:**
- Consumes: G03 两步 URL、Chrome DevTools `9222`、当前 56 路由合同。
- Produces: 可复现的创建链路证据、准确的路线数与“G03 两步视觉等待用户确认”停点。

- [x] **Step 1: 写并运行真实 Chrome 冒烟测试**

依次验证：默认 G03 显示创建表单；填写姓氏与谱名并点击主动作后进入 G03 祖先步骤；刷新后祖先步骤仍在；填写首代姓名后进入 T01；直接访问默认 G03 仍是创建步骤。

- [x] **Step 2: 截图并审视**

使用相同 Chrome/视口截取两步；并排比较 G01 根页视觉基准与 G03 的纸纹、页头、面板和按钮。检查图片已加载、无黑角、无横向裁切、字段和主动作完整可达。

- [x] **Step 3: 同步当前状态**

更新文档为：G01 空态已获用户验收；G04 已合并为 G03 `step=ancestor`；当前独立路由 56 条；G03 两步已实现/截图/自动验证，等待用户审美确认；下一项是 G07→G06。

- [x] **Step 4: 完成回归**

Run:

```powershell
powershell -ExecutionPolicy Bypass -File tests/g03-create-flow-contract.ps1
node tests/g03-create-flow-runtime-smoke.js http://localhost:5173
powershell -ExecutionPolicy Bypass -File tests/full-page-visual-contract.ps1
powershell -ExecutionPolicy Bypass -File tests/compile-audit.ps1
powershell -ExecutionPolicy Bypass -File tests/g01-empty-state-contract.ps1
node tests/g01-empty-state-runtime-smoke.js http://localhost:5173
powershell -ExecutionPolicy Bypass -File tests/a01-a02-ui-contract.ps1
powershell -ExecutionPolicy Bypass -File tests/a04-registration-contract.ps1
powershell -ExecutionPolicy Bypass -File tests/a05-reset-password-contract.ps1
powershell -ExecutionPolicy Bypass -File tests/a06-auth-status-contract.ps1
git diff --check
```

Expected: 全部通过；`git diff --check` 只允许现有 CRLF 警告，不存在空白错误。