NTP_V2/CLAUDE.md

7.7 KiB

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","<repo>/src/NTP.Api","--launch-profile","https","--no-build"],"port":7180,"url":"https://localhost:7180"},{"name":"web","runtimeExecutable":"npm","runtimeArgs":["run","dev","--prefix","<repo>/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(<id>, 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.