jiapuapp/docs/superpowers/plans/2026-07-19-g01-stretchable-complete-sheet.md

# G01 可伸缩完整底板实施计划

> **执行方式：** 仅允许在当前会话内使用 `superpowers:executing-plans` 逐项执行。用户明确禁止多代理、worktree、`git add`、`commit`、`push`、`reset` 和 `checkout`，因此本计划不包含分派、提交或分支步骤。

**目标：** 将 G01“添加家谱”弹层从“矩形宣纸 + 顶部过渡图”拼接结构改为单张完整 PNG，并只伸缩中间宣纸区域，使三按钮状态与未来长内容状态共用同一底板且顶部装饰不变形。

**架构：** `g01-add-sheet-background-v3.png` 是弹层底板的唯一视觉源。G01 本地使用 CSS `border-image` 的纵向三段伸缩：固定源图顶部 `220px` 装饰安全区、固定底部 `1px` 收口、填充并纵向伸缩中间宣纸区域；标题、关闭图标和现有 `AppButton` 保持独立交互节点。本轮不抽取通用组件，也不修改其他页面。

**技术栈：** uni-app、Vue 3 `<script setup>`、SCSS、CSS `border-image`、现有 `AppButton`、PowerShell 契约测试、Chrome DevTools Protocol 9222。

## 全局约束

- 只修改 G01 当前“添加家谱”弹层、对应契约、规格、计划和内部候选证据。
- 保留所有已修改、未跟踪、候选、母版、截图和资产文件，不删除或覆盖历史文件。
- 不使用多代理或 worktree，不执行任何 Git 写操作。
- 三个按钮继续直接复用现有 `AppButton` 与 `a01-scroll-primary-v3.png`、`a01-scroll-secondary-v3.png`。
- 不对接接口，不改变 `applyToJoin`、`joinByInvite`、`createGenealogy` 跳转逻辑。
- 只复用当前 9222 Chrome 窗口和唯一项目标签页，不打开第二个项目标签页。
- H5 截图只作为内部候选；Android/HBuilderX 继续标记为未验证。
- 未经用户明确“通过”，不得冻结 G01 或更新为 `[x]`。

---

### 任务 1：用视觉契约锁定单张底板和伸缩规则

**文件：**
- 修改：`tests/g01-visual-contract.ps1`
- 测试：`tests/g01-visual-contract.ps1`

**接口：**
- 消费：规格中的唯一底板路径 `static/assets/modules/genealogy/transparent/g01-add-sheet-background-v3.png`。
- 产出：模板、资产路径、旧拼接禁令和 `border-image` 切片参数的静态合同。

- [ ] **步骤 1：把旧拼接断言改为完整底板断言**

在 `$addMarkup` 合同中要求：

```powershell
$requiredAddTokens = @(
  'class="add-dialog"',
  'class="add-dialog__actions"',
  'class="add-dialog__close-icon"'
)

if ($addMarkup -match 'add-dialog__paper|add-dialog__edge|page-paper\.jpg|a01-paper-transition-v1\.png') {
  throw 'G-01 add sheet still assembles its background from separate paper and edge layers.'
}

if ($page -notmatch [regex]::Escape('/static/assets/modules/genealogy/transparent/g01-add-sheet-background-v3.png')) {
  throw 'G-01 add sheet does not use the approved complete background asset.'
}
```

增加伸缩参数合同：

```powershell
if ($page -notmatch '(?s)\.add-dialog\s*\{[^}]*border-image-source:\s*url\("/static/assets/modules/genealogy/transparent/g01-add-sheet-background-v3\.png"\);[^}]*border-image-slice:\s*220\s+0\s+1\s+0\s+fill;[^}]*border-image-width:\s*118rpx\s+0\s+1rpx;') {
  throw 'G-01 add sheet does not preserve the complete sheet top while stretching only the paper body.'
}
```

- [ ] **步骤 2：运行契约并确认按预期失败**

运行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tests/g01-visual-contract.ps1
```

预期：FAIL，错误明确指出仍存在 `add-dialog__paper` / `add-dialog__edge` 拼接结构或缺少完整底板资产引用；不能因语法、编码或文件缺失以外的原因失败。

---

### 任务 2：最小替换为完整可伸缩底板

**文件：**
- 修改：`pages/genealogy/g01-my-genealogies.vue`
- 使用：`static/assets/modules/genealogy/transparent/g01-add-sheet-background-v3.png`
- 测试：`tests/g01-visual-contract.ps1`

**接口：**
- 消费：任务 1 的资产路径和切片参数合同。
- 产出：`.add-dialog` 单背景伸缩结构；现有关闭和三个按钮交互保持不变。

- [ ] **步骤 1：删除模板中的两个拼接背景节点**

将：

```vue
<image class="add-dialog__paper" src="/static/assets/foundation/opaque/page-paper.jpg" mode="aspectFill" />
<view class="add-dialog__edge" aria-hidden="true">
  <image class="add-dialog__edge-image" src="/static/assets/modules/auth/transparent/a01-paper-transition-v1.png" mode="widthFix" />
