From c97304b7866361a6796ccda6668e236dba5a8227 Mon Sep 17 00:00:00 2001
From: XingfenD <xingfen.fendy@outlook.com>
Date: Tue, 11 Aug 2026 10:56:47 +0800
Subject: [PATCH] update README and AGENTS.md

---
 AGENTS.md         |  48 +++++++++++
 README.md         |   5 --
 docs/README.md    | 198 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/README_zh.md | 198 ++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 444 insertions(+), 5 deletions(-)
 create mode 100644 AGENTS.md
 delete mode 100644 README.md
 create mode 100644 docs/README.md
 create mode 100644 docs/README_zh.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3dcf016
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,48 @@
+# AGENTS.md
+
+## Commands
+
+- `npm run dev` — start Vite dev server (port 80 in Docker)
+- `npm run build` — production build to `dist/`
+- `npm run preview` — preview production build
+
+No test, lint, typecheck, or formatter scripts are configured.
+
+## Architecture
+
+Single-page Vue 3 app (JavaScript, no TypeScript). UI library is Element Plus, state via Pinia, routing via vue-router, i18n via vue-i18n (en-US, zh-CN).
+
+### Path alias
+
+`@` maps to `src/`. All internal imports use this alias.
+
+### gRPC-Web API layer
+
+Backend communication uses ConnectRPC (gRPC-Web). Generated protobuf code lives in `src/gen/` — **gitignored**, produced at build time by `protoc` from `proto/yoresee_doc/v1/yoresee_doc.proto` (sibling repo directory). The production Dockerfile runs codegen before `npm run build`.
+
+- `src/services/grpc_client.js` — transport, client instances, `unaryCall` wrapper, `messages` re-export
+- `src/services/api/*.js` — domain API functions that wrap `unaryCall` with protobuf request/response mappers
+- `src/services/api/shared.js` — common helpers (`unaryCall`, `messages`, mappers like `mapDocument`, `mapAttachment`)
+- `src/config/baseUrl.js` — `API_BASE_URL` (from `VITE_API_BASE_URL` env or `window.location.origin`), `GRPC_WEB_ENDPOINT` (defaults to `/grpc`)
+
+### Key libraries
+
+- **Rich text editors**: TipTap (collaborative, Yjs-backed), EasyMDE (Markdown), Vditor, CodeMirror
+- **Collaborative editing**: Yjs + y-websocket
+- **Diff rendering**: `diff` + `diff2html`
+- **Mind maps**: markmap-lib / markmap-view
+- **Spreadsheets**: x-data-spreadsheet
+
+### Environment
+
+- `VITE_API_BASE_URL` — REST/gRPC base (default: `http://localhost:8080` via `.env`)
+- `VITE_GRPC_WEB_ENDPOINT` — gRPC endpoint path (default: `/grpc`)
+- Dark mode is the default; toggled via `localStorage` key `darkMode`/`theme`
+
+## Conventions
+
+- Components are Vue SFCs using `<script setup>`
+- Router meta `requiresAuth: true` guards authenticated routes; `titleKey` drives i18n page titles
+- Auth token stored in `localStorage` as `token`; user info as JSON in `userInfo`
+- gRPC requests must include headers from `buildHeaders()` (Authorization + accept-language)
+- i18n keys are namespaced (e.g., `document.settings.title`, `navigation.home`)
diff --git a/README.md b/README.md
deleted file mode 100644
index 1511959..0000000
--- a/README.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Vue 3 + Vite
-
-This template should help get you started developing with Vue 3 in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
-
-Learn more about IDE Support for Vue in the [Vue Docs Scaling up Guide](https://vuejs.org/guide/scaling-up/tooling.html#ide-support).
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..e6c1369
--- /dev/null
+++ b/docs/README.md
@@ -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
diff --git a/docs/README_zh.md b/docs/README_zh.md
new file mode 100644
index 0000000..0e0b995
--- /dev/null
+++ b/docs/README_zh.md
@@ -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 渲染为思维导图
+- **深色模式**：默认深色主题，支持切换