ln-721-frontend-restructure

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

ln-721-frontend-restructure

类型： L3 Worker 类别： 7XX 项目引导

前端结构 Worker，提供两种模式：SCAFFOLD（从模板生成最小化 React 项目）或 RESTRUCTURE（将单体应用迁移为基于组件的架构）。

---

模式选择

模式	适用场景	输入	输出
SCAFFOLD	CREATE 流水线——没有现有前端	来自 ln-720 的目标技术栈配置	最小化 React + Vite 项目（约 7 个文件）
RESTRUCTURE	TRANSFORM 流水线——发现现有前端	单体 React 源码	基于组件的架构

---

用途与范围

方面	描述
输入	目标技术栈配置（SCAFFOLD）或单体 React 源码（RESTRUCTURE）
输出	最小化项目（SCAFFOLD）或基于组件的架构（RESTRUCTURE）
框架	React + TypeScript + Vite

范围边界：

• SCAFFOLD：生成最小化起始文件，不包含业务逻辑
• RESTRUCTURE：重构现有代码，不添加新功能
• 适用于 React + TypeScript 项目
• 应用参考文件中的转换规则

---

工作流

SCAFFOLD 模式（CREATE 流水线）

阶段	名称	操作	输出
S1	生成	创建最小化 React + Vite + TypeScript 项目文件	约 7 个起始文件
S2	验证	检查文件结构，验证配置	有效的项目骨架

RESTRUCTURE 模式（TRANSFORM 流水线）

阶段	名称	操作	输出
1	分析	扫描源码，检测组件类型，衡量复杂度	文件清单、复杂度指标
2	规划	应用拆分阈值，计算文件移动，检测冲突	迁移计划
3	执行	创建文件夹，提取内容，更新导入	重构后的文件
4	验证	运行构建，检查导入，验证结构	构建成功报告

---

SCAFFOLD 模式阶段

阶段 S1：生成起始文件

创建最小化 React + Vite + TypeScript 项目。

文件	用途
package.json	依赖项：react、react-dom、typescript、vite、@vitejs/plugin-react
vite.config.ts	Vite 配置，包含 React 插件、端口和代理设置
tsconfig.json	启用严格模式且配置了路径别名的 TypeScript 配置
index.html	包含 root div 的入口 HTML
src/main.tsx	使用 StrictMode 的 React 入口点
src/App.tsx	带有路由器占位符的根 App 组件
src/index.css	基础样式（重置、变量、布局）

阶段 S2：验证脚手架

检查项	方法	预期结果
已创建所有文件	检查文件是否存在	存在 7 个文件
package.json 有效	JSON 解析	无语法错误
tsconfig.json 有效	JSON 解析	无语法错误
没有硬编码值	扫描内容	项目名称来自配置，而非硬编码

---

RESTRUCTURE 模式阶段

阶段 1：分析

扫描当前前端结构并对组件进行分类。

步骤	操作	参考
1.1	扫描源码中的所有 .tsx 和 .ts 文件	—
1.2	衡量文件复杂度（行数、hooks、类型）	transformation_rules.md
1.3	按类别对组件进行分类	component_patterns.md
1.4	构建导入依赖关系图	import_strategy.md

输出： 包含分类和指标的组件清单。

---

阶段 2：规划

根据分析结果生成迁移计划。

步骤	操作	参考
2.1	应用拆分阈值，确定需要重构的文件	transformation_rules.md
2.2	计算每个文件的目标路径	react_folder_structure.md
2.3	确定需要更新的导入	import_strategy.md
2.4	检测潜在冲突（名称冲突、循环依赖）	—

输出： 包含迁移前后映射关系的迁移计划。

---

阶段 3：执行

按正确顺序应用转换。

步骤	操作	备注
3.1	创建目录结构	所有目标文件夹
3.2	将类型提取到 types.ts	类型没有依赖
3.3	将常量提取到 constants.ts	常量仅依赖类型
3.4	将钩子提取到 hooks.ts	钩子依赖类型和常量
3.5	提取子组件	组件使用上述所有内容
3.6	创建汇总导出文件（index.ts）	便于整洁地导入
3.7	更新所有导入路径	修正引用

顺序至关重要： 按顺序执行，避免导入失效。

---

阶段 4：验证

验证重构后的项目。

检查项	命令	预期结果
TypeScript 编译	npx tsc --noEmit	无错误
构建	npm run build	成功
无孤立文件	手动检查	源位置为空
导入解析正常	构建成功	没有找不到模块的错误

---

转换摘要

转换	转换前状态	转换后状态
组件拆分	单个文件超过 300 行	包含同目录文件的功能文件夹
类型提取	内联接口	独立的 types.ts
常量提取	内联魔法值	独立的 constants.ts
钩子提取	内联 useState/useEffect	独立的 hooks.ts 或共享钩子
UI 组件迁移	分散在各功能模块中	集中到 components/ui/
布局组件迁移	与功能模块混杂	集中到 components/layout/

---

关键规则

• 模式意识： SCAFFOLD 根据模板创建；RESTRUCTURE 转换现有内容——绝不混用
• 单一职责： 仅处理前端结构，不更改后端
• 幂等性： 可重复运行，不会产生重复文件或损坏
• 构建验证： 更改后必须验证构建通过（RESTRUCTURE：npm run build）
• 保留功能： 不更改行为，仅调整结构（RESTRUCTURE 模式）
• 备份策略： 验证通过前不得删除源文件（RESTRUCTURE 模式）
• 导入一致性： 共享内容使用路径别名，同目录内容使用相对路径

---

完成定义

SCAFFOLD 模式：

• 生成全部 7 个起始文件
• package.json 和 tsconfig.json 有效
• 没有硬编码的项目名称（使用配置值）

RESTRUCTURE 模式：

• 已分析并分类所有源文件
• 已生成包含迁移前后映射关系的迁移计划
• 已根据模板创建目录结构
• 已完成所有提取（类型、常量、钩子、组件）
• 已更新整个项目中的导入路径
• npm run build 成功通过
• 没有孤立的导入或缺失文件
• 已为共享文件夹创建汇总导出文件

---

风险缓解

风险	检测方式	缓解措施
重构后构建失败	npm run build 失败	回滚：从源文件恢复，并调查具体错误
缺少导入	找不到模块的错误	扫描更改前后的所有导入，更新遗漏路径
循环依赖	构建警告或运行时错误	分析依赖关系图，提取共享代码以打破循环
功能丢失	测试失败或 UI 异常	在转换前后运行现有测试
名称冲突	导出名称重复	移动前使用功能前缀重命名

---

参考文件

文件	用途
references/transformation_rules.md	拆分阈值、提取规则、转换顺序
references/component_patterns.md	按类别进行组件分类
references/import_strategy.md	导入更新规则、路径别名、汇总导出
references/react_folder_structure.md	目标目录结构模板

---

版本： 3.0.0 最后更新： 2026-02-07