Add CLAUDE.md and docs/HANDOVER.md for the next developer

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Samer Salameh 2026-11-17 16:20:41 +03:00
parent bf1c04b590
commit 6d6ac06704
2 changed files with 125 additions and 0 deletions

62
CLAUDE.md Normal file
View File

@ -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","<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.

63
docs/HANDOVER.md Normal file
View File

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