修改完成

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

@@ -0,0 +1,72 @@
+# 全项目数据驱动布局审核设计
+
+> 日期：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` 失败不得通过放宽阈值或删除长期资料处理。