40 lines
3.4 KiB
Markdown
40 lines
3.4 KiB
Markdown
# AGENTS.md
|
|
|
|
## Cursor Cloud specific instructions
|
|
|
|
### Project overview
|
|
|
|
GoodGo is an enterprise microservices monorepo. The Node.js/TypeScript layer (frontend apps + shared packages) is the primary development target in this cloud environment. Backend services are all .NET 10 and require external infrastructure (Neon PostgreSQL, Redis, Docker) that is not available by default.
|
|
|
|
### Runtime requirements
|
|
|
|
- **Node.js 25** (specified in `.nvmrc` and `package.json` engines). Install via `nvm install 25 && nvm alias default 25`.
|
|
- **pnpm 8.15.0** (specified in `package.json` `packageManager` field). Install via `npm install -g pnpm@8.15.0`.
|
|
|
|
### Key commands
|
|
|
|
Standard commands are documented in `README.md` and `package.json` scripts. Quick reference:
|
|
|
|
| Task | Command |
|
|
|------|---------|
|
|
| Install deps | `pnpm install` |
|
|
| Build shared packages | `pnpm -r --filter "./packages/*" build` |
|
|
| Lint | `pnpm lint` |
|
|
| Typecheck | `pnpm typecheck` |
|
|
| Test | `pnpm test` |
|
|
| Dev (web-client) | `pnpm --filter @goodgo/web-client dev` |
|
|
| Dev (docs) | `pnpm --filter @goodgo/vitepress-docs dev` |
|
|
| Format | `pnpm format` |
|
|
|
|
### Gotchas
|
|
|
|
- **Shared packages must be built before typecheck/dev**: `pnpm typecheck` automatically builds packages first (see the script in root `package.json`), but if running `pnpm --filter @goodgo/web-client dev` directly, ensure packages are built first with `pnpm -r --filter "./packages/*" build`.
|
|
- **Prisma warning on Node 25**: Prisma emits a preinstall warning that Node 25 is not officially supported. This is non-blocking; `pnpm install` completes successfully.
|
|
- **Pre-existing test failures**: 6 tests in `apps/web-client` fail due to Zustand persist middleware requiring `localStorage` which is not properly mocked in the jsdom test environment. These are pre-existing and not caused by environment setup. The failing stores are `auth-store` and `chat-store`.
|
|
- **Backend services (.NET)**: All services under `services/*-net/` require .NET 10 SDK, Neon PostgreSQL, and Redis. They are not runnable in the default cloud environment without those dependencies.
|
|
- **web-client dev server**: Runs on port 3000 by default via `next dev`.
|
|
- **.NET 10 SDK for Blazor apps**: Install via `~/.dotnet/dotnet-install.sh --channel 10.0 --install-dir $HOME/.dotnet`. The update script handles this automatically. Ensure `DOTNET_ROOT=$HOME/.dotnet` and `PATH` includes `$HOME/.dotnet`.
|
|
- **Blazor TPOS dev server**: `dotnet run --project src/WebClientTpos.Server` from `apps/web-client-tpos-net/` serves on port 5092 by default. Build with `dotnet build` from the same directory. Smoke tests: `dotnet test tests/WebClientTpos.SmokeTests/`.
|
|
- **Blazor POS page patterns**: All POS Razor files use `@layout PosLayout`, `@inherits PosBase`, bilingual `EN: / VI:` comments, `@* ═══ SECTION ═══ *@` separators, CSS variables (`--pos-*`), `FormatPrice(decimal)`, `NavigateTo(string)`, Lucide icons. Verticals: Cafe, Restaurant, Karaoke, Spa, Retail. Shared screens: Operations (ClockInOut, ShiftManagement, CashDrawer, PendingOrders, QuickSale), Payment, Dialogs.
|
|
- **BFF data layer**: Cafe, Restaurant, and Spa POS pages load data from `/api/bff/` endpoints via `PosDataService` (injected with `@inject`). The BFF controller (`BffDataController`) uses Dapper + Npgsql to read directly from PostgreSQL. Karaoke still uses mock data (pending FnB engine rooms schema). Pages show "Đang tải..." while loading and "Không thể tải dữ liệu" on API failure.
|