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 合同中要求：

$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.'
}

增加伸缩参数合同：

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 -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：删除模板中的两个拼接背景节点

将：

<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：

.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 -NoProfile -ExecutionPolicy Bypass -File tests/g01-visual-contract.ps1

预期：PASS G-01 visual contract。

• 步骤 4：运行已通过状态的回归契约

运行：

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：只读确认服务和唯一项目标签页

运行：

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：

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 追加本轮条目，必须记录：

- 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 仍明确未验证。