Legacy To Modern Migration

Use when planning or implementing an intentional migration from JavaScript, jQuery, HTML/CSS, server-rendered templates, MPA legacy frontend code, or older framework code toward a modern frontend stack while preserving behavior. Do not use for routine legacy bug fixes that stay in the old stack; Chinese triggers include 遗留项目, 技术栈升级, jQuery 迁移.

传统前端到现代框架迁移

适用于将 JavaScript + jQuery + HTML/CSS 多页面应用（MPA）、服务端模板渲染项目或旧框架代码，渐进迁移到 React、Vue、Next.js、Nuxt、TypeScript，或保留 MPA 形态但现代化模块、构建、类型和测试的场景。

Purpose

指导传统前端项目渐进迁移到目标现代栈，提供迁移策略、概念映射、分阶段步骤和实施约束，确保功能等价和风险可控。

Procedure

1. 先识别目标栈、迁移边界和是否保留 MPA/服务端模板形态。
2. 加载 references/migration-strategy-and-mapping.md，选择渐进式或一次性重写策略，并明确遗留模式到目标栈的映射。
3. 加载 references/migration-execution-checklist.md，完成存量盘点、依赖分析、优先级排序和分阶段迁移计划。
4. 撰写迁移分析或迁移计划报告时，加载 references/migration-report-template.md。
5. 按准备、基础层、模块/页面迁移、收尾的顺序推进，每次迁移一个可验证单元。
6. 每个迁移单元验证功能等价、视觉一致、类型安全、可访问性、i18n、资源和样式边界。

Constraints

• 迁移前必须先输出迁移分析报告，明确策略、优先级和风险。
• 不要在一次迁移中同时改架构、改 UI、改接口。
• 优先保证功能等价，再考虑优化和现代化。
• 迁移过程中保持旧系统可运行，避免大爆炸式上线。
• 遇到 jQuery 插件无现成替代时，可暂时用 iframe 或微前端方式嵌入，待后续替换。
• 目标栈先识别 React/Vue/Next/Nuxt、现代 MPA 或局部现代化目标，不默认强制改成 SPA。
• 图片使用原项目资源；图标体系优先沿用原项目或目标项目规范；内联 SVG 例外需有可访问性、组件化或维护理由。
• 样式参考原项目效果但不照搬 CSS，优先使用目标项目样式体系；内联样式例外需局部、可解释。
• 目标是视觉与交互一致、代码更简洁易维护，业务功能不得缺失。
• 涉及页面、组件、路由、表单、弹窗、导航或关键用户流程的迁移，必须建立重构前后的行为清单，并使用 Playwright 或同等真实浏览器验证方式对关键路径做对比验证。
• 对视觉敏感页面，应补充截图对比或人工截图验收；动态内容、动画、字体和环境差异需明确屏蔽、稳定化或说明。
• 对纯逻辑、类型、构建或无 UI 的迁移，不强制 Playwright，应选择更贴近风险的验证层：type-check、unit test、component test、build 或 lint。
• 验证目标不是像素级完全一致，而是确认业务功能无缺失、关键交互等价、主要视觉布局无非预期偏差，并且代码比旧实现更清晰、可维护。

Expected Output

• 迁移分析报告保存为 reports/migration-plan-YYYY-MM-DD-HHmmss.md，包含策略选择、存量盘点、依赖关系、分阶段步骤、风险与回滚方案。
• 迁移后的业务功能与原项目完全等价，无功能缺失。
• 视觉与交互与原项目一致，用户无感知差异。
• 类型定义完整，无 any 滥用，API 调用统一且类型安全。
• 图片使用原项目资源，样式进入目标项目样式体系，图标和内联样式例外有明确理由。
• 新代码文案已 i18n，关键路径有测试覆盖。