jiapuapp/docs/superpowers/plans/2026-07-13-g01-v5-structural-alignment.md

# G01 v5 Structural Alignment 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 G01’s title slip and list hierarchy, and align its header, hall eave, cloud button, background, and Tabbar to the v5 reference.

**Architecture:** `pages/genealogy/index.vue` owns the current title slip, spacing, lower background, and new cloud asset. `GenealogyCard.vue` owns the two-row list entry. `PageHeader.vue` and `AppTabbar.vue` keep their existing APIs and receive only scoped CSS changes.

**Tech Stack:** uni-app Vue 3, scoped SCSS, local RGBA PNG, PowerShell static contracts.

## Global Constraints

- Android only: use rpx and flexbox; do not add CSS Grid, `gap`, `clip-path`, filters, routes, APIs, or data fields.
- Visual source: `docs/design/screens/G01-我的家谱-紧凑版设计稿-v5-Tabbar安全区.png`.
- Dynamic values remain Vue text; visible ornaments remain local transparent PNGs.
- At `max-width: 340px`, hide only `更新于`.
- Keep G-01 unchecked until HBuilderX evidence exists at `360 × 800` and `320 × 568`.

---

### Task 1: Add failing structural and asset contracts

**Files:**
- Modify: `tests/g01-visual-contract.ps1`
- Modify: `tests/g01-asset-alpha-audit.ps1`

**Interfaces:** Requires `create-cloud-v2.png`, `.current-summary`, `.card-main`, and `.card-title-row`; rejects the v1 asset and `.card-copy`.

- [ ] **Step 1: Replace the old assertions**

Replace v1 with v2 in both test asset lists. Add this contract block:

```powershell
if ($header -notmatch 'height:\s*164rpx') { throw 'Header height does not match the approved narrow red-head proportion.' }
if ($header -notmatch 'opacity:\s*\.29') { throw 'Header hall line-art is not visible enough for the approved eave layer.' }
if ($tabbar -notmatch 'font-size:\s*30rpx') { throw 'Tabbar label size does not match the approved visual weight.' }
if ($tabbar -notmatch 'width:\s*64rpx') { throw 'Tabbar icon size does not match the approved visual weight.' }
foreach ($token in @('current-summary', 'create-cloud-v2.png')) { if ($page -notmatch $token) { throw "G-01 current panel is missing $token" } }
foreach ($token in @('card-main', 'card-title-row', 'card-detail-row')) { if ($card -notmatch $token) { throw "G-01 list card is missing $token" } }
if ($page -match 'create-cloud-v1\.png' -or $card -match 'card-copy') { throw 'G-01 retains a superseded visual structure.' }
```

- [ ] **Step 2: Verify old code fails**

Run `powershell -ExecutionPolicy Bypass -File tests\g01-visual-contract.ps1`.

Expected: `FAIL` because v2, title-slip/list structure, and new shared sizes do not yet exist.

- [ ] **Step 3: Commit the failing contract**

```powershell
git add tests/g01-visual-contract.ps1 tests/g01-asset-alpha-audit.ps1; git commit -m "test: define G01 v5 structural alignment"
```

### Task 2: Replace the cloud ornament

**Files:**
- Create: `static/assets/icons/action/create-cloud-v2.png`
- Delete: `static/assets/icons/action/create-cloud-v1.png`
- Modify: `pages/genealogy/index.vue`

**Interfaces:** v2 is a 96px RGBA transparent antique-gold horizontal cloud ornament rendered once normally and once with the existing mirror class.

- [ ] **Step 1: Generate and inspect v2**

Create one transparent-background 96px asset: two compact, symmetrical antique-gold Chinese cloud curls joined by a short fine line; no text, shadow, red fill, border, or background. The artwork fills the middle 70% of the canvas and matches the reference’s line weight.

- [ ] **Step 2: Install v2 and remove v1**

Point both button images to `/static/assets/icons/action/create-cloud-v2.png`. Set `.create-action` to `width: 350rpx`, `.create-cloud` to `74rpx × 36rpx`, `.create-action .create-icon` to `48rpx × 48rpx`, and its text to `34rpx`. Run `rg -n 'create-cloud-v1\.png' -g '!unpackage/**'`; expected no output. Remove v1 only after this check.

- [ ] **Step 3: Verify alpha and commit**

Run `powershell -ExecutionPolicy Bypass -File tests\g01-asset-alpha-audit.ps1`; expected `PASS static/assets/icons/action/create-cloud-v2.png transparent corners and visible artwork`.

```powershell
git add static/assets/icons/action/create-cloud-v2.png static/assets/icons/action/create-cloud-v1.png pages/genealogy/index.vue; git commit -m "feat: replace G01 create cloud ornament"
```

### Task 3: Rebuild the current title slip and list rows

**Files:**
- Modify: `pages/genealogy/index.vue`
- Modify: `components/GenealogyCard.vue`

**Interfaces:** Page owns `.current-summary` and full-width `.current-meta`; card owns `.card-main`, `.card-title-row`, and `.card-detail-row`. Props and `select` event stay unchanged.

- [ ] **Step 1: Replace current title-slip hierarchy**

Use this markup around the existing images and text bindings:

