194 lines
9.2 KiB
Markdown
194 lines
9.2 KiB
Markdown
# 全项目数据驱动布局审核实施计划
|
||
|
||
> **执行要求：** 使用 `superpowers:executing-plans` 在当前会话逐任务执行。用户明确禁止多代理、worktree 与全部 Git 写操作，因此在已获用户“开始”授权的当前 `main` 工作区内执行，不包含提交步骤。
|
||
|
||
**目标：** 让 52 条活动路由、共享组件及封存 A06 的布局能够承受数据数量、文案长度和字号增长，同时保留确有必要的固定视觉边界。
|
||
|
||
**架构：** 新增一个扫描固定容量风险的 PowerShell 合同和精确 JSON 白名单，作为规则单一所有者；新增一个 Chrome CDP 压力脚本，对代表性重复内容注入 1／10／50 条、2～3 倍文案和 1.3 倍字号。普通内容使用自然文档流，弹层使用限高滚动，世系树从数据计算画布边界。
|
||
|
||
**技术栈：** uni-app Vue 3、SCSS、PowerShell、Node.js、Chrome CDP。
|
||
|
||
## 全局约束
|
||
|
||
- 列表验证 1／10／50 条；弹层验证 2／6／12／50 条；相册验证 1／9／30 张。
|
||
- 世系树验证 1／5／10 代及单代 1／6／12 人。
|
||
- 文案验证正常、2 倍、3 倍；字号验证默认及约 1.3 倍。
|
||
- 固定视口为 320×568、360×640、360×800、412×915。
|
||
- 不接接口、不新增路由、不改变业务语义、不删除或重绘实际资产。
|
||
- 不执行多代理、worktree、git add/commit/push/reset/checkout。
|
||
- 每个问题记录五种方案：扩大固定尺寸、增加断点、限高滚动、自然撑高、数据计算边界；按内容类型选择最优方案。
|
||
|
||
---
|
||
|
||
### 任务 1：建立全局容量风险合同与审计报告
|
||
|
||
**文件：**
|
||
- 新建：`tests/data-driven-layout-risk-allowlist.json`
|
||
- 新建：`tests/data-driven-layout-contract.ps1`
|
||
- 新建：`docs/data-driven-layout-audit_2026-07-20.md`
|
||
|
||
**接口：**
|
||
- 合同扫描 `pages/**/*.vue`、`components/**/*.vue` 的 style 块。
|
||
- 风险类型固定为 `fixed-content-height`、`clipping-overflow`、`single-line-truncation`、`fixed-grid-track`、`fixed-capacity-canvas`。
|
||
- 白名单项必须包含 `file`、`selector`、`risk`、`reason`，并拒绝失效条目。
|
||
|
||
- [ ] **步骤 1：编写失败合同**
|
||
|
||
合同提取选择器和声明，普通内容命中以下条件即失败：固定内容高度、`overflow: hidden`、`nowrap/ellipsis/line-clamp`、百分比或固定值 grid 行、固定容量 `repeat(N, ...)`。
|
||
|
||
- [ ] **步骤 2：运行合同确认 RED**
|
||
|
||
运行：
|
||
|
||
```powershell
|
||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\tests\data-driven-layout-contract.ps1
|
||
```
|
||
|
||
预期：FAIL，并至少报告 T01、G05、G06、T07、`GenealogyCard` 的已知风险。
|
||
|
||
- [ ] **步骤 3：逐项分类并写五方案审计表**
|
||
|
||
审计表每行包含：文件／选择器、真实风险、五个候选方案、最优方案、选择理由、验证用例。装饰背景、媒体比例、图标、固定导航和明确滚动视口才允许加入白名单。
|
||
|
||
- [ ] **步骤 4：运行白名单失效自测**
|
||
|
||
临时增加不存在的选择器，确认合同以“失效白名单”失败；随后移除该临时条目。
|
||
|
||
### 任务 2：共享卡片、目录和普通结果卡自然撑高
|
||
|
||
**文件：**
|
||
- 修改：`components/GenealogyCard.vue`
|
||
- 修改：`pages/tree/t07-member-directory.vue`
|
||
- 修改：`pages/genealogy/g06-search-genealogies.vue`
|
||
- 修改：相关聚焦合同
|
||
|
||
**接口：**
|
||
- 关键姓名、谱名、地区、支系和身份允许换行。
|
||
- 卡片使用 `min-height`，不得使用固定 `height` 裁切正文。
|
||
- 摘要省略仅在存在同屏完整值或明确详情入口时允许。
|
||
|
||
- [ ] **步骤 1：扩展聚焦合同并确认 RED**
|
||
|
||
明确禁止 `.directory-card` 固定高度、`.directory-card__name/.directory-card__meta` 单行截断、`.result-card` 裁切、共享卡关键字段 `nowrap`。
|
||
|
||
- [ ] **步骤 2：记录五方案并选择自然撑高**
|
||
|
||
对上述普通卡片选择方案 4；方案 1 只延后溢出，方案 2 不解决数据量，方案 3 会制造卡片内滚动，方案 5 对普通文本过度复杂。
|
||
|
||
- [ ] **步骤 3：最小修改源码**
|
||
|
||
将固定高度改为 `min-height`，移除正文裁切和关键字段强制单行，使用 `flex-wrap`、`minmax(0, 1fr)` 和自然行高。
|
||
|
||
- [ ] **步骤 4：运行聚焦合同和现有 runtime smoke**
|
||
|
||
预期：聚焦合同、G06、T03—T08 与模块响应式 smoke 全部 PASS。
|
||
|
||
### 任务 3：G05 百分比轨道改为内容驱动
|
||
|
||
**文件：**
|
||
- 修改：`pages/genealogy/g05-genealogy-overview.vue`
|
||
- 修改：`tests/g05-document-flow-contract.ps1`
|
||
- 修改：`tests/g05-overview-runtime-smoke.js`
|
||
|
||
- [ ] **步骤 1：添加长谱名、长来源、长公开说明失败断言**
|
||
|
||
检查每个内容块 `scrollHeight <= clientHeight + 1` 或容器允许自然增长，操作按钮可达。
|
||
|
||
- [ ] **步骤 2：运行确认 RED**
|
||
|
||
预期：百分比固定行导致长内容裁切或重叠。
|
||
|
||
- [ ] **步骤 3：比较五方案并选择自然撑高**
|
||
|
||
普通概览正文选择方案 4；保留真实背景比例，但让内容层以 `auto/minmax` 和自然间距排列。
|
||
|
||
- [ ] **步骤 4：修改并验证**
|
||
|
||
移除正文百分比行轨道和固定详情行高，改为内容驱动 grid/flex；运行 G05 静态、运行时与四档压力检查。
|
||
|
||
### 任务 4：T01 世系树由数据计算画布
|
||
|
||
**文件：**
|
||
- 修改：`pages/tree/t01-tree-overview.vue`
|
||
- 修改：`tests/t01-tree-state-contract.ps1`
|
||
- 修改：`tests/t01-tree-state-runtime-smoke.js`
|
||
|
||
**接口：**
|
||
- `layoutMembers`：从成员的世代和同代顺序生成 grid 行列。
|
||
- `treeCanvasStyle`：根据最大列、最大行、节点尺寸和间距返回动态 `gridTemplateColumns`、`gridTemplateRows`、`width`、`height`。
|
||
- `generationRows`：从实际成员世代分组生成，不维护固定轨道行高数组。
|
||
|
||
- [ ] **步骤 1：写动态 10 代／单代 12 人失败测试**
|
||
|
||
断言所有节点处于画布边界内、世代标签与对应节点纵向相交、画布可横纵滚动、节点正文不使用定位。
|
||
|
||
- [ ] **步骤 2：运行确认 RED**
|
||
|
||
预期：固定 `900rpx`、180×180 网格和固定世代轨道无法满足压力数据。
|
||
|
||
- [ ] **步骤 3：比较五方案并选择数据计算边界**
|
||
|
||
选择方案 5；方案 3 仅解决滚动而不解决画布容量，方案 4 无法表达关系图坐标，方案 1／2 仍有硬上限。
|
||
|
||
- [ ] **步骤 4：实现动态布局并验证**
|
||
|
||
用 computed 数据推导画布、节点和世代轨道；保留关系线局部绘制白名单。运行 T01 静态、全状态、运行时和定位合同。
|
||
|
||
### 任务 5：其余页面全量风险清零
|
||
|
||
**文件：**
|
||
- 修改：任务 1 合同报告的其余 `pages/**/*.vue`、`components/**/*.vue`
|
||
- 修改：对应聚焦测试
|
||
|
||
- [ ] **步骤 1：按风险类型逐项写 RED**
|
||
|
||
每次只处理一个选择器；普通正文优先方案 4，弹层列表优先方案 3，媒体网格优先方案 5 或稳定 `aspect-ratio` 白名单。
|
||
|
||
- [ ] **步骤 2：逐项实现最小修改**
|
||
|
||
不得顺手重构相邻代码；每行修改必须对应审计表中的风险和选择方案。
|
||
|
||
- [ ] **步骤 3：全局合同归零**
|
||
|
||
运行容量合同，预期零未白名单风险、零失效白名单。
|
||
|
||
### 任务 6：全项目压力运行和二次视觉审核
|
||
|
||
**文件：**
|
||
- 新建：`tests/data-driven-layout-runtime-smoke.js`
|
||
- 修改：`scripts/capture-chrome-page.js`（只在需要新增审计动作时）
|
||
- 修改：三份交接／验收文档与本计划
|
||
|
||
**运行接口：**
|
||
- 对代表性重复项选择器复制到 10／50 条或 9／30 项。
|
||
- 对关键文本替换为 2～3 倍真实中文长文案。
|
||
- 对页面根设置 1.3 倍字号压力类，不改变生产默认字号。
|
||
- 输出只写 `%TEMP%\jiapuapp-runtime\data-driven-layout-audit`。
|
||
|
||
- [ ] **步骤 1：编写压力脚本并确认在未修页面 RED**
|
||
|
||
检查横向溢出、正文裁切、末项可达、弹层滚动、按钮可达和树节点边界。
|
||
|
||
- [ ] **步骤 2：运行四档全量压力 smoke**
|
||
|
||
预期：所有配置用例 PASS，且 9222 仍只有一个项目页面。
|
||
|
||
- [ ] **步骤 3：捕获并检查代表性截图**
|
||
|
||
至少覆盖共享卡、普通列表、弹层、G05、T01、T07、媒体网格；每张截图必须实际打开检查。
|
||
|
||
- [ ] **步骤 4：修改后再审核一次**
|
||
|
||
把修改前后同状态同尺寸图放入同一比较图，检查裁切、边距、字体、边框、圆角和装饰资产；发现问题回到对应任务继续 RED／GREEN。
|
||
|
||
- [ ] **步骤 5：最终验证与交接**
|
||
|
||
运行容量合同、定位合同、全部相关静态合同、关键 runtime smoke、`git diff --check`，确认 `docs/design/screens/runtime/` 不存在；不运行会恢复该目录的旧脚本。文档明确自动审核不等于用户新增 `[x]` 或 Android 完成。
|
||
|
||
## 2026-07-20 执行记录
|
||
|
||
- 任务 1—5 已完成：容量合同覆盖固定内容高度、裁切、单行截断、固定 grid 行和大固定画布；最终为零未解释风险、零失效白名单。
|
||
- TDD 记录已形成：共享卡/T07/G06、G05、T01、G08/G09/G11/G12 均先看到聚焦 RED，再完成最小实现和 GREEN。
|
||
- 任务 6 已完成 H5 自动化与二次目视审核：四档视口、50 条列表/弹层、30 项媒体、10×12 世系树、长文案和 1.3 倍字号模拟通过。
|
||
- 当前停点为用户视觉复核。所有有可见变化的旧 `[x]` 只能视为候选；用户再次明确“通过”前，不维护或新增验收勾选。
|