家谱 APP 地基重整 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: 在不改变 A01、G01 已验收视觉结果的前提下，完成页面路由命名、图片资产包、代码中文注释和无引用资源清理的可维护地基。

Architecture: pages.json 继续作为唯一实际路由源；P00 文档提供页面语义映射。跨模块图片归入 static/assets/foundation/{opaque,transparent}，模块专用图片归入 static/assets/modules/<module>/。页面只引用语义路径；公共组件仅复用两个及以上已确认页面的稳定结构。

Tech Stack: Vue 3、uni-app、SCSS、PowerShell 审计脚本、HBuilderX Android 预览。

Global Constraints

Android uni-app；不新增依赖、接口、业务功能或未确认页面状态。
A01、G01 在 412 × 915 的可见结果冻结，迁移后必须回归验证。
可见装饰一律为图片：opaque 负责完整底色，transparent 为 RGBA 叠加；禁止 CSS／SVG 装饰和截图切片。
页面路径采用 <编号>-<语义名>.vue；旧入口必须在所有引用更新并验证后删除。
关键结构、路由、资产图层和复杂逻辑使用中文注释；不得保留无用代码、资产、依赖或兼容入口。

Task 1: 建立可重复的地基审计

Files:

Create: tests/foundation-structure-audit.ps1
Modify: docs/design/P00_页面结构与资产清单.md
Test: tests/foundation-structure-audit.ps1

Interfaces:

Consumes: pages.json 的 pages[*].path，P00 的目标页面命名规则。
Produces: 退出码 0 表示路由、文件、资产目录和中文文件头满足当前迁移阶段；非 0 输出具体缺失路径。

Step 1: 写出会失败的结构审计

在 tests/foundation-structure-audit.ps1 定义下列检查：

$pages = (Get-Content -Raw pages.json | ConvertFrom-Json).pages
foreach ($page in $pages) {
  $file = "$($page.path).vue"
  if (-not (Test-Path $file)) { throw "缺少路由页面：$file" }
  if ($file -match '/(index|list|detail)\.vue$') { throw "最终页面名不允许使用：$file" }
  if (-not (Get-Content -Raw $file -Encoding utf8).StartsWith('<!-- 页面编号：')) {
    throw "缺少中文页面文件头：$file"
  }
}

Step 2: 运行并确认当前版本失败

Run: powershell -ExecutionPolicy Bypass -File tests/foundation-structure-audit.ps1
Expected: FAIL，指出当前 index.vue、list.vue 或缺少中文文件头的路由。
Step 3: 增加迁移阶段允许项

在同一脚本中把未迁移前的旧路径列为显式 legacyPaths，并要求其只在迁移批次开始前存在；迁移完成后删除该数组。检查 static/assets/foundation/opaque 和 static/assets/foundation/transparent 两个目录存在。
Step 4: 运行审计确认其仅报告真实缺失项

Run: powershell -ExecutionPolicy Bypass -File tests/foundation-structure-audit.ps1
Expected: FAIL，但每项错误都能对应 P00 中的未迁移项目。

Task 2: 迁移页面文件、路由与中文文件头

Files:

Modify: pages.json
Move: pages/auth/entry.vue → pages/auth/a01-entry.vue
Move: pages/auth/login.vue → pages/auth/a02-login.vue
Move: pages/genealogy/index.vue → pages/genealogy/g01-my-genealogies.vue
Move: pages/genealogy/create.vue → pages/genealogy/g03-create-genealogy.vue
Move: pages/lineage/first-person.vue → pages/genealogy/g04-first-ancestor.vue
Move: pages/genealogy/detail.vue → pages/genealogy/g05-genealogy-overview.vue
Move: pages/genealogy/search.vue → pages/genealogy/g06-search-genealogies.vue
Move: pages/genealogy/applications.vue → pages/genealogy/g10-application-review.vue
Move: pages/tree/index.vue → pages/tree/t01-tree-overview.vue
Move: pages/member/detail.vue → pages/tree/t03-member-profile.vue
Move: pages/family/index.vue → pages/family/f01-family-feed.vue
Move: pages/content/editor.vue → pages/family/f02-publish-feed.vue
Move: pages/content/list.vue → pages/skeleton/content-list-skeleton.vue
Move: pages/notification/index.vue → pages/notification/n01-message-center.vue
Move: pages/profile/index.vue → pages/profile/m01-profile-home.vue
Modify: every file that navigates to one of the 15 paths
Modify: docs/design/P00_页面结构与资产清单.md
Modify: tests/a01-a02-ui-contract.ps1, tests/g01-visual-contract.ps1
Test: tests/foundation-structure-audit.ps1, tests/compile-audit.ps1, tests/manifest-json.ps1

