jiapuapp/docs/superpowers/specs/2026-07-20-project-data-driven-layout-audit-design.md

全项目数据驱动布局审核设计

日期：2026-07-20
阶段：H5 视觉与布局韧性，不接接口，不宣称 Android 完成
约束：不使用多代理或 worktree，不执行 Git 写操作，不删除源码、测试、文档、长期截图或实际资产

目标

在全项目文档流迁移完成后，再以真实数据增长为前提审核 pages/、components/、52 条活动路由及封存 A06。当前 Mock 数量或短文案能显示正常，不再视为数据驱动布局通过。

审核必须证明：列表、卡片、表单、弹层、相册、世系树和共享组件能够由数据数量、文案长度和字号自然驱动；固定尺寸只用于图标、媒体比例、明确的装饰槽位和视口级导航等稳定视觉边界。

压力基线

• 列表：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。

审核分类

1. 普通页面和共享卡片：检查固定 height、固定 grid 行、overflow: hidden、单行截断、不可换行和固定项目数量假设。
2. 列表和目录：检查数据增加后页面自然增长、末项可达、底部导航避让和滚动所有权。
3. 弹层和底部层：检查少量内容自然增长、大量内容达到 max-height 后内部滚动、标题和操作区不被挤出。
4. 表单和状态页：检查错误文案、长标签、长输入值、键盘前后及成功／失败信息自然撑高。
5. 媒体网格：检查项目数量改变、长说明、失败状态和当前项标识；媒体缩略图可保留稳定 aspect-ratio。
6. 世系树：检查画布宽高、世代轨道、节点坐标和关系线是否由数据边界推导；不允许固定 900rpx 或固定 180×180 网格成为容量上限。

每项问题的五方案决策

每个确认问题都必须记录下列五种候选方案，并按该问题的内容类型选择最优方案，不机械套用同一种 CSS：

1. 扩大固定尺寸：改动最小，但只是推迟溢出，默认淘汰。
2. 增加尺寸断点：适合设备差异，不解决未知数据量，通常只作补充。
3. 容器限高并滚动：适合弹层、独立列表和全屏画布；普通卡片不使用。
4. 正常文档流自然撑高：适合正文、表单、状态卡、普通列表卡和长文案；为普通内容首选。
5. 由数据计算布局边界：适合世系树、媒体网格、可变列数和结构化关系；由数据推导行列、画布和连接关系。

选择顺序：普通内容优先方案 4；独立滚动容器优先方案 3；结构化画布优先方案 5。方案 1 不作为最终修复，方案 2 只处理确实由视口造成的差异。

实施规则

• 先建立全局静态容量合同，列出风险选择器，但对白名单视觉边界做精确说明，不能简单禁止所有固定尺寸。
• 每个确认问题先添加最小失败测试并看到预期 RED，再修改源码。
• 卡片默认使用 min-height 和自然撑高；文本默认允许换行。只有同时存在完整值查看路径、非关键摘要语义和明确空间边界时才允许省略号。
• 页面主列表使用正常文档流；弹层列表、固定导航下的独立区域和世系画布可以拥有明确滚动容器。
• 背景图使用 background、九宫格或稳定比例承载装饰，不让装饰图高度决定正文容量。
• 不改变接口、路由、业务状态含义、当前视觉资产和用户已确认的色彩／字体／装饰语言。

验证与证据

1. 静态容量合同为零未解释风险。
2. 每类页面运行压力数据 smoke，检查横向溢出、内容裁切、末项可达、滚动所有权和操作区可达。
3. 使用唯一 5173／9222 Chrome 项目页，在四档尺寸获取当前审核运行的新截图。
4. 修改后再次获取同状态、同尺寸截图；将修改前后放入同一比较图检查可见变化。
5. 自动化与截图只能证明候选稳定，不能代替用户视觉确认或新增 [x]。

已知首轮风险

• T01 使用固定 900rpx 画布、固定 180×180 网格及固定世代轨道行高，属于高风险。
• G05 使用百分比固定行轨道和局部固定行高，长文案可能挤压。
• G06 结果卡在可增长内容上保留 overflow: hidden，存在裁切风险。
• T07 成员卡固定高度，姓名和成员信息强制单行省略，存在长数据风险。
• 共享 GenealogyCard 的谱名、元信息、角色与更新时间多处不换行，存在真实数据截断风险。
• G01 切换家谱弹层已验证 2／6／12 条可增长与滚动，是可复用的弹层容量参考。

完成边界

本轮完成只表示 H5 数据容量候选通过源码合同、压力运行和同尺寸视觉回归。A06 封存路由只做静态检查；Android/HBuilderX、系统键盘、真实接口数据和设备级字体缩放仍需后续单独验证。既有 foundation-asset-audit 与 repository-handoff-size-contract 失败不得通过放宽阈值或删除长期资料处理。