From bd50f15d5c52bd936f783c4bdac3f0fa1db2503d Mon Sep 17 00:00:00 2001 From: rain Date: Mon, 13 Jul 2026 15:28:16 +0800 Subject: [PATCH] docs: plan A01 runtime visual calibration --- ...26-07-13-a01-runtime-visual-calibration.md | 273 ++++++++++++++++++ 1 file changed, 273 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-13-a01-runtime-visual-calibration.md diff --git a/docs/superpowers/plans/2026-07-13-a01-runtime-visual-calibration.md b/docs/superpowers/plans/2026-07-13-a01-runtime-visual-calibration.md new file mode 100644 index 0000000..890f55e --- /dev/null +++ b/docs/superpowers/plans/2026-07-13-a01-runtime-visual-calibration.md @@ -0,0 +1,273 @@ +# A-01 Runtime Visual Calibration Implementation Plan + +> **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:** Make the A-01 unchecked entry page's real DOM match the approved 412 x 915 visual reference for its header, title, dividers, buttons, registration entry, and agreement row. + +**Architecture:** `docs/design/A01_启动登录引导_设计记录.md` owns the calibrated A-01 layout contract. `pages/auth/entry.vue` consumes that contract through local scoped styles and named A-01 elements; it retains the existing local interaction handlers. `tests/a01-a02-ui-contract.ps1` guards the layout anchors and blocks the rejected registration side lines and button-corner construction. + +**Tech Stack:** uni-app Vue 3, scoped SCSS, local PNG assets, PowerShell contract scripts. + +## Global Constraints + +- Use `docs/design/screens/A01-启动登录引导-栅格验收-412x915.png` as the sole visual reference for the unchecked state. +- Keep real DOM, local-only interaction, the existing route to A-02, and explicit agreement gating. +- Do not use the whole reference image as page content, call APIs, modify A-02, or alter the existing authentication backgrounds in this task. +- Preserve vertical scrolling and `env(safe-area-inset-bottom)` for 320 x 568. +- Use local transparent PNG assets for title cloud imagery; do not use text glyphs or emoji as ornaments. + +--- + +### Task 1: Make the A-01 record the sole measured-layout owner and add a red visual contract + +**Files:** +- Modify: `docs/design/A01_启动登录引导_设计记录.md:30-33` +- Modify: `docs/superpowers/specs/2026-07-13-a01-runtime-visual-calibration-design.md:7-31` +- Modify: `docs/superpowers/specs/2026-07-13-a01-a02-static-ui-implementation-design.md:19` +- Modify: `tests/a01-a02-ui-contract.ps1:74-87` + +**Interfaces:** +- Consumes: approved `A01-启动登录引导-栅格验收-412x915.png` and the current local route/interaction contract. +- Produces: one permanent 750rpx coordinate table and a contract that rejects the old visual construction. + +- [ ] **Step 1: Replace the old prose layout values in the A-01 design record with the calibrated table** + + Replace the current fixed-layout bullets with this table. It is the only owner of these values: + + ```markdown + | 元素 | 412 × 915 像素基准 | 750rpx 实现基准 | + | --- | --- | --- | + | 朱砂家祠头图 | 高 139px | 高 253rpx | + | 标题区起点 | 红头后约 82px | `padding-top: 150rpx` | + | 标题分隔饰线 | 宽约 234px | 宽 426rpx；上、下间距独立 | + | 两个按钮 | x=60px，宽约 291px，高约 65px | `margin: 95rpx 110rpx 0`，高 118rpx | + | 两按钮间距 | 约 28px | `margin-top: 51rpx` | + | 注册入口 | 微信按钮后约 56px；无左右短线 | `margin-top: 98rpx` | + | 协议行 | 注册入口后约 70px | `margin-top: 128rpx` 加安全区 | + ``` + +- [ ] **Step 2: Remove the superseded dimensions from the static UI implementation contract** + + In `2026-07-13-a01-runtime-visual-calibration-design.md`, replace its numeric coordinate table with this ownership statement so the design record remains the only permanent coordinate source: + + ```markdown + ## Contract ownership + + `docs/design/A01_启动登录引导_设计记录.md` owns the calibrated 412 × 915 coordinate table and acceptance thresholds. This implementation specification records scope and component strategy only; it does not define duplicate layout values. + ``` + + Then replace the static UI implementation contract's layout sentence with: + + ```markdown + - A-01 的运行时布局唯一遵循 `docs/design/A01_启动登录引导_设计记录.md` 中的“412 × 915 运行时校准表”；本文件不再重复或定义按钮与间距数值。 + ``` + +- [ ] **Step 3: Extend the PowerShell contract before changing the page** + + Add these assertions immediately after the existing A-01 DOM-structure assertions: + + ```powershell + foreach ($requiredVisualAnchor in @( + 'brand-divider--top', + 'brand-divider--bottom', + 'entry-button--primary', + 'entry-button--secondary', + 'height: 253rpx', + 'padding: 150rpx 56rpx 0', + 'width: 426rpx', + 'margin: 95rpx 110rpx 0', + 'height: 118rpx', + 'margin-top: 51rpx', + 'margin-top: 98rpx', + 'margin-top: 128rpx' + )) { + Assert-Contains -Content $entry -Expected $requiredVisualAnchor -Message "Missing A-01 calibrated visual anchor: $requiredVisualAnchor" + } + foreach ($rejectedVisualConstruction in @('link-line', 'button-corner', 'class="auth-button primary-button"')) { + Assert-NotContains -Content $entry -Unexpected $rejectedVisualConstruction -Message "A-01 retains rejected visual construction: $rejectedVisualConstruction" + } + ``` + +- [ ] **Step 4: Run the focused contract to prove it is red** + + Run: `powershell -ExecutionPolicy Bypass -File tests\a01-a02-ui-contract.ps1` + + Expected: failure mentioning `Missing A-01 calibrated visual anchor` or `A-01 retains rejected visual construction`. + +### Task 2: Rebuild A-01's measured DOM layout without changing its interaction contract + +**Files:** +- Modify: `pages/auth/entry.vue:11-65,145-324` +- Test: `tests/a01-a02-ui-contract.ps1` + +**Interfaces:** +- Consumes: the measured A-01 table from the design record and existing `openLogin`, `prepareWechatLogin`, `prepareRegister`, and `toggleAgreement` handlers. +- Produces: `brand-divider--top`, `brand-divider--bottom`, `entry-button--primary`, and `entry-button--secondary` rendered from real DOM. + +- [ ] **Step 1: Replace the entry markup that creates the rejected decorations** + + Keep the existing cloud `image` source, but split the dividers by purpose, remove the registration side lines, remove the four corner views, and use A-01-specific button classes: + + ```vue + + + + + + + + + + 登录 + + + + 微信登录 + + + 还没有账号？注册账号 + + + ``` + + Render the second divider after `brand-subtitle` with the same child structure and class `brand-divider--bottom`. + +- [ ] **Step 2: Replace the old generic layout selectors with these calibrated scoped rules** + + Keep the existing background and script blocks unchanged. Replace `.auth-header` through `.link-hover` with the following A-01 rules: + + ```scss + .auth-header { position: relative; height: 253rpx; overflow: hidden; } + + .brand-intro { + display: flex; + flex-direction: column; + align-items: center; + padding: 150rpx 56rpx 0; + color: #3f2c1d; + } + + .brand-divider { + display: flex; + align-items: center; + justify-content: center; + width: 426rpx; + } + .brand-divider--top { margin: 47rpx 0 21rpx; } + .brand-divider--bottom { margin: 34rpx 0 30rpx; } + .brand-divider__line { flex: 1; height: 1rpx; background: #d5a34f; } + .brand-divider__ornament { width: 44rpx; height: 24rpx; margin: 0 14rpx; } + + .entry-actions { margin: 95rpx 110rpx 0; } + .entry-button { + position: relative; + display: flex; + align-items: center; + justify-content: center; + box-sizing: border-box; + width: 100%; + height: 118rpx; + border: 2rpx solid #d8ad63; + border-radius: 6rpx; + font-family: STKaiti, KaiTi, serif; + font-size: 38rpx; + letter-spacing: 4rpx; + } + .entry-button::after { + position: absolute; + inset: 10rpx; + border: 1rpx solid rgba(225, 180, 105, 0.92); + border-radius: 2rpx; + content: ''; + pointer-events: none; + } + .entry-button--primary { + border-color: #9e170e; + background: #b7170d; + color: #fffaf0; + } + .entry-button--primary::after { border-color: #edc67c; } + .entry-button--secondary { + margin-top: 51rpx; + background: rgba(255, 252, 245, 0.82); + color: #60442f; + } + .entry-button__icon { width: 46rpx; height: 46rpx; margin-right: 18rpx; } + .entry-button__icon--wechat { width: 52rpx; } + .entry-button--primary .entry-button__icon { filter: brightness(0) invert(1); } + .entry-button > text { position: relative; z-index: 1; } + .entry-button--pressed { opacity: 0.84; } + + .register-link { + display: flex; + align-items: center; + justify-content: center; + margin-top: 98rpx; + color: #60442f; + font-family: STKaiti, KaiTi, serif; + font-size: 30rpx; + letter-spacing: 2rpx; + white-space: nowrap; + } + .agreement-row { margin-top: 128rpx; } + ``` + + Delete `.gold-divider`, `.divider-line`, `.divider-ornament`, `.auth-button`, `.primary-button`, `.secondary-button`, `.button-icon`, `.wechat-icon`, `.button-hover`, `.button-corner`, all `.corner-*` selectors, and `.link-line`. Do not change any handler or copy. + +- [ ] **Step 3: Run the focused contract and relevant compilation audits** + + Run: + + ```powershell + powershell -ExecutionPolicy Bypass -File tests\a01-a02-ui-contract.ps1 + powershell -ExecutionPolicy Bypass -File tests\vue3-entry.ps1 + powershell -ExecutionPolicy Bypass -File tests\compile-audit.ps1 + ``` + + Expected: all three scripts print `PASS`; the focused contract prints `A01-A02-UI-CONTRACT PASS`. + +### Task 3: Record the completed static change and request runtime evidence + +**Files:** +- Modify: `docs/design/A01_启动登录引导_设计记录.md:51-57` +- Modify: `design-qa.md:1-31` +- Test: `tests/a01-a02-ui-contract.ps1`, `tests/vue3-entry.ps1`, `tests/compile-audit.ps1` + +**Interfaces:** +- Consumes: passing static contract and a page that still needs HBuilderX/Android visual evidence. +- Produces: an honest handoff that separates static verification from runtime screenshot acceptance. + +- [ ] **Step 1: Update the design record's verification state** + + Add this sentence under the runtime-verification gap: + + ```markdown + - 2026-07-13 已按 412 × 915 参考图重新校准真实 DOM 的标题区、分隔饰线、双按钮、注册入口与协议行；静态合同通过，但仍须由同尺寸 HBuilderX 或 Android 截图叠图确认，未确认前不得标记 A-01 完成。 + ``` + +- [ ] **Step 2: Replace the stale QA finding with the exact next capture** + + Set `design-qa.md` to state that the source remains `A01-启动登录引导-栅格验收-412x915.png`, static calibration has passed, and the sole remaining evidence is an unchecked `412 x 915` HBuilderX/Android capture without browser chrome plus a `320 x 568` safety/scroll capture. + +- [ ] **Step 3: Run the final static verification and inspect the scoped diff** + + Run: + + ```powershell + powershell -ExecutionPolicy Bypass -File tests\a01-a02-ui-contract.ps1 + powershell -ExecutionPolicy Bypass -File tests\vue3-entry.ps1 + powershell -ExecutionPolicy Bypass -File tests\compile-audit.ps1 + git diff --check + git diff -- pages/auth/entry.vue tests/a01-a02-ui-contract.ps1 docs/design/A01_启动登录引导_设计记录.md docs/superpowers/specs/2026-07-13-a01-runtime-visual-calibration-design.md docs/superpowers/specs/2026-07-13-a01-a02-static-ui-implementation-design.md design-qa.md + ``` + + Expected: all scripts pass, `git diff --check` is silent, and no interaction, route, or API code is changed. + +- [ ] **Step 4: Commit only the A-01 calibration work** + + ```powershell + git add -- pages/auth/entry.vue tests/a01-a02-ui-contract.ps1 docs/design/A01_启动登录引导_设计记录.md docs/superpowers/specs/2026-07-13-a01-runtime-visual-calibration-design.md docs/superpowers/specs/2026-07-13-a01-a02-static-ui-implementation-design.md design-qa.md + git commit -m "fix: calibrate A01 entry visual layout" + ``` + + Expected: the commit includes only the listed A-01 files; it must not include `components/GenealogyCard.vue` or Vite cache files.