</view>
```

从当前添加弹层模板移除。不要删除对应静态资产文件；切换家谱弹层保持原样。

- [ ] **步骤 2：让 `.add-dialog` 直接消费完整底板**

用以下本地样式替换 `.add-dialog__paper`、`.add-dialog__edge` 和 `.add-dialog__edge-image`：

```scss
.add-dialog {
  position: relative;
  width: 100%;
  max-height: calc(100vh - 80rpx);
  box-sizing: border-box;
  border: 1px solid transparent;
  border-image-source: url("/static/assets/modules/genealogy/transparent/g01-add-sheet-background-v3.png");
  border-image-slice: 220 0 1 0 fill;
  border-image-width: 118rpx 0 1rpx;
  border-image-repeat: stretch;
}
```

保持 `.add-dialog__content`、`.add-dialog__heading`、关闭热区和 `.add-dialog__actions` 的内容结构；若完整底板使标题压到透明区，只允许微调 `.add-dialog__content` 的顶部内边距，不改变按钮资产或全局 `AppButton`。

- [ ] **步骤 3：运行 G01 视觉契约确认转绿**

运行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tests/g01-visual-contract.ps1
```

预期：`PASS G-01 visual contract`。

- [ ] **步骤 4：运行已通过状态的回归契约**

运行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tests/g01-empty-state-contract.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File tests/g01-loading-state-contract.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File tests/g01-error-state-contract.ps1
git diff --check
```

预期：四项均退出码 `0`；前三项分别输出 PASS；`git diff --check` 不报告空白错误。不得修改或放宽既有阈值。

---

### 任务 3：验证三按钮高度与长内容压力高度

**文件：**
- 新增内部候选：`docs/design/screens/runtime/2026-07-19/g01-approval/05-add-dialog-complete-sheet-412x915.png`
- 新增内部候选：`docs/design/screens/runtime/2026-07-19/g01-approval/05-add-dialog-complete-sheet-pressure-412x915.png`
- 修改：`design-qa.md`

**接口：**
- 消费：任务 2 的 `.add-dialog`、`.add-dialog__actions` 和完整底板。
- 产出：同一资产在基准高度和压力高度下的 H5 运行证据；最终恢复正常三按钮状态供用户审批。

- [ ] **步骤 1：只读确认服务和唯一项目标签页**

运行：

```powershell
Invoke-WebRequest -UseBasicParsing 'http://127.0.0.1:5173' | Select-Object StatusCode
Invoke-RestMethod 'http://127.0.0.1:9222/json/list' | Where-Object { $_.type -eq 'page' -and $_.url -like 'http://localhost:5173*' } | Select-Object id,url
```

预期：5173 返回 `200`；项目 page 恰好一个。不启动 Chrome，不创建新标签页。

- [ ] **步骤 2：验证正常三按钮状态**

通过当前 page 的 CDP：

```text
Emulation.setDeviceMetricsOverride -> 412×915
若 .add-dialog 不存在，仅点击当前 .create-action
读取 .add-dialog、.add-dialog__content、三个 .app-button 的矩形
读取 borderImageSource、borderImageSlice、borderImageWidth
Page.captureScreenshot
```

预期：弹层贴底、无横向溢出，标题、说明、关闭和三个按钮全部可见；计算样式引用 `g01-add-sheet-background-v3.png`，切片为 `220 0 1 fill`，顶部曲线和纸面无接缝。

- [ ] **步骤 3：验证长内容只扩展中间纸面**

仅在 CDP 当前文档中临时克隆三个 `.app-button` 到 `.add-dialog__actions`，不写入源码；等待布局稳定后读取弹层高度并捕获压力图。

预期：弹层高度大于基准高度；背景仍为同一资产；顶部曲线、如意结和圆肩的可见高度与基准图一致；中间纸面扩展；内容超过安全高度时 `.add-dialog__content` 可纵向滚动；无横向溢出。

- [ ] **步骤 4：恢复正常审批状态并复测交互**

通过同一 page 执行 reload 或移除临时克隆节点，重新打开添加弹层，恢复 `412×915`。依次验证关闭图标关闭、重新打开、点击弹层内部不关闭、点击遮罩关闭、重新打开后列表位置不变。

预期：最终唯一项目标签页停留在正常三按钮“添加家谱”弹层，供用户审批；不展示压力态给用户作为当前状态。

- [ ] **步骤 5：完成内部设计 QA 记录**

在 `design-qa.md` 追加本轮条目，必须记录：

```markdown
- source visual truth path: docs/design/mockups/2026-07-19/g01-add-dialog-paper-sheet-target.png
- implementation screenshot path: docs/design/screens/runtime/2026-07-19/g01-approval/05-add-dialog-complete-sheet-412x915.png
- pressure screenshot path: docs/design/screens/runtime/2026-07-19/g01-approval/05-add-dialog-complete-sheet-pressure-412x915.png
- viewport: 412×915（另查 320×568）
- state: G01 添加家谱，正常三按钮与长内容压力态
- final result: passed 或 blocked
```

只有并排对照后不存在可执行 P0/P1/P2 问题时才写 `final result: passed`；否则保持 `blocked` 并继续只返工当前弹层。

---

## 完成条件

- 运行时底板只有 `g01-add-sheet-background-v3.png` 一个视觉源，不再拼接 `page-paper.jpg` 和 `a01-paper-transition-v1.png`。
- 三按钮和长内容压力态共用同一底板，顶部装饰不随高度拉伸。
- 当前按钮样式、关闭交互、遮罩交互、Android 返回键和列表位置保持合同。
- G01 四项相关契约与 `git diff --check` 通过。
- 唯一 Chrome 标签页最终显示 412×915 正常三按钮添加弹层。
- G01 仍未冻结、未标 `[x]`；Android/HBuilderX 仍明确未验证。