NTP_V2/docs/MIGRATION.md

21 KiB

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/<Slice>/
    • NTP.Application/Grains/<Slice>/ (interfaces I<X>Repository, I<X>Service, DTOs, validators)
    • NTP.Infrastructure/Persistence/Repositories/Grains/<Slice>/
    • NTP.Api/Controllers/V1/Grains/<Slice>Controller.cs, route api/v{version}/grains/<slice>
  • 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<T> 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/<feature>/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/<entity>.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/<Slice>/: I<X>Repository, I<X>Service + <X>Service (class name MUST end in Service, interface MUST be I<ClassName>), DTOs, AbstractValidator<T> classes. Namespace NTP.Application.Grains.<Slice>.
  2. NTP.Infrastructure/Persistence/Repositories/Grains/<Slice>/<X>Repository.cs: internal sealed class <X>Repository(IDbSession session, ILogger<<X>Repository> logger) : OracleRepositoryBase(session, logger), I<X>Repository. Base helpers: QueryAsync, QueryFirstAsync (new), QuerySingleOrDefaultAsync, ExecuteScalarAsync, ExecuteAsync.
  3. NTP.Api/Controllers/V1/Grains/<Slice>Controller.cs: [ApiController] [ApiVersion(1.0)] [Route("api/v{version:apiVersion}/grains/<slice>")], 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<ClassName> 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 <token>. 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 cfaborted), 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/<f>/ (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 roleCodes (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/<entity>.ts(x) (or meta.tsx) - declarative tables, types in @/components/meta/types:
    • GridMeta<T>: { key, endpoint | fetcher, rowKey, columns: ColumnMeta<T>[], filters?: FilterMeta[], status?: {param, options: StatusMeta[]}, defaultFilters?, requireFilter?, pageSize?, rowActions?: RowAction<T>[], 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<T> = {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<OptionItem[]>, 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 + <DataGrid meta={...}/> for lists; <MetaForm meta mode initialValues onSubmit onCancel serverErrors/> 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/<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 (<your sql>) 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).