diff --git a/.cursor/agents/doc-updater.md b/.cursor/agents/doc-updater.md index c22783c..1e8658d 100644 --- a/.cursor/agents/doc-updater.md +++ b/.cursor/agents/doc-updater.md @@ -1,51 +1,46 @@ --- name: doc-updater -description: Documentation specialist. Use PROACTIVELY to keep VitePress docs, READMEs, and architecture notes aligned with the codebase. Source of truth is apps/docs-dev plus package.json. +description: Documentation specialist. Use PROACTIVELY to keep user VitePress docs and READMEs aligned with the codebase. User docs live in apps/docs-dev; technical docs live in sibling trackgo-be/docs. tools: Read, Write, Edit, Bash, Grep, Glob model: opus --- # Documentation Updater -Keep docs aligned with this frontend monorepo. Do not invent a NestJS or database map. +Keep documentation aligned with this frontend monorepo. Follow `.cursor/rules/documentation.mdc` and `.cursor/rules/user-docs.mdc`. + +## Documentation split + +| Kind | Location | Audience | +| --- | --- | --- | +| User | `apps/docs-dev/` (VitePress) | Customers / operators — features and usage (web + mobile) | +| Technical | sibling `trackgo-be/docs/` + `mkdocs.yml` | Developers — stack, architecture, how to run | + +Going forward, **do not** add developer architecture, package API, desktop IPC, or setup/stack pages under `apps/docs-dev`. Prefer `src/user/web/` and `src/user/mobile/`. Existing legacy architecture pages stay until a later migration — do not expand them. ## Source of truth -1. Root and package `package.json` scripts -2. `apps/web/.env.example` -3. `apps/docs-dev` (VitePress) — concepts and package APIs -4. `apps/showcase` — actual component/API shape (prefer over stale docs) -5. Root `README.md` +1. Code in `apps/web`, `apps/landing`, and sibling `trackgo_mobile` (menus, modules, routes) +2. Root and package `package.json` scripts +3. `apps/web/.env.example` (`VITE_*` only; public to the client) +4. `apps/showcase` — component/API shape (prefer over stale docs) +5. Root `README.md` for local run commands -Do not create `docs/CONTRIB.md` or `docs/CODEMAPS` unless they already exist. Prefer updating `apps/docs-dev` and the root README. +If a product brief disagrees with code, follow the code or label **Coming soon**. No emoji. Diagrams: PlantUML, not Mermaid. Icons: `lucide-vue-next`. + +Do not create `docs/CONTRIB.md` or `docs/CODEMAPS` unless they already exist. Do not invent NestJS/Drizzle maps inside this frontend repo — put those in trackgo-be MkDocs. ## Workflow -1. Read scripts from root `package.json` (`pnpm dev:web`, `pnpm typecheck:web`, `pnpm check:all`, …) -2. Document env vars from `apps/web/.env.example` (`VITE_*` only; they are public to the client) -3. Detect apps (`web`, `showcase`, `docs-dev`, `desktop`, `landing`) and packages (`ui`, `core-api`, `core-storage`, `core-i18n`, `core-events`, `utils`, `brand`, `configs`) -4. Update VitePress pages under `apps/docs-dev` when APIs or structure change -5. List docs not touched in 90+ days for manual review -6. Show a diff summary - -## Architecture sketch (this repo) - -```text -Browser / Electron - → apps/web (modules: data / domain / presentation) - → @repo/core-api (createHttpClient, CommonRemoteDataServices) - → HTTP API (separate backend) -``` - -## README / VitePress should mention - -- `pnpm install`, `pnpm dev:web`, `pnpm dev:showcase`, `pnpm dev:docs-dev` -- Product work in `apps/web`; copy `example/full-page` -- Env in `apps/web/.env*` -- Tests: `pnpm test` (Vitest) +1. For **user** doc changes: update VitePress under `apps/docs-dev` (prefer `src/user/…`); register nav in `src/.vitepress/config.mts` +2. For **technical** FE/landing/mobile docs: edit sibling `trackgo-be/docs/` and `mkdocs.yml` (see trackgo-be `technical-docs.mdc`) +3. Keep root README run commands accurate (`pnpm install`, `pnpm dev:web`, `pnpm dev:showcase`, `pnpm dev:docs-dev`) +4. List user docs not touched in 90+ days for manual review +5. Show a diff summary ## Quality - Every path mentioned must exist - Commands must match `package.json` -- No NestJS, Drizzle, or PostgreSQL as this app's stack +- No NestJS, Drizzle, or PostgreSQL as this app's stack in user docs +- No emoji; PlantUML for diagrams; Lucide via `lucide-vue-next` when icons are needed diff --git a/.cursor/rules/documentation.mdc b/.cursor/rules/documentation.mdc new file mode 100644 index 0000000..7908684 --- /dev/null +++ b/.cursor/rules/documentation.mdc @@ -0,0 +1,25 @@ +--- +description: TrackGo docs split — user VitePress in apps/docs-dev, technical MkDocs in trackgo-be +alwaysApply: true +--- + +# Documentation Split + +TrackGo has two documentation kinds. Sibling repos: `trackgo-be`, `trackgo-fe`, `trackgo_mobile`. + +| Kind | Audience | Location | Tooling | +| --- | --- | --- | --- | +| Technical | Developers / engineers | `trackgo-be/docs/` + `trackgo-be/mkdocs.yml` | MkDocs / Backstage TechDocs | +| User | Customers / operators | `apps/docs-dev/` (this repo) | VitePress | + +## Rules + +- Technical: stack, architecture, how to run, module interactions (backend, web, landing, mobile) — write in trackgo-be MkDocs, not here. +- User: features and usage for web and mobile only — write under `apps/docs-dev`. +- Going forward, docs-dev is **user documentation only**. Do not add developer architecture, package APIs, desktop IPC, or setup/stack pages there. Existing legacy pages stay until a later migration. +- No emoji in any documentation. +- Diagrams and sequence diagrams: PlantUML fenced blocks (` ```plantuml `), not Mermaid. +- Icons in user docs: Lucide via `lucide-vue-next` (VitePress is Vue). Match icon names used in `apps/web` (`lucide-react` in `menu.data.ts`). Do not paste ad-hoc SVG copies of Lucide. +- Source of truth is the codebase. If a brief disagrees with code, follow the code or label **Coming soon**. Do not invent features. + +Authoring details: `.cursor/rules/user-docs.mdc` (when editing `apps/docs-dev/**`). diff --git a/.cursor/rules/frontend-overview.mdc b/.cursor/rules/frontend-overview.mdc index 9fb3878..e0fb919 100644 --- a/.cursor/rules/frontend-overview.mdc +++ b/.cursor/rules/frontend-overview.mdc @@ -13,7 +13,8 @@ pnpm + Turborepo monorepo. Work from the repository root. Package manager: `pnpm |---|---|---| | **Product development** | `apps/web/` | Primary app — features, auth, modules | | **Component / API reference** | `apps/showcase/` | Living demos of `@repo/*` usage — copy patterns, do not ship product here | -| Deep docs | `apps/docs-dev/` | VitePress (`pnpm dev:docs-dev`) | +| **User documentation** | `apps/docs-dev/` | VitePress user guides (`pnpm dev:docs-dev`) — features and usage only; do not add developer architecture pages | +| **Technical documentation** | sibling `trackgo-be/docs/` | MkDocs / TechDocs — stack, architecture, how to run (web, landing, mobile, backend) | | Shared UI / forms / foundations | `packages/ui` → `@repo/ui/*` | | | HTTP, data services, telemetry | `packages/core-api` → `@repo/core-api/*` | | | Storage | `packages/core-storage` → `@repo/core-storage` | | @@ -28,7 +29,7 @@ pnpm + Turborepo monorepo. Work from the repository root. Package manager: `pnpm ## Hard rules - Implement product features in `apps/web`, not in `showcase` or `docs-dev`. -- Before inventing UI or package usage, match `apps/showcase` demos and `apps/docs-dev` docs. +- Before inventing UI or package usage, match `apps/showcase` demos (component/API shape). User workflows: `apps/docs-dev`. Technical FE architecture: sibling `trackgo-be/docs/`. - Prefer `@repo/ui`, `@repo/core-*`, `@repo/utils` over app-local duplicates or raw Mantine/axios. - Env files live **inside the app** (`apps/web/.env*`), never at monorepo root. Read env via `src/core/environment` (`ENV`), not `import.meta.env` in components. - Run scripts from root: `pnpm dev:web`, `pnpm dev:showcase`, `pnpm lint`, `pnpm typecheck:web`, `pnpm test`, `pnpm test:e2e:web`, `pnpm check:all`. diff --git a/.cursor/rules/user-docs.mdc b/.cursor/rules/user-docs.mdc new file mode 100644 index 0000000..767e117 --- /dev/null +++ b/.cursor/rules/user-docs.mdc @@ -0,0 +1,89 @@ +--- +description: How to write TrackGo user docs in VitePress (apps/docs-dev) +globs: apps/docs-dev/** +alwaysApply: false +--- + +# User Documentation (VitePress) + +Audience: customers and operators. Location: `apps/docs-dev/`. + +## Scope + +Document **features and usage** (menus, screens, workflows) for: + +- Web — `apps/web` +- Mobile — sibling `trackgo_mobile` + +Do **not** document tech stack, package internals, Electron IPC, or monorepo setup here. Technical docs belong in `trackgo-be/docs/` (MkDocs). + +## Where to add pages + +Prefer: + +```text +apps/docs-dev/src/user/web/ +apps/docs-dev/src/user/mobile/ +``` + +Register new pages in `src/.vitepress/config.mts` sidebar/nav. + +Do **not** add new pages under the legacy architecture sidebar paths (`/packages/*`, `/apps/desktop/*`, `/setup`, `/overview`). Those stay until a later migration; do not expand them. + +Existing user how-tos (e.g. `src/apps/web/SALES_WORKFLOW.md`): keep user-facing; when editing, convert Mermaid to PlantUML and remove emoji. + +## Topics (only if present in code) + +**Web** (from menus / modules — verify in `apps/web`): + +- Master data: company settings, branches, divisions, customers, products, employees +- Users and privileges +- Plans (one-time / recurring) and attached invoices / packing slips +- Live timeline / activity history +- Import of invoices / packing slips +- Sales flow: request → order → invoice → payment +- Logistics packing slips + +**Mobile** (from `trackgo_mobile/lib/ui/features/` and `lib/config/router.dart`): + +- Branch check-in before work +- Plans, customers / visits, invoice payment +- Home performance / history + +Anything in a product brief that is not in the code → **Coming soon**. + +## Style + +- No emoji. +- Diagrams / sequences: PlantUML only (do not add Mermaid on new or edited pages). +- Icons: `lucide-vue-next` in markdown ` +``` + +```text +# BAD — new architecture page in docs-dev +apps/docs-dev/src/packages/core-api/new-api.md + +# BAD — Mermaid / emoji / React Lucide in VitePress +```mermaid +``` +"📦 Sales" +import { ShoppingCart } from 'lucide-react' + +# GOOD +apps/docs-dev/src/user/web/sales-workflow.md +apps/docs-dev/src/user/mobile/check-in.md +```