Go to file
Samer Salameh 2a339afee3 Permits list: shortcuts to the tender order permits and distribution summary reports
Shown per report permission, same as the orders report shortcut.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-18 15:01:25 +03:00
db Registry exports, ratios report as legacy Excel, RED_SEA distribution, UI fixes 2026-11-18 14:21:57 +03:00
deploy Port mobile notifications: push via legacy SOAP service, SMS for owners without the app, per-environment settings 2026-11-18 10:24:26 +03:00
docs Registry exports, ratios report as legacy Excel, RED_SEA distribution, UI fixes 2026-11-18 14:21:57 +03:00
src Truck inquiry: match legacy searchTruckDistribution exactly 2026-11-18 14:25:54 +03:00
tests/NTP.Tests Port mobile notifications: push via legacy SOAP service, SMS for owners without the app, per-environment settings 2026-11-18 10:24:26 +03:00
web Permits list: shortcuts to the tender order permits and distribution summary reports 2026-11-18 15:01:25 +03:00
.dockerignore Deploy: QA and production Docker setup, serve web app from the API, report menu names 2026-11-12 17:31:22 +03:00
.gitignore Deploy: QA and production Docker setup, serve web app from the API, report menu names 2026-11-12 17:31:22 +03:00
CLAUDE.md Scheduled jobs: SU screen to start, stop and time the three legacy jobs 2026-11-17 17:15:24 +03:00
Directory.Build.props Initial commit: NTP V2 (.NET 10 API + React web) with Dev, QA and Production environments 2026-11-11 11:56:48 +03:00
Directory.Packages.props Bump Microsoft.AspNetCore.OpenApi to 10.0.15 (fixes Microsoft.OpenApi NU1903 advisory); fix XML doc warning 2026-11-15 12:51:08 +03:00
Jenkinsfile DISP role: view tender-order permits of own company; permit edit dialog (trailer and driver only, validate on Enter) 2026-11-15 12:24:04 +03:00
NTP.slnx Initial commit: NTP V2 (.NET 10 API + React web) with Dev, QA and Production environments 2026-11-11 11:56:48 +03:00
README.md Initial commit: NTP V2 (.NET 10 API + React web) with Dev, QA and Production environments 2026-11-11 11:56:48 +03:00

README.md

NTP API

.NET 10 Web API over an existing Oracle 11g database, built to host the rewritten backend logic.

Why this stack

Choice Reason
Oracle.ManagedDataAccess.Core 3.21.x (ODP.NET 21c) Last ODP.NET line that supports DB 11.2.0.4. The 23.x line needs 19c+. Pinned in Directory.Packages.props — only bump within 3.21.x.
Dapper (not EF Core) Current EF Core Oracle providers generate 12c+ SQL (OFFSET/FETCH, identity). Dapper keeps SQL explicit and 11g-safe, and fits a database-first legacy schema.
Clean layers (Api → Application → Infrastructure → Domain) Business logic is ported into Application services, independent of Oracle. When the DB is upgraded, only Infrastructure changes.

Layout

src/
  NTP.Api/              Controllers (thin), ProblemDetails + ORA-code mapping, versioning, OpenAPI, health
  NTP.Application/      Services (business logic), DTOs, FluentValidation, repository interfaces, paging
  NTP.Domain/           Entities mapped to existing tables
  NTP.Infrastructure/   ODP.NET + Dapper: DbSession (connection/transaction per request), repositories, health check
db/sample-schema.sql              Scratch table for the Shipment example only

Run it

# Requires .NET 10 SDK and network access to the Oracle server
cd src/NTP.Api
cp appsettings.Local.example.json appsettings.Local.json   # then edit it
dotnet run
  • Swagger UI: https://localhost:7180/swagger (Development only)
  • OpenAPI JSON: /openapi/v1.json
  • Health: /health/live, /health/ready (runs SELECT 1 FROM DUAL)
  • The app fails fast at startup if no connection is configured, and logs the target DB (password masked).

Environments (Development / QA / Production), the settings each server must provide and the web build modes are described in docs/ENVIRONMENTS.md.

Configuring the database connection

Configure them in src/NTP.Api/appsettings*.json (secrets only in git-ignored files or env vars).

The API uses two Oracle connections (the two legacy ColdFusion datasources):

Key Schema / legacy datasource Used by
ConnectionStrings:NAFITHTCS (primary) NAFITHTCS / nafithtcs IDbSession, OracleRepositoryBase, IUnitOfWork: PERMITS, NTP_TRUCKS, EVENTS, GRAINS*, UTT, LOCATIONS, STATUS ...
ConnectionStrings:NtpSchema (required) NTP / NTP INtpDbSession, NtpRepositoryBase, INtpUnitOfWork: NTPUSERS, ROLES, LOGS, COMPANIES, NATIONALITY ...