```vue
<view class="current-summary"><view class="current-seal"><image class="current-seal-frame" src="/static/assets/icons/genealogy/seal-current-frame-v1.png" mode="scaleToFill" /><text class="current-seal-title">家谱</text></view><text class="current-name">{{ currentGenealogy.name }}</text></view><view class="current-info-divider"></view><view class="current-meta"><view class="current-meta-item"><image class="current-meta-icon" src="/static/assets/icons/common/location-v1.png" mode="aspectFit" /><text class="current-meta-item-text">{{ currentGenealogy.location }}</text></view><view class="current-meta-item"><image class="current-meta-icon" src="/static/assets/icons/common/member-meta-v1.png" mode="aspectFit" /><text class="current-meta-item-text">{{ currentGenealogy.memberCount }} 位成员</text></view><view class="current-meta-item"><image class="current-meta-icon" src="/static/assets/icons/common/admin-v1.png" mode="aspectFit" /><text class="current-meta-item-text">管理员</text></view></view>
```

Delete `.current-copy`. Use `.current-slip { display: block; min-height: 268rpx; padding: 30rpx 34rpx 28rpx; }`, `.current-summary { display: flex; align-items: center; }`, `.current-meta { display: flex; justify-content: space-between; }`, and `.current-meta-item { margin: 0; }`.

- [ ] **Step 2: Replace the list’s split columns**

Use this layout after the existing seal:

```vue
<view class="card-main"><view class="card-title-row"><text class="card-name">{{ genealogy.name }}</text><view class="card-side"><text class="card-role">{{ role }}</text><image class="card-chevron" src="/static/assets/icons/common/chevron-right-v2.png" mode="aspectFit" /></view></view><view class="card-detail-row"><view class="card-metas"><view class="card-meta-item"><image class="card-meta-icon" src="/static/assets/icons/common/location-v1.png" mode="aspectFit" /><text class="card-meta">{{ genealogy.location }}</text></view><view class="card-meta-item"><image class="card-meta-icon" src="/static/assets/icons/common/member-meta-v1.png" mode="aspectFit" /><text class="card-meta">{{ genealogy.memberCount }} 位成员</text></view></view><view class="card-updated"><text>更新于 {{ genealogy.updatedAt }}</text></view></view></view>
```

Use `.card-main { display: flex; min-width: 0; flex: 1; flex-direction: column; }`, `.card-title-row { display: flex; align-items: center; justify-content: space-between; }`, and remove the fixed-width `.card-side` column. Preserve `.card-updated { display: none; }` at 340px.

- [ ] **Step 3: Reduce spacing and expand landscape coverage**

Set `.genealogy-content` to `padding: 24rpx 32rpx 176rpx`; set `.page-footer-landscape` to `bottom: 112rpx`, `height: 480rpx`, and `opacity: 0.5`. Reduce only existing shortcut/list margins; do not alter handlers or states.

- [ ] **Step 4: Verify and commit**

Run `powershell -ExecutionPolicy Bypass -File tests\g01-visual-contract.ps1`; expected `PASS G-01 visual contract`.

```powershell
git add pages/genealogy/index.vue components/GenealogyCard.vue; git commit -m "feat: restructure G01 information hierarchy"
```

### Task 4: Calibrate shared shell, document, and verify

**Files:**
- Modify: `components/PageHeader.vue`
- Modify: `components/AppTabbar.vue`
- Modify: `docs/design/G01_我的家谱_设计记录.md`
- Modify: `docs/规划.md`

**Interfaces:** Header events and Tabbar routes remain unchanged; docs record implementation without checking off G-01.

- [ ] **Step 1: Implement narrow header and visible eave**

Set `.page-header--root` to `height: 164rpx`. Set `.header-hall` to `bottom: -2rpx`, `left: -48rpx`, `width: 476rpx`, `height: 166rpx`, and `opacity: .29`. Keep all click targets at least `88rpx` high.

- [ ] **Step 2: Compact the Tabbar while increasing its visual weight**

Set `.app-tabbar` to `height: 112rpx`, `.tab-item` padding to `4rpx 0`, `.tab-icon` to `64rpx × 64rpx`, and `.tab-label` to `30rpx`. Preserve the safe area and active/default assets.

- [ ] **Step 3: Record and run focused checks**

Append a dated record covering the new current slip, list rows, header/eave, compact spacing, landscape, and v2 cloud. Leave G-01 unchecked in `docs/规划.md`. Then run:

```powershell
powershell -ExecutionPolicy Bypass -File tests\g01-visual-contract.ps1; powershell -ExecutionPolicy Bypass -File tests\g01-asset-alpha-audit.ps1; powershell -ExecutionPolicy Bypass -File tests\compile-audit.ps1; powershell -ExecutionPolicy Bypass -File tests\uni-scss-injection.ps1; powershell -ExecutionPolicy Bypass -File tests\vue3-entry.ps1
```

Expected: five `PASS` results. Capture HBuilderX at `360 × 800` and `320 × 568`; only a direct v5 comparison can complete G-01.

- [ ] **Step 4: Commit**

```powershell
git add components/PageHeader.vue components/AppTabbar.vue docs/design/G01_我的家谱_设计记录.md docs/规划.md; git commit -m "feat: align G01 shared visual shell"
```

## Plan self-review

- Task 1 locks every structural and asset change before runtime edits.
- Task 2 replaces only the mismatched cloud asset and removes its old path.
- Task 3 covers title-slip/list structure, compact spacing, and landscape coverage.
- Task 4 covers header/eave, Tabbar, docs, static checks, and HBuilderX evidence.