# 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: owner decisions (2026-11-17) Decided **to match legacy** (done): blacklist expiry uses shift 1 for a typed permit number and for NO_ANSWER (the real order shift only when a permit id is sent); the dialer callback accepts numbers or strings, any key case and any content type, and answers with the legacy keys `CODE` / `MSG`; trailer edit needs one document (stored or new); revoking a trailer resets its truck to REGREQST only when the revoke is made from the truck's page (trailer opened with `?truckId=`), and never a revoked truck. Decided **to keep V2** (not open): `acceptDriver` accepts (legacy never did), upload rules (fixed extension list, 10 MB), `TO_CHAR(pn/tn)` comparisons, manual weighbridge entry+exit without an outer transaction, manual-input date list, done-by shown to company users, used-orders count summed. Settled: time zone (container `TZ=Asia/Amman`, verified by the owner). No rate limit on the dialer callback; replays duplicate blacklist rows, as in legacy. Still open / not ported: company destinations save (Orders slice) only deletes the locations the screen offers (PCKD / BULK / BULK_GALLAB) where legacy deleted every row of the company, and it writes only ID / SCAC / LOCATIONID where legacy also wrote date and user (check the production table's columns and NOT NULL flags: `select column_name, nullable from user_tab_columns where table_name='GRAINS_COMPANIES_LOCATION'`); company users' "registered count share/open" on the truck / trailer grids; head-type change log; Firebase push; QUED/TCS permit flow (tables missing on QA); the approvals-file import is a second copy of the phone logic and likely broken (SU-only, legacy button commented out). ### 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%'`.