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>/(interfacesI<X>Repository,I<X>Service, DTOs, validators)NTP.Infrastructure/Persistence/Repositories/Grains/<Slice>/NTP.Api/Controllers/V1/Grains/<Slice>Controller.cs, routeapi/v{version}/grains/<slice>
- DI is convention based (foundation provides it): concrete classes named
*Service/*Repositoryare registered against theirI*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 datasourcesnafithtcsandNTPare TWO different schemas - see "Database connection notes" (defaultIDbSession= NAFITHTCS; real columns indocs/schema/*.md). - Port business rules faithfully (statuses, validations, event logging via
EVENTS, sequence names likeSEQ_EVENTS.nextval). Replace string-concatenated SQL with bind variables. Keep legacy user-facing Arabic messages as the default message text and also return a stablecode. - Current user:
ICurrentUser(UserId, Name, RoleCode, Domain, LocationId, StkId, CompId, CompanyCode, CompanyId, Lang, IsStaff). It replaces legacysession.*. Auth is JWT bearer; every Grains endpoint is[Authorize]; role gating mirrors legacy role checks (session.userrolecode). - Errors: throw
ValidationException/NotFoundException/business exceptions fromNTP.Application.Common; GlobalExceptionHandler turns them into ProblemDetails. - Lists: server-side paging via
PageRequest/PagedResult<T>andOracleSql.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 -> typedApiError); per-feature hooks inweb/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 inweb/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 inweb/src/features/grains/routes.tsx(each feature exportsRouteObject[]+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
/apitohttps://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)
NTP.Application/Grains/<Slice>/:I<X>Repository,I<X>Service+<X>Service(class name MUST end inService, interface MUST beI<ClassName>), DTOs,AbstractValidator<T>classes. NamespaceNTP.Application.Grains.<Slice>.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.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 = legacysession.userrolecode, compare case-insensitively viaICurrentUser.IsInAnyRole).- Registration is automatic: classes ending
Service/Repository(internal ok) are registered scoped againstI<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. - Inject
ICurrentUser(never read HttpContext) andIEventLogger; useIUnitOfWork.ExecuteInTransactionAsyncfor 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": "..." }(legacyDOMAIN.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>. ConfigJwt(Key, Issuer, Audience, ExpiryMinutes, ActiveCheckCacheSeconds),Auth:SuperUsers,Cors:AllowedOrigins.Jwt:Key(>= 32 chars) comes from envJwt__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), cachedJwt:ActiveCheckCacheSeconds(default 10 s). RoleSUonly forAuth: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))= legacyaddEvent(SEQ_EVENTS.nextval, binds, DONEBY upper-cased).AddForCurrentUserAsync(refColumn, refId, prev, curr, eventType, remarks)fills user/domain/location fromICurrentUser. 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):
routes.tsx- REQUIRED, auto-collected bysrc/registry.ts(import.meta.glob('./features/*/routes.tsx')). Exportsroutes: RouteObject[](absolute paths,/grains/permits,/grains/permits/new,/grains/permits/:id; optionalhandle: { crumb: L10n }for a trailing breadcrumb such as "New"/"Edit") andmenu: MenuItem[].MenuItem = { key, title:{en,ar}, icon: MuiIconComponent, path?, createPath?, roles?: string[], color?, children?: MenuItem[] }. Group =children(no path).createPathshows the "+" on the row (row itself opens the list).roles= allowedroleCodes (omitted = everyone); filters menu, dashboard links and also guards the URL (403 page) via longest-prefix match onpath/createPath. Several slices can each add their ownroutes.tsxonly if the folder differs; for ONE feature with many slices, keep oneroutes.tsxthat imports per-slice route/menu arrays (add slice files, edit only that feature'sroutes.tsx).strings.ts- feature strings:export default defineStrings({ 'grains.title': { en, ar }, ... })(defineStringsfrom@/i18n/useUi). Use in components:const { t, tr, lang } = useFeatureUi(strings);taccepts 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 likeUPPER_CASE_KEYis translated if a feature string with that key exists; everything else is shown verbatim). Prefix keys with the feature name to avoid collisions.meta/<entity>.ts(x)(ormeta.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 returnPagedResult<T>={items,page,pageSize,totalCount}; request params arepage(1-based),pageSize+ each active filter name + status param. Filters/status/paging live in URL params (?f=1marker only whendefaultFiltersexist), one request per action; defaults are used for the first request. After writes:queryClient.invalidateQueries({ queryKey: gridKey(meta.key) })(gridKeyfrom@/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/isDisabledinMetaForm/rules.ts) used by render, validation and payload. Payload = visible, non-read-only fields only (empty string -> null). Dates areyyyy-mm-ddstrings (displaydd/mm/yyyy; the native date picker follows the browser locale). - Options: static
OptionItem[]({value,label: string | {en,ar}}) orOptionsLoader { key, load({lang,parent}) => Promise<OptionItem[]>, staleTime? }(cached by React Query withlangin the key;dependsOnpasses the parent field value and clears the child on change).
api.ts- React Query hooks via the shared client:api.get/post/put/patch/delete/uploadfrom@/api/client(bearer token,ApiErrorwithstatus,code,message= ProblemDetails detail/title verbatim,fieldErrors). Reads:useQuery. Writes:useWrite(fn, { invalidate: [keys], successMessage? })from@/api/hooks- toasts the responsemessage(or default "Saved"), toastsApiError.messageon 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: putlang(fromuseUi()) in the key and gate withuseLanguage().langReady(useOptionsandDataGridalready do).- 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; feedApiError.fieldErrorstoserverErrorsto mark+focus the failing field). Other building blocks:useConfirm()(@/providers/ConfirmProvider),useToast()(success/warning/error),StatusChip,LoadingBanner,EmptyState,FileUpload(stub, posts to/files/temporattachment.endpoint, expects{id}),Logo. - Mock data (optional, dev only):
registerMock('GET', /^\/grains\/permits$/, ({params,body,match}) => ...)from@/api/mock, import it from yourroutes.tsx; active only withVITE_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 fromNtpRepositoryBase/OracleRepositoryBasefor one and wrap the other in a small private helper subclass). There is no distributed transaction:IUnitOfWorkcovers only the NAFITHTCS connection,INtpUnitOfWorkonly 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## SEQUENCESsection of the schema doc of the schema that owns the table./health/readychecks 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.IPADDRESSVARCHAR2(15),INVALID_ACCESS_LOG.BROWSERVARCHAR2(300),EVENTS.PREVSTATUS/CURRENTSTATUSVARCHAR2(10),EVENTS.EVENTTYPEVARCHAR2(20);EVENTShas insert triggers (TRG_EVENT_RECORD_DATE, TRG_EVENT_PERMIT_ROUTE).
How a slice agent validates its own SQL read-only
- Check every table/column/type/nullability against
docs/schema/<SCHEMA>.md(columns markednotnullwithout a default must be supplied by INSERTs). - Optionally confirm against the live DB with a throwaway console project OUTSIDE the solution (e.g. scratchpad; reference
Oracle.ManagedDataAccess.Core3.21.130; read the password from an env var or fromappsettings.Local.json, never write it into a file you create). For each SELECT: open a connection as the owning schema and runSELECT * FROM (<your sql>) WHERE 1=0with every:bindadded as a nullOracleParameter(BindByName = true); a clean execute means tables, columns and syntax are valid. For INSERT/UPDATE: do NOT execute them - select the same columns withWHERE 1=0, and queryuser_tab_columns(type, length, NULLABLE, DATA_DEFAULT) anduser_triggers/user_sequencesfor the target. Never callNEXTVAL, DML, DDL or stored procedures that write. - Do not guess or brute-force user passwords; the login flow can only be exercised with a bogus user (401).