pos-system/AGENTS.md

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.