NTP_V2/docs/HANDOVER.md

8.2 KiB

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%'.