# A-01 V3 Visual Fidelity 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:** Make the running A-01 page reproduce the selected `A01-启动登录引导-效果稿-v3-文字注册入口.png` 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-启动登录引导-效果稿-v3-文字注册入口.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:

```powershell
Assert-Contains -Content $entry -Expected "import entryGuideVisual from '@/docs/design/screens/A01-启动登录引导-效果稿-v3-文字注册入口.png'" -Message 'A-01 must import the selected v3 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**

```vue
<script setup>
import { ref } from 'vue'
import entryGuideVisual from '@/docs/design/screens/A01-启动登录引导-效果稿-v3-文字注册入口.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**

```vue
<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**

```js
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**

```powershell
$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**

```powershell
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

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