jiapuapp/docs/superpowers/plans/2026-07-16-genealogy-background-opacity.md

G 模块公共背景 28% 透明度实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 让 9 个活动 G 页面通过共享背景组件统一使用 28% 不透明度的连续长背景画层，同时保持宣纸底色、内容层和现有布局不变。

Architecture: components/GenealogyPageBackground.vue 继续作为背景显示规则的唯一所有者，只在图片画层增加 opacity: 0.28。tests/genealogy-shared-background-contract.ps1 锁定该值及单一所有权，页面级运行 smoke 和截图负责验证布局与可读性没有回归。

Tech Stack: uni-app、Vue 3、SCSS/CSS、PowerShell 契约测试、Node.js Chrome DevTools Protocol 运行 smoke。

Global Constraints

• 只修改共享背景图片画层，不修改背景 PNG、母版、裁切、贴底方式或页面滚动结构。
• G01、G03、G05、G06、G08、G09、G10、G11、G12 统一生效；各页面不得重复定义透明度。
• H5 截图仅作为内部候选；Android/HBuilderX 真机或模拟器仍待复核。
• 不使用多代理、worktree，不执行 git add、commit、push、reset 或 checkout。
• 保留所有已有修改、未跟踪文件、测试、文档和证据。

---

Task 1: 用共享背景契约锁定 28% 不透明度

Files:

• Modify: tests/genealogy-shared-background-contract.ps1
• Test: tests/genealogy-shared-background-contract.ps1

Interfaces:

• Consumes: .genealogy-page-background__art 作为共享长背景图片画层。

• Produces: 背景透明度唯一值 opacity: 0.28 的仓库契约。

• Step 1: 写入会失败的透明度与单一所有权断言

在组件画层断言之后加入：

Assert-Contract ($componentSource -match '(?s)\.genealogy-page-background__art\s*\{[^}]*opacity:\s*0\.28;') 'shared artwork must use the approved 28% opacity'

在每个 G 页面循环中加入：

Assert-Contract ($pageSource -notmatch '(?s)\.genealogy-page-background__art\s*\{[^}]*opacity:') "$route must not override the shared background opacity"

• Step 2: 运行契约并确认按预期失败

Run:

powershell -NoProfile -ExecutionPolicy Bypass -File tests/genealogy-shared-background-contract.ps1

Expected: FAIL，错误包含 shared artwork must use the approved 28% opacity。

---

Task 2: 在共享组件实现 28% 画层不透明度

Files:

• Modify: components/GenealogyPageBackground.vue
• Test: tests/genealogy-shared-background-contract.ps1

Interfaces:

• Consumes: Task 1 的 opacity: 0.28 契约。

• Produces: 9 个活动 G 页面共用的淡化背景，无页面级覆盖。

• Step 1: 最小修改共享画层样式

将画层规则改为：

.genealogy-page-background__art {
  position: absolute;
  bottom: 0;
  right: 0;
  left: 0;
  display: block;
  width: 100%;
  opacity: 0.28;
}

• Step 2: 运行契约并确认通过

Run:

powershell -NoProfile -ExecutionPolicy Bypass -File tests/genealogy-shared-background-contract.ps1

Expected: PASS G genealogy shared background contract。

• Step 3: 证明契约能捕获回归

临时把 opacity: 0.28 改回无透明度，运行同一契约并确认失败；随后恢复 opacity: 0.28，再次运行并确认通过。临时变化不得保留。

---

Task 3: 运行回归、截图并更新内部状态

Files:

• Modify: docs/交接记录.md
• Modify: docs/验收规划.md
• Modify: docs/design/G01_列表背景候选与换机重建.md
• Modify: design-qa.md
• Evidence: docs/design/screens/runtime/2026-07-16/

Interfaces:

• Consumes: Task 2 已通过契约的共享组件。

• Produces: 五档 G01 H5 内部候选证据、其余 G 页面运行回归结果，以及不夸大验收层级的交接记录。

• Step 1: 顺序运行 G 页面 smoke，避免调试端口竞争

Run:

node tests/g01-empty-state-runtime-smoke.js http://localhost:5173
node tests/g03-create-flow-runtime-smoke.js http://localhost:5173
node tests/g05-overview-runtime-smoke.js http://localhost:5173
node tests/g06-search-flow-runtime-smoke.js http://localhost:5173
node tests/g08-g10-application-flow-runtime-smoke.js http://localhost:5173
node tests/g11-g12-settings-poems-runtime-smoke.js http://localhost:5173

Expected: 六组脚本全部输出 PASS，无浏览器异常或 console.error。

• Step 2: 生成并检查 G01 五档截图

尺寸为 320×568、360×640、360×800、412×915、412×1000。截图必须确认：背景比原候选明显变淡；标题、卡片、文字、按钮和底栏未同步变淡；左右不裁剪；内部列表滚动后底栏仍固定。

• Step 3: 更新权威状态文档

文档统一写明：用户确认共享背景画层为 28% 不透明度；当前只有 H5 内部候选证据；G01 及其余 G 页面没有因此获得整页验收；Android/HBuilderX 与 4GB Android 长图性能仍待复核。

• Step 4: 最终一致性检查

Run:

git diff --check
git status --short

Expected: git diff --check 退出码为 0；只报告已有换行符提示，不覆盖或清理工作区中的任何既有修改。