# Src 前端指引 (v0.2.0)

本文件适用于 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
- **网页搜索块**：components/WebSearchBlockCrepe.vue（可折叠/压缩/删除的搜索结果卡片）
- **OCR 包装器**：components/OCRImageWrapper.vue（加载/成功/失败状态覆盖层）
- **验证码组件**：components/CaptchaComponent.vue（vue3-captcha 封装）
- 插件层：plugins/
- 设置状态：stores/settings.js
- 请求层：utils/api.js、**utils/fetch.js**（安全 fetch wrapper）
- 环境配置：utils/config.js
- 文件转换：utils/convert.js
- OCR 缓存：utils/ocrCache.js
- 文档块工具：utils/docBlock.js
- **SSE 解析**：utils/sse.ts（Server-Sent Events 事件解析）
- **文档管理 API**：utils/docsApi.js（上传/预览/删除接口客户端）
- **PRO 接受追踪**：utils/proAccept.js（使用分析和统计）
- **Cookie 策略**：utils/cookie_policy.js（SameSite/Secure 标志处理）
- **字符串工具**：utils/string.ts（长度计算、编码检测）
- **网页搜索上下文**：utils/webSearch.js（搜索结果 Markdown 构建与解析）

## 路由事实

- / -> EditorView
- /docs -> DocsView

## 核心行为

### 编辑器主控

- MilkdownEditor.vue 是前端最重要的控制点。
- 它负责：
	- 创建 Crepe 编辑器
	- 注册 copilot、docBlock、mermaid、**webSearchBlock** 插件
	- 上传图片和文档
	- 触发 OCR（通过 **OCRImageWrapper.vue**）
	- 导入导出 Markdown
	- 导出 DOCX 和 PDF（纯前端，从展开后的编辑器 HTML 导出）
	- AI 开关
	- 32 KB 大小限制
	- TTS 菜单和播放器
	- **验证码显示**（通过 CaptchaComponent.vue）
	- 把 Markdown 更新回父组件

### 设置状态

- settings.js 负责持久化用户设置到 localStorage。
- 当前重要字段包括：
	- theme
	- modelThinking
	- debounceMs
	- privacyMode
	- language
	- country
	- 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 请求和状态请求。
- **utils/fetch.js** 提供安全 fetch wrapper，自动附加 X-API-Key 认证头。
- fetchSuggestion 会：
	- 生成 request_id
	- 绑定 AbortSignal
	- 触发中止时的 cancel 请求
	- 读取 settings store 中的 thinking、privacy、language、country、timezone 信息
	- 向后端发 POST 并读取 JSON

## 当前真实约定

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

## 容易踩坑的点

- 文档超过 32 KB 时，AI 补全会被禁用。
- AI 开关需要同时作用到主编辑器、文档块嵌套编辑器、网页搜索块嵌套编辑器；当前通过 `llm-in-text:copilot-toggle` 广播同步。
- 在文档块、Mermaid、LaTeX 等特定上下文中，部分 AI 行为和上传行为会被禁用或改道。
- OCR 文本和文档块摘录会被注入补全上下文，但这些内容不应直接作为用户可见输出回写到文档。
- DOCX/PDF 导出当前不再依赖 `/v1/export/pdf`；导出逻辑看 `utils/richExport.js`。
- 上传单文件限制统一为 100MB；图片上传会等待 OCR 完成并给出全局进度与失败反馈。
- 视频上传会调用 `/v1/ocr` 的 `media_type=video` 路径，后端返回合并后的 OCR/ASR 文本，再插入文档块。
- **Web Search 块使用 ```llm-websearch fenced code 语法，触发词为 [WEBSEARCH]（不区分大小写）。**
- **验证码组件依赖 vue3-captcha 库，刷新和验证逻辑需保持与后端 /captcha/generate 和 /captcha/verify 接口同步。**
- 当前前端多处仍保留占位 API Key 或默认值；不要把这种写法继续扩散到新代码。
- 需要多语言 UI 时，优先走现有 i18n 结构，而不是在组件里新增硬编码文案。

## 调试路径

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

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

- Web Search 问题：
	components/WebSearchBlockCrepe.vue
	-> plugins/webSearchBlockPlugin.ts
	-> utils/webSearch.js
	-> backend/job_handlers.py（web_search_handler）

- 验证码问题：
	components/CaptchaComponent.vue
	-> backend/captcha_api.py（/captcha/generate, /captcha/verify）

- 文档导入转换问题：
	components/MilkdownEditor.vue
	-> utils/convert.js、**utils/docsApi.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/fetch.js** 和 utils/api.js。
- **新增组件问题优先看对应的 wrapper/component（OCRImageWrapper、WebSearchBlockCrepe、CaptchaComponent）。**
- 改前端时尽量避免同时改样式、文案、结构和网络逻辑，多做局部可验证修改。

## 不要做的事

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