# 全项目文档流迁移实施计划

> **执行要求：** 使用 `superpowers:executing-plans` 当前会话内联执行。用户禁止多代理、worktree 及全部 Git 写操作；不执行提交步骤。

**目标：** 除精确白名单内确有必要的定位职责外，清除全项目普通页面内容的全部无意义 `position` 声明（包括 `relative`），并保持现有业务状态与视觉语言。

**架构：** 以一个静态合同和精确 JSON 白名单为单一规则所有者；先完成 R02 样板，再迁移共享组件和模块页面。每批通过现有 CDP smoke、四档响应式及同尺寸截图后进入下一批。

**技术栈：** uni-app Vue 3、SCSS、PowerShell、Node.js、Chrome CDP。

## 2026-07-20 执行结果

- 合同已扫描全部 `position` 声明并去除注释干扰；初始基线为 35 个文件、390 条未白名单声明，其中 278 条为 `relative`。当前未白名单违规为 0，失效白名单为 0。
- F10 与 T01 完成后继续按 R → N → M → F → G → T → A 全面迁移，并覆盖共享组件、`ModulePage`、Tree 表单和封存 A06；没有把单页修复冒充全项目完成。
- 普通根容器、Header/Content、正文、字段、按钮和卡片使用正常文档流、flex、grid 或 grid 同单元叠放。白名单只保留固定导航、视口背景、真实弹层/Toast/遮罩/底部弹层/全屏预览、必要媒体覆盖、局部装饰与 T01 关系线等明确职责。
- 已完成迁移批次的聚焦合同、关键 H5 runtime smoke 与同尺寸前后对比；未观察到语义性可见变化。该自动结果不替代用户确认，本轮不新增 `[x]`；A06 仅静态覆盖，Android 未验证。
- `tests/t07-module-baseline-runtime-smoke.js` 因会重新生成已清理的 runtime 截图且“清空搜索恢复全部成员”断言失败，不计入通过项；核心 `tests/t03-t08-member-flow-runtime-smoke.js` 独立通过。既有资产命名与仓库交接体积失败未通过放宽阈值或删除长期资料处理。

## 全局约束

- 禁止普通内容使用无明确必要的 `relative/absolute/fixed/sticky` 或其他 `position` 声明、负外边距或以位移 transform 承担布局；按钮按压等不改变排版的交互微动效可以保留。
- 允许定位的职责为固定顶部/底部导航、独立视口背景、真实弹层，以及受明确父容器约束的纯装饰、角标、红点和关系线，必须精确白名单。
- 不删除或重绘现有资产；装饰图优先改作 background/border-image，只有确需局部叠放时保留 absolute。
- 四档为 320×568、360×640、360×800、412×915。
- 每次只修改当前批次，验证失败立即停止扩散。

---

### 任务 1：建立全项目失败合同

**文件：**
- 新建：`tests/document-flow-position-allowlist.json`
- 新建：`tests/document-flow-position-contract.ps1`

- [x] 白名单登记固定顶部／底部导航、真实弹层、Toast、独立视口背景及经审计确有必要的局部装饰、角标和关系线；每项使用精确文件+选择器+用途，不放行普通 `relative`。
- [x] 合同扫描 `pages/**/*.vue` 与 `components/**/*.vue` 的 style 块，报告不在精确白名单内的所有 `position` 声明，包括 `relative`。
- [ ] 合同继续补齐普通选择器的负 margin 和 `transform: translate(...)` 布局检查。
- [x] 2026-07-20 新口径初始基线为 35 个文件、390 条未白名单声明，其中 278 条为 `relative`；预期 FAIL，不再使用旧“37 文件／112 条”作为完整数字。

### 任务 2：F10 无意义 relative 返工样板

**文件：**
- 修改：`pages/family/f10-video-list.vue`
- 修改：`tests/f10-video-status-contract.ps1`
- 验证：`tests/f10-video-status-runtime-smoke.js`

