ax-frontend-app

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 对话和工作流通过后端代理访问，使用 VITE_AI_PROXY_URL 与 VITE_WORKFLOW_PROXY_URL

---

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)
• 错误信息标准化提取

默认配置:

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

AI 和工作流上游密钥只能配置在后端，禁止放入任何 VITE_* 变量。

配置步骤

1. 复制 .env.example 为 .env
2. 修改环境变量值
3. 重启开发服务器

---

🚀 开发与部署

安装依赖

npm install
# 或
pnpm install

开发模式

npm run dev
# 启动 Vite 开发服务器，默认端口 5173

构建生产版本

npm run build
# 编译 TypeScript 并打包为静态文件（dist/）

预览生产构建

npm run preview
# 本地预览生产构建结果

代码质量工具

Linting & Formatting

# 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 提交规范

<type>(<scope>): <subject>

<body>

<footer>

Type 类型:

• feat: 新功能
• fix: 修复 bug
• docs: 文档更新
• style: 代码格式调整
• refactor: 重构代码
• test: 测试相关
• chore: 构建/工具链相关

示例:

feat(editor): add table support in WYSIWYG editor

- Integrate @mdxeditor/editor table plugin
- Add table formatting toolbar
- Support table cell alignment

Closes #123

---

👥 团队协作

分支管理

• main - 生产分支（受保护）
• develop - 开发分支
• feature/* - 功能分支
• bugfix/* - 修复分支
• hotfix/* - 紧急修复

Pull Request 流程

1. 从 develop 创建功能分支
2. 完成开发并自测
3. 提交 PR 并关联 Issue
4. Code Review（至少 1 人审核）
5. CI/CD 自动测试通过
6. 合并到 develop

---

📚 相关资源

官方文档

• React 官方文档
• TypeScript 手册
• Vite 文档
• Ant Design 组件库
• Zustand 状态管理

关键依赖文档

• MDXEditor 编辑器
• react-markdown
• remark-gfm
• Axios HTTP 客户端

后端 API 文档

后端 API 文档请参考: D:\work space\ax-shell\ax-backend-shell\docs\

---

🤝 贡献指南

如何贡献

1. Fork 项目仓库
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 提交 Pull Request

问题反馈

• 提交 Issue 时请使用模板
• 包含详细的复现步骤
• 附上截图或错误日志
• 标注优先级和类型

---

📄 许可证

本项目为私有项目，版权所有。未经授权，不得复制、修改或分发。

---

📞 联系方式

项目维护者: AX Development Team
后端项目: D:\work space\ax-shell\ax-backend-shell
前端项目: D:\work space\ax-shell\ax-frontend-app

---

最后更新: 2026-07-01
文档版本: 1.0.0