ln-721-frontend-restructure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ln-721-frontend-restructure

ln-721-前端结构重构

Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-720-structure-migrator

Frontend structure worker with two modes: SCAFFOLD (generate minimal React project from template) or RESTRUCTURE (migrate monolith to component-based architecture).

类型： L3 处理工具 分类： 7XX 项目初始化 父级工具： ln-720-结构迁移工具

这款前端结构处理工具包含两种模式：SCAFFOLD（从模板生成极简React项目）和RESTRUCTURE（将单体应用迁移为组件化架构）。

Mode Selection

模式选择

Mode	When	Input	Output
SCAFFOLD	CREATE pipeline — no existing frontend	Target stack config from ln-720	Minimal React + Vite project (~7 files)
RESTRUCTURE	TRANSFORM pipeline — existing frontend found	Monolithic React source	Component-based architecture

模式	适用场景	输入	输出
SCAFFOLD	创建流水线场景——无现有前端项目	来自ln-720的目标技术栈配置	极简React + Vite项目（约7个文件）
RESTRUCTURE	转换流水线场景——存在现有前端项目	单体式React源码	组件化架构

Purpose & Scope

目标与范围

Aspect	Description
Input	Target stack config (SCAFFOLD) or monolithic React source (RESTRUCTURE)
Output	Minimal project (SCAFFOLD) or component-based architecture (RESTRUCTURE)
Framework	React + TypeScript + Vite

Scope boundaries:

SCAFFOLD: generates minimal starter files, no business logic
RESTRUCTURE: restructures existing code, does not add new functionality
Works with React + TypeScript projects
Applies transformation rules from reference files

维度	说明
输入	目标技术栈配置（SCAFFOLD模式）或单体式React源码（RESTRUCTURE模式）
输出	极简项目（SCAFFOLD模式）或组件化架构（RESTRUCTURE模式）
技术栈	React + TypeScript + Vite

范围边界：

SCAFFOLD：仅生成极简启动文件，不包含业务逻辑
RESTRUCTURE：仅重构现有代码，不添加新功能
仅支持React + TypeScript项目
基于参考文件中的转换规则执行操作

Workflow

工作流程

SCAFFOLD Mode (CREATE pipeline)

SCAFFOLD模式（创建流水线）

Phase	Name	Actions	Output
S1	Generate	Create minimal React + Vite + TypeScript project files	~7 starter files
S2	Verify	Check file structure, validate configs	Valid project skeleton

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

RESTRUCTURE Mode (TRANSFORM pipeline)

RESTRUCTURE模式（转换流水线）

Phase	Name	Actions	Output
1	Analyze	Scan source, detect component types, measure complexity	File inventory, complexity metrics
2	Plan	Apply split thresholds, calculate file moves, detect conflicts	Migration plan
3	Execute	Create folders, extract content, update imports	Restructured files
4	Verify	Run build, check imports, validate structure	Build success report

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

SCAFFOLD Mode Phases

SCAFFOLD模式阶段

Phase S1: Generate Starter Files

阶段S1：生成启动文件

Create minimal React + Vite + TypeScript project.

File	Purpose
`package.json`	Dependencies: react, react-dom, typescript, vite, @vitejs/plugin-react
`vite.config.ts`	Vite config with React plugin, port, proxy settings
`tsconfig.json`	Strict TypeScript config with path aliases
`index.html`	Entry HTML with root div
`src/main.tsx`	React entry point with StrictMode
`src/App.tsx`	Root App component with router placeholder
`src/index.css`	Base styles (reset, variables, layout)

创建极简React + Vite + TypeScript项目。

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

Phase S2: Verify Scaffold

阶段S2：验证搭建结果

Check	Method	Expected
All files created	File existence check	7 files present
package.json valid	JSON parse	No syntax errors
tsconfig.json valid	JSON parse	No syntax errors
No hardcoded values	Content scan	Project name from config, not hardcoded

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

RESTRUCTURE Mode Phases

RESTRUCTURE模式阶段

Phase 1: Analyze

阶段1：分析

Scan current frontend structure and classify components.

Step	Action	Reference
1.1	Scan all `.tsx` and `.ts` files in source	—
1.2	Measure file complexity (lines, hooks, types)	`transformation_rules.md`
1.3	Classify components by category	`component_patterns.md`
1.4	Build import dependency graph	`import_strategy.md`

Output: Component inventory with classifications and metrics.

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

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

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

Phase 2: Plan

阶段2：规划

Generate migration plan based on analysis.

Step	Action	Reference
2.1	Apply split thresholds to identify files to restructure	`transformation_rules.md`
2.2	Calculate target paths for each file	`react_folder_structure.md`
2.3	Identify import updates needed	`import_strategy.md`
2.4	Detect potential conflicts (name collisions, circular deps)	—

Output: Migration plan with Before/After mapping.

基于分析结果生成迁移计划。

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

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

Phase 3: Execute

阶段3：执行

Apply transformations in correct order.

Step	Action	Notes
3.1	Create directory structure	All target folders
3.2	Extract types to `types.ts`	Types have no dependencies
3.3	Extract constants to `constants.ts`	Constants depend only on types
3.4	Extract hooks to `hooks.ts`	Hooks depend on types, constants
3.5	Extract sub-components	Components use all above
3.6	Create barrel exports ( `index.ts` )	For clean imports
3.7	Update all import paths	Fix references

