eigen/trackgo-fe
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

refactor: update documentation structure and guidelines for TrackGo

Browse Source 
- Revised the `doc-updater` documentation to clarify the separation between user and technical documentation, specifying locations and audiences for each type.
- Introduced new rules for authoring user documentation in VitePress, emphasizing the exclusion of technical content and the use of PlantUML for diagrams.
- Added a new `documentation.mdc` file to outline the documentation split and rules for maintaining clarity and consistency across the codebase.
- Updated existing documentation to reflect the new guidelines, ensuring a streamlined approach to documentation management.

These changes enhance the clarity and organization of documentation efforts, improving the overall user experience and maintainability of the codebase.
This commit is contained in:
shancheas
2026-09-04 15:54:48 +07:00
parent 78a1a905d8
commit 2445df8e20
4 changed files with 143 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/agents/doc-updater.md
+26 -31
View File
@@ -1,51 +1,46 @@
--- ---
name: doc-updater 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 tools: Read, Write, Edit, Bash, Grep, Glob
model: opus model: opus
--- ---
# Documentation Updater # 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 ## Source of truth
1. Root and package `package.json` scripts 1. Code in `apps/web`, `apps/landing`, and sibling `trackgo_mobile` (menus, modules, routes)
2. `apps/web/.env.example` 2. Root and package `package.json` scripts
3. `apps/docs-dev` (VitePress) — concepts and package APIs 3. `apps/web/.env.example` (`VITE_*` only; public to the client)
4. `apps/showcase` — actual component/API shape (prefer over stale docs) 4. `apps/showcase` — component/API shape (prefer over stale docs)
5. Root `README.md` 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 ## Workflow
1. Read scripts from root `package.json` (`pnpm dev:web`, `pnpm typecheck:web`, `pnpm check:all`, …) 1. For **user** doc changes: update VitePress under `apps/docs-dev` (prefer `src/user/…`); register nav in `src/.vitepress/config.mts`
2. Document env vars from `apps/web/.env.example` (`VITE_*` only; they are public to the client) 2. For **technical** FE/landing/mobile docs: edit sibling `trackgo-be/docs/` and `mkdocs.yml` (see trackgo-be `technical-docs.mdc`)
3. Detect apps (`web`, `showcase`, `docs-dev`, `desktop`, `landing`) and packages (`ui`, `core-api`, `core-storage`, `core-i18n`, `core-events`, `utils`, `brand`, `configs`) 3. Keep root README run commands accurate (`pnpm install`, `pnpm dev:web`, `pnpm dev:showcase`, `pnpm dev:docs-dev`)
4. Update VitePress pages under `apps/docs-dev` when APIs or structure change 4. List user docs not touched in 90+ days for manual review
5. List docs not touched in 90+ days for manual review 5. Show a diff summary
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)
## Quality ## Quality
- Every path mentioned must exist - Every path mentioned must exist
- Commands must match `package.json` - 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
.cursor/rules/documentation.mdc
+25
View File
@@ -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/**`).
.cursor/rules/frontend-overview.mdc
+3 -2
View File
@@ -13,7 +13,8 @@ pnpm + Turborepo monorepo. Work from the repository root. Package manager: `pnpm
|---|---|---| |---|---|---|
| **Product development** | `apps/web/` | Primary app — features, auth, modules | | **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 | | **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/*` | | | Shared UI / forms / foundations | `packages/ui` → `@repo/ui/*` | |
| HTTP, data services, telemetry | `packages/core-api` → `@repo/core-api/*` | | | HTTP, data services, telemetry | `packages/core-api` → `@repo/core-api/*` | |
| Storage | `packages/core-storage` → `@repo/core-storage` | | | Storage | `packages/core-storage` → `@repo/core-storage` | |
@@ -28,7 +29,7 @@ pnpm + Turborepo monorepo. Work from the repository root. Package manager: `pnpm
## Hard rules ## Hard rules
- Implement product features in `apps/web`, not in `showcase` or `docs-dev`. - 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. - 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. - 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`. - Run scripts from root: `pnpm dev:web`, `pnpm dev:showcase`, `pnpm lint`, `pnpm typecheck:web`, `pnpm test`, `pnpm test:e2e:web`, `pnpm check:all`.
.cursor/rules/user-docs.mdc
+89
View File
@@ -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 `<script setup>`, same Lucide names as web menus.
````markdown
```plantuml
@startuml
actor User
User -> Web: Create sales order
@enduml
```
````
```vue
<script setup>
import { ShoppingCart } from 'lucide-vue-next'
</script>
```
```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
```