Interfaces:

Consumes: P00 第 2 节的逐项映射。
Produces: pages.json 中每个路径指向一个存在、带中文文件头的语义页面文件。
Step 1: 搜索全部旧路由引用

Run: rg -n "pages/(auth/entry|auth/login|genealogy/index|genealogy/create|genealogy/detail|genealogy/search|genealogy/applications|lineage/first-person|content/list|content/editor|tree/index|member/detail|family/index|profile/index|notification/index)" --glob '!unpackage/**'

Expected: 得到 pages.json、Vue 跳转和测试中的完整引用列表；将结果逐项写入 P00 的迁移备注。
Step 2: 移动一个文件并在文件头加入中文身份注释

每个迁移页面使用固定文件头：
```

<template>
```
A01、G01 文件头额外注明“视觉冻结”；content-list-skeleton.vue 明确注明“功能骨架，不计为设计完成页面”。
Step 3: 在同一批次更新路由和跳转

pages.json 的路径去掉 .vue 后必须与新文件完全一致，例如：
```
{ "path": "pages/auth/a01-entry", "style": { "navigationStyle": "custom" } }
```
所有 uni.navigateTo、uni.reLaunch、测试断言同步改为新 URL；不留下旧 URL 回退分支。
Step 4: 运行路由审计

Run: powershell -ExecutionPolicy Bypass -File tests/foundation-structure-audit.ps1
Expected: PASS，所有 pages.json 路径对应真实 Vue 文件并带中文文件头。
Step 5: 运行现有编译与 manifest 审计

Run: powershell -ExecutionPolicy Bypass -File tests/compile-audit.ps1
Expected: PASS，所有 pages.json 路由和本地模块引用均存在。

Run: powershell -ExecutionPolicy Bypass -File tests/manifest-json.ps1
Expected: PASS，manifest.json 仍是有效 JSON。

Task 3: 建立图片资产清单并迁移 A01／G01 资产

Files:

Create: static/assets/foundation/opaque/
Create: static/assets/foundation/transparent/
Create: static/assets/modules/genealogy/opaque/
Create: static/assets/modules/genealogy/transparent/
Create: tests/foundation-asset-audit.ps1
Modify: pages/auth/a01-entry.vue, pages/auth/a02-login.vue, pages/genealogy/g01-my-genealogies.vue, components/PageHeader.vue, components/AppTabbar.vue
Modify: tests/a01-a02-ui-contract.ps1, tests/a01-asset-alpha-audit.ps1, tests/g01-asset-alpha-audit.ps1, tests/g01-visual-contract.ps1
Modify: docs/design/P00_页面结构与资产清单.md
Test: tests/foundation-asset-audit.ps1, tests/a01-asset-alpha-audit.ps1

Interfaces:

Consumes: 当前已验收 A01／G01 图片、D1 的 opaque／transparent 规则。
Produces: 每一项保留图片有唯一语义路径、透明属性与至少一个明确代码引用。
Step 1: 写出会失败的资产审计

tests/foundation-asset-audit.ps1 扫描 pages/、components/、pages.json 和测试内的 /static/assets/ 路径；对每个路径检查文件存在。脚本还读取 P00 中的资产登记表，拒绝 -v1、-v2、-source、重复语义文件作为最终 foundation/ 路径。
Step 2: 运行并确认当前版本失败

