changes

apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts

@@ -4,6 +4,7 @@ import {
   Injectable,
   Logger,
 } from '@nestjs/common';
+import { randomUUID } from 'node:crypto';
 import { Readable } from 'stream';
 import { insertWithGeneratedReference } from '@edr/api-common';
 import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
@@ -21,16 +22,35 @@ import { DropdownSettingsService } from '../dropdown-settings/dropdown-settings.
 import { FilesService } from '../files/files.service';
 import { SignaturesService } from '../signatures/signatures.service';
 import { OtpService } from '../otp/otp.service';
+import { ContractTemplatesService } from '../contract-templates/contract-templates.service';
 import { ContractPricingService } from './contract-pricing.service';
 import { ContractNotifierService } from './contract-notifier.service';
 import { ClearanceMilestoneService } from './clearance-milestone.service';
 import { ContractsRepository } from './contracts.repository';
 import { ContractsService } from './contracts.service';
 import { contractClearanceSettingCode } from './contract-clearance.util';
-import { Contract } from './entities/contract.entity';
+import {
+  Contract,
+  ContractDocumentArticle,
+  ContractDocumentSnapshot,
+  ContractDocumentSnapshotInput,
+} from './entities/contract.entity';
 import { ContractSignerRole } from './entities/contract-signature.entity';
 import { SignContractDto } from './dto/sign-contract.dto';
 
+/** The editable contract-document draft returned for the accept/edit dialog. */
+export interface ContractDocumentDraft {
+  documentTitle: string | null;
+  whereasClauses: string[];
+  articles: ContractDocumentArticle[];
+  code: string | null;
+  name: string | null;
+  /** True once the document may no longer be edited/regenerated. */
+  locked: boolean;
+  generatedAt: Date | null;
+  status: string;
+}
+
 /**
  * Dropdown-settings code holding the admin-configured contract validity options
  * (each option's `value` is a day count). The staff accept dialog reads the same
@@ -68,6 +88,7 @@ export class ContractTransitionService {
     private readonly minioService: MinioService,
     private readonly otpService: OtpService,
     private readonly notifier: ContractNotifierService,
+    private readonly contractTemplates: ContractTemplatesService,
   ) {}
 
   /** Customer submits the contract for approval → SUBMITTED; freeze unit rates. */
