Sprint D Architecture Notes Axlogis Design Decisions

Context

In ASolute, spContainerBatchUpdate uses a temp table called TmpJobContainer as a staging area when an ops user uploads a batch of container numbers from Excel or CSV (e.g., 20 containers assigned to one job in a single file upload). The SP:

• Reads the uploaded data into TmpJobContainer
• Validates all rows (checks TypeSize, duplicates, date formats, SOC flags)
• If @Confirm = 0: returns validation results only — no changes to the job
• If @Confirm = 1: applies container numbers to empty container slots in the job via spContainerAmendment

The question

SQL Server has two kinds of temp tables:

Why it matters for Axlogis

In the new system, spContainerBatchUpdate is rewritten as ContainerBatchUpdateService. The C# equivalent of the staging table must be either:

• An in-memory collection (List<ContainerUploadRow>) scoped to the request — safe by construction
• A temporary DB table created per-request and dropped after — session-scoped equivalent
• A global shared structure — only safe with explicit locking

Implementation pattern

// POST /api/v1/freight/containers/batch-validate
// POST /api/v1/freight/containers/batch-apply
public record ContainerUploadRow(
    string ContainerNo, string? TypeSize, string? SealNo,
    DateOnly? RequiredDate, string? RequiredTime, bool IsSOC,
    string? ErrorDesc  // null = valid; set by validate phase);

// Validate: returns rows with ErrorDesc populated where invalid
public async Task<IReadOnlyList<ContainerUploadRow>>
    ValidateAsync(string orderNo, IReadOnlyList<ContainerUploadRow> rows) { ... }

// Apply: only called when zero errors; applies containers to job
public async Task<int> ApplyAsync(string orderNo,
    IReadOnlyList<ContainerUploadRow> rows) { ... }

Context

When a transport request (ROT — Release Order from Terminal) is created for a job's containers, the legacy system generates a running number via fnContReqRunningNo. This number identifies the request and is stored in JobContainer.RequestLinkId to track which containers are assigned to which transport request.

The function is called inside spConsolidatePlanSave for each sub-job container in a consolidation plan — meaning it can be called multiple times in rapid succession, making race-condition safety critical.

The question

Three possible implementations, each with different concurrency properties:

Number format

ContainerRequest numbers follow the same convention as job numbers and consignment notes:

Implementation pattern

// Reuses existing JobNumberService — zero new infrastructure
var requestNo = await _jobNumbers.GenerateAsync(
    tenant.Enterprise, tenant.Entity, "ROT", DateTime.UtcNow, ct);

// ContainerRequest entity
var request = new ContainerRequest {
    RequestNo     = requestNo,
    OrderNo       = cmd.OrderNo,
    HaulierId     = cmd.HaulierId,
    RequestedDate = cmd.RequestedDate,
    Status        = "New",
};

What MinIO is for in Axlogis

Logistics jobs accumulate binary documents: Bills of Lading, Packing Lists, Delivery Orders, customs forms, and driver POD photos. These cannot live in SQL Server (BLOBs in relational DBs are slow, expensive, and not CDN-friendly). MinIO is the object store — it is already running in Docker Compose on ports 9000 (API) and 9001 (console).

The upload flow uses pre-signed URLs — the API never handles file bytes directly:

• Ops uploads → API requests a pre-signed upload URL from MinIO (time-limited) → browser uploads file directly to MinIO
• Ops views documents → API requests a pre-signed download URL → browser fetches file directly from MinIO
• API stores only the object key (a path string) in the JobDoc table

Decision 1 — bucket strategy

Decision 2 — pre-signed URL expiry

IDocumentService interface

public interface IDocumentService
{
    // Returns a pre-signed URL the browser uses to upload a file directly to MinIO
    Task<string> GetUploadUrlAsync(
        string enterprise, string entity, string jobNo,
        string fileName, string mimeType, CancellationToken ct = default);

    // Returns a pre-signed download URL for an existing object key
    Task<string> GetDownloadUrlAsync(
        string objectKey, TimeSpan? expiry = null,
        CancellationToken ct = default);

    // Deletes an object (soft-delete: marks JobDoc.IsDeleted, then dequeues for async purge)
    Task DeleteAsync(string objectKey, CancellationToken ct = default);
}

JobDoc entity

public class JobDoc : AuditableEntity
{
    public Guid   Id         { get; set; } = Guid.NewGuid();
    public string JobNo      { get; set; }  // FK → Job
    public string ObjectKey  { get; set; }  // MinIO object path
    public string FileName   { get; set; }  // original filename
    public string DocType    { get; set; }  // BOL, DO, POD, PACKING, OTHER
    public string MimeType   { get; set; }
    public long   FileSize   { get; set; }  // bytes
    public string?Remark     { get; set; }
}