Run: powershell -ExecutionPolicy Bypass -File tests/foundation-asset-audit.ps1
Expected: FAIL，指出当前资源仍在旧 backgrounds/、icons/ 路径且没有最终登记。

Step 3: 按属性迁移已验收资源

迁移时不修改像素内容，只改路径和名称：

auth-rice-paper-v1.jpg       -> foundation/opaque/auth-page-paper.jpg
auth-ancestral-header-v1.png -> foundation/opaque/auth-header.png
auth-ink-scenery-v1.png      -> foundation/transparent/auth-ink-scenery.png
auth-title-cloud-v1.png      -> foundation/transparent/auth-title-cloud.png
auth-divider-knot-v1.png     -> foundation/transparent/auth-divider-knot.png
auth-button-corner-v1.png    -> foundation/transparent/auth-button-frame.png

G01 的纸纹、页头、导航底图归 opaque；谱印、云纹、功能图标、Tab 图标、分隔纹归 transparent。如果某个当前按钮仍依赖 CSS 填色或四角拼接，记录为“待完整按钮图片替代”，不得把它伪装为已完成。

Step 4: 更新所有引用并写中文图层注释

每个页面的图片层在模板中标明，例如：
```

<image class="paper-background" src="/static/assets/foundation/opaque/auth-page-paper.jpg" mode="aspectFill" />
```
透明 PNG 注释注明叠加的宿主底图。不得新增新图片或改变 A01／G01 的尺寸、层级或 mode。
Step 5: 运行资产审计和透明度审计

Run: powershell -ExecutionPolicy Bypass -File tests/foundation-asset-audit.ps1
Expected: PASS，所有代码图片引用存在且最终资产路径没有临时版本名。

Run: powershell -ExecutionPolicy Bypass -File tests/a01-asset-alpha-audit.ps1
Expected: PASS，A01 中登记为透明的 PNG 保持 RGBA 属性。

Task 4: 删除无引用旧资产并做视觉回归

Files:

Delete: 资产审计确定为 无引用删除 或 迁移后删除 的旧文件
Modify: docs/design/P00_页面结构与资产清单.md
Test: tests/foundation-asset-audit.ps1, tests/a01-a02-ui-contract.ps1, tests/compile-audit.ps1

Interfaces:

Consumes: Task 3 的通过资产审计和 P00 中的去留状态。
Produces: 不存在无引用旧资产；A01、G01 仍引用唯一的语义资产。
Step 1: 输出删除候选并二次扫描

Run: rg -n "/static/assets/" pages components tests pages.json --glob '!unpackage/**'

Expected: 每一个候选旧文件均不在输出中；若仍有输出，保留文件并回到 Task 3。
Step 2: 删除已确认路径并立即更新 P00

仅删除 P00 表格中标记为 无引用删除 或 迁移后删除 的文件；不递归删除目录，不删除用户未确认的模块资产。
Step 3: 运行视觉与编译回归

Run: powershell -ExecutionPolicy Bypass -File tests/a01-a02-ui-contract.ps1
Expected: PASS。

Run: powershell -ExecutionPolicy Bypass -File tests/compile-audit.ps1
Expected: PASS。

在 HBuilderX 以 412 × 915 复核 A01、G01：纸纹、页头、按钮、祥云、谱印、导航无断裂、无缺失、无拼接痕迹。
Step 4: 检查差异与文档状态

Run: git diff --check
Expected: PASS。

将 P00 每个页面和资产的处理状态更新为真实结论；仅在上述检查均通过后将总规划的 P-00 标记为完成。

11 KiB Raw Blame History Unescape Escape

家谱 APP 地基重整 Implementation Plan

Global Constraints

Task 1: 建立可重复的地基审计

Task 2: 迁移页面文件、路由与中文文件头

Task 3: 建立图片资产清单并迁移 A01／G01 资产

Task 4: 删除无引用旧资产并做视觉回归

11 KiB

Raw Blame History