1

2026-07-21 21:02:55 +08:00
parent 5d99bae3f2
commit a127280ce6
12 changed files with 1131 additions and 0 deletions
@@ -0,0 +1,116 @@
+### 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"
+```
+