# 远楒文档前端

远楒文档协作平台的 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 渲染为思维导图
- **深色模式**：默认深色主题，支持切换