# AX 前端项目文档

## 文档定位

本文档描述 `ax-frontend-app` 当前实际运行的前端实现。项目是一个基于 React、TypeScript 和 Vite 的文档工作台，提供：

- AI 聊天和流式消息展示
- 导出记录查看
- 文档块编辑
- 标题、段落、表格、图片和目录块处理
- Word、PDF、Markdown 导出
- 文档大纲导航
- 会话历史和文档预览

当前编辑器已经直接使用块编辑器实现，不再通过 Feature Flag 切换到旧的 MDXEditor。`新编辑器与聊天面板集成方案.md`、`集成快速参考.md` 等文件保留作为设计和迁移历史参考，不能作为当前代码接口的唯一依据。

## 快速开始

在项目目录执行：

```bash
npm install
npm run dev
```

开发服务器默认运行在 `http://localhost:5173`。

生产构建：

```bash
npm run build
npm run preview
```

性能审计应使用生产预览，而不是 Vite 开发服务器：

```bash
npm run serve:prod
```

然后使用 Lighthouse 访问 `http://localhost:4173/`。开发服务器返回未压缩模块源码，会夸大 JavaScript 和 CSS 的优化空间。

## 常用命令

| 命令                       | 用途                           |
| -------------------------- | ------------------------------ |
| `npm run dev`              | 启动开发服务器                 |
| `npm run build`            | TypeScript 检查并构建生产包    |
| `npm run preview`          | 预览已构建的生产包             |
| `npm run serve:prod`       | 构建并启动生产预览             |
| `npm run lighthouse:ready` | 构建并启动 Lighthouse 审计目标 |
| `npm run lint`             | 检查全部前端代码               |
| `npm run format:check`     | 检查格式                       |
| `npm run test`             | 运行 Vitest 测试               |
| `npm run test:document`    | 运行文档块和富文本转换测试     |
| `npm run test:export`      | 运行导出服务测试               |
| `npm run build:analyze`    | 构建并生成 `dist/stats.html`   |
| `npm run analyze`          | 执行构建并输出资源体积统计     |

## 当前架构

```text
main.tsx
  └─ App
      ├─ ConfigProvider / ErrorBoundary
      ├─ ChatPanel                 (懒加载，左侧)
      ├─ ExportRecordList           (懒加载，右侧默认视图)
      ├─ EditorPanel                (懒加载，打开文档后显示)
      ├─ SessionList                (打开抽屉时才挂载)
      └─ ResizableLayout
```

### 应用入口

- `src/main.tsx` 创建 React 根节点并加载全局样式。
- `src/App.tsx` 负责双面板布局、网络状态提示、会话抽屉和右侧视图切换。
- `src/components/Layout/ResizableLayout.tsx` 负责左右面板拖拽和宽度持久化。
- `src/stores/uiStore.ts` 保存文档预览状态和 UI 偏好。

右侧面板的选择规则：

1. `previewDocumentId` 存在时显示 `EditorPanel`。
2. 没有打开文档时显示 `ExportRecordList`。
3. 会话历史 Drawer 关闭时不挂载 `SessionList`，打开后才加载对应 chunk。

## 编辑器实现

当前编辑器调用链如下：

```text
EditorPanel
  └─ EditorWithOutline
      ├─ BlockEditor
      │   ├─ MainToolbar
      │   └─ BlockCanvas
      │       └─ BlockRenderer
      │           ├─ HeadingBlock
      │           ├─ ParagraphBlock
      │           ├─ TableBlock
      │           ├─ ImageBlock
      │           └─ TOCBlock
      └─ DocumentOutline
```

### Block 类型

类型定义位于 `src/types/editor.ts`，当前支持：

| 类型        | 用途             | 主要内容                        |
| ----------- | ---------------- | ------------------------------- |
| `heading`   | 1 至 6 级标题    | `RichText[]` 或字符串           |
| `paragraph` | 普通段落和列表   | `RichText[]` 或字符串           |
| `table`     | 表格及单元格编辑 | rows、cells、rowspan、colspan   |
| `image`     | 图片块           | Base64 Data URL、宽高和对齐方式 |
| `toc`       | 目录块           | 由文档标题生成                  |

块通过 `block_order` 排序。插入、移动和删除操作由 `editorStore` 统一处理，必要时进行排序重建和保存。

### 富文本

富文本片段结构：

```ts
{
  text: '示例文本',
  style: {
    bold: true,
    color: 'FF0000',
    font_size: 12
  }
}
```

- `RichTextEditor` 使用 `contenteditable`。
- `richTextConverter.ts` 负责 `RichText[]` 与 HTML 的双向转换。
- 工具栏通过保存和恢复 `Range` 维护用户选区。
- 表格单元格使用表格结构工具栏，不显示普通浮动格式工具栏。
- 表格结构操作位于 `src/components/Editor/blocks/TableToolbar.tsx`。

### 表格

当前支持：

- 插入和删除行、列
- 合并和拆分单元格
- `rowspan` 和 `colspan`
- 单元格选区
- 列宽和行高调整
- 单元格文字格式和垂直对齐

表格结构算法主要位于 `src/utils/blockOperations.ts`，修改表格结构时应优先复用其中的视觉坐标和重建逻辑，不要直接按数组索引插入单元格。

## 状态和数据流

项目使用 Zustand 管理状态：

| Store           | 职责                                   |
| --------------- | -------------------------------------- |
| `chatStore`     | 消息、会话、流式回复和会话持久化       |
| `editorStore`   | 文档、blocks、选中状态、自动保存和重试 |
| `uiStore`       | 文档预览、面板偏好和全局 UI 状态       |
| `documentStore` | 文档创建和文档相关操作                 |

