# NTP V2: instructions for Claude Code .NET 10 API + React web app that replace the legacy ColdFusion "NTP" system (Aqaba; the **Grains / حبوب** modules are the active work). The legacy system is the specification: when behaviour is unclear, read the legacy code and match it. Current state, open decisions and deployment checklists are in **docs/HANDOVER.md** (read it first in a new session). Environments: docs/ENVIRONMENTS.md. Porting conventions: docs/MIGRATION.md. Table definitions: docs/schema/NTP.md and NAFITHTCS.md. Stack rationale: README.md. ## Layout - `src/NTP.Api` controllers (thin), error mapping (`GlobalExceptionHandler`), auth, versioning - `src/NTP.Application` services, contracts, validators (FluentValidation), repository interfaces, permission keys/defaults - `src/NTP.Infrastructure` Oracle + Dapper repositories (raw SQL), gateways (TCS, IVR, notifications), file store - `src/NTP.Domain` entities and rules; `tests/NTP.Tests` xUnit (283 tests at hand-over) - `web/src/features/grains-{orders,permits,registry,reports}` screens (metadata-driven DataGrid / MetaForm in `web/src/components`), `web/src/shell` menu, header, home - `db/*.sql` one-off permission / role scripts (run by hand per environment, not by the app); `deploy/` Docker + Jenkins (see `Jenkinsfile`) ## Commands (Windows; Git Bash or PowerShell) - Needs the **.NET 10 SDK** (`dotnet --list-sdks`). On the previous machine PATH pointed to SDK 9, so a local SDK 10 folder was used explicitly. - Build: `dotnet build src/NTP.Api` - Tests: `dotnet test tests/NTP.Tests` - Web type check: `cd web && npx tsc -b --noEmit` - **Stop the running API before building** (otherwise MSB3248 "file is being used"; a failed build then silently leaves the old DLLs). Wait a few seconds after stopping. - Run: API `https://localhost:7180` (profile `https`), web `npm run dev` in `web/` (http://localhost:5173, proxies /api). Local DB settings go in `src/NTP.Api/appsettings.Local.json` (git-ignored, copy `appsettings.Local.example.json`): `ConnectionStrings:NAFITHTCS` and `ConnectionStrings:NtpSchema`. - `.claude/` is git-ignored, so recreate `.claude/launch.json` for the preview tools: `{"version":"0.0.1","configurations":[{"name":"api","runtimeExecutable":"dotnet","runtimeArgs":["run","--project","/src/NTP.Api","--launch-profile","https","--no-build"],"port":7180,"url":"https://localhost:7180"},{"name":"web","runtimeExecutable":"npm","runtimeArgs":["run","dev","--prefix","/web"],"port":5173}]}` (`--no-build`: always build first). - Never print `appsettings.Local.json` or any connection string (it holds real database passwords). - Shell quoting: backslashes inside regexes get lost in heredocs / `node -e`. For code with regexes write a script file or use the Edit tool, then compile. ## Legacy references (read-only, never edit; paths are per machine, ask for a copy if missing) - `C:\inetpub\wwwroot\NTP_LIVE` legacy app: `services\Grains\cfc\grains.cfc` (6.2k lines: permits, queue, distribution, weighbridge, blacklist), `register.cfc` (trucks / trailers / drivers), `autoCallResponse.cfc` (IVR callback), `GrainsFactoryWeb.cfc`, `customtags\menu.cfm` (menu roles), `services\Grains\*.cfm` (screens), `components\` (common helpers) - `C:\inetpub\wwwroot\AqabaTCS_LIVE\IVR\callivr.cfc` IVR web service (SOAP `callAPI` dials every REQST truck); that app's `Application.cfc` base64-decodes URL parameters - `C:\inetpub\wwwroot\mams` reference project for the look and feel (palette, Cairo font, grids) - Legacy gates screens with `application.objAuth.isActAuthorized(, session.lstGID)`. The id->group mapping is in the database (`GROUP_ACTIONS` + `GROUPS` + `ACTIONS`, NTP schema): 72 register turn, 73 submit, 74 accept, 77 edit, 85 reject, 88 cancel confirmation, 93 phone confirm, 94 distribute, 96 voice-call/report, 100/101 print, 106 cancel order, 107 destinations, 167 cancel permit, 66-71 registry accept / revoke ## Rules of the code base - **Oracle 11.2** (ODP.NET 3.21.x pinned): no OFFSET/FETCH or identity; page with ROWNUM (`OracleSql.Paginate`). Dapper, not EF. - Dapper maps a positional record badly with Oracle NUMBER (decimal vs long): use classes with settable properties for query results. - ODP.NET binds by name: a parameter added to `DynamicParameters` that the SQL text does not use fails with **ORA-01006** (anonymous objects are filtered, DynamicParameters are not). - Do not wrap indexed number columns in `TO_CHAR(...)` in new SQL (it kills the index); bind a number. Several old queries still do. - Services register by convention (`*Service` / `*Repository` against `I{Name}`, scoped). Two connections: `IDbSession` = primary NAFITHTCS, `INtpDbSession` = NTP schema; transactions are per connection. - Errors: throw `BusinessException` (422), `ForbiddenException` (403), `NotFoundException` (404), FluentValidation (400); user-facing messages are the legacy Arabic texts, keep them verbatim. Unexpected 5xx errors are written to `NTP.SYSTEM_ERRORS`. - Writes: `IUnitOfWork.ExecuteInTransactionAsync`; permit history goes through `IEventLogger` (EVENTS table: type, previous/current status, remarks, doneBy). - **Permissions** (`src/NTP.Application/Access`): keys in `PermissionKeys`; the table `GRAINS_SCREEN_PERMISSIONS` (role -> key) is the source of truth, `PermissionDefaults` only applies when that table is missing. SU is always allowed; role `DISABLED` switches a key off for everybody. Hard-coded role lists also exist (`GrainsRoles` in `PermitSupport.cs`, `RegistryAccessService`, `BlacklistService`, web `OPERATORS` in grains-permits/pages.tsx): when a role is added, grep for `"GTO"` and update them together. Registry accept / revoke / destinations use legacy `GROUPS`/`GROUP_ACTIONS` by role name (`HasActionAsync`). - Company users (`stkid 62` or role `DISP`) see and change only their own company (`EnsureCompanyAccess`); company code 327 = "الأهالي" (individual owners, `BadiyaScac`). - Web: Arabic (RTL) is the default and only language shown; light default, dark available; use logical CSS properties (`marginInlineStart`, not left/right); MUI 9 (`sx`, no system props); strings are bilingual `{ en, ar }` in each feature's `strings.ts`; theme in `web/src/theme`. - Every new SQL script in `db/` must be safe to re-run and listed in docs/ENVIRONMENTS.md. ## Domain vocabulary PN permit number, TN truck, TRN trailer, NNPN driver national no., SCAC company code, TT cargo class (BULK / PCKD / GALLAB). Permit status: OPEN on the turn (على الدور), REQST distributed to an order, PLND submitted by the company, ACCPT confirmed (ready for release), RESD released (تسريب), ACTRL at control, CLRPR cleared, CLOSE closed, RVKD revoked. Distribution categories: PCKD, BULK_AHALE, BULK_COMP, BULK_GALLAB_AHALE, BULK_GALLAB_COMP (queue type `AHALI` in queues, `AHALE` in orders: a legacy quirk). ## How to work here (agreed with the owner) - Understand the legacy behaviour first and cite legacy file:line when porting or fixing. Do not port dead legacy code (check `menu.cfm` and callers). - For a review request: report findings first (grouped definite bug / needs confirmation / benign), fix only what the owner picks. Verify agent findings in the code before presenting them. - Before saying "done": `dotnet build`, `dotnet test`, `npx tsc -b --noEmit`, restart the API and check its log. Say plainly what was not tested (nothing here was run against production data). - Commit only when asked. `git push` fails from a Claude session (no Gitea credentials): give the owner the command instead. - Production values (`appsettings.Production.json`) hold only non-secret settings; secrets come from the server `.env`. Never put passwords, keys or tokens in the repo or in chat. - Keep answers short, plain, and in the language the owner writes in; UI texts stay Arabic.