60 lines
5.0 KiB
Markdown
60 lines
5.0 KiB
Markdown
# 前端重构续办说明（next_steps_4）
|
||
|
||
> 承接 `next_steps_3`，本阶段工作完成了“第二阶段：业务面板与个性化”的全部目标，并准备进入“第三阶段：全局壳层与 Socket/Overlay 拆解”。下文总结当前状态、仍需处理的事项及建议顺序，供下一位开发者参考。若与 `legacy_ui_spec.md` 有冲突，请以规范文档为准。
|
||
|
||
## 阶段成果回顾
|
||
|
||
1. **文件/待办/右键菜单**
|
||
- 新增 `useFileStore` 托管 `fileTree`/`expandedFolders`/`todoList` 与右键菜单；文件树更新、右键定位、下载入口、TODO Socket 事件均通过 store 维护，`LeftPanel` 与 `FileNode` 直接消费 store 状态。
|
||
- 上传/下载触发链路保留在 `app.ts`，但右键显示/隐藏、目录展开逻辑已与模板解耦。
|
||
|
||
2. **聚焦面板**
|
||
- 新增 `useFocusStore` 负责 `/api/focused` 拉取与 `focused_files_update` Socket 事件，`FocusPanel` 直接订阅 Pinia 状态；聚焦变化时的 Token 刷新仍由 `resourceStore` 完成。
|
||
|
||
3. **子智能体**
|
||
- 新增 `useSubAgentStore` 托管列表数据与轮询；`LeftPanel` 切换到 store action，App 仅在 mounted/unmounted 时启动/停止 Polling，并在切换到子智能体面板时触发拉取。
|
||
|
||
4. **个性化/个人空间**
|
||
- 新增 `usePersonalizationStore`，封装整个 Drawer 的状态、表单、拖拽、保存/启停与登出逻辑；`PersonalizationDrawer` 由 store 驱动，App 只负责打开入口和上传/Socket 相关联动。
|
||
|
||
5. **App.vue/App.ts 解耦**
|
||
- 删除了原有的 `fileTree/focusedFiles/todoList/subAgents/personalization` data 字段、方法与 watchers，将布局中对应 props/事件精简为 store 驱动。
|
||
|
||
## 当前状态
|
||
|
||
- **第一阶段（聊天/输入域）**：全部子任务已完成（状态迁移、Action 组件化、动作按钮 store 化、append/modify payload 渲染），请以 `doc/frontend/next_steps_3.md` 为参考。
|
||
- **第二阶段（业务面板/个性化）**：三个模块均完成 Pinia 化；`app.ts` 中已无业务状态，仅保留连接、聊天和工具相关逻辑。
|
||
- **第三阶段（待启动）**：App 仍承载 Socket 管理、Toast/Confirm/Overlay/EasterEgg 等壳层逻辑；`app.ts` 依旧超出推荐体量，需要继续拆解。
|
||
|
||
## 下一步建议（第三阶段）
|
||
|
||
1. **Socket 与跨模块事件**
|
||
- 抽象 `useLegacySocket()` 或类似 composable，将所有 `socket.on/emit` 管理集中到独立模块，通过事件总线或 store action 分发。目标：`app.ts` 仅负责初始化 & 注入依赖。
|
||
- 结合 `useResourceStore`/`useChatStore`/`useFileStore` 等 store，统一处理 `token_update`、`todo_updated`、`focused_files_update` 等事件，避免重复逻辑。
|
||
|
||
2. **全局壳层**
|
||
- 拆分 ToastStack、ConfirmDialog、QuotaToast、EasterEggOverlay、ContextMenu 等通用 UI，创建 `AppShell.vue` 或多个全局组件，使用 store/composable 提供状态（如 `useUiStore` 新增 toast/confirm/easterEgg slice）。
|
||
- 移除 `app.ts` 中的 DOM 事件监听（click/scroll/keydown）与手动 `document.body` 操作，改为组件级的事件绑定或 `onMounted` composable。
|
||
|
||
3. **输入/上传/工具联动**
|
||
- 虽已存在 `useUploadStore`，但上传流程、Quick Menu 与工具禁用仍在 `app.ts`；推荐将上传动作（`uploadSelectedFile`、toast 管理、错误文案）迁至新 composable/stores，并为 Quick Menu 建立独立模块。
|
||
|
||
4. **样式与可维护性**
|
||
- 当前仍使用旧版 CSS，大量样式依赖 `static/style.css`。第三阶段完成后，可按组件拆分 SCSS 或 CSS Modules（长期目标），确保 `legacy` 风格可控。
|
||
|
||
## 风险与注意事项
|
||
|
||
- **Socket 兼容**：拆分过程中确保所有 `socket.emit` 与 `socket.on` 名称、顺序保持与后端契约一致；必要时在 composable 中集中打印日志便于调试。
|
||
- **Store 循环依赖**：多个 store 之间会互相引用（如子智能体依赖 UI store 的 `panelMode`）；拆分时注意封装结构，避免在 store 初始化阶段互相 import 产生循环。
|
||
- **右键菜单/下载**：现阶段下载操作仍在 `app.ts` 中调用 `downloadResource`，但 contextMenu 状态来自 `useFileStore`；迁移时要保留 `legacy_ui_spec` 里要求的按钮标题与行为。
|
||
- **个性化**：`usePersonalizationStore` 目前直接调用 `fetch`；后续若新增 API 校验或需要与其他 store 联动，可考虑抽象 API 层，保持请求可 Mock。
|
||
|
||
## 推荐实施顺序
|
||
|
||
1. 重构 Socket 管理（建立 composable + 事件分发）。
|
||
2. 拆出 AppShell/Toast/Confirm/EasterEgg 组件，与 `useUiStore` 整合。
|
||
3. 将上传/Quick Menu/工具禁用逻辑移入专用 store/composable。
|
||
4. 在 store/composable 稳定后，继续拆分 `style.css`，并补充端到端验证脚本或自动化测试（例如聚焦文件/子智能体/Todo socket 事件回放）。
|
||
|
||
> 完成第三阶段后，`app.ts` 应仅承担框架级入口（createApp、Pinia 注册、Shell 布局），所有业务状态通过 store + 组件组合而成。请持续参考 `legacy_ui_spec.md`，确保视觉与交互严格一致。
|