# 前端重构续办说明（next_steps_2）

> 本文基于 `doc/frontend/next_steps.md` 的上下文，记录当前阶段的新进展、注意事项和下一步工作计划，供接力开发者参考。凡是与旧版 UI/交互存在歧义时，以 `doc/frontend/legacy_ui_spec.md` 及 `static/old_version_backup/前端备份` 目录为最终权威。

## 最新状态（相较上一版 next_steps）

1. **Pinia 引入**：`static/src/main.ts` 已创建 Pinia 实例；`useUiStore`/`useConversationStore` 落地，侧栏/会话列表基本信息改由 store 管理。App 通过 `mapWritableState` 读取这两个 store。
2. **组件化进展**：
   - `ConversationSidebar`、`LeftPanel`、`FocusPanel`、`TokenDrawer`、`PersonalizationDrawer`、`QuickMenu` 已单独成组件。
   - 聊天区拆成 `ChatArea.vue`（含全部 action 块）、输入区拆成 `InputComposer.vue`，`App.vue` 只负责传状态/事件。
3. **兼容逻辑**：
   - 自动滚动、思考块滚动锁、工具卡片等逻辑仍在 `app.ts` 中，通过对新组件暴露的 `rootEl / getThinkingRef` 引用继续工作。
   - Quick Menu/Settings/工具禁用/压缩对话等入口仍走原 methods，只是事件链路转接到了组件。

## 待办事项

1. **Pinia Store 拆分补全**
   - 参考 `doc/frontend/componentization_plan.md`，逐步迁移 `app.ts` 的数据/方法至 `useChatStore`、`useInputStore`、`useToolStore`、`useResourceStore`、`usePersonalizationStore` 等。
   - 控制流程：先搬 state，再迁 actions/watch，最后清理 `app.ts` 中重复逻辑。

2. **聊天/动作组件细分**
   - 目前的 `ChatArea` 仍包含大量内联模板，可按行动类型（Thinking/Text/System/Modify/Tool/Summary）拆成独立子组件，增强可读性与复用性。
   - Markdown 渲染、工具卡片展示、thinking-scroll 等复杂逻辑建议拆到 composable（如 `useMarkdownRenderer`、`useToolPayloadRenderer`）。

3. **输入区状态/事件整合**
   - 将 `inputMessage`、`inputLineCount`、`inputIsFocused`、`quickMenuOpen` 等迁入 store 或 composable；InputComposer 只负责展示，避免 `app.ts` 持有大量 ref。
   - 文件上传逻辑（`handleFileSelected`、`uploadSelectedFile`）可以移至 `useUploadStore` 或专用 composable，配合 InputComposer 的事件使用。

4. **Socket/轮询拆分**
   - 现有 socket 事件与轮询仍在 `app.ts`，需抽出 `useLegacySocket`、`usePolling` 等组合式函数，让各 store 订阅自己关心的事件。

5. **Overlay/Toast 组件化**
   - ToastStack/ConfirmDialog/EasterEggOverlay/ContextMenu 仍在 `App.vue`，后续需转成 `AppShell` 或独立组件，并提供订阅 API。

6. **样式与测试**
   - 长期目标是按模块拆分 `style.css`，但当前仍以遗留 CSS 为准。组件化完成后再考虑 Sass 模块化。
   - 继续保持 `npm run build` 通过；若引入 Pinia store/composable，补充单元测试/故事（可选）以防 regression。

## 推荐执行顺序

1. 完成 Input/Chat 相关 store/composable 拆分，移除 `App.vue` 的大部分 refs 和 watchers。
2. 逐步把资源/工具/子智能体等模块迁至对应 store，同时将轮询/Socket 事件拆出。
3. 在 store/composable 稳定后，再处理 Overlay/Toast/EasterEgg 等全局 UI。
4. 全量对照 `static/old_version_backup/前端备份` 与 `legacy_ui_spec` 做细节校验，确保折叠/aria/title 动作一致。

## 注意事项

- 任何新逻辑都需以 `legacy_ui_spec` 和 `static/old_version_backup/前端备份` 为准，确保视觉、交互、API 行为不偏离旧版。
- 操作 DOM 时尽量通过组件暴露出的 ref/composable，而不是直接访问 `$refs`。拆分后应逐步删除 `app.ts` 中的 DOM 引用。
- 保持现有 API / Socket 事件名不变；若有必要增加事件，请先在文档中说明。
- 在大规模迁移前，先写好过渡层（store/composable），避免一次性修改导致回退困难。