典型编辑流程：

```text
用户输入
  -> RichTextEditor
  -> onChange
  -> editorStore.updateBlock
  -> dirtyBlocks / hasModified
  -> 自动保存或 MainToolbar 手动保存
  -> blockService / 后端 API
```

服务层位于 `src/services/`，API 请求优先通过 `src/services/api.ts` 的 Axios 实例完成，以获得统一的超时、错误归一化和通知行为。

## 导出和大型依赖

- Word：通过后端导出接口完成。
- Markdown：前端根据 blocks 同步生成并下载。
- PDF：前端使用 `html2canvas` 和 `jspdf`，仅在点击 PDF 导出时动态加载。
- Word 文档解析：`mammoth` 仅在文档内容解析时动态加载。

PDF、截图和 Word 解析库不应改为入口静态 import，否则会增加首屏 JavaScript 和 TBT。

## 性能策略

项目当前针对 FCP、LCP、TBT、CLS 的主要策略：

- 面板、会话列表和导出能力使用懒加载或动态 import。
- 生产构建启用 Oxc JS 压缩和 Lightning CSS 压缩。
- 生产构建关闭 source map。
- 关闭 Rollup 传递依赖的过度预加载。
- 分栏拖拽使用 `requestAnimationFrame` 节流，拖动结束后才写入 `localStorage`。
- 长聊天列表使用 `content-visibility: auto` 和 `contain-intrinsic-size`。
- 图片使用预留比例、`loading="lazy"` 和 `decoding="async"`，降低 CLS。
- 图片、PDF 和编辑器大模块不会进入初始页面的同步资源链。

性能验证建议：

1. 执行 `npm run serve:prod`。
2. 使用无痕窗口访问 `http://localhost:4173/`。
3. 分别测试默认列表页面和打开编辑器后的页面。
4. 在 Lighthouse 中记录 FCP、LCP、TBT、CLS、总传输量和未使用资源。
5. 使用 `npm run build:analyze` 查看 `dist/stats.html`。

## 安全边界

当前代码审查重点：

- 未发现 `eval`、`new Function`、`document.write` 等危险执行接口。
- 未发现直接使用 `dangerouslySetInnerHTML` 渲染聊天内容的路径。
- 富文本 HTML 由转换器生成，并对文本和样式值进行限制/转义。
- 下载文件通过 Axios 获取 Blob，再由临时 object URL 下载。
- API 错误由统一服务层归一化。

必须注意：

`VITE_*` 环境变量会进入浏览器构建产物，因此 `VITE_AI_API_KEY` 和 `VITE_WORKFLOW_API_KEY` 不能作为生产秘密。生产环境应使用后端代理：

```text
浏览器 -> 自有后端 -> AI / Workflow 服务
```

不要把真正的生产密钥继续放在前端环境变量中。

依赖漏洞检查使用官方 npm registry 或支持 audit advisory API 的镜像：

```bash
npm config set registry https://registry.npmjs.org/
npm audit --omit=dev
```

## 环境变量

常用配置包括：

| 变量                    | 用途                            |
| ----------------------- | ------------------------------- |
| `VITE_API_BASE_URL`     | 后端 API 地址                   |
| `VITE_AI_API_URL`       | AI 聊天服务地址                 |
| `VITE_AI_API_KEY`       | AI 服务访问令牌，不应放生产秘密 |
| `VITE_WORKFLOW_API_URL` | 文档工作流地址                  |
| `VITE_WORKFLOW_API_KEY` | 工作流访问令牌，不应放生产秘密  |
| `VITE_DEBUG`            | 是否输出 API 调试日志           |

默认后端地址由服务层提供，仅适合本地开发。部署时应显式配置 `VITE_API_BASE_URL`。

## 目录导航

```text
src/
├─ components/
│  ├─ ChatPanel/                 聊天面板和消息列表
│  ├─ Editor/                    块编辑器、表格、图片、富文本
│  ├─ EditorPanel/               编辑器面板外壳
│  ├─ ExportRecordList/          导出记录列表
│  ├─ Layout/                    可拖拽双面板布局
│  ├─ SessionList/               会话历史
│  └─ common/                    ErrorBoundary 等通用组件
├─ hooks/                        自定义 hooks
├─ services/                     API、文档、聊天和导出服务
├─ stores/                       Zustand 状态
├─ types/                        TypeScript 数据类型
└─ utils/                        转换、存储、表格和样式工具
```

## 相关文档

| 文档                                                             | 用途                       |
| ---------------------------------------------------------------- | -------------------------- |
| [新编辑器架构设计.md](./新编辑器架构设计.md)                     | 块编辑器架构和数据模型设计 |
| [新编辑器功能设计.md](./新编辑器功能设计.md)                     | 功能和交互设计             |
| [新编辑器开发手册.md](./新编辑器开发手册.md)                     | 开发和调试参考             |
| [新编辑器与聊天面板集成方案.md](./新编辑器与聊天面板集成方案.md) | 集成过程和历史决策         |
| [集成快速参考.md](./集成快速参考.md)                             | 历史集成检查清单           |
| [新编辑器实现路线图.md](./新编辑器实现路线图.md)                 | 历史计划和里程碑           |

后端配套文档位于工作区的 `ax-backend-v1/docs/`，包括 blocks 数据模型、编辑器 API 和导出映射说明。

## 文档维护规则

修改组件、Store、服务或构建脚本后，应同步检查本文档中的：

1. 架构调用链
2. 支持的 Block 类型
3. npm 命令和生产预览端口
4. 性能策略和安全边界
5. 相关文档链接

最后更新：2026-07-17