diff --git a/docs/superpowers/plans/2026-07-21-a01-adaptive-structure-proof.md b/docs/superpowers/plans/2026-07-21-a01-adaptive-structure-proof.md new file mode 100644 index 0000000..604b967 --- /dev/null +++ b/docs/superpowers/plans/2026-07-21-a01-adaptive-structure-proof.md @@ -0,0 +1,368 @@ +# A01 自适应结构证明 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 将 A01 从“整页合成背景 + 交互内容叠层定位”改为真正的纵向 Flex 文档流，并在当前 MuMu `720×1280 / 320dpi` 上证明默认密码态和验证码态无需滑动即可完整显示。 + +**Architecture:** A01 根容器只负责最小可用视口和自然溢出；固定比例品牌头图、独立宣纸内容区和登录内容形成真实布局层级。品牌印章可以在头图内部作为装饰定位，所有标题、输入、按钮和协议都在宣纸区正常流中，不再使用背景地标作为坐标。 + +**Tech Stack:** uni-app、Vue 3、SCSS、PowerShell 合同测试、Node.js CDP 辅助检查、HBuilderX Android、MuMu、ADB。 + +## Global Constraints + +- 规格源：`docs/superpowers/specs/2026-07-21-project-mobile-viewport-adaptation-design.md`。 +- 本计划只覆盖 A01；用户确认 MuMu 画面前不迁移其他页面。 +- 不改变登录业务、字段、校验、协议、反馈、路由和文案语义。 +- 删除 A01 对整页合成背景、`scaleToFill`、`page-canvas`、`page-backdrop` 和整页网格叠层的依赖。 +- 头图使用 `a01-vnext-header-v1.png`，保持原始 `824:340` 比例。 +- 宣纸区使用 `auth-page-paper.jpg` 作可重复装饰背景，不承担内容坐标。 +- MuMu 约 `360×640dp` 默认密码态和验证码态不滚动；`320×568`、错误、大字号或键盘空间不足时允许自然滚动但不得裁切。 +- 交互目标最小高度 `44px`；禁止整页缩放。 +- H5 只作结构辅助验证，最终视觉放行必须来自 MuMu 原生截图。 + +--- + +### Task 1: 撤销被否定的旧视口实验 + +**Files:** +- Revert: 当前工作区中上一版 viewport 实验修改的组件、页面、样式和测试 +- Delete: `docs/superpowers/plans/2026-07-21-project-mobile-viewport-adaptation.md` +- Delete: `tests/mobile-viewport-page-contract.json` +- Delete: `tests/mobile-viewport-page-contract.ps1` +- Delete: `tests/mobile-viewport-runtime-smoke.js` + +**Interfaces:** +- Consumes: 已提交的新设计规格 `2d33ee7` +- Produces: 无上一版实验残留的 A01 实施基线 + +- [ ] **Step 1: 核对待撤销集合** + +Run: `git status --short` 和 `git diff --name-only` + +Expected: 修改集合只包含上一版实验触及的组件、页面、样式、A 系列/共享测试和风险白名单。发现未知修改时停止整批恢复并逐文件保留。 + +- [ ] **Step 2: 精确恢复已确认属于旧实验的跟踪文件** + +仅在 Step 1 的集合完全吻合后运行： + +```powershell +$experimentFiles = git diff --name-only +foreach ($file in $experimentFiles) { git restore -- $file } +``` + +禁止运行 `git restore .`；不得恢复设计规格和本计划。 + +- [ ] **Step 3: 用 `apply_patch` 精确删除四个旧实验新增文件** + +只删除本任务 Files 中列出的旧计划和三个 `mobile-viewport-*` 文件。 + +- [ ] **Step 4: 验证基线** + +Run: `powershell -ExecutionPolicy Bypass -File tests/a01-a02-ui-contract.ps1` + +Expected: `A01-LOGIN-MERGE-CONTRACT PASS`，且 `git status --short` 只显示本计划。 + +--- + +### Task 2: 用失败合同锁定新结构 + +**Files:** +- Modify: `tests/a01-a02-ui-contract.ps1` +- Test: `tests/a01-a02-ui-contract.ps1` + +**Interfaces:** +- Produces: A01 头图、宣纸和正常流静态合同 + +- [ ] **Step 1: 替换旧坐标断言** + +保留业务、文案、交互、按钮皮肤、Toast 和 Dialog 断言。删除要求整页背景、品牌印章网格对齐及 `--auth-paper-start` 的断言，加入： + +```powershell +foreach ($required in @('class="auth-header"','class="auth-header__image"','a01-vnext-header-v1.png','mode="widthFix"','class="auth-paper"','auth-page-paper.jpg')) { + Assert-Contains -Content $entry -Expected $required -Message "A01 adaptive structure is missing: $required" +} +foreach ($forbidden in @('class="page-canvas"','class="page-backdrop"','a01-red-hall-ink-backdrop-v1.png','mode="scaleToFill"','--auth-paper-start','1665rpx')) { + Assert-NotContains -Content $entry -Unexpected $forbidden -Message "A01 still uses rejected page coordinates: $forbidden" +} +$pageRule = [regex]::Match($entry, '(?ms)^\.auth-page\s*\{(?.*?)^\}') +$paperRule = [regex]::Match($entry, '(?ms)^\.auth-paper\s*\{(?.*?)^\}') +$contentRule = [regex]::Match($entry, '(?ms)^\.login-content\s*\{(?.*?)^\}') +Assert-Contains $pageRule.Groups['Body'].Value 'display: flex;' 'A01 root must use flex flow.' +Assert-Contains $pageRule.Groups['Body'].Value 'min-height: var(--app-viewport-height);' 'A01 root must fill without locking content height.' +Assert-NotContains $pageRule.Groups['Body'].Value 'height: var(--app-viewport-height);' 'A01 root must not lock the viewport.' +Assert-Contains $paperRule.Groups['Body'].Value 'flex: 1;' 'A01 paper must receive remaining space.' +Assert-Contains $contentRule.Groups['Body'].Value 'justify-content: space-between;' 'A01 must distribute spare height in normal flow.' +Assert-NotContains $contentRule.Groups['Body'].Value 'grid-area:' 'A01 interactive content must not overlap page artwork.' +``` + +- [ ] **Step 2: 验证 RED** + +Run: `powershell -ExecutionPolicy Bypass -File tests/a01-a02-ui-contract.ps1` + +Expected: FAIL，提示缺少 `auth-header` 或仍存在 `page-canvas`。 + +- [ ] **Step 3: 提交失败合同** + +Run: `git add tests/a01-a02-ui-contract.ps1`，然后 `git commit -m "测试A01自适应页面结构"`。 + +--- + +### Task 3: 建立最小全局视口原语 + +**Files:** +- Modify: `styles/global.scss` + +**Interfaces:** +- Produces: `--app-viewport-height`、`--app-safe-top`、`--app-safe-bottom`、`--app-touch-min` +- Consumed by: `pages/auth/a01-entry.vue` + +- [ ] **Step 1: 在现有 `page` 规则中加入变量** + +```scss +page { + --app-viewport-height: 100vh; + --app-safe-top: env(safe-area-inset-top, 0px); + --app-safe-bottom: env(safe-area-inset-bottom, 0px); + --app-touch-min: 44px; +} +@supports (height: 100dvh) { + page { --app-viewport-height: 100dvh; } +} +``` + +本任务不增加全项目页面类，不修改共享组件或其他路由。 + +- [ ] **Step 2: 验证并提交** + +Run: `git diff --check -- styles/global.scss`。 + +Expected: exit 0，差异只有四个变量和 `100dvh` 能力覆盖。 + +Run: `git add styles/global.scss`，然后 `git commit -m "增加手机可用视口基础变量"`。 + +--- + +### Task 4: 将 A01 重构为正常流 + +**Files:** +- Modify: `pages/auth/a01-entry.vue` +- Test: `tests/a01-a02-ui-contract.ps1` + +**Interfaces:** +- Consumes: Task 3 的四个变量 +- Produces: `.auth-header`、`.auth-header__image`、`.auth-paper`、正常流 `.login-content` + +- [ ] **Step 1: 替换顶层模板** + +```diff +- +- +- ++