# 迁移执行与检查清单

## 迁移前分析

在动手迁移前，必须完成以下分析并输出**迁移分析报告**：

1. **存量盘点**
   - 页面数量、功能模块数量
   - 依赖的 jQuery 插件及替代方案（如 DataTables → TanStack Table）
   - 现有 API 调用方式、是否有统一封装
   - 是否有服务端模板（JSP/Thymeleaf/EJS 等）需要保留、局部替换或改为纯前端渲染
   - 目标栈是 React/Vue/Next/Nuxt、现代 MPA，还是只做局部 TypeScript/构建/测试现代化

2. **依赖关系**
   - 页面间共享的 JS/CSS 模块
   - 跨页面复用的业务逻辑
   - 与后端的接口契约（是否需调整）

3. **迁移优先级**
   - 按业务价值、复杂度、耦合度排序
   - 优先迁移独立模块、低耦合页面
   - 识别可复用的工具函数、常量、类型定义

## 分阶段迁移流程

### 阶段 0：准备

- 搭建或识别目标项目骨架：React/Vue/Next/Nuxt、现代 MPA，或现有项目内的渐进式 TypeScript/构建入口
- 配置 ESLint、Prettier、测试框架
- 建立 `services/request.ts` 统一请求层，与现有 API 兼容
- 将遗留项目中的 `utils`、`constants` 逐步迁移并补充类型

### 阶段 1：基础层

- 迁移并类型化 API 调用（`$.ajax` → `axios`/`fetch`）
- 迁移工具函数（日期、格式化、校验等）
- 迁移常量、枚举、类型定义
- 建立目标导航/页面入口骨架；未迁移页面可继续走旧路由、重定向、iframe 或微前端嵌入

### 阶段 2：按模块/页面迁移

- 每次迁移一个完整功能或页面
- 从简单到复杂：静态页 → 列表页 → 表单页 → 复杂交互页
- 迁移时提取可复用组件，遵循目标 React 或 Vue 项目的目录结构
- 每完成一个模块，补充单元测试和 E2E 关键路径

### 阶段 3：收尾

- 按迁移策略移除或冻结旧代码入口；若保留 MPA，则收敛旧入口并完成现代化边界
- 配置 404、错误边界、全局错误处理
- 性能优化（懒加载、代码分割、缓存策略）
- 文档更新、部署流程调整

## 重构实施要求

迁移时需遵循以下实施约束，确保视觉与交互一致、代码更简洁易维护。

### 图片与图标

- 直接使用原项目的图片资源路径，不重新托管或替换
- 可使用 SVG 图片（`<img src="*.svg" />` 或 CSS `background-image`）；图标组件或可访问交互确需内联 SVG 时，应遵循目标项目图标规范并说明理由。
- 若原项目使用了 iconfont 或 IcoMoon 图标，重构时优先继续使用，保持图标体系一致；替换为其他图标方案前需评估视觉一致性、包体和维护成本。
- 图标优先使用原项目已有的图标文件（iconfont / IcoMoon / 已有 SVG），必要时可引入 SVG 文件作为独立资源

### 国际化（i18n）

- 新栈代码（React / Vue 等）中的用户可见文案须走项目 i18n，不在新代码里硬编码中/英文案
- 遗留 HTML/JS 中**不要新增**用户可见硬编码文案，除非纯静态且仓库尚无可用 i18n 接入点；改动文案前先查 locales 是否已有条目，并同步主要语言文件
- key 按页面/模块/语义组织，复用既有 key；仅当旧 key 为对外契约时才做映射过渡，详见项目规则中的 **国际化 (i18n)**（`templates/shared/rules/fec-i18n.md` 内「遗留代码与迁移场景」）

### 样式

- 布局样式对齐原项目视觉效果，但**只参考原项目效果，不照搬其 CSS**
- 优先使用 **flex 弹性布局**，避免 `float`、复杂 `position`、冗余嵌套
- 避免不合理写法：如 `!important` 滥用、过深选择器、重复定义
- 组件中优先避免内联样式（`style={{ ... }}` / `style="..."`）；确需使用运行时动态值、第三方组件 API 或 CSS 变量桥接时，应保持局部、可解释，并优先放入目标项目样式体系。

### 目标

- **视觉和交互**：与原项目一致，用户无感知差异
- **代码质量**：更简洁、易维护，符合目标框架规范
- **业务功能**：与原项目保持一致，**不得缺失功能**；迁移前后行为等价

### 验证分层

- 涉及页面、组件、路由、表单、弹窗、导航或关键用户流程的迁移，先建立重构前后的行为清单，再使用 Playwright 或同等真实浏览器验证方式对关键路径做对比验证。
- 对视觉敏感页面，补充截图对比或人工截图验收；动态内容、动画、字体和环境差异需明确屏蔽、稳定化或说明。
- 对纯逻辑、类型、构建或无 UI 的迁移，不强制 Playwright，应选择更贴近风险的验证层：type-check、unit test、component test、build 或 lint。
- 验证目标不是像素级完全一致，而是确认业务功能无缺失、关键交互等价、主要视觉布局无非预期偏差，并且代码比旧实现更清晰、可维护。

## 迁移检查清单

每个迁移单元完成后，确认：

- [ ] 已建立重构前后的行为清单，覆盖公共 API、路由、表单、权限、错误状态、缓存、埋点和关键交互
- [ ] 业务逻辑与旧实现一致，无功能遗漏，功能完整等价
- [ ] 涉及 UI、交互或关键流程的迁移已使用 Playwright 或同等真实浏览器验证方式完成关键路径对比
- [ ] 视觉敏感页面已完成截图对比或人工截图验收，并说明动态内容、动画、字体和环境差异处理方式
- [ ] 纯逻辑、类型、构建或无 UI 迁移已选择更贴近风险的验证层，不强制套用 Playwright
- [ ] 类型定义完整，无 `any` 滥用
- [ ] API 调用使用统一 request 层，错误处理完整
- [ ] 表单校验、loading、空状态、错误状态已实现
- [ ] 可访问性：表单有 label、交互可键盘操作
- [ ] 无 XSS 风险（用户输入已转义或使用安全 API）
- [ ] 关键路径有测试覆盖
- [ ] 符合目标栈的项目规范（React / Vue / Next / Nuxt / MPA 现代化等）
- [ ] 图片使用原项目资源；图标体系优先沿用原项目或目标项目规范，例外已说明
- [ ] 样式参考原项目效果但不照搬 CSS，优先使用目标项目样式体系，内联样式例外已说明
- [ ] 视觉与交互与原项目一致，代码更简洁易维护
- [ ] 新代码路径文案已 i18n；遗留层未扩大硬编码；locales 检索与多语言同步已完成（参见 i18n 规则迁移补充清单）