# Global Loading System 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:** 将 `AppLoading.vue` 建成页面级／局部级统一加载组件，并接入首批 11 个页面及 G06 搜索结果区域。

**Architecture:** `AppLoading` 单一维护朱砂谱印、呼吸动效、两档尺寸和文案层级；页面只传入 `variant`、`text`、`description`，并继续拥有业务状态。按钮提交、列表刷新和上传进度不进入本组件。

**Tech Stack:** uni-app、Vue 3、SCSS、PowerShell 契约测试、Node/Chrome H5 runtime smoke。

## Global Constraints

- `variant` 只允许 `page` 与 `section`，默认 `page`。
- 页面级尺寸为谱印 `96×96rpx`、印字 `40rpx`、主文案 `30rpx`、说明 `24rpx`、最小高度 `320rpx`。
- 局部级尺寸为谱印 `64×64rpx`、印字 `28rpx`、主文案 `24rpx`、说明 `22rpx`、最小高度 `180rpx`。
- 不创建全屏遮罩，不接管标题栏、底栏或业务状态。
- 不修改按钮提交、下拉刷新、触底加载和上传流程。
- 不使用多代理、worktree 或 Git 写操作。
- H5 证据不代表 Android/HBuilderX 或页面正式验收。

---

### Task 1: `AppLoading` 双变体合同

**Files:**
- Create: `tests/app-loading-contract.ps1`
- Modify: `components/AppLoading.vue`
- Modify: `tests/g01-loading-state-contract.ps1`

**Interfaces:**
- Consumes: `variant: 'page' | 'section'`、`text: string`、`description: string`。
- Produces: `.app-loading--page`、`.app-loading--section`、`.app-loading__mark`、`.app-loading__copy`、`.app-loading__description`。

- [ ] **Step 1: 写入失败契约**

契约锁定三个属性、两个变体类、设计尺寸、`1.35s` 动画和可选说明；G01 必须传入 `description`，不再在页面复制辅助说明。

- [ ] **Step 2: 验证失败**

Run: `powershell -NoProfile -ExecutionPolicy Bypass -File tests/app-loading-contract.ps1`

Expected: FAIL，指出 `variant` 或 `description` 尚未实现。

- [ ] **Step 3: 实施组件**

```vue
<template>
  <view class="app-loading" :class="`app-loading--${variant}`">
    <view class="app-loading__mark"><text>谱</text></view>
    <text class="app-loading__copy">{{ text }}</text>
    <text v-if="description" class="app-loading__description">{{ description }}</text>
  </view>
</template>

<script setup>
defineProps({
  variant: { type: String, default: 'page', validator: (value) => ['page', 'section'].includes(value) },
  text: { type: String, default: '正在展开，请稍候…' },
  description: { type: String, default: '' }
})
</script>
```

样式按 Global Constraints 的两档精确尺寸实现，动画继续由 `app-loading-breathe` 唯一维护。

- [ ] **Step 4: 更新 G01 消费方式**

```vue
<AppLoading text="正在整理家谱" description="请稍候，家族记忆正在归卷。" />
```

删除 G01 的 `.state-copy--loading` 独立说明节点。

- [ ] **Step 5: 验证通过**

Run:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tests/app-loading-contract.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File tests/g01-loading-state-contract.ps1
```

Expected: 全部 PASS。

---

### Task 2: G 系列接入

**Files:**
- Create: `tests/g-series-app-loading-contract.ps1`
- Modify: `pages/genealogy/g05-genealogy-overview.vue`
- Modify: `pages/genealogy/g06-search-genealogies.vue`
- Modify: `pages/genealogy/g09-my-applications.vue`
- Modify: `pages/genealogy/g10-application-review.vue`
- Modify: `pages/genealogy/g11-genealogy-settings.vue`
- Modify: `pages/genealogy/g12-generation-poems.vue`

**Interfaces:**
- Consumes: Task 1 的 `AppLoading` 属性合同。
- Produces: G05/G09/G10/G11/G12 页面级 Loading 与 G06 局部 Loading。

- [ ] **Step 1: 写入失败契约**

每页必须导入 `AppLoading`；G05、G09、G10、G11、G12 在自身 `loading` 分支渲染页面级组件；G06 搜索区渲染 `variant="section"`。

- [ ] **Step 2: 验证失败**

Run: `powershell -NoProfile -ExecutionPolicy Bypass -File tests/g-series-app-loading-contract.ps1`

Expected: FAIL，指出首个尚未接入的 G 页面。

- [ ] **Step 3: 接入页面级分支**

各页在现有成功／空／失败分支之前加入：

```vue
<AppLoading
  v-if="pageState === 'loading'"
  text="页面对应的已确认文案"
  description="页面对应的辅助说明"
