# AX Document Editor - 项目总结文档 ## 📋 项目概述 **项目名称**: AX Document Editor (ax-frontend-app) **版本**: 0.0.0 **类型**: React + TypeScript 单页应用 **构建工具**: Vite **开发框架**: React 18.3.1 ### 项目定位 AX Document Editor 是一个现代化的文档编辑与管理系统，提供智能对话、文档预览、在线编辑和导出功能。该系统集成了 AI 对话能力，支持 Word 文档解析、Markdown 编辑和多格式导出。 --- ## 🏗️ 技术架构 ### 核心技术栈 | 类别 | 技术 | 版本 | 说明 | |------|------|------|------| | **前端框架** | React | 18.3.1 | 用户界面开发 | | **类型系统** | TypeScript | 6.0.2 | 类型安全保障 | | **构建工具** | Vite | 8.0.12 | 快速开发构建 | | **UI 组件库** | Ant Design | 5.22.6 | 企业级UI组件 | | **状态管理** | Zustand | 4.5.5 | 轻量级状态管理 | | **HTTP 客户端** | Axios | 1.7.9 | API 请求处理 | ### 主要依赖库 #### 文档处理 - **@mdxeditor/editor** (3.19.0) - WYSIWYG Markdown 编辑器，支持表格、代码块等富文本功能 - **react-markdown** (10.1.0) - Markdown 渲染引擎 - **remark-gfm** (4.0.1) - GitHub Flavored Markdown 支持 - **rehype-raw** & **rehype-sanitize** - HTML 处理和安全过滤 - **mammoth** (1.12.0) - Word 文档解析 - **turndown** (7.2.4) - HTML 转 Markdown - **docx-preview** (0.3.7) - Word 文档预览 #### 导出功能 - **jspdf** (4.2.1) - PDF 生成 - **html2canvas** (1.4.1) - 网页截图 #### 工具库 - **uuid** (14.0.0) - 唯一标识符生成 - **@ant-design/icons** (6.2.5) - 图标库 --- ## 📁 项目结构 ``` ax-frontend-app/ ├── src/ │ ├── components/ # UI 组件 │ │ ├── ChatPanel/ # 聊天面板（AI 对话） │ │ ├── EditorPanel/ # 文档编辑器面板 │ │ ├── DocumentList/ # 文档列表 │ │ ├── DocumentManagement/ # 文档管理 │ │ ├── DocumentManagementLayout/ # 文档管理布局 │ │ ├── DocumentOutline/ # 文档大纲 │ │ ├── DocumentViewer/ # 文档查看器 │ │ ├── DocumentUpload/ # 文档上传 │ │ ├── ExportRecordList/ # 导出记录列表 │ │ ├── MarkdownPreview/ # Markdown 预览 │ │ ├── SessionList/ # 会话历史 │ │ ├── Layout/ # 布局组件（可调整大小） │ │ ├── ThemeSwitcher/ # 主题切换 │ │ └── common/ # 通用组件（ErrorBoundary 等） │ │ │ ├── services/ # API 服务层 │ │ ├── api.ts # Axios 客户端配置 │ │ ├── documentService.ts # 文档 CRUD 服务 │ │ ├── exportService.ts # 导出服务 │ │ ├── exportRecordService.ts # 导出记录服务 │ │ ├── documentContentService.ts # 文档内容服务 │ │ └── chatService.ts # AI 聊天服务 │ │ │ ├── stores/ # Zustand 状态管理 │ │ ├── chatStore.ts # 聊天状态 │ │ └── uiStore.ts # UI 状态 │ │ │ ├── types/ # TypeScript 类型定义 │ │ ├── api.ts # API 通用类型 │ │ ├── chat.ts # 聊天相关类型 │ │ ├── document.ts # 文档类型 │ │ └── export.ts # 导出类型 │ │ │ ├── hooks/ # 自定义 React Hooks │ │ └── useOnlineStatus.ts # 网络状态检测 │ │ │ ├── utils/ # 工具函数 │ │ └── formatDate.ts # 日期格式化 │ │ │ ├── theme/ # 主题配置 │ ├── App.tsx # 根组件 │ └── main.tsx # 应用入口 │ ├── .env.example # 环境变量示例 ├── package.json # 项目配置 ├── tsconfig.json # TypeScript 配置 ├── vite.config.ts # Vite 配置 └── eslint.config.js # ESLint 配置 ``` --- ## 🎯 核心功能模块 ### 1. AI 智能对话 (ChatPanel) **功能描述**: - 基于流式 SSE (Server-Sent Events) 的实时 AI 对话 - 支持两种 AI 模式: - **常规对话模式** (v1): 纯文本问答 - **工作流模式** (v2): 集成文档生成流程 - 对话历史管理与持久化 - 导出记录卡片展示（点击可预览/下载） **技术实现**: - 使用 `EventSource` 实现 SSE 流式响应 - Zustand 管理聊天状态和消息列表 - 支持断网检测和重连机制 **API 集成**: - AI 对话通过后端代理 `/api/v1/ai/chat` - 文档工作流通过后端代理 `/api/v1/ai/workflow`，对应平台接口 `/api/v2/chat/completions` - 平台 `appId/projectId` 和 API 密钥只配置在 `ax-backend-v1/.env`，不会进入前端构建 --- ### 2. 文档编辑器 (EditorPanel) **功能描述**: - WYSIWYG (所见即所得) Markdown 编辑器 - 实时文档大纲导航 - 支持表格、代码块、图片等富文本元素 - 支持源码模式和预览模式切换 - 多格式导出（Word、PDF、Markdown） **核心组件**: - **WYSIWYGEditor**: 基于 `@mdxeditor/editor` 的富文本编辑器 - **DocumentOutline**: 自动生成文档大纲，支持点击跳转 **技术特性**: - Markdown 内容自动清理（移除零宽字符、控制字符） - 错误边界处理（解析失败时提示切换到源码模式） - 编辑器插件: headings、lists、tables、codeBlocks、links 等 --- ### 3. 文档管理 (DocumentManagement & DocumentManagementLayout) **功能描述**: - 文档列表浏览（支持分页、排序、筛选） - 文档详情查看 - 文档导出到 Word - 批量删除（按会话ID） - 三栏布局：文档列表 + 文档大纲 + 文档内容 **数据管理**: - 按用户ID和会话ID过滤 - 支持按创建时间/更新时间排序 - 分页加载，默认每页 20 条 **用户交互**: - 表格展示（无竖线，简洁设计） - 操作按钮：查看、导出、删除 - Modal 弹窗展示文档详情 --- ### 4. 导出记录管理 (ExportRecordList) **功能描述**: - 查看所有导出记录（按时间倒序） - 下载已导出的 Word 文档 - 删除导出记录及其文件 - 实时展示文件名、创建时间、文件大小 **技术实现**: - 使用 `apiClient` 的 Blob 下载方式（避免混合内容警告） - 前端生成临时下载链接并自动触发下载 - 安全删除确认（Popconfirm） --- ### 5. 会话历史 (SessionList) **功能描述**: - 查看所有历史会话 - 按时间分组展示 - 加载指定会话的聊天记录 - 会话列表侧边栏抽屉 **数据存储**: - LocalStorage 持久化会话数据 - 会话元数据包括: sessionId、title、timestamp、messageCount --- ### 6. 文档预览 (MarkdownPreview) **功能描述**: - 渲染 Markdown 文档为 HTML - 支持表格、代码块、引用等 GFM 语法 - 编辑模式与预览模式切换 - 保存修改回后端 - 导出当前文档 **技术实现**: - 使用 `react-markdown` + `remark-gfm` 渲染 - 使用 `rehype-raw` 支持原始 HTML - 使用 `rehype-sanitize` 防止 XSS 攻击 - 自定义组件样式（表格、标题、代码块等） --- ## 🔌 API 服务层 ### API 客户端配置 (api.ts) **核心功能**: - Axios 实例配置（baseURL、timeout、headers） - 请求/响应拦截器（统一错误处理） - 环境变量读取 (`VITE_API_BASE_URL`) - 错误信息标准化提取 **默认配置**: ```typescript baseURL: 'http://192.168.0.195:8000' timeout: 30000ms Content-Type: 'application/json' ``` --- ### 文档服务 (documentService.ts) **API 端点**: | 方法 | 端点 | 说明 | |------|------|------| | POST | `/api/v1/documents` | 创建文档（从 Word URL） | | GET | `/api/v1/documents/:id` | 获取文档详情 | | PUT | `/api/v1/documents/:id` | 更新文档内容 | | DELETE | `/api/v1/documents/:sessionId` | 删除会话所有文档 | | GET | `/api/v1/documents` | 列出文档（分页） | **主要方法**: - `createDocument()` - 解析 Word 文档为 Markdown - `getDocument()` - 获取完整文档（含内容） - `getDocumentContent()` - 获取文档内容（标题+正文） - `updateDocument()` - 全量或分块更新 - `deleteDocuments()` - 按会话ID删除 - `listDocuments()` - 分页列表（不含内容字段） --- ### 导出服务 (exportService.ts) **API 端点**: | 方法 | 端点 | 说明 | |------|------|------| | POST | `/api/v1/export/doc` | 导出为 Word 文档 | **主要方法**: - `exportToWord(documentId, styleId)` - 导出文档为 Word 格式 - 返回: `{ recordId, downloadUrl, fileName, warning }` - styleId: null 表示使用默认样式 **导出流程**: 1. 调用导出 API 创建导出记录 2. 后端生成 Word 文件 3. 返回下载 URL 和记录 ID 4. 前端使用 Blob 方式下载（避免混合内容警告） --- ### 导出记录服务 (exportRecordService.ts) **API 端点**: | 方法 | 端点 | 说明 | |------|------|------| | GET | `/api/v1/export/records` | 列出导出记录 | | GET | `/api/v1/export/records/:id/download` | 下载导出文件 | | DELETE | `/api/v1/export/records/:id` | 删除导出记录 | | GET | `/api/v1/admin/storage` | 获取存储信息（管理员） | **主要方法**: - `listExportRecords()` - 获取导出历史（分页） - `downloadExportRecord()` - 下载文件（Blob 方式） - `deleteExportRecord()` - 删除记录和文件 - `getAdminStorage()` - 查看存储使用情况 --- ### 聊天服务 (chatService.ts) **功能**: - 流式 AI 对话（SSE） - 两种模式切换（常规/工作流） - 消息流解析和回调处理 **技术细节**: - 使用 `EventSource` 建立 SSE 连接 - 逐块接收 AI 响应并更新 UI - 支持错误处理和连接超时 - 自动提取导出记录信息（工作流模式） --- ## 💾 状态管理 ### 聊天状态 (chatStore.ts) **管理数据**: - `messages` - 消息列表 - `isLoading` - 加载状态 - `currentSessionId` - 当前会话 ID - `sessions` - 会话历史（LocalStorage 持久化） **主要方法**: - `addMessage()` - 添加消息 - `updateLastMessage()` - 更新最后一条消息（流式响应） - `setLoading()` - 设置加载状态 - `createNewSession()` - 创建新会话 - `loadSession()` - 加载指定会话 - `saveSession()` - 保存会话到 LocalStorage - `getSessions()` - 获取会话列表 --- ### UI 状态 (uiStore.ts) **管理数据**: - `previewDocumentId` - 当前预览的文档 ID - `previewDocumentName` - 文档名称 - `theme` - 主题（light/dark） **主要方法**: - `openDocumentPreview()` - 打开文档预览 - `closeDocumentPreview()` - 关闭预览 - `toggleTheme()` - 切换主题 --- ## 🎨 UI/UX 设计 ### 布局架构 **主界面布局**: ``` ┌─────────────────────────────────────────────────┐ │ 顶部工具栏 (会话历史 | 文档列表) │ ├──────────────────┬──────────────────────────────┤ │ 左侧 (40%) │ 右侧 (60%) │ │ │ │ │ ChatPanel │ ExportRecordList (默认) │ │ (AI 对话) │ 或 │ │ │ EditorPanel (文档打开时) │ │ │ │ └──────────────────┴──────────────────────────────┘ ``` **可调整布局 (ResizableLayout)**: - 支持拖拽调整左右面板宽度 - 最小宽度限制: 300px - 默认比例: 40% / 60% --- ### 组件样式规范 **设计原则**: - 简洁现代：最小化视觉干扰 - 扁平化：无多余阴影和边框 - 响应式：适配不同屏幕尺寸 - 一致性：统一的间距、圆角、颜色 **颜色系统**: - 主色调：`#1677ff` (蓝色) - 背景色：`#ffffff` (白色), `#f5f5f5` (浅灰) - 边框色：`#e8e8e8`, `#d9d9d9` - 文字色：`#262626` (深色), `#595959` (次要), `#8c8c8c` (辅助) **字体规范**: - 标题：14-28px, 字重 500-600 - 正文：13-14px, 行高 1.6-1.8 - 代码：Monaco, Consolas, Courier New (等宽字体) --- ## ⚙️ 环境配置 ### 环境变量说明 | 变量名 | 说明 | 默认值 | |--------|------|--------| | `VITE_API_BASE_URL` | 后端 API 地址 | `http://192.168.0.195:8000` | | `VITE_APP_TITLE` | 应用标题 | `AX Document Editor` | | `VITE_DEBUG` | 调试模式 | `false` | | `VITE_AI_PROXY_URL` | 后端 AI 代理 | `/api/v1/ai/chat` | | `VITE_WORKFLOW_PROXY_URL` | 后端工作流代理 | `/api/v1/ai/workflow` | ### 配置步骤 1. 复制 `.env.example` 为 `.env` 2. 修改环境变量值 3. 重启开发服务器 --- ## 🚀 开发与部署 ### 安装依赖 ```bash npm install # 或 pnpm install ``` ### 开发模式 ```bash npm run dev # 启动 Vite 开发服务器，默认端口 5173 ``` ### 构建生产版本 ```bash npm run build # 编译 TypeScript 并打包为静态文件（dist/） ``` ### 预览生产构建 ```bash npm run preview # 本地预览生产构建结果 ``` ### 代码质量工具 #### Linting & Formatting ```bash # ESLint 代码检查 npm run lint # Prettier 格式化 npm run format # 检查格式（不修改） npm run format:check ``` #### 测试（已移除） 注意：项目中的测试配置和文件已被移除，包括： - `vitest.config.ts` 已删除 - 所有 `console.log/error/warn` 语句已清理 --- ## 🔒 安全性考虑 ### API 安全 1. **CORS 配置**: 后端配置允许的源 2. **API 密钥**: 环境变量中存储，不提交到版本控制 3. **请求拦截**: Axios 拦截器统一处理认证 ### 内容安全 1. **XSS 防护**: 使用 `rehype-sanitize` 清理 HTML 2. **Markdown 清理**: 移除零宽字符和控制字符 3. **文件下载**: 使用 Blob URL 方式，自动清理内存 ### 数据隐私 1. **本地存储**: 会话数据仅存储在浏览器 LocalStorage 2. **文件处理**: 导出文件经后端处理，不在前端暴露敏感数据 --- ## 📊 性能优化 ### 代码分割 - **Lazy Loading**: 非关键组件使用 `React.lazy()` - **Suspense**: 加载组件时显示占位符 - **Tree Shaking**: Vite 自动移除未使用代码 ### 渲染优化 - **React.memo**: 避免不必要的组件重渲染 - **useMemo/useCallback**: 缓存计算结果和函数引用 - **虚拟滚动**: 长列表使用 Ant Design 的虚拟滚动 ### 网络优化 - **请求合并**: 批量操作减少请求次数 - **缓存策略**: 利用 HTTP 缓存头 - **超时控制**: 30 秒请求超时限制 --- ## 🐛 已知问题与解决方案 ### 1. 混合内容警告（已解决） **问题**: 文件下载时浏览器报 "loaded over an insecure connection" 警告 **解决方案**: - 所有下载改用 `apiClient.get()` + `responseType: 'blob'` - 使用相对 URL 路径，避免硬编码 HTTP URL - Blob URL 方式下载，自动清理内存 ### 2. MDXEditor 解析错误 **问题**: 文档包含特殊字符导致编辑器无法渲染 **解决方案**: - Markdown 内容预处理（清理零宽字符、控制字符） - 错误边界捕获并提示用户切换到源码模式 - 强制重新创建编辑器实例（通过 key 值变化） ### 3. 后端 BASE_URL 不一致 **问题**: 下载 URL 中的 IP 地址错误（200 vs 195） **解决方案**: - 后端 `.env` 文件统一配置为 `192.168.0.195` - 前端增加 URL 修正逻辑（自动替换错误 IP） --- ## 🔮 未来规划 ### 短期计划 1. **协作编辑**: 多用户实时协作编辑文档 2. **版本管理**: 文档版本历史和回滚功能 3. **模板系统**: 预定义文档模板库 4. **批量操作**: 批量导出、批量删除 ### 中期计划 1. **移动端适配**: 响应式设计优化移动端体验 2. **离线支持**: Service Worker + IndexedDB 离线编辑 3. **插件系统**: 支持第三方插件扩展功能 4. **多语言支持**: i18n 国际化 ### 长期计划 1. **桌面应用**: Electron 打包桌面客户端 2. **云端同步**: 多设备数据同步 3. **AI 增强**: 智能写作助手、内容推荐 4. **企业版**: 权限管理、审计日志、SSO 登录 --- ## 📖 开发规范 ### 代码风格 1. **TypeScript 优先**: 所有代码使用 TypeScript，避免 `any` 类型 2. **函数式组件**: 使用 React Hooks，避免类组件 3. **命名规范**: - 组件: PascalCase（如 `ChatPanel.tsx`） - 文件: camelCase（如 `documentService.ts`） - 常量: UPPER_SNAKE_CASE（如 `API_BASE_URL`） 4. **注释规范**: 使用 JSDoc 注释说明复杂逻辑 ### 目录组织 1. **按功能模块划分**: 每个功能独立目录（components、services、stores） 2. **共享代码**: 放在 `common/`、`utils/`、`types/` 目录 3. **样式文件**: 与组件同目录，命名为 `Component.css` ### Git 提交规范 ``` ():