# Src 前端指引

本文件适用于 src/ 下的前端代码。进入 src/plugins/ 后，以子目录 AGENTS.md 为准。

## 前端职责

- 启动 Vue 应用并挂载路由和 Pinia。
- 提供编辑器界面、上传导出、OCR 触发、TTS 菜单、设置面板和多语言 UI。
- 把编辑器状态、设置和网络请求接到后端接口。

## 先看哪里

- 应用入口：main.js
- 根组件：App.vue
- 路由：router/index.js
- 编辑页：views/EditorView.vue
- 文档页：views/DocsView.vue
- 编辑器主组件：components/MilkdownEditor.vue
- 文件预览：components/FileContent.vue、components/OfficePreview.vue
- 设置面板：components/SettingsPanel.vue
- TTS 组件：components/TTSMenu.vue、components/TTSPlayer.vue
- 插件层：plugins/
- 设置状态：stores/settings.js
- 请求层：utils/api.js
- 环境配置：utils/config.js
- 文件转换：utils/convert.js
- OCR 缓存：utils/ocrCache.js
- 文档块工具：utils/docBlock.js

## 路由事实

- / -> EditorView
- /docs -> DocsView

## 核心行为

### 编辑器主控

- MilkdownEditor.vue 是前端最重要的控制点。
- 它负责：
	- 创建 Crepe 编辑器
	- 注册 copilot、docBlock、mermaid 插件
	- 上传图片和文档
	- 触发 OCR
	- 导入导出 Markdown
	- 导出 DOCX 和 PDF
	- AI 开关
	- 32 KB 大小限制
	- TTS 菜单和播放器
	- 把 Markdown 更新回父组件

### 设置状态

- settings.js 负责持久化用户设置到 localStorage。
- 当前重要字段包括：
	- theme
	- modelThinking
	- debounceMs
	- privacyMode
	- language
	- currency
	- backgroundType
	- backgroundImage
	- backgroundOpacity
	- ttsInstruct
- initialMarkdown 也是由 store 推导出来的，编辑器初始化会消费它。

### 请求层

- utils/config.js 负责从 VITE_* 环境变量拼接接口地址。
- 前端 API 默认基址必须是 `https://api.imageteach.tech:8002`；不要把前端请求导向 Docker 内后端、本机 `localhost:8001` / `localhost:8081`，也不要依赖 Docker nginx 的同源 `/v1` 代理。
- utils/api.js 负责补全请求、取消补全、TTS 请求和状态请求。
- fetchSuggestion 会：
	- 生成 request_id
	- 绑定 AbortSignal
	- 触发中止时的 cancel 请求
	- 读取 settings store 中的 thinking、privacy、language、currency、timezone 信息
	- 向后端发 POST 并读取 JSON

## 当前真实约定

- 这个目录不是纯 JS，也不是纯 TS，而是 Vue SFC + JS + TS 混合。
- 组件、视图文件多为 PascalCase。
- 工具和配置模块多为小写 .js。
- 不要根据旧文档把前端文件统一改成另一种命名风格。
- 代码风格存在历史混合，优先跟随当前文件周围风格，不要做无关格式化。

## 容易踩坑的点

- 文档超过 32 KB 时，AI 补全会被禁用。
- 在文档块、Mermaid、LaTeX 等特定上下文中，部分 AI 行为和上传行为会被禁用或改道。
- OCR 文本和文档块摘录会被注入补全上下文，但这些内容不应直接作为用户可见输出回写到文档。
- 前端存在 /v1/export/pdf 调用，但调试前先确认后端是否真的实现了这个端点。
- 当前前端多处仍保留占位 API Key 或默认值；不要把这种写法继续扩散到新代码。
- 需要多语言 UI 时，优先走现有 i18n 结构，而不是在组件里新增硬编码文案。

## 调试路径

- 补全问题：
	components/MilkdownEditor.vue
	-> plugins/copilotPlugin.ts
	-> utils/api.js
	-> backend

- OCR 问题：
	components/MilkdownEditor.vue
	-> OCR 请求
	-> backend/main.py

- 文档导入转换问题：
	components/MilkdownEditor.vue
	-> utils/convert.js
	-> backend/main.py

- TTS 问题：
	components/TTSMenu.vue / components/TTSPlayer.vue / components/MilkdownEditor.vue
	-> utils/api.js
	-> backend/tts_asr.py

## 改动建议

- 编辑器相关问题优先从 MilkdownEditor.vue 入手，不要先到处搜。
- 插件逻辑问题优先看 plugins/，尤其是 copilotPlugin.ts。
- 状态问题优先看 stores/settings.js。
- 网络问题优先看 utils/config.js 和 utils/api.js。
- 改前端时尽量避免同时改样式、文案、结构和网络逻辑，多做局部可验证修改。

## 不要做的事

- 不要修改 milkdown-docs/。
- 不要在组件里继续新增硬编码密钥。
- 不要绕开现有 store 直接分散持久化设置。
- 不要把隐藏上下文数据直接渲染进用户文档。
- 不要因为某个文件风格不统一就顺手改整个 src/。
