update README and AGENTS.md
This commit is contained in:
@@ -0,0 +1,198 @@
|
||||
# 远楒文档前端
|
||||
|
||||
远楒文档协作平台的 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
|
||||
|
||||
### 安装与运行
|
||||
|
||||
```bash
|
||||
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 端点路径 |
|
||||
|
||||
### 生产构建
|
||||
|
||||
```bash
|
||||
npm run build # 输出到 dist/
|
||||
npm run preview # 预览生产构建
|
||||
```
|
||||
|
||||
生产 Dockerfile（`Dockerfile.prod`）会在构建前自动执行 `protoc` 代码生成。详见 [Protobuf 代码生成](#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）：
|
||||
|
||||
1. `src/services/grpc_client.js` 创建传输层和各服务的客户端实例。
|
||||
2. `src/services/api/*.js` 封装 `unaryCall()`，负责 protobuf 请求构造与响应映射。
|
||||
3. `src/services/api/shared.js` 提供通用映射器（`mapDocument`、`mapAttachment` 等）和 `unaryCall` 包装器，自动注入鉴权 headers 并处理 401 跳转。
|
||||
4. `src/config/baseUrl.js` 解析 `API_BASE_URL` 和 `GRPC_WEB_ENDPOINT`。
|
||||
|
||||
所有 gRPC 请求必须包含 `buildHeaders()` 返回的 headers（Authorization bearer + accept-language）。`unaryCall` 包装器已自动处理。
|
||||
|
||||
### 鉴权
|
||||
|
||||
- Token 存储在 `localStorage`，键为 `token`
|
||||
- 用户信息以 JSON 存储在 `userInfo`
|
||||
- 路由守卫（`requiresAuth: true` meta）将未认证用户重定向到 `/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
|
||||
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 渲染为思维导图
|
||||
- **深色模式**：默认深色主题，支持切换
|
||||
Reference in New Issue
Block a user