Example (placeholders only; real passwords go in git-ignored appsettings.Local.json or env vars ConnectionStrings__NAFITHTCS / ConnectionStrings__NtpSchema): "NAFITHTCS": "User Id=NAFITHTCS;Password=<password>;Data Source=<host>:1521/<service>", "NtpSchema": "User Id=NTP;Password=<password>;Data Source=<host>:1521/<service>".

The primary connection is resolved in this order (first match wins):

# Where Example
1 ConnectionStrings:NAFITHTCS (then legacy ConnectionStrings:NTP) "NAFITHTCS": "User Id=NAFITHTCS;Password=<password>;Data Source=db-host:1521/ORCL"
2 Oracle:ConnectionString same format, kept with the other Oracle settings
3 Oracle:Host, Port, ServiceName (or Sid), UserId, Password built for you, plus pool settings (MinPoolSize, MaxPoolSize, ConnectionTimeoutSeconds, StatementCacheSize)

Files are layered, later overriding earlier: appsettings.json → appsettings.{Environment}.json → user-secrets (Development) → environment variables → appsettings.Local.json (git-ignored).

  • Local dev: copy appsettings.Local.example.json to appsettings.Local.json and put your password there.
  • Server / IIS / Docker: keep the non-secret parts in appsettings.Production.json; supply the password with an env var, e.g. Oracle__Password=... or the whole string with ConnectionStrings__NAFITHTCS=... plus ConnectionStrings__NtpSchema=....
  • SID listeners: set Sid instead of ServiceName, or use Data Source=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=db-host)(PORT=1521))(CONNECT_DATA=(SID=ORCL))).
  • Never commit real passwords to appsettings.json.

Migrating a table / module (recipe)

  1. Entity — Domain/Entities/<Name>.cs, one property per column (ORDER_DATE → OrderDate).
  2. Repository interface — Application/Abstractions/I<Name>Repository.cs.
  3. Repository — copy ShipmentRepository.cs; explicit column lists, :Param binds, OracleSql.Paginate for lists, <SEQ>.NEXTVAL ... RETURNING ... INTO for inserts.
  4. Service — port the old business logic into Application/<Module>/<Name>Service.cs; wrap multi-statement writes in unitOfWork.ExecuteInTransactionAsync.
  5. Validators + DTOs — keep max lengths in sync with VARCHAR2 sizes.
  6. Controller — Controllers/V1/<Name>Controller.cs, no logic.
  7. Register — one line each in Application/DependencyInjection.cs and Infrastructure/DependencyInjection.cs.

Existing PL/SQL packages can be called from a repository with CommandType.StoredProcedure; ref-cursor outputs need OracleDynamicParameters (ask for the helper when needed).

Oracle 11g rules baked in

  • Paging: ROWNUM wrapper, not OFFSET/FETCH. Always order by a unique tie-breaker (PK).
  • IDs: sequences (or the legacy trigger), never identity columns.
  • Booleans: NUMBER(1); write with OracleSql.ToNumber(bool) — ODP.NET 21 cannot bind bool.
  • One result set per command: list endpoints do COUNT + page as two queries.
  • Empty string = NULL in Oracle; don't rely on '' vs NULL distinctions from the old code.
  • VARCHAR2 lengths are bytes by default (NLS_LENGTH_SEMANTICS=BYTE) — Arabic text uses 2 bytes/char in AL32UTF8.
  • Dates: SYSDATE is DB-server local time; the API returns DateTime with Kind=Unspecified.
  • Optimistic concurrency via ROW_VERSION; drop those clauses if a legacy table has no such column.
  • Errors: ORA codes map to HTTP (ORA-00001 → 409, ORA-02292 → 409, ORA-12899 → 400, network ORA-12541/12514/03113 → 503, …) in GlobalExceptionHandler.

Next steps to align with NafithServices

  • JWT auth (same issuer/audience as the gateway), then add [Authorize].
  • OpenTelemetry tracing/metrics (add OpenTelemetry.Instrumentation.AspNetCore; ODP.NET 21 has no OTel instrumentation, so wrap repository calls in an ActivitySource if DB spans are required).
  • Ocelot route for /api/v1/... and Dockerfile.
  • Integration tests against a disposable Oracle XE container (note: XE 11g images are no longer distributed — use a shared test schema on the 11g server instead).