frontend/docs/README.md

# 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