# 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+

### 安装依赖

```bash
npm install
```

### 配置环境变量

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

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

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

# Debug Mode - 调试模式
VITE_DEBUG=false
```

### 开发模式

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

```bash
npm run dev
```

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

### 生产构建

构建生产版本：

```bash
npm run build
```

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

### 预览生产构建

本地预览生产构建：

```bash
npm run preview
```

### 运行测试

单次运行所有测试：

```bash
npm run test
```

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

```bash
npm run test:watch
```

### 代码质量检查

运行 ESLint 检查：

```bash
npm run lint
```

运行 Prettier 格式检查：

```bash
npm run format:check
```

自动格式化代码：

```bash
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 配置示例

```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. 使用演示页面

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

#### 2. 使用控制台测试工具

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

```javascript
// 运行完整工作流测试
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. 运行自动化测试

```bash
# 运行所有测试
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`)

```typescript
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`)

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

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

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

### UI组件

#### DocumentUpload 组件

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

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

#### DocumentManagement 组件

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

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

### 相关文档

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

### 测试覆盖

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

### 新增npm脚本

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

### 环境变量

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

```env
VITE_API_BASE_URL=http://192.168.0.200:8000
```