furniture-3d-system-Wu/docs/solutions/workflow-issues/ui-monolith-workspace-modularization-batch-20260216.md

UI 大文件拆分为工作区模块（批量案例）

• 日期：2026-02-16
• 适用范围：前端超大组件（页面/3D 编辑器/弹窗）因“壳文件转发”被审查驳回，需做实质拆分。

问题特征

1. 单文件超过 500~800 行，状态、请求、渲染全部混在一起。
2. 之前只做了 *.container.tsx -> *.workspace.tsx 的壳层迁移，审查仍判定为未拆分。
3. 复核关注点不是“文件名变化”，而是“职责分层是否可见”。

解决方案（本次落地）

1. 先补齐可编译基线，避免在红灯状态做结构重构。
2. 按“容器编排 + 业务 hooks + 视图区块组件”拆分：
   • Assembly：hooks/useAssemblyEditorState.ts + 顶栏/预览/步骤面板组件。
   • Home：home/hooks/* + home/components/HomeModelsSection.tsx。
   • ProductDetail：顶部栏、信息卡、创建分享弹窗拆成独立组件。
   • SKUDetail：顶部动作区、只读侧栏、规格切换抽屉拆分。
   • HoleViewer：渲染层 hook + 控制层 hook + 图例统计组件。
   • AddSKUModal：schema + submit hook + 字段分组组件。
   • HoleEditor：types + validation + interaction hook。
3. 每个拆分点都保持原有行为不变，Workspace 只做组装。

验证方式

1. npm run type-check -- --pretty false
2. npm test -- tests/api/auth-me.test.ts --runInBand
3. npm test -- tests/lib/zip-parser.test.ts --runInBand
4. npm test -- tests/services/sku-upload.service.test.ts --runInBand

复用清单

1. 先找“状态管理块”和“大段 JSX 区块”，优先抽这两类。
2. hooks 命名按能力域（use-xxx），组件命名按区域（TopBar/Sidebar/Modal）。
3. 重构后保留统一入口（container/workspace），避免页面导入路径抖动。
4. 台账同步标注“已修复待复核”，并写清新增模块文件路径。