8.3 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
mamsproject (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-foldersntp_trucks_files/ntp_trailers_files/ntp_drivers_files; legacy names like0.723.pdfare 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 withTZ=Asia/Amman. - Roles:
COwas given the same code-level rights asGTO(see 3.1). - Last local commit at hand-over:
bf1c04b. It may not be pushed (Claude sessions cannot authenticate to Gitea): rungit log origin/main..HEADand push it.
2. Deploy / configuration checklist (nothing below was verified on the production server)
- Jenkins builds
deploy/qa/Dockerfile(WEB_MODE=build:prod), pushes the image, copiesdeploy/prod/docker-compose.ymlto the server and runsdocker compose pull && up -d --no-build(seeJenkinsfile). The compose file must reach the server for new volumes / env to apply. - Server
.env(never committed):ConnectionStrings__NAFITHTCS,ConnectionStrings__NtpSchema,Jwt__Key,Cors__AllowedOrigins__0; optionalGrains__Permits__AutoCall__ApiKey(the dialer's callback key, empty = callback disabled). - Host folder
/mnt/NTPFilesmust exist, be writable by the container, and hold the legacy files inntp_*_files. Checkdocker inspect ntpv2-prod --format '{{json .Mounts}}'. Grains:Registry:UploadedFilesPathmust be a plain path (/mnt/NTPFiles), never ahost:containermapping.appsettings.Production.jsonsets: attachment paths,Grains:Permits:AutoCall(enabled, IVR WSDL address), ownership code lists (BadiyaOwnershipCodes 3,2,OtherOwnershipCodes 1,2- confirm against productionSYSTEM_VARIABLES).- The provider of the dialer must call
/api/v1/grains/permit-autocall/callbackwith headerX-Api-Key; nothing in the repo repoints it. - Mobile push / SMS (legacy Firebase) is not ported:
Grains:Permits:Notificationsonly posts to a URL that does not exist yet (disabled by default). - The NTP database user needs INSERT on
SYSTEM_ERRORSand SELECT onSEQ_SYSTEM_ERRORS, otherwise error logging only writes a warning to the API log. - 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). - 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.Nowexpiry vs OracleSYSDATE(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_CATEGORYmay 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.jsonwere 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 (
.envandappsettings.Local.jsonare 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%'.