jiapuapp/docs/superpowers/plans/2026-07-13-foundation-rebuild.md

# 家谱 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` 定义下列检查：

  ```powershell
  $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: 移动一个文件并在文件头加入中文身份注释**

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

  ```vue
  <!-- 页面编号：A-01；用途：启动／登录引导；视觉基准已由用户验收，重构时不得改变可见效果。 -->
  <template>
  ```

  A01、G01 文件头额外注明“视觉冻结”；`content-list-skeleton.vue` 明确注明“功能骨架，不计为设计完成页面”。

- [ ] **Step 3: 在同一批次更新路由和跳转**

  `pages.json` 的路径去掉 `.vue` 后必须与新文件完全一致，例如：

  ```json
  { "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: 按属性迁移已验收资源**

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

  ```text
  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: 更新所有引用并写中文图层注释**

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

  ```vue
  <!-- 不透明纸纹底图：承担页面底色，不能由 CSS 替代。 -->
  <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 标记为完成。