Files

T

rain 5a31a75da0 Review changes batch 6 of 6

2026-07-20 06:52:33 +08:00

7.9 KiB

Raw Blame History

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: 实施组件

<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 消费方式

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

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

Step 5: 验证通过

Run:

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: 接入页面级分支

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

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

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

Step 4: 接入 G06 局部加载

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

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

Step 5: 验证通过

Run:

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: 实施五页分支

统一结构：

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

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

Step 4: 验证通过

Run:

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 -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 提示单独报告。

7.9 KiB Raw Blame History Unescape Escape

Global Loading System Implementation Plan

Global Constraints

Task 1: AppLoading 双变体合同

Task 2: G 系列接入

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

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

7.9 KiB

Raw Blame History

Task 1: `AppLoading` 双变体合同