# 全项目文档流迁移设计

## 目标

把项目中除固定顶部导航栏、固定底部导航栏、真实弹窗、Toast、遮罩、底部弹层和全屏预览外的页面结构全部改为正常文档流，消除正常文字、输入框、按钮、卡片和背景依赖 `absolute`、`fixed` 或 `sticky` 的布局风险。迁移覆盖 `pages/`、`components/`、活动页面和封存的 A06 源码，不接接口、不删除资产。

## 当前证据

旧只读审计只发现 37 个 Vue 文件包含 `position: absolute|fixed|sticky`，漏掉了普通容器上的 `relative`，因此旧“剩余 112 条”无效。2026-07-20 扩展合同后，新口径发现 35 个文件存在 390 条未白名单 `position` 声明，其中 278 条为 `relative`；F10 一页即有 6 条无意义 `relative`。用法混合了正常内容、装饰图层、页面背景、Tabbar、世系关系线和真实弹层，不能机械删除。R02 已证明普通文字、字段标签和输入框也被定位到装饰图之上，系统字体、长文案、键盘或尺寸变化时存在重叠风险。

## 执行状态

2026-07-20 已按本设计完成全项目源码迁移。合同从上述 390 条未白名单声明收敛为零，并增加失效白名单检查，保证白名单与源码实际定位逐项对应。迁移覆盖共享组件、R/N/M/F/G/T/A 页面及封存 A06；普通内容改用正常文档流、flex、grid 或 grid 同单元叠放，只有本设计列出的明确职责保留定位。H5 同尺寸回归未发现语义性可见变化，但这不替代用户确认；本次不新增视觉 `[x]`，不宣称 Android 或接口完成。

## 单一合同

- 正常页面内容只允许块级流、flex、grid、gap、padding、margin 和内容自然撑高。
- 禁止用 `absolute`、`fixed`、`sticky`、负外边距或位移 transform 摆放普通文字、输入、按钮、卡片、页面背景或世系节点。
- `position: relative` 虽不脱离文档流，但普通内容无明确必要时不使用；不得以它作为重新叠放内容的前置手段。
- 装饰框优先使用 `background-image`、`border-image` 或九宫格背景；确实需要叠在明确局部容器内的纯装饰图层、角标和红点可以使用 `absolute`，但不得承担正文排版。
- 世系节点使用 grid/flex 文档流；关系线属于节点间局部绘制层，可按实际结构使用 grid 边框或受父容器约束的 `absolute`，不得用定位摆放节点正文。
- 允许定位的职责只有：固定顶部/底部导航、独立视口背景层、真实弹窗、Toast、遮罩、底部弹层、全屏预览，以及受明确父容器约束的纯装饰/角标/关系线。顶部、底部导航使用 `position: fixed`，页面内容通过正常流占位和安全区 padding 避让。每条例外必须进入精确白名单，记录文件、选择器和用途，不允许按模糊类名放行。
- 合同所有者为 `tests/document-flow-position-contract.ps1`，白名单为 `tests/document-flow-position-allowlist.json`。合同必须扫描所有 `position` 声明，包括 `relative`；普通容器不得因叠层或 z-index 习惯而残留无意义定位。运行代码、文档和其他测试不得重新定义第二套例外规则。

## 迁移顺序

1. 建立扫描全部 `position` 的合同和精确白名单，以 35 文件／390 条未白名单声明作为新初始基线；测试先失败并输出全部违规位置。
2. F10 先移除页面根容器、Header/Content、正文和卡片的 6 条无意义 `relative`，作为新口径最小返工样板。
3. T01 随后迁移世代栏与成员节点；节点正文使用 grid/flex，关系线只保留经审计的局部绘制职责。
4. 复核 R02 样板并迁移共享控件：AppButton、PageHeader、AppTabbar、ModulePageBackground、GenealogyPageBackground、GenealogyCard；PageHeader 与 AppTabbar 保留用户指定的 fixed 白名单，清除其内部普通内容定位；弹层组件保留白名单定位。
5. 迁移 `ModulePage`，让普通 F/R/N/M 页面共享文档流结构。
6. 按 R → N → M → F → G → T → A 迁移其余专属页面；A06 源码也纳入静态合同。
7. 每批执行聚焦合同、现有交互 smoke、四档响应式、真实截图和 `git diff --check`。

## 冻结页

当前冻结页不自动取消 `[x]`。每次共享组件或页面迁移后进行同尺寸前后对比：无可见变化且四档通过则保留；有任何可见变化则退回 `[~]` 等待用户复核。不得用自动化通过替代用户确认。

## 验收门槛

- 全项目合同最终为零未白名单违规；白名单只含固定顶部/底部导航、独立视口背景、真实弹层/Toast/遮罩/底部弹层/全屏预览，以及经审计确有必要的局部装饰、角标和关系线。
- 52 条活动路由和封存 A06 源码均被扫描。
- 四档固定为 320×568、360×640、360×800、412×915。
- 长文案、约 1.3 倍字号、输入校验和键盘场景不重叠，操作区可滚动到达。
- 5173 和唯一 9222 Chrome 标签继续复用；不声明 Android 已完成。

## 边界

不执行多代理、worktree、git add/commit/push/reset/checkout；不删除、覆盖或清理现有修改、未跟踪文件、测试、文档、截图、母版和候选资产。已知仓库治理失败不通过放宽阈值或删除文件处理。