64 lines
7.8 KiB
Markdown
64 lines
7.8 KiB
Markdown
# 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
|
|
- `src/NTP.*/Jobs` + `web/src/features/jobs` scheduled jobs (SU screen `/jobs`; catalog in `JobCatalog`; tables from `db/grains-jobs.sql`)
|
|
- `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.
|