/>
```

其中 `pageState` 分别为 `overviewState`、`applicationState`、`reviewState`、`settingsState`、`poemState`；保留各页其他分支和操作。

- [ ] **Step 4: 接入 G06 局部加载**

```vue
<AppLoading
  v-if="searchState === 'loading'"
  variant="section"
  text="正在检索公开家谱"
  description="请稍候，正在整理匹配结果。"
/>
```

搜索框、模式切换、地区筛选和分隔线继续可见。

- [ ] **Step 5: 验证通过**

Run:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tests/g-series-app-loading-contract.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File tests/g01-visual-contract.ps1
node tests/module-page-runtime-smoke.js http://localhost:5173
```

Expected: 全部 PASS。

---

### Task 3: T/F/N 页面级接入

**Files:**
- Create: `tests/module-app-loading-contract.ps1`
- Modify: `pages/tree/t01-tree-overview.vue`
- Modify: `pages/tree/t03-member-profile.vue`
- Modify: `pages/tree/t07-member-directory.vue`
- Modify: `pages/family/f01-family-feed.vue`
- Modify: `pages/notification/n01-message-center.vue`

**Interfaces:**
- Consumes: Task 1 的页面级 `AppLoading`。
- Produces: 五个页面独立且不会误落入错误卡的 `loading` 分支。

- [ ] **Step 1: 写入失败契约**

锁定五页导入组件并在现有列表／详情／树／错误判断之前单独处理 `loading`；Loading 期间不显示错误操作或发布／审核按钮。

- [ ] **Step 2: 验证失败**

Run: `powershell -NoProfile -ExecutionPolicy Bypass -File tests/module-app-loading-contract.ps1`

Expected: FAIL，指出首个仍把 `loading` 当成错误／空状态的页面。

- [ ] **Step 3: 实施五页分支**

统一结构：

```vue
<AppLoading
  v-if="pageState === 'loading'"
  text="页面对应的已确认文案"
  description="请稍候，正在读取页面数据。"
/>
<template v-else-if="pageState === 'ready-state'">…</template>
<view v-else>…原空／错误状态…</view>
```

只调整状态分支，不改变数据、入口、卡片和按钮行为。

- [ ] **Step 4: 验证通过**

Run:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tests/module-app-loading-contract.ps1
node tests/t01-tree-state-runtime-smoke.js http://localhost:5173
node tests/t03-t08-member-flow-runtime-smoke.js http://localhost:5173
node tests/root-pages-runtime-smoke.js http://localhost:5173
```

Expected: 全部 PASS。

---

### Task 4: 全量验证与视觉检查

**Files:**
- Verify only: all modified files.

**Interfaces:**
- Consumes: Tasks 1–3 的加载组件和页面状态分支。
- Produces: H5 内部候选证据，不改变验收状态。

- [ ] **Step 1: 静态与编译验证**

Run:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tests/app-loading-contract.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File tests/g01-loading-state-contract.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File tests/g-series-app-loading-contract.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File tests/module-app-loading-contract.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File tests/compile-audit.ps1
```

- [ ] **Step 2: 运行态验证**

Run G01、G 系列、T/F/N 现有 runtime smoke，任何失败均先定位状态分支，不放宽测试。

- [ ] **Step 3: 代表性截图**

捕获 G01 页面级与 G06 局部级在 320×568、360×640、360×800、412×915 的真实 H5 画面，检查无横向溢出、无错误态闪现、固定底栏不遮挡。

- [ ] **Step 4: 工作区检查**

Run: `git diff --check`

Expected: 无空白错误；现有 LF/CRLF 提示单独报告。