diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f3aa56a --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,62 @@ +# 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. diff --git a/docs/HANDOVER.md b/docs/HANDOVER.md new file mode 100644 index 0000000..dab8906 --- /dev/null +++ b/docs/HANDOVER.md @@ -0,0 +1,63 @@ +# Hand-over notes (written 2026-11-17) + +How to start: open the repository folder in Claude Code (it reads `CLAUDE.md` by itself), then say +"Read docs/HANDOVER.md and CLAUDE.md, summarise the state and the open items". Claude's per-machine memory does **not** travel with the +repository: everything a new person needs is in these two files, `docs/ENVIRONMENTS.md` and `docs/MIGRATION.md`. Keep them updated. + +## 1. State of the work +- **Look and feel** ported from the `mams` project (theme tokens, Cairo font, grids, framed form sections, view page with Details / Attachments tabs, grouped home page, collapsible menu, Arabic only, breadcrumbs in the header). +- **Billing (المطالبات المالية)** ported from the new legacy `Invoice.cfc` (wages / fines lookup, invoice creation, serial / invoice number mapping). +- **Registry (trucks, trailers, drivers):** attachments are stored under `Grains:Registry:UploadedFilesPath` (production `/mnt/NTPFiles`, sub-folders `ntp_trucks_files` / `ntp_trailers_files` / `ntp_drivers_files`; legacy names like `0.723.pdf` are read). +- **Reports:** the two GTO reports (ارسالية عطاء التموين, ملخص التوزيع) and turn reports (translated values, centred counters). +- **Permits / distribution:** distribution reviewed twice against legacy and fixed (BlCategory bind, General Cargo exclusion, OPEN guards, queue cursor reset at sign-in, per-category confirmation, process-with-destination dropdowns + server check); voice call (الاتصال الصوتي) uses the legacy SOAP call; dialer callback hardened. +- **Security pass:** accept / reject / cancel-confirmation staff-only, submit needs REQST, company-access null check, seed / check-trucks SU-only, attachment download scoped to the company. +- **Operations:** unexpected 5xx errors go to `SYSTEM_ERRORS`; containers run with `TZ=Asia/Amman`. +- **Roles:** `CO` was given the same code-level rights as `GTO` (see 3.1). +- Last local commit at hand-over: `bf1c04b`. **It may not be pushed** (Claude sessions cannot authenticate to Gitea): run `git log origin/main..HEAD` and push it. + +## 2. Deploy / configuration checklist (nothing below was verified on the production server) +1. Jenkins builds `deploy/qa/Dockerfile` (`WEB_MODE=build:prod`), pushes the image, copies `deploy/prod/docker-compose.yml` to the server and runs `docker compose pull && up -d --no-build` (see `Jenkinsfile`). The compose file must reach the server for new volumes / env to apply. +2. Server `.env` (never committed): `ConnectionStrings__NAFITHTCS`, `ConnectionStrings__NtpSchema`, `Jwt__Key`, `Cors__AllowedOrigins__0`; optional `Grains__Permits__AutoCall__ApiKey` (the dialer's callback key, empty = callback disabled). +3. Host folder `/mnt/NTPFiles` must exist, be writable by the container, and hold the legacy files in `ntp_*_files`. Check `docker inspect ntpv2-prod --format '{{json .Mounts}}'`. +4. `Grains:Registry:UploadedFilesPath` must be a plain path (`/mnt/NTPFiles`), never a `host:container` mapping. +5. `appsettings.Production.json` sets: attachment paths, `Grains:Permits:AutoCall` (enabled, IVR WSDL address), ownership code lists (`BadiyaOwnershipCodes 3,2`, `OtherOwnershipCodes 1,2` - confirm against production `SYSTEM_VARIABLES`). +6. The provider of the dialer must call `/api/v1/grains/permit-autocall/callback` with header `X-Api-Key`; nothing in the repo repoints it. +7. Mobile push / SMS (legacy Firebase) is **not ported**: `Grains:Permits:Notifications` only posts to a URL that does not exist yet (disabled by default). +8. The NTP database user needs INSERT on `SYSTEM_ERRORS` and SELECT on `SEQ_SYSTEM_ERRORS`, otherwise error logging only writes a warning to the API log. +9. After deploy: `docker exec ntpv2-prod date` (Amman time), `/health/ready`, sign in, open a truck attachment, click الاتصال الصوتي once (it really dials every requested truck: do not test casually). +10. Database scripts: see docs/ENVIRONMENTS.md ("Database objects"). They are applied by hand; which ones ran on which environment is not recorded: check the tables before re-running (all are safe to re-run). + +## 3. Open decisions and known gaps +### 3.1 Role CO +`CO` already existed in the database ("مدير العمليات وخدمة الجمهور", own group id 149, stakeholder 61, 29 mostly oil-related actions, 1 user) and the legacy menu uses it in many places. The code now treats CO like GTO, and `GRAINS_SCREEN_PERMISSIONS` already has the same 27 rows for both. **Decide** whether that user should really get GTO's grains authority or whether a new role code is wanted. Also unresolved: CO's legacy group has none of the registry actions 66-71 / 107, so accept / revoke of trucks, trailers, drivers and destinations are off for CO; `db/role-co.sql` does not create `GROUPS` / `GROUP_ACTIONS` rows. + +### 3.2 Role lists in code differ from the legacy action holders +Legacy holders (from the database): phone confirm 93 = GNSU, GOO, GTO, MOT, SU; cancel order 106 = GNSU, GOO, GPO, MOT, SU; cancel permit 167 = GTO, MOT; voice call 96 = GNAC, GNSU, GTO, MOT, SU; accept / reject / cancel-confirmation 74 / 85 / 88 = GNSU, GOO, GPO, GTO, MOT, SU. V2 uses the single list `GrainsRoles.Operators` (SU, GPO, GNSU, GNCO, GTO, CO), so GOO cannot confirm by phone or cancel an order, and the "staff" gate for accept / reject is "any non-company user" (includes GGO). Proposed: one explicit role list per action. + +### 3.3 Review findings not yet fixed (from the legacy review of grains.cfc, register.cfc, autoCallResponse.cfc) +- Time zone of `DateTime.Now` expiry vs Oracle `SYSDATE` (container now Amman; verify). +- NO_ANSWER / blacklist expiry use the order's real shift; legacy always used shift 1 for typed numbers (confirm which is wanted). +- Dialer callback: strict string fields (400 on numeric JSON), no rate limit, replays duplicate blacklist rows (as in legacy). +- Company destinations save (Orders slice) deletes only PCKD / BULK / BULK_GALLAB locations; audit columns not written. +- `acceptDriver`: legacy never accepts (bug), V2 accepts; accepted drivers then disappear from the GOO grid. +- Trailer edit needs 2 attachments (stored + new), legacy effectively 1; revoke trailer always resets the truck to REGREQST. +- Not ported: company users' "registered count share/open" on the truck / trailer grids, head-type change log, Firebase push, QUED/TCS permit flow (its tables are missing on QA), the approvals-file import is a second copy of the phone logic and likely broken (SU-only; legacy button commented out). +- Production upload rules differ from legacy (legacy allowed xls / xlsx / zip, no size limit; V2 a fixed list, 10 MB). +- Performance: many queries use `TO_CHAR(pn)` / `TO_CHAR(tn)` on indexed number columns; measure a real distribution run (the command timeout is 30 s). +- Manual weighbridge entry + exit are not in one transaction; manual-input screen date list differs from legacy and assumes `GN_MANUAL_ORDER.id = GRAINSTENDERORDER.id` (unverified). +- Done-by column is still shown to company users (legacy hid it) - deliberately skipped so far. +- Used-orders count: the view `GN_USED_ORDER_BY_CATEGORY` may return several rows for PCKD; V2 sums them, legacy read the first row. Check the view's rows. + +### 3.4 Never tested against real data +Distribution runs, the IVR call, dialer callbacks, `SYSTEM_ERRORS` insert, the attachment folder in the container, the Amman time zone. Everything was verified only by build, unit tests, type check and read-only queries. + +## 4. Security housekeeping for the owner +- Database passwords from `appsettings.Local.json` were once shown in a Claude session's output: **rotate them**. +- Make sure the new developer has Gitea access (push) and their own `appsettings.Local.json`; they need network access to the Oracle servers. +- The repository holds no secrets by design (`.env` and `appsettings.Local.json` are git-ignored). + +## 5. Useful read-only database checks +Role and groups: `select * from roles where code='GTO'`, `select id,name,stakeholderid,status from groups where name in ('GTO','CO')`. +Who holds a legacy action: `select ga.actionid, listagg(g.name,',') within group (order by g.name) from group_actions ga join groups g on g.id=ga.groupid and g.status=1 where ga.actionid in (73,74,93,94) group by ga.actionid`. +Screen rights per role: `select rolecode, count(*) from grains_screen_permissions group by rolecode`. +Ownership lists: `select name, value from system_variables where upper(name) like '%OWNERSHIP%'`.