diff --git a/docs/superpowers/plans/2026-07-21-page-header-safe-area-g03.md b/docs/superpowers/plans/2026-07-21-page-header-safe-area-g03.md new file mode 100644 index 0000000..602419a --- /dev/null +++ b/docs/superpowers/plans/2026-07-21-page-header-safe-area-g03.md @@ -0,0 +1,335 @@ +# 公共页头安全区与 G03 复用实施计划 + +> **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:** 让所有普通二级页的公共页头自动避开 Android 状态栏,并让 G03 删除自建页头后复用同一组件。 + +**Architecture:** `components/PageHeader.vue` 继续作为根页面与二级页面页头的唯一实现;普通变体统一拥有“状态栏高度 + 104rpx 内容区”,根变体保持现状。G03 只提供动态标题和自定义返回处理,不再拥有页头结构、图标、背景或安全区样式。 + +**Tech Stack:** uni-app、Vue 3 Composition API、SCSS、PowerShell 静态契约、现有 Node.js CDP smoke、HBuilderX Android、MuMu、ADB。 + +## Global Constraints + +- 普通二级页头总高度必须是 `calc(104rpx + var(--status-bar-height, 0px))`,状态栏补偿只能由 `PageHeader.vue` 持有。 +- 根页面 `root` 变体继续使用现有 `calc(124rpx + var(--status-bar-height, 0px))`,不得改变 G01 已放行布局。 +- `customBack` 默认值必须为 `false`;默认返回与深链 fallback 行为保持不变。 +- G03 第一、第二步都必须使用公共 `PageHeader`,且第二步返回第一步的原业务行为保持不变。 +- 不修改 G03 表单、弹层、按钮、背景和业务数据;原生 `step=ancestor` 路由参数问题另行修复。 +- 自动检查覆盖 320px、360px、412px CSS 视口;最终视觉结论只依据 MuMu 原生画面。 + +--- + +### Task 1: 为公共 PageHeader 建立安全区与返回契约 + +**Files:** +- Modify: `tests/shared-component-document-flow-contract.ps1` +- Modify: `tests/shared-interaction-accessibility-contract.ps1` +- Modify: `components/PageHeader.vue` + +**Interfaces:** +- Consumes: uni-app 提供的 `var(--status-bar-height, 0px)`、`getCurrentPages()`、`uni.navigateBack()`、`uni.reLaunch()`。 +- Produces: `customBack: Boolean = false` 属性和 `back` 事件;普通页头及占位槽均使用安全区总高度。 + +- [ ] **Step 1: 写入普通页头安全区的失败契约** + +在 `tests/shared-component-document-flow-contract.ps1` 的 PageHeader 断言中加入: + +```powershell +Assert-Match $header '(?s)\.page-header-slot\s*\{[^}]*height:\s*calc\(104rpx \+ var\(--status-bar-height, 0px\)\);' 'PageHeader secondary slot must reserve status bar plus 104rpx content height' +Assert-Match $header '(?s)\.page-header\s*\{[^}]*height:\s*calc\(104rpx \+ var\(--status-bar-height, 0px\)\);[^}]*padding-top:\s*var\(--status-bar-height, 0px\);' 'PageHeader secondary header must place its 104rpx content below the status bar' +Assert-Match $header '(?s)\.page-header-slot--root\s*\{[^}]*height:\s*calc\(124rpx \+ var\(--status-bar-height, 0px\)\);' 'PageHeader root slot height must remain unchanged' +Assert-Match $header '(?s)\.page-header--root\s*\{[^}]*height:\s*calc\(124rpx \+ var\(--status-bar-height, 0px\)\);' 'PageHeader root height must remain unchanged' +``` + +- [ ] **Step 2: 写入自定义返回的失败契约** + +在 `tests/shared-interaction-accessibility-contract.ps1` 的 PageHeader 检查中加入: + +```powershell +foreach ($token in @( + 'customBack: { type: Boolean, default: false }', + 'const emit = defineEmits(["brand", "notice", "action", "back"]);', + 'if (props.customBack) {', + 'emit("back");', + 'uni.navigateBack();', + 'uni.reLaunch({ url: props.fallbackUrl });' +)) { + if (-not $header.Contains($token)) { throw "PageHeader back contract missing: $token" } +} +``` + +- [ ] **Step 3: 运行聚焦契约并确认 RED** + +Run: + +```powershell +& powershell -ExecutionPolicy Bypass -File tests/shared-component-document-flow-contract.ps1 +& powershell -ExecutionPolicy Bypass -File tests/shared-interaction-accessibility-contract.ps1 +``` + +Expected: 两项均 FAIL,分别指出普通页头仍为固定 `104rpx`、`customBack` 合同不存在。 + +- [ ] **Step 4: 实现最小公共组件改动** + +在 `components/PageHeader.vue` 中补充属性和事件: + +```js +const props = defineProps({ + title: { type: String, required: true }, + action: { type: String, default: "" }, + root: { type: Boolean, default: false }, + unreadCount: { type: Number, default: 0 }, + fallbackUrl: { type: String, default: "/pages/genealogy/g01-my-genealogies" }, + customBack: { type: Boolean, default: false }, +}); + +const emit = defineEmits(["brand", "notice", "action", "back"]); + +const goBack = () => { + if (props.customBack) { + emit("back"); + return; + } + const stack = getCurrentPages(); + if (stack.length > 1) { + uni.navigateBack(); + return; + } + uni.reLaunch({ url: props.fallbackUrl }); +}; +``` + +把普通变体的尺寸改为: + +```scss +.page-header-slot { + height: calc(104rpx + var(--status-bar-height, 0px)); + flex: none; +} + +.page-header { + height: calc(104rpx + var(--status-bar-height, 0px)); + padding: 0 24rpx; + padding-top: var(--status-bar-height, 0px); +} +``` + +保留 `.page-header-slot--root` 与 `.page-header--root` 的现有 `124rpx` 规则不变。 + +- [ ] **Step 5: 运行聚焦契约并确认 GREEN** + +Run: + +```powershell +& powershell -ExecutionPolicy Bypass -File tests/shared-component-document-flow-contract.ps1 +& powershell -ExecutionPolicy Bypass -File tests/shared-interaction-accessibility-contract.ps1 +git diff --check +``` + +Expected: 两项输出 `PASS`,`git diff --check` 退出码为 0。 + +- [ ] **Step 6: 提交公共组件改动** + +```powershell +git add components/PageHeader.vue tests/shared-component-document-flow-contract.ps1 tests/shared-interaction-accessibility-contract.ps1 +git commit -m "fix: adapt shared page header to safe area" +``` + +### Task 2: 用公共 PageHeader 替换 G03 自建页头 + +**Files:** +- Modify: `tests/g03-visual-states-contract.ps1` +- Modify: `tests/g03-create-flow-contract.ps1` +- Modify: `tests/g03-document-flow-contract.ps1` +- Modify: `pages/genealogy/g03-create-genealogy.vue` + +**Interfaces:** +- Consumes: Task 1 的 ``。 +- Produces: G03 动态标题 `isAncestorStep ? "录入首代人物" : "创建家谱"`,以及现有 `goBack()` 对第一、第二步的业务分流。 + +- [ ] **Step 1: 将 G03 契约改成公共页头要求** + +在 `tests/g03-visual-states-contract.ps1` 删除 `.flow-header__back`、`.flow-header__side` 和 `.flow-header__back-icon` 尺寸断言,改为: + +```powershell +Assert-Match -Content $g03 -Pattern '(?s)' -Message 'G03 must use PageHeader with its dynamic title and custom back handler' +if ($g03 -match 'flow-header|flow-header__back|flow-header__title') { throw 'G03 must not retain a private header implementation' } +``` + +在 `tests/g03-create-flow-contract.ps1` 的 required 项中加入: + +```powershell +'import PageHeader from "@/components/PageHeader.vue";', +' +``` + +在 `