242 lines
7.9 KiB
Markdown
242 lines
7.9 KiB
Markdown
# 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 提示单独报告。
|