ax-frontend-app

AX Frontend App

企业级文档编辑和管理前端应用，基于 React 18 + TypeScript + Vite 构建。

技术栈

• 核心框架: React 18.3+ (Hooks + Function Components)
• 类型系统: TypeScript 6.0+ (strict mode enabled)
• 构建工具: Vite 8.0+
• UI 组件库: Ant Design 5.0+
• 状态管理: Zustand 4.0+
• 富文本编辑器: Slate.js 0.100+
• HTTP 客户端: Axios 1.7+
• 代码规范: ESLint + Prettier

⚠️ 重要说明

本项目使用 React 18 而不是 React 19，因为 Ant Design v5 目前仅官方支持 React 16-18。

更多信息请参考：https://u.ant.design/v5-for-19

项目结构

src/
├── components/          # UI 组件
│   ├── ChatPanel/       # 聊天面板组件
│   ├── EditorPanel/     # 编辑器面板组件
│   ├── DocumentList/    # 文档列表组件
│   ├── Layout/          # 布局组件（双栏、分割器）
│   └── common/          # 通用 UI 组件
├── services/            # 业务服务层
│   ├── api.ts           # API 客户端封装
│   ├── documentService.ts  # 文档 CRUD 服务
│   ├── exportService.ts    # 导出服务
│   └── autoSaveService.ts  # 自动保存服务
├── stores/              # Zustand 状态管理
│   ├── documentStore.ts # 文档状态
│   ├── chatStore.ts     # 聊天状态
│   └── uiStore.ts       # UI 状态
├── types/               # TypeScript 类型定义
│   ├── document.ts      # 文档类型
│   ├── chat.ts          # 聊天类型
│   └── api.ts           # API 类型
├── utils/               # 工具函数
│   ├── debounce.ts      # 防抖函数
│   ├── formatDate.ts    # 日期格式化
│   └── storage.ts       # localStorage 封装
├── hooks/               # 自定义 Hooks
│   ├── useAutoSave.ts   # 自动保存 hook
│   ├── useDocumentList.ts  # 文档列表 hook
│   └── useResponsive.ts    # 响应式布局 hook
├── App.tsx              # 根组件
├── main.tsx             # 应用入口
└── vite-env.d.ts        # Vite 环境类型

开始使用

环境要求

• Node.js 18+
• npm 9+ 或 yarn 1.22+

安装依赖

npm install

配置环境变量

复制 .env.example 文件并重命名为 .env，然后配置环境变量：

# API Base URL - 后端服务地址
VITE_API_BASE_URL=http://localhost:8000

# Application Title - 应用标题
VITE_APP_TITLE=AX Document Editor

# Debug Mode - 调试模式
VITE_DEBUG=false

开发模式

启动开发服务器（带热重载）：

npm run dev

应用将在 http://localhost:5173 运行。

生产构建

构建生产版本：

npm run build

构建输出将生成在 dist/ 目录。

预览生产构建

本地预览生产构建：

npm run preview

运行测试

单次运行所有测试：

npm run test

以监听模式运行测试（文件变更时自动重新运行）：

npm run test:watch

代码质量检查

运行 ESLint 检查：

npm run lint

运行 Prettier 格式检查：

npm run format:check

自动格式化代码：

npm run format

核心功能

1. 双栏布局

• 左侧：AI 聊天面板，用于对话生成文档
• 右侧：富文本编辑器，支持实时编辑
• 支持拖拽分隔器调整宽度
• 响应式设计，移动端自动切换为单栏

2. 文档管理

• 文档列表查看和筛选
• 按来源（chat/workflow）过滤
• 按时间排序（创建/更新时间）
• 分页浏览
• 文档删除（带确认）

3. 富文本编辑

• 基于 Slate.js 的 Markdown 编辑器
• 支持标题、粗体、斜体、列表等格式
• 撤销/重做功能
• 快捷键支持
• 自动保存（防抖 3 秒）

4. 文档导出

• 导出为 .doc 格式
• 自动触发浏览器下载
• 错误处理和用户反馈

5. AI 集成

• 聊天界面与 AI 对话
• 从对话生成文档
• 一键在编辑器中打开

TypeScript 配置

项目已启用 TypeScript 严格模式，包括：

• strict: true - 启用所有严格类型检查选项
• noUnusedLocals: true - 检查未使用的局部变量
• noUnusedParameters: true - 检查未使用的参数
• noFallthroughCasesInSwitch: true - 检查 switch 语句的 fallthrough

代码规范

ESLint

• React 推荐规则
• React Hooks 规则
• TypeScript 推荐规则

Prettier

• 单引号
• 分号
• 2 空格缩进
• 100 字符行宽
• ES5 尾随逗号

部署

构建后的应用可以部署到任何静态托管服务：

• Vercel
• Netlify
• AWS S3 + CloudFront
• Nginx

Nginx 配置示例

