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.Apicontrollers (thin), error mapping (GlobalExceptionHandler), auth, versioningsrc/NTP.Applicationservices, contracts, validators (FluentValidation), repository interfaces, permission keys/defaultssrc/NTP.InfrastructureOracle + Dapper repositories (raw SQL), gateways (TCS, IVR, notifications), file storesrc/NTP.Domainentities and rules;tests/NTP.TestsxUnit (283 tests at hand-over)web/src/features/grains-{orders,permits,registry,reports}screens (metadata-driven DataGrid / MetaForm inweb/src/components),web/src/shellmenu, header, homedb/*.sqlone-off permission / role scripts (run by hand per environment, not by the app);deploy/Docker + Jenkins (seeJenkinsfile)
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(profilehttps), webnpm run devinweb/(http://localhost:5173, proxies /api). Local DB settings go insrc/NTP.Api/appsettings.Local.json(git-ignored, copyappsettings.Local.example.json):ConnectionStrings:NAFITHTCSandConnectionStrings:NtpSchema. .claude/is git-ignored, so recreate.claude/launch.jsonfor 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.jsonor 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_LIVElegacy 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.cfcIVR web service (SOAPcallAPIdials every REQST truck); that app'sApplication.cfcbase64-decodes URL parametersC:\inetpub\wwwroot\mamsreference 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
DynamicParametersthat 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/*RepositoryagainstI{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 toNTP.SYSTEM_ERRORS. - Writes:
IUnitOfWork.ExecuteInTransactionAsync; permit history goes throughIEventLogger(EVENTS table: type, previous/current status, remarks, doneBy). - Permissions (
src/NTP.Application/Access): keys inPermissionKeys; the tableGRAINS_SCREEN_PERMISSIONS(role -> key) is the source of truth,PermissionDefaultsonly applies when that table is missing. SU is always allowed; roleDISABLEDswitches a key off for everybody. Hard-coded role lists also exist (GrainsRolesinPermitSupport.cs,RegistryAccessService,BlacklistService, webOPERATORSin grains-permits/pages.tsx): when a role is added, grep for"GTO"and update them together. Registry accept / revoke / destinations use legacyGROUPS/GROUP_ACTIONSby role name (HasActionAsync). - Company users (
stkid 62or roleDISP) 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'sstrings.ts; theme inweb/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.cfmand 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 pushfails 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.