update README and AGENTS.md

2026-08-11 10:56:47 +08:00
parent a1cccc8068
commit c97304b786
4 changed files with 444 additions and 5 deletions
@@ -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`)