jiapuapp/.superpowers/sdd/task-1-brief.md

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 断言中加入：

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 检查中加入：

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 -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 中补充属性和事件：

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 });
};

把普通变体的尺寸改为：

.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 -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: 提交公共组件改动

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"