@@ -110,6 +131,7 @@ export class ContractTransitionService {
     contractId: string,
     actorId: string,
     validityDays: number,
+    documentSnapshot?: ContractDocumentSnapshotInput | null,
   ): Promise<Contract> {
     const contract = await this.contractsService.findById(contractId);
     assertContractStatus(contract, ['SUBMITTED']);
@@ -128,6 +150,12 @@ export class ContractTransitionService {
 
     await this.instantiateApprovalSteps(contract);
 
+    // Freeze the contract document for THIS contract only. Staff may have edited
+    // the articles in the accept dialog; otherwise the live template is captured
+    // as-is so later template edits never change an in-flight contract. The
+    // shared six templates are never written here.
+    const snapshot = await this.resolveDocumentSnapshot(contract, documentSnapshot);
+
     await this.contractsRepository.update(contractId, {
       status: 'PENDING_APPROVAL',
       approvedByStaffId: actorId,
@@ -135,12 +163,148 @@ export class ContractTransitionService {
       contractValidityDays: validityDays,
       contractValidFrom: validFrom,
       contractValidUntil: validUntil,
+      documentSnapshot: snapshot,
     } as never);
     const updated = await this.contractsService.findById(contractId);
     this.notifier.accepted(updated);
     return updated;
   }
 
+  // ── Per-contract document snapshot (US: edit articles for one contract) ─────
+
+  /**
+   * The editable document draft for the accept/edit dialog: the frozen snapshot
+   * if one exists, else the live active template resolved for this contract's
+   * direction/freight pair. `locked` flips true once the document may no longer
+   * be edited (an approver has acted, or the contract has left the pre-approval
+   * window).
+   */
+  async getContractDocumentDraft(
+    contractId: string,
+  ): Promise<ContractDocumentDraft> {
+    const contract = await this.contractsService.findById(contractId);
+    const snapshot =
+      (contract.documentSnapshot as ContractDocumentSnapshot | null) ??
+      (await this.resolveDocumentSnapshot(contract));
+    return {
+      documentTitle: snapshot?.documentTitle ?? null,
+      whereasClauses: snapshot?.whereasClauses ?? [],
+      articles: snapshot?.articles ?? [],
+      code: snapshot?.code ?? null,
+      name: snapshot?.name ?? null,
+      locked: !this.documentIsEditable(contract),
+      generatedAt: contract.contractGeneratedAt ?? null,
+      status: contract.status,
+    };
+  }
+
+  /**
+   * Replace this contract's document articles from the editor. Per-contract
+   * only — it writes the contract's own snapshot and never the shared templates.
+   * Allowed while the document is still editable (PENDING_APPROVAL, no approver
+   * has acted).
+   */
+  async updateContractDocument(
+    contractId: string,
+    input: ContractDocumentSnapshotInput,
+  ): Promise<Contract> {
+    const contract = await this.contractsService.findById(contractId);
+    assertContractStatus(contract, ['PENDING_APPROVAL']);
+    this.assertDocumentEditable(contract);
+
+    const current =
+      (contract.documentSnapshot as ContractDocumentSnapshot | null) ??
+      (await this.resolveDocumentSnapshot(contract));
+    const merged: ContractDocumentSnapshotInput = {
+      code: current?.code ?? null,
+      name: input.name ?? current?.name ?? null,
+      documentTitle: input.documentTitle ?? current?.documentTitle ?? null,
+      whereasClauses: input.whereasClauses ?? current?.whereasClauses ?? [],
+      articles: input.articles ?? current?.articles ?? [],
+    };
+    await this.contractsRepository.update(contractId, {
+      documentSnapshot: this.normalizeSnapshot(merged),
+    } as never);
+    return this.contractsService.findById(contractId);
+  }
+
+  /**
+   * Build the per-contract document snapshot. Prefer the staff's edited articles
+   * from the dialog; otherwise freeze the active template matching the
+   * contract's direction/freight. Returns null when no active template exists
+   * (the renderer then falls back to the built-in generic layout at render time).
+   */
+  private async resolveDocumentSnapshot(
+    contract: Contract,
+    provided?: ContractDocumentSnapshotInput | null,
+  ): Promise<ContractDocumentSnapshot | null> {
+    if (provided && (provided.articles?.length ?? 0) > 0) {
+      return this.normalizeSnapshot(provided);
+    }
+    const active = await this.contractTemplates.findActiveForContract(
+      contract.tradeDirection,
+      contract.freightType,
+    );
+    if (!active) return null;
+    return {
+      code: active.code,
+      name: active.name,
+      documentTitle: active.documentTitle,
+      whereasClauses: active.whereasClauses ?? [],
+      articles: this.normalizeArticles(active.articles ?? []),
+    };
+  }
+
+  private normalizeSnapshot(
+    input: ContractDocumentSnapshotInput,
+  ): ContractDocumentSnapshot {
+    return {
+      code: input.code ?? null,
+      name: input.name ?? null,
+      documentTitle: input.documentTitle ?? null,
+      whereasClauses: Array.isArray(input.whereasClauses)
+        ? input.whereasClauses
+            .map((c) => String(c))
+            .filter((c) => c.trim().length > 0)
+        : [],
+      articles: this.normalizeArticles(input.articles ?? []),
+    };
+  }
+
+  /** Re-key ids and renumber order sequentially, dropping empty-title rows. */
+  private normalizeArticles(
+    articles: Array<{ id?: string; title?: string; body?: string; order?: number }>,
+  ): ContractDocumentArticle[] {
+    return articles
+      .filter((a) => (a.title ?? '').trim().length > 0 || (a.body ?? '').trim().length > 0)
+      .map((a, index) => ({
+        id: a.id ?? randomUUID(),
+        title: (a.title ?? '').trim(),
+        body: a.body ?? '',
+        order: index + 1,
+      }));
+  }
+
+  /**
+   * The per-contract document may be edited/regenerated while the contract is at
+   * the accept stage (SUBMITTED) or in approval with NO approver having acted
+   * yet. The first approval action freezes it.
+   */
+  private documentIsEditable(contract: Contract): boolean {
+    if (contract.status === 'SUBMITTED') return true;
+    if (contract.status !== 'PENDING_APPROVAL') return false;
+    return !(contract.approvalSteps ?? []).some((s) => s.status !== 'PENDING');
+  }
+
+  private assertDocumentEditable(contract: Contract): void {
+    if (!this.documentIsEditable(contract)) {
+      throw new ConflictException(
+        'The contract document is locked — an approver has already acted or the ' +
+          'contract has advanced. It can no longer be edited or regenerated.',
+      );
+    }
+  }
+
   /**
    * Ensure the chosen validity (days) is one of the admin-configured options in
    * the `contract_validity_periods` dropdown setting. If the setting is missing
@@ -303,6 +467,15 @@ export class ContractTransitionService {
     const contract = await this.contractsService.findById(contractId);
     assertContractStatus(contract, ['PENDING_APPROVAL', 'APPROVED_PENDING_SIGNATURE']);
 
+    // Approvers review the generated contract document, so it must exist before
+    // the first approval can be recorded. Staff generate it (from the frozen,
+    // optionally-edited snapshot) at the accept stage.
+    if (contract.status === 'PENDING_APPROVAL' && !contract.contractGeneratedAt) {
+      throw new BadRequestException(
+        'Generate the contract document before it can be approved.',
+      );
+    }
+
     const step = await this.contractsRepository.findApprovalStepById(contractId, stepId);
     if (!step || step.status !== 'PENDING') {
       throw new BadRequestException('Approval step not found or already actioned');
@@ -350,15 +523,14 @@ export class ContractTransitionService {
     const updated = await this.contractsService.findById(contractId);
     if (allDone) {
       this.notifier.approved(updated);
-      // Final approval step also generates the contract document from the
-      // template matching the contract's direction/freight pair. Best-effort:
-      // a rendering hiccup must not roll back the approval — the document can
-      // still be generated manually or lazily on view/download.
+      // Every step approved → CONTRACT_READY. The document was already generated
+      // (and reviewed) at the accept stage, so we reuse it rather than
+      // re-rendering. Best-effort: a hiccup must not roll back the approval.
       try {
-        return await this.generateContract(contractId);
+        return await this.finalizeApprovedContract(contractId);
       } catch (err) {
         this.logger.warn(
-          `Auto contract generation after final approval failed for ${updated.reference}: ${err}`,
+          `Finalizing contract after final approval failed for ${updated.reference}: ${err}`,
         );
       }
     }
@@ -366,30 +538,66 @@ export class ContractTransitionService {
   }
 
   /**
-   * Render the contract PDF from the Contract aggregate, store it via FilesService,
-   * stamp the template key, and move to CONTRACT_READY. PDF rendering (Puppeteer/
-   * Chromium) is best-effort and must NOT block the contract from becoming ready —
-   * the document is (re)rendered lazily on view/download once Chromium is available.
+   * Staff (re)generate the contract PDF. Two stages:
+   *  - PENDING_APPROVAL: render from the frozen (optionally staff-edited)
+   *    snapshot so approvers review the real document. Status is UNCHANGED, and
+   *    it is blocked once an approver has acted (the document is then locked).
+   *  - APPROVED / APPROVED_PENDING_SIGNATURE (fallback): render and advance to
+   *    CONTRACT_READY.
+   * PDF rendering (Puppeteer/Chromium) is best-effort and never blocks the
+   * transition — the document re-renders lazily on view/download.
    */
   async generateContract(contractId: string): Promise<Contract> {
     const contract = await this.contractsService.findById(contractId);
+
+    if (contract.status === 'PENDING_APPROVAL') {
+      this.assertDocumentEditable(contract);
+      await this.renderContractDocument(contract);
+      return this.contractsService.findById(contractId);
+    }
+
     assertContractStatus(contract, ['APPROVED', 'APPROVED_PENDING_SIGNATURE']);
+    await this.renderContractDocument(contract);
+    await this.contractsRepository.update(contractId, {
+      status: 'CONTRACT_READY',
+    } as never);
+    return this.contractsService.findById(contractId);
+  }
 
-    const { view } = await this.documentViewModelBuilder.build(contractId);
-
+  /**
+   * Render the contract PDF from the Contract aggregate (snapshot-driven), store
+   * it via FilesService, and stamp the template key + generated timestamp. Never
+   * changes status. Rendering is best-effort — a Chromium hiccup defers the file
+   * (it re-renders on view/download) but the timestamp is still stamped.
+   */
+  private async renderContractDocument(contract: Contract): Promise<void> {
+    const { view } = await this.documentViewModelBuilder.build(contract.id);
     try {
-      await this.upsertContractPdf(contractId, contract.reference, view);
+      await this.upsertContractPdf(contract.id, contract.reference, view);
     } catch (err) {
       this.logger.warn(
         `Contract PDF deferred for ${contract.reference}: ${err}. It will render on view/download once Chromium is available.`,
       );
     }
-
-    await this.contractsRepository.update(contractId, {
-      status: 'CONTRACT_READY',
+    await this.contractsRepository.update(contract.id, {
       contractTemplateKey: view.templateKey,
       contractGeneratedAt: new Date(),
     } as never);
+  }
+
+  /**
+   * Every approval step landed → CONTRACT_READY. The document was already
+   * generated (and reviewed) at the accept stage, so reuse it; render now only
+   * if it was somehow never generated. Never re-renders over an existing file.
+   */
+  private async finalizeApprovedContract(contractId: string): Promise<Contract> {
+    const contract = await this.contractsService.findById(contractId);
+    if (!contract.contractGeneratedAt) {
+      await this.renderContractDocument(contract);
+    }
+    await this.contractsRepository.update(contractId, {
+      status: 'CONTRACT_READY',
+    } as never);
     return this.contractsService.findById(contractId);
   }
 

apps/edr-freight-api/src/modules/contracts/contracts.controller.ts

@@ -8,6 +8,7 @@ import {
   ParseUUIDPipe,
   Patch,
   Post,
+  Put,
   Query,
   Res,
   UnauthorizedException,
@@ -57,6 +58,7 @@ import { UpdateContractDto } from './dto/update-contract.dto';
 import { FilterContractDto } from './dto/filter-contract.dto';
 import { ContractListSummaryDto } from './dto/contract-list-summary.dto';
 import { AcceptContractDto } from './dto/accept-contract.dto';
+import { UpdateContractDocumentDto } from './dto/contract-document.dto';
 import {
   ApproveStepDto,
   RejectContractDto,
@@ -340,9 +342,33 @@ export class ContractsController {
       id,
       resolveAuthUserId(user),
       dto.validityDays,
+      dto.documentSnapshot,
     );
   }
 
+  @Get(':id/document/draft')
+  @BookingStaff(FREIGHT_PERMS.contracts.staffAccept)
+  @ApiOperation({
+    summary:
+      'Editable contract-document draft (this contract\'s snapshot, or the live template) for the accept/edit dialog',
+  })
+  getContractDocumentDraft(@Param('id', ParseUUIDPipe) id: string) {
+    return this.transitionService.getContractDocumentDraft(id);
+  }
+
+  @Put(':id/document/articles')
+  @BookingStaff(FREIGHT_PERMS.contracts.staffAccept)
+  @ApiOperation({
+    summary:
+      'Edit this contract\'s document articles only (per-contract; never touches the six shared templates)',
+  })
+  updateContractDocument(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: UpdateContractDocumentDto,
+  ) {
+    return this.transitionService.updateContractDocument(id, dto);
+  }
+
   @Post(':id/staff/request-changes')
   @BookingStaff(FREIGHT_PERMS.contracts.requestChanges)
   @ApiOperation({ summary: 'Staff return contract for customer updates' })

apps/edr-freight-api/src/modules/contracts/dto/accept-contract.dto.ts

@@ -1,5 +1,8 @@
-import { ApiProperty } from '@nestjs/swagger';
-import { IsInt, Max, Min } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import { IsInt, IsOptional, Max, Min, ValidateNested } from 'class-validator';
+
+import { UpdateContractDocumentDto } from './contract-document.dto';
 
 export class AcceptContractDto {
   @ApiProperty({
@@ -14,4 +17,16 @@ export class AcceptContractDto {
   @Min(1)
   @Max(3650)
   validityDays!: number;
+
+  /**
+   * Optional per-contract document override edited by staff in the accept
+   * dialog. When present its articles are frozen onto THIS contract; when
+   * omitted the live template is snapshotted as-is. Never edits the shared
+   * six templates.
+   */
+  @ApiPropertyOptional({ type: UpdateContractDocumentDto })
+  @IsOptional()
+  @ValidateNested()
+  @Type(() => UpdateContractDocumentDto)
+  documentSnapshot?: UpdateContractDocumentDto;
 }

apps/edr-freight-api/src/modules/contracts/dto/contract-document.dto.ts

@@ -0,0 +1,64 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import {
+  IsArray,
+  IsInt,
+  IsOptional,
+  IsString,
+  ValidateNested,
+} from 'class-validator';
+
+/** One article of a per-contract document override sent from the editor. */
+export class ContractDocumentArticleDto {
+  @ApiPropertyOptional({ description: 'Stable id; omitted for a new article.' })
+  @IsOptional()
+  @IsString()
+  id?: string;
+
+  @ApiProperty()
+  @IsString()
+  title!: string;
+
+  @ApiProperty({ description: 'Plain multiline body; each line becomes a clause.' })
+  @IsString()
+  body!: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsInt()
+  order?: number;
+}
+
+/**
+ * The per-contract document override sent from the accept/edit editor. It edits
+ * ONLY this contract's frozen snapshot — it is never written back to the shared
+ * six {@link ContractTemplate} rows.
+ */
+export class UpdateContractDocumentDto {
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  code?: string | null;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  name?: string | null;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  documentTitle?: string | null;
+
+  @ApiPropertyOptional({ type: [String] })
+  @IsOptional()
+  @IsArray()
+  @IsString({ each: true })
+  whereasClauses?: string[];
+
+  @ApiProperty({ type: [ContractDocumentArticleDto] })
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => ContractDocumentArticleDto)
+  articles!: ContractDocumentArticleDto[];
+}

apps/edr-freight-api/src/modules/contracts/entities/contract.entity.ts

@@ -42,6 +42,43 @@ export const CONTRACT_STATUSES = [
 
 export type ContractStatus = (typeof CONTRACT_STATUSES)[number];
 
+/** One article on a per-contract document snapshot (mirrors the template shape). */
+export interface ContractDocumentArticle {
+  id: string;
+  title: string;
+  body: string;
+  order: number;
+}
+
+/**
+ * A per-contract copy of the resolved contract-document template, frozen when
+ * staff accept the contract for approval. Staff may edit these articles for a
+ * single contract in the accept/edit dialog — editing NEVER writes back to the
+ * shared six {@link ContractTemplate} rows. The PDF is rendered from this
+ * snapshot when present; a null snapshot renders from the live template.
+ */
+export interface ContractDocumentSnapshot {
+  code?: string | null;
+  name?: string | null;
+  documentTitle?: string | null;
+  whereasClauses: string[];
+  articles: ContractDocumentArticle[];
+}
+
+/** Loose inbound shape (article ids/order optional) — normalized before store. */
+export interface ContractDocumentSnapshotInput {
+  code?: string | null;
+  name?: string | null;
+  documentTitle?: string | null;
+  whereasClauses?: string[];
+  articles?: Array<{
+    id?: string;
+    title?: string;
+    body?: string;
+    order?: number;
+  }>;
+}
+
 export const CONTRACT_KINDS = ['ONE_TIME', 'GENERAL'] as const;
 export type ContractKindValue = (typeof CONTRACT_KINDS)[number];
 
@@ -193,6 +230,14 @@ export class Contract extends BaseEntity {
   @Column({ name: 'contract_generated_at', type: 'timestamptz', nullable: true })
   contractGeneratedAt?: Date | null;
 
+  /**
+   * Per-contract frozen copy of the document template (articles + WHEREAS),
+   * captured at staff accept. Editing it affects only this contract, never the
+   * shared six templates. Null → the PDF renders from the live template.
+   */
+  @Column({ name: 'document_snapshot', type: 'jsonb', nullable: true })
+  documentSnapshot?: ContractDocumentSnapshot | null;
+
   @Column({ name: 'contract_summary', type: 'text', nullable: true })
   contractSummary?: string | null;