- [ ] 先扩展 F10 聚焦合同，禁止页面根容器、Header/Content 包装、导语正文、状态卡和状态卡正文使用 `position: relative`，保留已审计装饰层的精确白名单。
- [ ] 运行聚焦合同确认 RED。
- [ ] 使用正常文档流和 grid 同单元叠放移除 6 条无意义 `relative`，装饰图不得承担正文排版。
- [ ] 运行全局定位合同，确认 F10 的 6 条 `relative` 违规归零且其他基线未被掩盖。
- [ ] 复用唯一 5173／9222 项目页执行四档 smoke 和同尺寸前后截图；有可见变化时 F10 退回 `[~]`，只有用户重新明确通过才能维持 `[x]`。

### 任务 3：T01 世代栏与成员节点文档流

**文件：**
- 修改：`pages/tree/t01-tree-overview.vue`
- 修改：`tests/t01-tree-state-contract.ps1`
- 修改：`tests/t01-all-states-visual-contract.ps1`
- 验证：`tests/t01-tree-state-runtime-smoke.js`

- [ ] 聚焦合同先禁止 `.generation-band`、`.generation-rail` 和 `.member-node` 使用定位摆放普通节点内容，关系线只保留经审计的局部绘制职责。
- [ ] 运行聚焦合同确认 RED。
- [ ] 世代栏、成员节点和节点正文改为 grid/flex 文档流；关系线使用 grid 边框或受父容器约束的精确白名单层。
- [ ] 运行 T01 状态合同、全状态视觉合同、运行时 smoke 和全局定位合同。
- [ ] 复用唯一项目页完成正常、状态、节点选择和四档同尺寸对比；有可见变化时 T01 退回 `[~]` 等待用户重新确认。

### 任务 4：R02 文档流样板复核

**文件：**
- 修改：`pages/records/r02-person-detail.vue`
- 修改：`tests/r02-person-detail-contract.ps1`
- 修改：`tests/r02-person-detail-runtime-smoke.js`

- [ ] 先扩展 R02 合同，禁止文件内 `absolute/fixed/sticky` 并要求题签、卡片、短字段、长字段和状态卡使用 background + flex/grid。
- [ ] 运行确认 RED。
- [ ] 删除装饰 `<image>` 叠层；对应容器使用 records 资产作为背景。
- [ ] 题签 copy、字段 label/input、textarea、状态文案全部使用文档流；容器高度由内容和 min-height 控制。
- [ ] 运行 R02 合同、入口交互 smoke、四档 smoke，捕获 412×915 详情和编辑态供复核。

### 任务 5：共享基础组件

**文件：** `components/AppButton.vue`、`PageHeader.vue`、`AppTabbar.vue`、`ModulePageBackground.vue`、`GenealogyPageBackground.vue`、`GenealogyCard.vue`

- [ ] 每个组件先新增聚焦合同并确认 RED。
- [ ] PageHeader 与 AppTabbar 保留 fixed，并分别提供正常流顶部占位和页面底部避让；按钮/Header 的局部装饰、角标与红点逐项判断，能用背景则转背景，必须叠放则精确白名单；独立视口背景层可保留 fixed。
- [ ] GenealogyCard 内容改 flex/grid，皮肤转背景。
- [ ] 对 G01、T07、F01、R01、N01、M01 六基准做四档和同尺寸回归。

### 任务 6：通用 ModulePage

**文件：** `components/ModulePage.vue` 及其聚焦测试

- [ ] 合同禁止普通表单、列表、详情、时间轴、设置和状态卡定位。
- [ ] 装饰图转背景；字段用 grid；卡片内容自然撑高。
- [ ] 执行全部消费 ModulePage 的路由 smoke 和四档回归。

### 任务 7：模块分批迁移

- [ ] R → N → M → F：每页先合同 RED，再改文档流，再跑模块四档。
- [ ] G：保留真实弹层白名单，页面卡片、表单、Header 和普通内容全部文档流；独立视口背景只保留精确白名单。
- [ ] T：T01 完成后，继续把目录和表单迁移到 grid/flex。
- [ ] A：登录、注册、重置和封存 A06 的普通内容文档流；验证弹窗／Toast 保留精确白名单。

### 任务 8：最终收敛

- [ ] `tests/document-flow-position-contract.ps1` 最终 PASS，输出零普通内容违规。
- [ ] 运行活动路由转换、关键交互 smoke、四档响应式和 `git diff --check`。
- [ ] 更新验收规划与交接记录，逐一说明冻结页是否保留 `[x]`；没有截图或用户确认不得宣称视觉冻结完成。