server {
  listen 80;
  server_name example.com;
  root /var/www/ax-frontend-app;
  index index.html;

  # SPA 回退
  location / {
    try_files $uri $uri/ /index.html;
  }

  # API 代理（可选）
  location /api/ {
    proxy_pass http://backend:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
}

开发指南

命名规范

• 组件文件：PascalCase（如 ChatPanel.tsx）
• 工具函数：camelCase（如 debounce.ts）
• 类型文件：小写字母（如 document.ts）
• 常量：UPPER_SNAKE_CASE（如 MAX_FILE_SIZE）

组件编写规范

• 优先使用函数组件和 Hooks
• 避免使用 any 类型
• 为所有函数和组件添加类型定义
• 使用 JSDoc 注释关键函数
• 业务逻辑与 UI 组件分离

状态管理

• 使用 Zustand 进行全局状态管理
• 组件内部状态使用 useState
• 副作用使用 useEffect
• 可复用逻辑封装为自定义 Hooks

性能优化

• 使用 React.lazy 和 Suspense 进行代码分割
• 使用 React.memo 避免不必要的重新渲染
• 使用 useMemo 和 useCallback 优化计算和回调
• 防抖自动保存（3 秒）
• 虚拟滚动处理长文档（>10000 字）

问题排查

开发服务器无法启动

1. 检查 Node.js 版本是否 ≥ 18
2. 删除 node_modules 和 package-lock.json 后重新安装
3. 检查端口 5173 是否被占用

类型错误

1. 运行 npm run lint 检查 ESLint 错误
2. 运行 npx tsc --noEmit 检查 TypeScript 错误
3. 确保所有导入都有正确的类型定义

构建失败

1. 检查 TypeScript 类型错误
2. 检查环境变量配置
3. 清理缓存：rm -rf node_modules/.vite

许可证

Copyright © 2025 Axonix Frontend Team

---

文档版本: v1.0
最后更新: 2025-01-11

🆕 新功能：文档管理与导出

功能概述

已完成与后端文档管理和导出API的完整集成，提供：

• ✅ 文档CRUD操作（创建、读取、更新、删除）
• ✅ Word文档解析为Markdown
• ✅ Markdown导出为Word格式
• ✅ 局部块更新支持
• ✅ 文档列表管理
• ✅ 存储配额监控
• ✅ 完整的测试覆盖

快速开始

1. 使用演示页面

npm run dev
# 访问 http://localhost:5173/document-demo

2. 使用控制台测试工具

打开浏览器控制台（F12）：

// 运行完整工作流测试
await window.documentTestUtils.testFullWorkflow(
  'https://example.com/test.docx',
  'test-user',
  'test-session'
);

// 测试文档创建
await window.documentTestUtils.testDocumentFlow(
  'https://example.com/test.docx',
  'test-user',
  'test-session'
);

// 测试导出
await window.documentTestUtils.testExportFlow('doc-abc123');

3. 运行自动化测试

# 运行所有测试
npm test

# 运行特定测试
npm run test:document      # 文档服务测试
npm run test:export        # 导出服务测试
npm run test:integration   # 集成测试

# 监听模式
npm run test:watch

# 生成覆盖率报告
npm run test:coverage

API服务

文档服务 (documentService.ts)

import { createDocument, getDocument, updateDocument, deleteDocuments, listDocuments } from '@/services/documentService';

// 创建文档
const doc = await createDocument({
  userId: 'user-123',
  fileUrl: 'https://example.com/document.docx',
  sessionId: 'session-456',
});

// 获取文档
const document = await getDocument('doc-abc123');

// 更新文档（全量）
await updateDocument('doc-abc123', {
  content: '# 新标题\n\n新内容...',
});

// 更新文档（局部块）
await updateDocument('doc-abc123', {
  blocks: [
    { level: 2, index: 0, content: '## 新章节\n\n内容...' },
  ],
});

// 列出文档
const result = await listDocuments({
  userId: 'user-123',
  page: 1,
  pageSize: 20,
});

// 删除会话文档
await deleteDocuments('session-456');

导出服务 (exportService.ts)

import { exportToWord } from '@/services/exportService';

// 导出为Word
const result = await exportToWord({
  documentId: 'doc-abc123',
  styleId: null, // 使用默认样式
});

// 下载文件
window.open(result.downloadUrl, '_blank');

UI组件

DocumentUpload 组件

import { DocumentUpload } from '@/components/DocumentUpload';

<DocumentUpload
  userId="user-123"
  sessionId="session-456"
  onSuccess={(result) => console.log('创建成功:', result)}
  showInstructions={true}
/>

DocumentManagement 组件

import { DocumentManagement } from '@/components/DocumentManagement';

<DocumentManagement
  userId="user-123"
  sessionId="session-456"
  showSessionFilter={true}
  pageSize={20}
/>

相关文档

• 📖 完整集成文档: FRONTEND_API_INTEGRATION_SUMMARY.md
• 🚀 快速开始指南: QUICK_START_GUIDE.md
• 🧪 测试说明: src/services/tests/README.md
• 📝 后端API文档: ../ax-backend-shell/docs/

测试覆盖

• ✅ 文档服务单元测试
• ✅ 导出服务单元测试
• ✅ 文档导出集成测试
• ✅ 错误场景测试
• ✅ UI组件功能测试
• ✅ 手动测试工具

新增npm脚本

npm run test:document      # 运行文档服务测试
npm run test:export        # 运行导出服务测试
npm run test:integration   # 运行集成测试
npm run test:coverage      # 生成测试覆盖率报告

环境变量

确保 .env 文件包含后端API地址：

VITE_API_BASE_URL=http://192.168.0.200:8000