jiapuapp/docs/superpowers/plans/2026-07-13-a01-v3-visual-fidelity.md

A-01 V3 Visual Fidelity Implementation Plan

状态：已失效。用户否决“整张效果图作为页面视觉层”的方案；当前 A-01 必须以真实 DOM 还原 v3，见 docs/design/A01_启动登录引导_设计记录.md。

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make the running A-01 page reproduce the selected 412×915 visual baseline at mobile width while preserving its existing local-only interactions.

Architecture: The accepted v3 image is a complete 852 × 1846 mobile visual, including typography, ornamental borders, header, ink scenery and the empty agreement circle. pages/auth/entry.vue renders it at a logical width of 750rpx and layers only transparent interaction regions above it. The existing agreed state and local-only toast/navigation functions remain the sole interaction owner.

Tech Stack: uni-app Vue 3 <script setup>, local PNG imported with @/, PowerShell contract audit.

Global Constraints

• Visual source of truth: docs/design/screens/A01-启动登录引导-栅格验收-412x915.png.
• Do not generate artwork, redraw v3 ornaments in CSS, add API calls, write login state, or create routes.
• A-01 stays vertically scrollable below 430 × 932; render the source with width-fixed scaling.
• A-01 is unchecked by default and retains the exact guard message 请先阅读并同意相关协议.
• Only pages/auth/entry.vue, tests/a01-a02-ui-contract.ps1, and A-01 design/hand-off records may change.

---

Task 1: Change the A-01 contract to the selected v3 source

Files:

• Modify: tests/a01-a02-ui-contract.ps1

Interfaces:

• Consumes: the local v3 visual source and existing openLogin, prepareWechatLogin, prepareRegister, prepareAgreement functions.

• Produces: a source-level guard that rejects the former hand-built header, title, cloud and button decorations.

• Step 1: Write the failing visual-source assertions

Add these checks while retaining agreement, route, local-toast and forbidden-API checks:

Assert-Contains -Content $entry -Expected "import entryGuideVisual from '@/docs/design/screens/A01-启动登录引导-栅格验收-412x915.png'" -Message 'A-01 must import the selected visual source'
foreach ($requiredClass in @('guide-art', 'entry-login-hit', 'entry-wechat-hit', 'entry-register-hit', 'entry-agreement-hit')) {
  Assert-Contains -Content $entry -Expected $requiredClass -Message "Missing A-01 interaction region: $requiredClass"
}
foreach ($forbiddenClass in @('auth-header', 'brand-intro', 'entry-actions', 'cloud')) {
  Assert-NotContains -Content $entry -Unexpected $forbiddenClass -Message "A-01 must not redraw the v3 visual with $forbiddenClass"
}

• Step 2: Run the contract test before changing the page

Run: & .\tests\a01-a02-ui-contract.ps1

Expected: failure stating that A-01 does not import the selected v3 visual source.

• Step 3: Do not commit red state

Leave the failing contract uncommitted until Task 2 passes.

---

Task 2: Replace the hand-built A-01 visual with the accepted v3 source

Files:

• Modify: pages/auth/entry.vue

Interfaces:

• Consumes: entryGuideVisual, agreed, requireAgreement, openLogin, prepareWechatLogin, prepareRegister, and prepareAgreement.

• Produces: the v3 presentation plus four screen-coordinate interaction regions.

• Step 1: Import and render the accepted source width-fixed

<script setup>
import { ref } from 'vue'
import entryGuideVisual from '@/docs/design/screens/A01-启动登录引导-栅格验收-412x915.png'
</script>

<template>
  <view class="entry-page">
    <image class="guide-art" :src="entryGuideVisual" mode="widthFix" />
  </view>
</template>

Set the root to width: 750rpx; min-height: 1625rpx; with no overflow: hidden, so 320 × 568 remains scrollable.

• Step 2: Add only invisible v3 hit regions

<view class="entry-hit entry-login-hit" hover-class="entry-hit-active" @click="openLogin" />
<view class="entry-hit entry-wechat-hit" hover-class="entry-hit-active" @click="prepareWechatLogin" />
<view class="entry-hit entry-register-hit" hover-class="entry-hit-active" @click="prepareRegister" />
<view class="entry-hit entry-agreement-hit" @click="toggleAgreement" />
<view v-if="agreed" class="agreement-confirmed">✓</view>

Use v3’s 750rpx logical coordinates: login top: 799rpx; left: 99rpx; width: 552rpx; height: 126rpx; WeChat top: 960rpx; register top: 1155rpx; left: 200rpx; width: 350rpx; height: 72rpx; agreement toggle top: 1362rpx; left: 126rpx; width: 60rpx; height: 60rpx. Display the check marker only after a user toggle.

• Step 3: Preserve the existing local-only behavior

const requireAgreement = () => {
  if (agreed.value) return true
  uni.showToast({ title: '请先阅读并同意相关协议', icon: 'none' })
  return false
}

const openLogin = () => {
  if (!requireAgreement()) return
  uni.navigateTo({ url: '/pages/auth/login?agreed=1' })
}

Keep prepared-state toasts for WeChat, registration and agreement pages. Do not add appApi, calcMD5, loginWithPassword, uni.reLaunch, or an implicit agreement sentence.

• Step 4: Run the focused test cycle

Run: & .\tests\a01-a02-ui-contract.ps1

Expected: A01-A02-UI-CONTRACT PASS.

---

Task 3: Record the v3 runtime source and verify

Files:

• Modify: docs/design/A01_启动登录引导_设计记录.md
• Modify: docs/交接记录.md

Interfaces:

• Consumes: selected v3 source and current A-01 local interaction contract.

• Produces: one documented visual source for the next Android screenshot comparison.

• Step 1: Update the A-01 record

State that v3 is the runtime visual source, not merely archived evidence. Correct the principal button copy to 登录; its destination remains A-02’s default account/password tab after explicit agreement.

• Step 2: Update hand-off status

Record that the first local preview diverged from v3 in header height, button width and vertical rhythm, and that the correction uses v3 directly. Keep four-size Android runtime comparison pending.

• Step 3: Run project verification

$tests = Get-ChildItem -LiteralPath .\tests -Filter *.ps1 | Sort-Object Name
foreach ($test in $tests) { & $test.FullName }
git diff --check
git status --short

Expected: all scripts pass, git diff --check is silent, and only these four files changed besides user-owned dirty files.

• Step 4: Commit scoped work

git add -- pages/auth/entry.vue tests/a01-a02-ui-contract.ps1 docs/design/A01_启动登录引导_设计记录.md docs/交接记录.md
git commit -m "fix: match A01 v3 visual reference"

---

Self-Review

• The target is the exact saved v3 image the user displayed, not a new interpretation.
• The plan replaces hand-drawn visible ornaments with the existing visual asset and keeps interactions local.
• The contract goes red before the page change, then verifies the visual source and interaction regions.
• No API, new route, Android configuration, or non-A-01 screen is included.
• Android runtime screenshot comparison remains follow-up work, not an unverified claim.