ax-frontend-app/docs

AX 前端项目文档

文档定位

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

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

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

快速开始

在项目目录执行：

npm install
npm run dev

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

生产构建：

npm run build
npm run preview

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

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	执行构建并输出资源体积统计

当前架构

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。

编辑器实现

当前编辑器调用链如下：

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 统一处理，必要时进行排序重建和保存。

富文本

富文本片段结构：

{
  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	文档创建和文档相关操作

典型编辑流程：

用户输入
  -> 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 不能作为生产秘密。生产环境应使用后端代理：

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

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

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

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。

目录导航

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	历史计划和里程碑

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

文档维护规则

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

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

最后更新：2026-07-17