YoreseeDoc/frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update README and AGENTS.md

Browse Source
This commit is contained in:
XingfenD
2026-08-11 10:56:47 +08:00
parent a1cccc8068
commit c97304b786
4 changed files with 444 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+198
View File
@@ -0,0 +1,198 @@
# Yoresee Doc Frontend
Vue 3 single-page application for the Yoresee Doc collaborative document platform.
## Tech Stack
| Category | Technology |
|----------|-----------|
| Framework | Vue 3 (`<script setup>` SFCs, JavaScript) |
| Build tool | Vite |
| UI library | Element Plus |
| State management | Pinia |
| Routing | Vue Router |
| Internationalization | vue-i18n (en-US, zh-CN) |
| Backend communication | ConnectRPC (gRPC-Web) |
| Rich text editor | TipTap (collaborative, Yjs-backed) |
| Markdown editors | EasyMDE, Vditor |
| Code editor | CodeMirror |
| Collaborative editing | Yjs + y-websocket |
| Diff rendering | diff + diff2html |
| Mind maps | markmap-lib / markmap-view |
| Spreadsheets | x-data-spreadsheet |
| CSS preprocessing | Less |
## Getting Started
### Prerequisites
- Node.js 20+
- npm
### Install & Run
```bash
npm install
npm run dev
```
The dev server starts on port 80 (configured for Docker). In local development without Docker, it will attempt port 80 and may need adjustment.
### Environment Variables
Set in `.env`:
| Variable | Default | Description |
|----------|---------|-------------|
| `VITE_API_BASE_URL` | `http://localhost:8080` | REST/gRPC base URL |
| `VITE_GRPC_WEB_ENDPOINT` | `/grpc` | gRPC-Web endpoint path |
### Production Build
```bash
npm run build # outputs to dist/
npm run preview # preview production build
```
The production Dockerfile (`Dockerfile.prod`) runs `protoc` code generation before building. See [Protobuf Codegen](#protobuf-codegen) below.
## Project Structure
```
src/
├── main.js # App entry: creates Vue app, registers plugins
├── App.vue # Root component
├── assets/ # Static assets
├── components/ # Vue components
│ ├── base/ # Base/primitive components
│ ├── comment/ # Comment & inline comment
│ ├── document/ # Document-related components
│ ├── knowledge-base/ # Knowledge base components
│ ├── layout/ # Layout shell (nav, sidebar)
│ ├── list/ # List/table components
│ ├── manage/ # System management components
│ ├── shared/ # Shared/reusable components
│ └── template/ # Template components
├── composables/ # Composition API hooks
│ ├── 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 # Route definitions, auth guard, page title sync
├── services/
│ ├── api.js # Barrel re-export for all API modules
│ ├── api/ # Domain-specific API functions
│ │ ├── shared.js # unaryCall, messages, mapper helpers
│ │ ├── document.js
│ │ ├── knowledgeBase.js
│ │ ├── template.js
│ │ ├── membership.js
│ │ ├── invitation.js
│ │ ├── setting.js
│ │ ├── notification.js
│ │ └── comment.js
│ ├── auth.js # Auth API
│ └── grpc_client.js # ConnectRPC transport, client instances, buildHeaders()
├── store/
│ └── user.js # Pinia user store (token, userInfo)
├── styles/
│ ├── variables.css # CSS variables (theming)
│ ├── column-resize.css
│ ├── list-cell.css
│ └── mention.css
├── utils/
│ ├── collabUrl.js # Collaboration WebSocket URL builder
│ ├── documentType.js # Document type enum helpers
│ ├── fileUrl.js # File URL resolution
│ └── tableUtils.js # Spreadsheet utilities
└── views/
├── auth/ # Login, Register
├── document/ # Editor, History, Settings, Attachments
├── error/ # 404
├── knowledge-base/ # Knowledge base list & detail
├── manage/ # System admin (users, groups, org, security, invitations)
├── template/ # Template list & preview
├── user/ # Profile, settings, notifications, invitations
└── workspace/ # Home, MyDocuments, Search
```
## Key Architecture Notes
### Path Alias
`@` maps to `src/`. All internal imports use this alias.
### gRPC-Web API Layer
All backend communication goes through ConnectRPC (gRPC-Web):
1. `src/services/grpc_client.js` creates the transport and client instances for each service.
2. `src/services/api/*.js` wraps `unaryCall()` with protobuf request construction and response mapping.
3. `src/services/api/shared.js` provides common mappers (`mapDocument`, `mapAttachment`, etc.) and the `unaryCall` wrapper that injects auth headers and handles 401 redirects.
4. `src/config/baseUrl.js` resolves `API_BASE_URL` and `GRPC_WEB_ENDPOINT`.
All gRPC requests must include headers from `buildHeaders()` (Authorization bearer + accept-language). The `unaryCall` wrapper handles this automatically.
### Authentication
- Token stored in `localStorage` as `token`
- User info stored as JSON in `userInfo`
- Router guard (`requiresAuth: true` meta) redirects unauthenticated users to `/login`
- On 401 (Unauthenticated) response, token is cleared and user is redirected to `/login`
### Theming
- Dark mode is the default
- Toggle persists to `localStorage` key `darkMode` / `theme`
- Theme is applied early in `index.html` to avoid flash of unstyled content
### Protobuf Codegen
Generated protobuf code lives in `src/gen/` (gitignored). It is produced from `proto/yoresee_doc/v1/yoresee_doc.proto` in the parent repo directory.
During production builds (`Dockerfile.prod`), `protoc` runs automatically. For local development, run the repo-level codegen script:
```bash
bash ../deploy/script/gen_proto.sh
```
Generated files include:
- `src/gen/yoresee_doc/v1/yoresee_doc_pb.js` — message types
- `src/gen/yoresee_doc/v1/yoresee_doc_connect.js` — ConnectRPC service definitions
### i18n
- Locales: `en-US`, `zh-CN`
- Language preference stored in `localStorage` as `language`
- Router sets page titles via `meta.titleKey` (i18n key) or `meta.dynamicTitle`
- Keys are namespaced by feature (e.g., `document.settings.title`, `navigation.home`)
## Features
- **Document management**: Create, edit, delete, rename documents; organize in folders
- **Multiple document types**: Markdown, rich text (TipTap), spreadsheet, slide
- **Real-time collaboration**: Multi-user editing via Yjs CRDT over WebSocket
- **Version history**: View and compare document versions with side-by-side diff
- **Knowledge bases**: Organize documents into shared knowledge bases with membership controls
- **Templates**: Create and preview document templates
- **Comments**: Inline comments and document-level comments with @mentions
- **Attachments**: Upload, preview, and download file attachments
- **Search**: Full-text document search
- **Notifications**: Comment, reply, mention, and system notifications
- **System management**: User, user group, organization, security, and invitation management
- **Mind maps**: Render Markdown as mind maps via markmap
- **Dark mode**: Default dark theme with toggle
docs/README_zh.md
+198
View File
@@ -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 渲染为思维导图
- **深色模式**：默认深色主题，支持切换