From 3d36fbba13cd132960c4d917f45c958c4bbaeb2b Mon Sep 17 00:00:00 2001 From: rain Date: Mon, 13 Jul 2026 16:08:13 +0800 Subject: [PATCH] docs: plan A01 reference asset rebuild --- .../2026-07-13-a01-reference-asset-rebuild.md | 150 ++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-13-a01-reference-asset-rebuild.md diff --git a/docs/superpowers/plans/2026-07-13-a01-reference-asset-rebuild.md b/docs/superpowers/plans/2026-07-13-a01-reference-asset-rebuild.md new file mode 100644 index 0000000..4a497d8 --- /dev/null +++ b/docs/superpowers/plans/2026-07-13-a01-reference-asset-rebuild.md @@ -0,0 +1,150 @@ +# A01 Reference Asset Rebuild 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:** Rebuild A01's visible red header, paper scene, title lockup, divider knots, and button frames from the approved 412 × 915 reference while preserving real DOM interactions. + +**Architecture:** `pages/auth/entry.vue` remains the only interactive owner. Reference-derived raster assets own decorative visual details, while DOM owns button labels, icons, agreement state, and navigation. A small local asset-preparation command reads only the approved source screen, exports composited header/body layers and alpha PNG foreground assets, then leaves no runtime dependency on that command. + +**Tech Stack:** Uni-app Vue 3, scoped SCSS, PowerShell/System.Drawing asset preparation, existing PowerShell contract and alpha audits. + +## Global Constraints + +- Visual truth is `docs/design/screens/A01-启动登录引导-栅格验收-412x915.png` at 412 × 915. +- Do not render the whole reference image as page content; header, body scene, title lockup, divider knot, and button frames are distinct assets. +- Preserve A01 agreement gating and `'/pages/auth/login?agreed=1'` navigation. +- Do not modify `components/GenealogyCard.vue` or `unpackage/dist/cache/.vite/deps/*`. +- New v2 frame/title/knot assets must have transparent outer corners; remove A01's unused v1 generated ornaments. + +--- + +### Task 1: Encode the v2 reference-asset contract + +**Files:** +- Modify: `tests/a01-a02-ui-contract.ps1` +- Modify: `tests/a01-asset-alpha-audit.ps1` + +**Interfaces:** +- Consumes: current `pages/auth/entry.vue` and existing v1 A01 assets. +- Produces: a failing contract requiring `auth-header-reference-v2.png`, `auth-body-scene-v2.png`, `auth-brand-lockup-v2.png`, `auth-divider-knot-v2.png`, `auth-primary-frame-v2.png`, and `auth-secondary-frame-v2.png`. + +- [ ] **Step 1: Write the failing test** + +Add these required paths to the A01 entry contract: + +```powershell +foreach ($asset in @( + 'auth-header-reference-v2.png', 'auth-body-scene-v2.png', + 'auth-brand-lockup-v2.png', 'auth-divider-knot-v2.png', + 'auth-primary-frame-v2.png', 'auth-secondary-frame-v2.png' +)) { + Assert-Contains -Content $entry -Expected $asset -Message "Missing A01 reference asset: $asset" +} +Assert-NotContains -Content $entry -Unexpected 'auth-button-corner-v1.png' -Message 'A01 must not retain the rejected generated corner asset' +``` + +Replace the alpha-audit icon list with the four transparent v2 foreground assets and assert their source dimensions: brand lockup `240 × 110`, divider knot `80 × 48`, primary frame `291 × 65`, secondary frame `291 × 65`. Assert header `412 × 139` and body scene `412 × 776` exist as opaque scene layers. + +- [ ] **Step 2: Run test to verify it fails** + +Run: `powershell -ExecutionPolicy Bypass -File tests\a01-a02-ui-contract.ps1; powershell -ExecutionPolicy Bypass -File tests\a01-asset-alpha-audit.ps1` + +Expected: FAIL because the six `v2` paths are not referenced or do not exist. + +- [ ] **Step 3: Commit the contract only after Task 2 passes** + +Do not commit an intentionally failing contract. It is staged with the asset and page changes in Task 3. + +### Task 2: Prepare exact reference-derived v2 assets + +**Files:** +- Create: `static/assets/backgrounds/auth-header-reference-v2.png` +- Create: `static/assets/backgrounds/auth-body-scene-v2.png` +- Create: `static/assets/icons/auth/auth-brand-lockup-v2.png` +- Create: `static/assets/icons/auth/auth-divider-knot-v2.png` +- Create: `static/assets/icons/auth/auth-primary-frame-v2.png` +- Create: `static/assets/icons/auth/auth-secondary-frame-v2.png` +- Delete: `static/assets/icons/auth/auth-button-corner-v1.png` +- Delete: `static/assets/icons/auth/auth-divider-knot-v1.png` +- Delete: `static/assets/icons/auth/auth-title-cloud-v1.png` + +**Interfaces:** +- Consumes: `docs/design/screens/A01-启动登录引导-栅格验收-412x915.png`. +- Produces: fixed-pixel v2 assets used by `entry.vue`; no asset contains a clickable control or agreement copy. + +- [ ] **Step 1: Export the visual layers from the approved source** + +Use System.Drawing to read the 412 × 915 source. Crop rows `0..138` to `auth-header-reference-v2.png`. Crop rows `139..914` to `auth-body-scene-v2.png`, replacing the title, divider, button, register and agreement foreground rectangles with sampled rice-paper pixels before saving. The retained side architecture, bamboo, and lower mountain must stay in their original reference positions. + +- [ ] **Step 2: Export alpha foregrounds** + +Use the same source to create: a `240 × 110` brand lockup (dark title plus both gold clouds), an `80 × 48` divider knot, and two `291 × 65` button frame images. For the foregrounds, make the paper/background pixels transparent, preserve the exact colored ornament pixels, and for each frame clear its center rectangle while retaining the double rule and all four reference corner curls. + +- [ ] **Step 3: Inspect and audit the assets** + +Open the three frame/title/knot PNGs and confirm their outer corners are transparent and their visible artwork has no green matte. Run: `powershell -ExecutionPolicy Bypass -File tests\a01-asset-alpha-audit.ps1`. + +Expected: PASS once the Task 1 audit rules are in place. + +### Task 3: Replace the A01 decorative layer implementation + +**Files:** +- Modify: `pages/auth/entry.vue` +- Modify: `docs/design/A01_启动登录引导_设计记录.md` +- Modify: `design-qa.md` +- Modify: `tests/a01-a02-ui-contract.ps1` +- Modify: `tests/a01-asset-alpha-audit.ps1` + +**Interfaces:** +- Consumes: all six v2 assets from Task 2. +- Produces: reference-derived visuals with unchanged `toggleAgreement`, `openLogin`, `prepareWechatLogin`, `prepareRegister`, and `prepareAgreement` functions. + +- [ ] **Step 1: Update page asset ownership** + +Replace the generated header plus `header-seal` overlay with `auth-header-reference-v2.png`. Replace the current paper/scenery pair with the prepared body scene layer. Replace the text/cloud title group with `auth-brand-lockup-v2.png`; retain its wrapper only for layout. Keep CSS gold rules but replace each v1 divider ornament with `auth-divider-knot-v2.png`. + +For both button types, remove all four `.button-corner-asset` images. Add one absolute `.entry-button__frame` image that uses the matching primary or secondary frame asset. Keep the DOM icon/text group above the frame and preserve existing click handlers. + +- [ ] **Step 2: Update visual calibration values and records** + +Set the lockup and divider image dimensions to their source ratios, keep the validated vertical anchors, and remove stale v1 asset statements from the A01 design record. Update `design-qa.md` to list the latest screenshot as pending visual confirmation rather than passed. + +- [ ] **Step 3: Run the focused tests** + +Run: `powershell -ExecutionPolicy Bypass -File tests\a01-a02-ui-contract.ps1; powershell -ExecutionPolicy Bypass -File tests\a01-asset-alpha-audit.ps1; powershell -ExecutionPolicy Bypass -File tests\a01-design-record-audit.ps1; powershell -ExecutionPolicy Bypass -File tests\compile-audit.ps1` + +Expected: all four scripts print `PASS` with exit code 0. + +- [ ] **Step 4: Run full regression verification** + +Run: `Get-ChildItem -LiteralPath tests -Filter *.ps1 | Sort-Object Name | ForEach-Object { & powershell -ExecutionPolicy Bypass -File $_.FullName; if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } }; git diff --check` + +Expected: every test script passes and `git diff --check` reports no errors. + +- [ ] **Step 5: Commit the reference rebuild** + +```powershell +git add -- pages/auth/entry.vue tests/a01-a02-ui-contract.ps1 tests/a01-asset-alpha-audit.ps1 docs/design/A01_启动登录引导_设计记录.md design-qa.md static/assets/backgrounds/auth-header-reference-v2.png static/assets/backgrounds/auth-body-scene-v2.png static/assets/icons/auth/auth-brand-lockup-v2.png static/assets/icons/auth/auth-divider-knot-v2.png static/assets/icons/auth/auth-primary-frame-v2.png static/assets/icons/auth/auth-secondary-frame-v2.png static/assets/icons/auth/auth-button-corner-v1.png static/assets/icons/auth/auth-divider-knot-v1.png static/assets/icons/auth/auth-title-cloud-v1.png +git commit -m "fix: rebuild A01 reference visual assets" +``` + +### Task 4: Obtain runtime evidence + +**Files:** +- Modify: `design-qa.md` after receiving user-provided HBuilderX/Android screenshots. + +**Interfaces:** +- Consumes: rendered unchecked A01 screenshots at 412 × 915 and 320 × 568. +- Produces: a visual QA verdict grounded in those screenshots. + +- [ ] **Step 1: Compare the two same-state screenshots** + +At 412 × 915, verify: header bottom gold band and seal, side architecture/bamboo/lower mountain placements, brand lockup scale, both frame corner curls, divider knots, and agreement baseline. + +- [ ] **Step 2: Check narrow-screen safety** + +At 320 × 568, scroll to the agreement row and verify that the checkbox and all copy remain visible above the system navigation area. + +- [ ] **Step 3: Record evidence status** + +Set `design-qa.md` to `final result: passed` only if both screenshots satisfy the checks; otherwise document the remaining pixel difference and keep it pending.