# NTP migration conventions (Grains first) Legacy: ColdFusion 9, `C:\inetpub\wwwroot\NTP_LIVE` (read-only reference — NEVER edit it). Target: `C:\inetpub\wwwroot\NTP_V2` — .NET 10 API (`src/`) + React front end (`web/`). Legacy Grains code: `NTP_LIVE\services\Grains\` (pages `*.cfm`, logic `cfc\*.cfc`, `Reports\`, `ReadFiles\`), plus Grains-related code elsewhere (grep `grain` in `NTP_LIVE\jobs`, `NTP_LIVE\services\MOT`, `NTP_LIVE\components`, root `*Grains*.cfm`). ## Toolchain (Windows, Git Bash or PowerShell) .NET 10 SDK is installed in a user folder, not on the default PATH: ``` export PATH="/c/Users/samers/.dotnet-sdk10:$PATH"; export DOTNET_ROOT='C:\Users\samers\.dotnet-sdk10' dotnet build C:/inetpub/wwwroot/NTP_V2/NTP.slnx ``` Node 26 / npm available. Web app: `C:\inetpub\wwwroot\NTP_V2\web` (Vite + React + TS + MUI). Type-check with `npx tsc --noEmit`. A real QA Oracle DB is reachable (see "Database connection notes" at the end). Verify SQL read-only against it and by compiling/type-checking; never run INSERT/UPDATE/DELETE against it. Say what was and was not verified in reports. ## Backend (follow README.md recipe; Oracle 11g, Dapper, no EF) - Layers: Domain/Entities -> Application (services, DTOs, FluentValidation, repository interfaces) -> Infrastructure (Dapper repos) -> Api (thin controllers). - Per module folders (so parallel work never collides): - `NTP.Domain/Grains//` - `NTP.Application/Grains//` (interfaces `IRepository`, `IService`, DTOs, validators) - `NTP.Infrastructure/Persistence/Repositories/Grains//` - `NTP.Api/Controllers/V1/Grains/Controller.cs`, route `api/v{version}/grains/` - DI is convention based (foundation provides it): concrete classes named `*Service` / `*Repository` are registered against their `I*` interface by assembly scanning; validators by FluentValidation scanning. Do NOT edit shared DI files per slice. - Tables are the legacy Oracle tables (e.g. PERMITS, NTP_TRUCKS, NTP_TRAILERS, NTP_DRIVERS, EVENTS, GRAINSTENDERORDER, GRAINS_COMPANIES_QUEUE, GRAINS_COMPANIES_LOCATION, NTP_COMPANY_DISTINATION, TRUCK_DISTRIBUTION_LOG, GRAINSBLACKLIST, ...). Column names come from the legacy SQL — read the CFC queries; never invent columns. Where legacy does `select *`, list the columns the legacy code actually reads/writes. Unqualified table names. The legacy datasources `nafithtcs` and `NTP` are TWO different schemas - see "Database connection notes" (default `IDbSession` = NAFITHTCS; real columns in `docs/schema/*.md`). - Port business rules faithfully (statuses, validations, event logging via `EVENTS`, sequence names like `SEQ_EVENTS.nextval`). Replace string-concatenated SQL with bind variables. Keep legacy user-facing Arabic messages as the default message text and also return a stable `code`. - Current user: `ICurrentUser` (UserId, Name, RoleCode, Domain, LocationId, StkId, CompId, CompanyCode, CompanyId, Lang, IsStaff). It replaces legacy `session.*`. Auth is JWT bearer; every Grains endpoint is `[Authorize]`; role gating mirrors legacy role checks (`session.userrolecode`). - Errors: throw `ValidationException`/`NotFoundException`/business exceptions from `NTP.Application.Common`; GlobalExceptionHandler turns them into ProblemDetails. - Lists: server-side paging via `PageRequest` / `PagedResult` and `OracleSql.Paginate`; filters as query-string params. ## Front end (`web/`) Use the user's skills: `bilingual-rtl-ui`, `metadata-driven-forms-grids`, `ux-conventions-admin-ui`, `replace-legacy-frontend` (in `~/.claude/skills/*/SKILL.md` — read the relevant ones). - Vite + React + TypeScript + MUI + React Query + react-router. Arabic RTL default, English LTR, light default + dark. Two Emotion caches (stylis-plugin-rtl). Logical CSS props only. - Built-in typed UI string table (`web/src/i18n/ui.ts`, `{ en, ar }` per key) — every string, label and message is bilingual; no raw keys on screen. - API client `web/src/api/client.ts` (fetch + bearer token + ProblemDetails -> typed `ApiError`); per-feature hooks in `web/src/features//api.ts`. - Metadata-driven: grids and forms are generic components (`web/src/components/DataGrid`, `web/src/components/MetaForm`) driven by small declarative TS tables in `web/src/features/grains/meta/.ts` (fields, types, required, sections, conditional rules, grid columns, filters). Entity code = overrides only. - Routes under `/grains/...`; menu entries registered in `web/src/features/grains/routes.tsx` (each feature exports `RouteObject[]` + `MenuItem[]`; the shell collects them — do not edit shell files per slice). - UX conventions: equal field widths, sections, confirm dialog before writes + toast with backend message, loading banner text, empty states, status chips + filter drawer, Enter runs search, filters in URL params, one request per action. - Dev proxy: Vite proxies `/api` to `https://localhost:7180`. ## Reporting Every agent ends with: what was built (files), how verified (build/tsc output), what is NOT verified, legacy behaviours skipped or uncertain, and assumptions the user must confirm. ## Backend foundation notes Shared plumbing is finished; slice agents should NOT edit any file listed under "Shared (do not edit)". ### How to add a Grains slice (only new files) 1. `NTP.Application/Grains//`: `IRepository`, `IService` + `Service` (class name MUST end in `Service`, interface MUST be `I`), DTOs, `AbstractValidator` classes. Namespace `NTP.Application.Grains.`. 2. `NTP.Infrastructure/Persistence/Repositories/Grains//Repository.cs`: `internal sealed class Repository(IDbSession session, ILogger<Repository> logger) : OracleRepositoryBase(session, logger), IRepository`. Base helpers: `QueryAsync`, `QueryFirstAsync` (new), `QuerySingleOrDefaultAsync`, `ExecuteScalarAsync`, `ExecuteAsync`. 3. `NTP.Api/Controllers/V1/Grains/Controller.cs`: `[ApiController] [ApiVersion(1.0)] [Route("api/v{version:apiVersion}/grains/")]`, thin. Authenticated by default (see below); add `[Authorize(Roles = "GOP,...")]` for legacy role gating (role claim = legacy `session.userrolecode`, compare case-insensitively via `ICurrentUser.IsInAnyRole`). 4. Registration is automatic: classes ending `Service`/`Repository` (internal ok) are registered scoped against `I` in both Application and Infrastructure (`ConventionRegistration.AddConventionalServices`); validators by FluentValidation assembly scan; controllers by MVC discovery. A class named otherwise (e.g. a `*Job`, `*Logger`) needs manual registration - avoid, or name it `*Service`. 5. Inject `ICurrentUser` (never read HttpContext) and `IEventLogger`; use `IUnitOfWork.ExecuteInTransactionAsync` for multi-statement writes. ### Shared (do not edit) - `NTP.Application/DependencyInjection.cs`, `NTP.Infrastructure/DependencyInjection.cs`, `NTP.Api/Program.cs`, `NTP.Api/Auth/*`, `NTP.Api/ErrorHandling/GlobalExceptionHandler.cs`, `Directory.Packages.props` (ask if a new package is needed), `appsettings*.json`, `NTP.Application/Common/*`, `NTP.Application/Auth/*`, `NTP.Application/Lookups/*`, `NTP.Application/Abstractions/*`. ### Auth - Every endpoint requires a JWT by default (fallback authorization policy). Only `[AllowAnonymous]` (login, health, openapi) is public. - `POST api/v1/auth/login` `{ "userName": "ASEZA.50034", "password": "..." }` (legacy `DOMAIN.login`) -> `{ accessToken, tokenType:"Bearer", expiresAtUtc, user, mustChangePassword }`. `GET auth/me`, `POST auth/change-password {oldPassword,newPassword,confirmNewPassword?}`, `POST auth/language {lang:"AR"|"EN"}` (returns a NEW token with the lang claim), `POST auth/logout` (writes LOGS type 2; client drops token). - Send `Authorization: Bearer `. Config `Jwt` (Key, Issuer, Audience, ExpiryMinutes, ActiveCheckCacheSeconds), `Auth:SuperUsers`, `Cors:AllowedOrigins`. `Jwt:Key` (>= 32 chars) comes from env `Jwt__Key` / user-secrets / `appsettings.Local.json` (see the example file); outside Development the app refuses to start without it; in Development a random per-process key is used if unset. - Per request, the token's user is re-checked in NTPUSERS (status=1 and same ROLECODE, Application.cfc `qry_validateUser`), cached `Jwt:ActiveCheckCacheSeconds` (default 10 s). Role `SU` only for `Auth:SuperUsers`. - `ICurrentUser`: `Id` (NTPUSERS.ID), `UserId` (upper-case login = legacy session.userid), `Name`, `RoleCode`, `RoleName`, `Domain`, `LocationId`/`StkId`/`CompId`/`CompanyId` (`long?`), `LocationName`, `CompanyName`, `CompanyCode`, `EmpNo`, `Lang`, `IsStaff` (CompanyId = 15), `IsAuthenticated`, `IsInRole`, `IsInAnyRole`. ### Errors Throw from `NTP.Application.Common`: `ValidationException` (FluentValidation, 400 with per-field errors), `NotFoundException` (404), `ConcurrencyException` (409), `BusinessException(code, arabicMessage)` (422, ProblemDetails `detail`/`title` = message, extension `code` = stable code), `AuthenticationFailedException` (401), `ForbiddenException` (403). Keep legacy Arabic text as the message. ### Event log and lookups - `IEventLogger.AddAsync(new EventEntry("PERMITID", id, prev, curr, userId, "OVRD", domain, locationId, "NTP", weight, extras))` = legacy `addEvent` (`SEQ_EVENTS.nextval`, binds, DONEBY upper-cased). `AddForCurrentUserAsync(refColumn, refId, prev, curr, eventType, remarks)` fills user/domain/location from `ICurrentUser`. Ref/extra column names are validated as plain identifiers (no whitelist of EVENTS columns - they must exist; legacy uses PERMITID, CRID, ORDERID, WAYBILLID and extra REMARKS). - Generic lookups (`api/v1/lookups/...`, domain defaults to the caller's): `statuses?domain=&isActive=`, `locations?domain=&type=&includeInactive=`, `cargo-types?domain=`, `companies`, `nationalities`, `cities`. Tables/columns taken from legacy SQL (STATUS, LOCATIONS, CARGOTYPE, COMPANIES, NATIONALITY, CITIES). Grains-specific lookups belong in the slice. - Tests: `tests/NTP.Tests` (xunit): `dotnet test C:/inetpub/wwwroot/NTP_V2/NTP.slnx`. ### Auth gaps vs legacy (not ported) Captcha counters (RECAPTCHA_*), SSO and kiosk/`kiosksLogin`, multi-user single-login (`LoggedInUsers` auto-logout), `session.encryptionKey`, Petroleum dashboard session vars, printer ids (UTT/systemprinters), DISP `USER_ACTIVITIES`, ASEZA `getManagedCompany`/`application.TenderCompanies`, `URL_SECURITY` role rules (they match legacy page URLs; use `[Authorize(Roles=...)]` per endpoint instead), the hardcoded OPOFF/ONO IP-lockout and user/IP exemptions in Application.cfc/checkLogin, `resetPass` (legacy body is `cfabort`ed), `session.companyCodeNO`. ASEZA `application.encryptPwd.doEncryption` (Java `pwd.EncryptPwd`, not in repo) cannot be ported exactly: login accepts a guessed Base64(SHA-1(password)) variant (UNVERIFIED) plus the exact SHA-1(UPPER(login)+password) hex; change-password always writes the SHA-1 form. There is no lockout in legacy (only captcha); failed attempts are not logged anywhere in legacy, so none are here. ## Front-end foundation notes Foundation lives in `web/` (Vite 8, React 19, TS strict, MUI 9, React Query 5, react-router 7). Run: `npm run dev` (proxy `/api` -> https://localhost:7180), `npm run typecheck`, `npm run build`. `VITE_MOCK=1 npm run dev` uses the in-browser mock API and shows the `_example` feature (copy it as a template; it is hidden otherwise). Path alias `@/` = `web/src/`. MUI 9 note: system props on `Typography`/`Stack`/`Box` (e.g. `fontWeight`, `alignItems`) are gone; put them in `sx`. ### How a slice agent adds a feature (never edit shell/foundation files or `i18n/ui.ts`) Create only files under `web/src/features//` (e.g. `grains`, then sub-slices as sub-folders or extra files): 1. `routes.tsx` - REQUIRED, auto-collected by `src/registry.ts` (`import.meta.glob('./features/*/routes.tsx')`). Exports `routes: RouteObject[]` (absolute paths, `/grains/permits`, `/grains/permits/new`, `/grains/permits/:id`; optional `handle: { crumb: L10n }` for a trailing breadcrumb such as "New"/"Edit") and `menu: MenuItem[]`. `MenuItem = { key, title:{en,ar}, icon: MuiIconComponent, path?, createPath?, roles?: string[], color?, children?: MenuItem[] }`. Group = `children` (no path). `createPath` shows the "+" on the row (row itself opens the list). `roles` = allowed `roleCode`s (omitted = everyone); filters menu, dashboard links and also guards the URL (403 page) via longest-prefix match on `path`/`createPath`. Several slices can each add their own `routes.tsx` only if the folder differs; for ONE feature with many slices, keep one `routes.tsx` that imports per-slice route/menu arrays (add slice files, edit only that feature's `routes.tsx`). 2. `strings.ts` - feature strings: `export default defineStrings({ 'grains.title': { en, ar }, ... })` (`defineStrings` from `@/i18n/useUi`). Use in components: `const { t, tr, lang } = useFeatureUi(strings)`; `t` accepts the feature keys and the shell keys (`common.save`, `grid.empty`, ...), `tr({en,ar})` picks from inline labels. Auto-merged for backend caption lookups too (toast text that looks like `UPPER_CASE_KEY` is translated if a feature string with that key exists; everything else is shown verbatim). Prefix keys with the feature name to avoid collisions. 3. `meta/.ts(x)` (or `meta.tsx`) - declarative tables, types in `@/components/meta/types`: - `GridMeta`: `{ key, endpoint | fetcher, rowKey, columns: ColumnMeta[], filters?: FilterMeta[], status?: {param, options: StatusMeta[]}, defaultFilters?, requireFilter?, pageSize?, rowActions?: RowAction[], onRowClick? }`. `ColumnMeta`: `{ key, header:{en,ar}, field?, format?: 'text'|'number'|'date'|'datetime'|'boolean'|'status', statuses?, render?(row,{lang}), ltr?, align?, width?, hideBelow?: 'sm'|'md'|'lg' }`. `StatusMeta`: `{ value, label:{en,ar}, color }`. List endpoints must return `PagedResult` = `{items,page,pageSize,totalCount}`; request params are `page` (1-based), `pageSize` + each active filter name + status param. Filters/status/paging live in URL params (`?f=1` marker only when `defaultFilters` exist), one request per action; defaults are used for the first request. After writes: `queryClient.invalidateQueries({ queryKey: gridKey(meta.key) })` (`gridKey` from `@/components/DataGrid`). - `FormMeta`: `{ key, sections: [{ key, title?, columns?: 1|2|3, fields: FieldMeta[] }] }`. `FieldMeta`: `{ name, type: 'text'|'number'|'date'|'select'|'autocomplete'|'checkbox'|'textarea'|'attachment', label, required?, readOnly?, hiddenOnCreate?, hiddenWhen?, requiredWhen?, disabledWhen?, defaultValue?, maxLength?, min?, max?, pattern?:{regex,message}, options?, dependsOn?, inputKind?: 'plate'|'phone'|'email'|'code' (forces LTR input), ltr?, span?: 1|2|3|'full', rows?, placeholder?, helper?, attachment?:{endpoint?,accept?} }`. - Conditional rules are declarative `Rule = {field, op?: eq|ne|in|nin|empty|notEmpty|truthy|falsy, value?} | {all:[]} | {any:[]} | {not: Rule}`; evaluated by ONE function (`isHidden`/`isRequired`/`isDisabled` in `MetaForm/rules.ts`) used by render, validation and payload. Payload = visible, non-read-only fields only (empty string -> null). Dates are `yyyy-mm-dd` strings (display `dd/mm/yyyy`; the native date picker follows the browser locale). - Options: static `OptionItem[]` (`{value,label: string | {en,ar}}`) or `OptionsLoader { key, load({lang,parent}) => Promise, staleTime? }` (cached by React Query with `lang` in the key; `dependsOn` passes the parent field value and clears the child on change). 4. `api.ts` - React Query hooks via the shared client: `api.get/post/put/patch/delete/upload` from `@/api/client` (bearer token, `ApiError` with `status`, `code`, `message` = ProblemDetails detail/title verbatim, `fieldErrors`). Reads: `useQuery`. Writes: `useWrite(fn, { invalidate: [keys], successMessage? })` from `@/api/hooks` - toasts the response `message` (or default "Saved"), toasts `ApiError.message` on failure, and the client shows the blocking "Saving..." overlay for every non-GET call. Pass `{ silent: true }` as the last arg for background lookups (no progress bar). Language-dependent queries: put `lang` (from `useUi()`) in the key and gate with `useLanguage().langReady` (`useOptions` and `DataGrid` already do). 5. Pages (`pages.tsx`): `PageHeader` + `` for lists; `` for forms (confirm dialog before save is built in, `confirmMessage={false}` skips it; feed `ApiError.fieldErrors` to `serverErrors` to mark+focus the failing field). Other building blocks: `useConfirm()` (`@/providers/ConfirmProvider`), `useToast()` (success/warning/error), `StatusChip`, `LoadingBanner`, `EmptyState`, `FileUpload` (stub, posts to `/files/temp` or `attachment.endpoint`, expects `{id}`), `Logo`. 6. Mock data (optional, dev only): `registerMock('GET', /^\/grains\/permits$/, ({params,body,match}) => ...)` from `@/api/mock`, import it from your `routes.tsx`; active only with `VITE_MOCK=1`. Rules: bilingual everything (no raw keys, no English in the Arabic layout); logical CSS props only (`marginInlineStart`, `paddingInlineEnd`, `textAlign:'start'`); `dir="ltr"` for plates/phones/codes; same-width fullWidth controls; auth endpoint shapes are isolated in `web/src/api/auth.ts` (login `{username,password}` -> `{token,user}`, `/auth/me`, `PUT /auth/language {lang:'AR'|'EN'}`, `POST /auth/change-password {currentPassword,newPassword}`) - adjust there if the backend differs. ## Database connection notes Real QA Oracle 11.2.0.4 (`qajodb`) with two schemas = the two legacy ColdFusion datasources. **Real column lists are in `docs/schema/NAFITHTCS.md` and `docs/schema/NTP.md` - consult them before writing SQL; legacy CFC queries are the source of intent, the schema docs are the source of truth for names/types/lengths/nullability.** ### Two sessions (transactions are per connection) | Session / base / unit of work | Config key | Schema | Tables | |---|---|---|---| | `IDbSession` / `OracleRepositoryBase` / `IUnitOfWork` (**primary, default for slices**) | `ConnectionStrings:NAFITHTCS` | NAFITHTCS | PERMITS, NTP_TRUCKS, NTP_TRAILERS, NTP_DRIVERS, EVENTS, GRAINS*, UTT, INVALID_ACCESS_LOG, LOCATIONS_IPS, and LOCATIONS / STATUS / CARGOTYPE / CITIES (the NAFITHTCS copies, which have DOMAIN etc.) | | `INtpDbSession` / `NtpRepositoryBase` / `INtpUnitOfWork` | `ConnectionStrings:NtpSchema` | NTP | NTPUSERS, ROLES, GROUPS, LOGS, COMPANIES, NATIONALITY, URL_SECURITY and other tables listed only in `docs/schema/NTP.md` | - A repository that needs both takes both sessions (see `AuthRepository`, `LookupRepository`: derive from `NtpRepositoryBase`/`OracleRepositoryBase` for one and wrap the other in a small private helper subclass). There is no distributed transaction: `IUnitOfWork` covers only the NAFITHTCS connection, `INtpUnitOfWork` only the NTP one. - NAFITHTCS can only SELECT (+UPDATE NTPUSERS) on NTP objects, so every NTP-owned INSERT (e.g. `LOGS`) must go through the NTP session. Do not rely on same-named tables: NTP.LOCATIONS / NTP.STATUS are different, smaller tables than the NAFITHTCS ones. - `EventLogger` (EVENTS, `SEQ_EVENTS`) is on the primary connection. Sequences verified present: SEQ_EVENTS, SEQ_INVALID_ACCESS_LOG (NAFITHTCS), SEQ_LOGS (NTP). Check any other sequence in the `## SEQUENCES` section of the schema doc of the schema that owns the table. - `/health/ready` checks both connections (`oracle` = NAFITHTCS, `oracle-ntp` = NTP). - Local credentials: git-ignored `src/NTP.Api/appsettings.Local.json` (template: `appsettings.Local.example.json`); never put passwords in tracked files. - Column-length gotchas seen: `LOGS.IPADDRESS` VARCHAR2(15), `INVALID_ACCESS_LOG.BROWSER` VARCHAR2(300), `EVENTS.PREVSTATUS/CURRENTSTATUS` VARCHAR2(10), `EVENTS.EVENTTYPE` VARCHAR2(20); `EVENTS` has insert triggers (TRG_EVENT_RECORD_DATE, TRG_EVENT_PERMIT_ROUTE). ### How a slice agent validates its own SQL read-only 1. Check every table/column/type/nullability against `docs/schema/.md` (columns marked `notnull` without a default must be supplied by INSERTs). 2. Optionally confirm against the live DB with a throwaway console project OUTSIDE the solution (e.g. scratchpad; reference `Oracle.ManagedDataAccess.Core` 3.21.130; read the password from an env var or from `appsettings.Local.json`, never write it into a file you create). For each SELECT: open a connection as the owning schema and run `SELECT * FROM () WHERE 1=0` with every `:bind` added as a null `OracleParameter` (`BindByName = true`); a clean execute means tables, columns and syntax are valid. For INSERT/UPDATE: do NOT execute them - select the same columns with `WHERE 1=0`, and query `user_tab_columns` (type, length, NULLABLE, DATA_DEFAULT) and `user_triggers` / `user_sequences` for the target. Never call `NEXTVAL`, DML, DDL or stored procedures that write. 3. Do not guess or brute-force user passwords; the login flow can only be exercised with a bogus user (401).