Order is critical: Execute in sequence to avoid broken imports.

按正确顺序应用转换操作。

步骤	操作	注意事项
3.1	创建目录结构	生成所有目标文件夹
3.2	将类型提取至 `types.ts`	类型无依赖项
3.3	将常量提取至 `constants.ts`	常量仅依赖类型
3.4	将hooks提取至 `hooks.ts`	hooks依赖类型和常量
3.5	提取子组件	组件依赖上述所有内容
3.6	创建桶导出文件（ `index.ts` ）	实现简洁的导入方式
3.7	更新所有导入路径	修复引用关系

执行顺序至关重要：需按顺序执行，避免导入关系断裂。

Phase 4: Verify

阶段4：验证

Validate restructured project.

Check	Command	Expected
TypeScript compilation	`npx tsc --noEmit`	No errors
Build	`npm run build`	Success
No orphan files	Manual check	Source location empty
Imports resolve	Build success	No module not found errors

验证重构后的项目。

检查项	命令	预期结果
TypeScript编译	`npx tsc --noEmit`	无错误
构建	`npm run build`	执行成功
无孤立文件	手动检查	原源码目录为空
导入路径可解析	构建成功	无“模块未找到”错误

Transformation Summary

转换总结

Transformation	Before State	After State
Component Split	Single file >300 lines	Feature folder with co-located files
Type Extraction	Inline interfaces	Separate `types.ts`
Constant Extraction	Inline magic values	Separate `constants.ts`
Hook Extraction	Inline useState/useEffect	Separate `hooks.ts` or shared hooks
UI Component Move	Scattered in features	Centralized in `components/ui/`
Layout Component Move	Mixed with features	Centralized in `components/layout/`

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

Critical Rules

核心规则

Mode Awareness: SCAFFOLD creates from template; RESTRUCTURE transforms existing — never mix
Single Responsibility: Handle only frontend structure, no backend changes
Idempotent: Can re-run without duplicate files or corruption
Build Verification: Must verify build passes after changes (RESTRUCTURE:
```
npm run build
```
)
Preserve Functionality: No behavioral changes, only structural (RESTRUCTURE mode)
Backup Strategy: Do not delete source files until verification passes (RESTRUCTURE mode)
Import Consistency: Use path aliases for shared, relative for co-located

模式感知：SCAFFOLD模式从模板创建项目；RESTRUCTURE模式转换现有项目——切勿混合使用
单一职责：仅处理前端结构，不修改后端内容
幂等性：可重复执行，不会产生重复文件或损坏项目
构建验证：修改后必须验证构建是否通过（RESTRUCTURE模式：执行
```
npm run build
```
）
保留功能：仅修改结构，不改变行为（RESTRUCTURE模式）
备份策略：验证通过前，请勿删除原源码文件（RESTRUCTURE模式）
导入一致性：共享模块使用路径别名，同域文件使用相对路径

Definition of Done

完成标准

SCAFFOLD mode:

All 7 starter files generated
package.json and tsconfig.json valid
No hardcoded project names (uses config values)

RESTRUCTURE mode:

All source files analyzed and classified
Migration plan generated with Before/After mapping
Directory structure created per template
All extractions completed (types, constants, hooks, components)
Import paths updated throughout project
```
npm run build
```
passes successfully
No orphan imports or missing files
Barrel exports created for shared folders

SCAFFOLD模式：

已生成全部7个启动文件
package.json和tsconfig.json配置有效
无硬编码项目名称（使用配置值）

RESTRUCTURE模式：

所有源码文件已完成分析与分类
已生成包含前后映射关系的迁移计划
已按模板创建目录结构
已完成所有提取操作（类型、常量、hooks、组件）
已更新项目中所有导入路径
```
npm run build
```
执行成功
无孤立导入或缺失文件
已为共享文件夹创建桶导出文件

Risk Mitigation

风险缓解

Risk	Detection	Mitigation
Build failure after restructure	`npm run build` fails	Rollback: restore from source, investigate specific error
Missing imports	Module not found errors	Scan all imports before/after, update missed paths
Circular dependencies	Build warning or runtime error	Analyze dependency graph, break cycles by extracting shared code
Lost functionality	Tests fail or UI broken	Run existing tests before/after transformation
Name collisions	Duplicate export names	Rename with feature prefix before moving

风险	检测方式	缓解措施
重构后构建失败	`npm run build` 执行失败	回滚：从原源码恢复，排查具体错误
缺失导入	“模块未找到”错误	扫描重构前后的所有导入路径，更新遗漏的路径
循环依赖	构建警告或运行时错误	分析依赖关系图，通过提取共享代码打破循环
功能丢失	测试失败或UI异常	转换前后运行现有测试用例
名称冲突	导出名称重复	迁移前添加功能前缀重命名

Reference Files

参考文件

File	Purpose
`references/transformation_rules.md`	Split thresholds, extraction rules, transformation order
`references/component_patterns.md`	Component classification by category
`references/import_strategy.md`	Import update rules, path aliases, barrel exports
`references/react_folder_structure.md`	Target directory structure template

Version: 3.0.0 Last Updated: 2026-02-07

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

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