# 前端代码瘦身与简化方案

> 目标：化繁为简，减少重复代码与文件体积，提升可维护性与一致性，确保后续迭代成本可控。

## 1. 现状痛点速记
- 页面脚本重复：各页面内嵌 fetch/toast/fallback 分支、事件委托与表单处理重复编写（如 wizard `dynamic.js` >450 行，admin `categories.js` 近 1000 行且含大段图标数据）。
- 基础模板冗余：`base.html` 自带完整导航/头部/用户区，无法按需裁剪；导航状态判断重复。
- 公共工具分散：`FormHandler`、`ModalManager`、`utils.js` 已有，但页面仍写双分支兼容（window.api / fetch、toast / showToast）。
- 静态资源过碎：`css/pages/**` 36+ 文件，样式重复；图标数据内嵌在页面脚本，无法复用与按需加载。
- 命名与结构不统一：页面入口与公共模块缺少明确分层，难以按域拆分。

## 2. 设计原则
- **单一职责**：公共能力（请求、toast、模态、表单、JSON、安全 DOM 操作）集中在核心模块，页面只写业务。
- **按域拆分**：页面入口仅做组装，业务域模块（wizard、admin categories 等）拆成 state/ui/actions。
- **按需加载**：大体积数据/模块（图标表、复杂组件）按需导入，减少首屏成本。
- **向后兼容、可渐进**：保留可回退路径，不一次性大改模板结构，优先“可无痛迁移”的改造。

## 3. 目录与模块规划
```
static/js/core/
  api.js          // 统一请求封装（headers、错误提示、重定向处理）
  toast.js        // 统一提示
  modal.js        // 统一模态（封装 bootstrap modal）
  form.js         // 表单序列化+校验+提交
  json.js         // 安全 JSON 解析
  event.js        // 事件委托/节流/防抖
  storage.js      // 本地存储（主题、用户首选项）
static/js/data/icons.js 或 static/data/icons.json // 图标数据

static/js/pages/generate/wizard/
  state.js        // 字段/难度规则/选择状态
  ui.js           // 步骤、徽章、选中态更新
  actions.js      // 提交、重置、跳转
  init.js         // 事件绑定入口（替代当前 dynamic.js 里大部分内容）
  index.js        // 页面入口（仅导入并 init）

static/js/pages/admin/categories/
  icons-panel.js  // 图标面板渲染、过滤、选择
  list.js         // 加载/渲染类别卡片
  form.js         // 新增/编辑保存逻辑
  import-export.js// 导入/导出/进度
  index.js        // 页面入口（组装各模块）
```

## 4. 核心封装设计
- `core/api.js`：基于 fetch 的轻量封装，统一 JSON 解析、错误码处理、重定向、全局 loading 钩子；暴露 `get/post/put/delete`.
- `core/toast.js`：统一 `success/info/warning/error`，封装当前 toast 库；页面不再判断 `window.toast`/`showToast`.
- `core/modal.js`：封装 bootstrap modal，提供 `show(id, options)`、`hide(id)`、`confirm({title, message, icon, okText, cancelText})`.
- `core/form.js`：统一序列化、HTML5 校验、提交（自动调用 api），支持自定义数据与 headers。
- `core/json.js`：安全解析带默认值与 debug 开关，替代各文件的 try/catch。
- `core/event.js`：事件委托、防抖/节流包装。

## 5. 模板与组件策略
- 将侧边栏、头部、用户卡片拆成 Jinja 片段：`templates/components/layout/{sidebar,header,usercard}.html`，`base.html` 只 include；为首页/登录/纯内容页提供轻量 base 变体（无侧栏版本）。
- 保持现有 class 兼容，逐步替换页面模板。

## 6. 页面级拆分要点
### Wizard（生成向导）
- 动作拆分：state（字段/规则存取）、ui（步骤/徽章/锁定）、actions（提交/重置）、init（事件绑定）。
- 移除调试与多套 fallback，统一用 core/api + core/form + core/json。
- 表单提交统一构建 FormData/URLSearchParams 由 core/form 处理；重定向判定抽到统一 util。

### Admin Categories
- 图标数据外置：按需 fetch/import；首次展开图标面板时加载。
- 列表渲染与表单保存模块化；导入/导出逻辑独立文件；删除大段内联模板字符串重复。
- 统一 toast/modal/api；删除双分支兼容与重复 console.log。

## 7. 样式与资源
- 抽取通用卡片/表格/空态样式到 `css/common/components.css`，页面差异保留小文件。
- 可选：使用简单构建（例如 npm script + PostCSS/clean-css）合并/压缩公共 CSS，生成 `css/bundle/common.css`，保留源文件方便维护。
- 图标数据改为静态 JSON/JS，按需加载，减少入口体积。

## 8. 迭代与实施顺序（可 2~3 天内完成）
1) 核心模块落地：`core/{api,toast,modal,form,json,event}.js` + 在 `base.html` 注入，保持向后兼容（旧全局名仍可指向新实现）。  
2) Wizard 拆分：重写入口 `wizard/index.js` 调用新模块，删除 `dynamic.js` 冗余分支。  
3) Categories 拆分：图标数据外置，入口组装 list/form/import-export/icons-panel；去掉重复 fetch/toast 逻辑。  
4) 模板抽片段：分离侧栏/头部/用户卡片，加入轻量 base 变体。  
5) 样式抽取与合并：提炼通用组件样式，生成公共 bundle。  
6) 清理与回归：移除遗留 fallback/console，跑 lint/手测关键流程（登录、生成向导、分类管理、导入导出）。

## 9. 风险与回滚
- 风险：全局对象替换可能影响老页面；图标数据按需加载需确认路径与跨域。  
- 缓解：核心模块保持旧全局名映射（window.api 等）；首轮保留原 JS 文件（标记 deprecated），一周后移除。  
- 回滚：通过切换 script 引用回旧文件；核心模块旁保留 `*-legacy.js` 快速兜底。

## 10. 交付检查清单
- [ ] 核心模块脚本完成并在 base 引入，旧全局接口可用。  
- [ ] Wizard 拆分后页面可正常生成任务（含重定向）。  
- [ ] Categories 页面：列表、增删改、导入导出、图标选择正常；图标数据按需加载。  
- [ ] 模板片段化后导航/头部渲染正确，移动端菜单正常。  
- [ ] CSS 公共化后主要页面无样式回退；bundle 构建脚本可运行。  
- [ ] lint/手测通过，控制台无新增错误。