7.2 KiB
7.2 KiB
远楒文档前端
远楒文档协作平台的 Vue 3 单页应用。
技术栈
| 类别 | 技术 |
|---|---|
| 框架 | Vue 3（<script setup> SFC，JavaScript） |
| 构建工具 | Vite |
| UI 组件库 | Element Plus |
| 状态管理 | Pinia |
| 路由 | Vue Router |
| 国际化 | vue-i18n（en-US, zh-CN） |
| 后端通信 | ConnectRPC（gRPC-Web） |
| 富文本编辑器 | TipTap（协作，基于 Yjs） |
| Markdown 编辑器 | EasyMDE、Vditor |
| 代码编辑器 | CodeMirror |
| 协作编辑 | Yjs + y-websocket |
| Diff 渲染 | diff + diff2html |
| 思维导图 | markmap-lib / markmap-view |
| 电子表格 | x-data-spreadsheet |
| CSS 预处理 | Less |
快速开始
前置要求
- Node.js 20+
- npm
安装与运行
npm install
npm run dev
开发服务器默认运行在 80 端口（为 Docker 配置）。本地开发如非 Docker 环境，可能需要调整端口。
环境变量
在 .env 中配置：
| 变量 | 默认值 | 说明 |
|---|---|---|
VITE_API_BASE_URL |
http://localhost:8080 |
REST/gRPC 基础 URL |
VITE_GRPC_WEB_ENDPOINT |
/grpc |
gRPC-Web 端点路径 |
生产构建
npm run build # 输出到 dist/
npm run preview # 预览生产构建
生产 Dockerfile（Dockerfile.prod）会在构建前自动执行 protoc 代码生成。详见 Protobuf 代码生成。
项目结构
src/
├── main.js # 应用入口：创建 Vue 实例，注册插件
├── App.vue # 根组件
├── assets/ # 静态资源
├── components/ # Vue 组件
│ ├── base/ # 基础/原子组件
│ ├── comment/ # 评论与行内评论
│ ├── document/ # 文档相关组件
│ ├── knowledge-base/ # 知识库组件
│ ├── layout/ # 布局外壳（导航、侧边栏）
│ ├── list/ # 列表/表格组件
│ ├── manage/ # 系统管理组件
│ ├── shared/ # 通用/可复用组件
│ └── template/ # 模板组件
├── composables/ # Composition API 组合式函数
│ ├── actions/
│ ├── document/
│ ├── knowledge-base/
│ ├── layout/
│ ├── list/
│ ├── notification/
│ ├── shell/
│ ├── template/
│ ├── useMentionInput.js
│ └── usePageTitle.js
├── config/
│ └── baseUrl.js # API_BASE_URL、GRPC_WEB_ENDPOINT、resolveWithApiBase()
├── i18n/
│ ├── index.js
│ └── locales/
│ ├── en-US.js
│ └── zh-CN.js
├── router/
│ └── index.js # 路由定义、鉴权守卫、页面标题同步
├── services/
│ ├── api.js # 所有 API 模块的聚合导出
│ ├── api/ # 按领域划分的 API 函数
│ │ ├── shared.js # unaryCall、messages、映射器辅助
│ │ ├── document.js
│ │ ├── knowledgeBase.js
│ │ ├── template.js
│ │ ├── membership.js
│ │ ├── invitation.js
│ │ ├── setting.js
│ │ ├── notification.js
│ │ └── comment.js
│ ├── auth.js # 鉴权 API
│ └── grpc_client.js # ConnectRPC 传输层、客户端实例、buildHeaders()
├── store/
│ └── user.js # Pinia 用户 store（token、userInfo）
├── styles/
│ ├── variables.css # CSS 变量（主题）
│ ├── column-resize.css
│ ├── list-cell.css
│ └── mention.css
├── utils/
│ ├── collabUrl.js # 协作 WebSocket URL 构建
│ ├── documentType.js # 文档类型枚举辅助
│ ├── fileUrl.js # 文件 URL 解析
│ └── tableUtils.js # 电子表格工具函数
└── views/
├── auth/ # 登录、注册
├── document/ # 编辑器、历史版本、设置、附件
├── error/ # 404
├── knowledge-base/ # 知识库列表与详情
├── manage/ # 系统管理（用户、用户组、组织、安全、邀请）
├── template/ # 模板列表与预览
├── user/ # 个人资料、设置、通知、邀请
└── workspace/ # 首页、我的文档、搜索
核心架构说明
路径别名
@ 映射到 src/。所有内部导入使用该别名。
gRPC-Web API 层
所有后端通信通过 ConnectRPC（gRPC-Web）：
src/services/grpc_client.js创建传输层和各服务的客户端实例。src/services/api/*.js封装unaryCall()，负责 protobuf 请求构造与响应映射。src/services/api/shared.js提供通用映射器（mapDocument、mapAttachment等）和unaryCall包装器，自动注入鉴权 headers 并处理 401 跳转。src/config/baseUrl.js解析API_BASE_URL和GRPC_WEB_ENDPOINT。
所有 gRPC 请求必须包含 buildHeaders() 返回的 headers（Authorization bearer + accept-language）。unaryCall 包装器已自动处理。
鉴权
- Token 存储在
localStorage，键为token - 用户信息以 JSON 存储在
userInfo - 路由守卫（
requiresAuth: truemeta）将未认证用户重定向到/login - 收到 401（Unauthenticated）响应时，自动清除 token 并跳转登录页
主题
- 默认深色模式
- 切换后持久化到
localStorage，键为darkMode/theme - 在
index.html中尽早应用主题，避免白屏闪烁
Protobuf 代码生成
生成的 protobuf 代码位于 src/gen/（已 gitignore），由父仓库目录下的 proto/yoresee_doc/v1/yoresee_doc.proto 生成。
生产构建时（Dockerfile.prod），protoc 自动执行。本地开发请运行仓库级代码gen脚本：
bash ../deploy/script/gen_proto.sh
生成文件：
src/gen/yoresee_doc/v1/yoresee_doc_pb.js— 消息类型src/gen/yoresee_doc/v1/yoresee_doc_connect.js— ConnectRPC 服务定义
国际化
- 语言：
en-US、zh-CN - 语言偏好存储在
localStorage，键为language - 路由通过
meta.titleKey（i18n key）或meta.dynamicTitle设置页面标题 - Key 按功能命名空间划分（如
document.settings.title、navigation.home）
功能特性
- 文档管理：创建、编辑、删除、重命名文档；文件夹组织
- 多种文档类型：Markdown、富文本（TipTap）、电子表格、幻灯片
- 实时协作：基于 Yjs CRDT 的多人协作编辑（WebSocket）
- 版本历史：查看与对比文档版本，支持左右对照 diff
- 知识库：将文档组织为共享知识库，支持成员权限管控
- 模板：创建与预览文档模板
- 评论：行内评论与文档级评论，支持 @提及
- 附件：上传、预览、下载文件附件
- 搜索：全文搜索文档
- 通知：评论、回复、提及、系统通知
- 系统管理：用户、用户组、组织架构、安全设置、邀请管理
- 思维导图：通过 markmap 将 Markdown 渲染为思维导图
- 深色模式：默认深色主题，支持切换