Merge branch 'dev-latest' into feature/advanceLoanProduct

2026-10-07 15:44:36 +05:30
parent 0ea57b3f82 6b0f218b70
commit a5a64d4efe
238 changed files with 21432 additions and 3047 deletions
@@ -643,8 +643,9 @@ export class ClientGeneralStepComponent implements OnInit, OnDestroy, OnChanges
          this.createClientForm.get('degreeQualificationId')?.setValue('');
        }
      });
-    // Fetch all constitution options from code ID 17
-    this.clientService.getCodeValuesById(17).subscribe((options) => {
+    // Constitution options by code NAME, never by id: code ids differ per tenant (on abc_bank id 17 is the empty
+    // ClientClassification code and Constitution is id 24), so a hardcoded id left the dropdown empty.
+    this.clientService.getCodeValuesByName('Constitution').subscribe((options) => {
      if (options?.length) {
        this.constitutionOptions = options;
        // Sort master by value length descending so longer/more-specific keys match first
@@ -1321,6 +1321,11 @@
          kycForm.get('kycDocumentNumber')?.hasError('pattern') && kycForm.get('kycDocumentNumber')?.touched
        ) {
          <mat-error>Only letters, numbers, hyphens and slashes allowed</mat-error>
+        } @else if (
+          kycForm.get('kycDocumentNumber')?.hasError('aadhaarLast4Mismatch') &&
+          kycForm.get('kycDocumentNumber')?.touched
+        ) {
+          <mat-error>Last 4 digits do not match the Aadhaar number entered above</mat-error>
        }
      </mat-form-field>

@@ -8,7 +8,14 @@

 import { Component, Input, OnInit, OnChanges, OnDestroy, SimpleChanges, inject } from '@angular/core';
 import { forkJoin, catchError, of } from 'rxjs';
-import { UntypedFormBuilder, UntypedFormGroup, Validators, FormsModule } from '@angular/forms';
+import {
+  UntypedFormBuilder,
+  UntypedFormGroup,
+  Validators,
+  FormsModule,
+  AbstractControl,
+  ValidationErrors
+} from '@angular/forms';
 import {
  MatDialog,
  MAT_DIALOG_DATA,
@@ -567,6 +574,28 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
  /** Existing signature document ID (for re-upload/delete) */
  existingSignatureDocId: string = '';

+  /**
+   * Cross-field check for the OVD "Document Number" field (kycDocumentNumber): when Aadhaar Card
+   * is the selected KYC document, its value must identify the same Aadhaar as the aadhaarNumber
+   * field captured earlier in this step - the last 4 digits are what's compared, since
+   * aadhaarNumber may hold either the raw 12-digit number or a masked value (masking only ever
+   * obscures the first 8 digits - see aadhaarMasked in the kycData getter below - so the last 4
+   * characters are always the real digits either way). Not applicable to any other document type,
+   * where kycDocumentNumber is unrelated to Aadhaar entirely.
+   */
+  private aadhaarLast4MatchValidator = (control: AbstractControl): ValidationErrors | null => {
+    if (this.selectedKycDoc?.code !== 'AADHAAR') {
+      return null;
+    }
+    const docNumber = (control.value || '').toString().trim();
+    const aadhaarValue = (control.parent?.get('aadhaarNumber')?.value || '').toString().trim();
+    if (docNumber.length < 4 || aadhaarValue.length < 4) {
+      // Required/pattern validators already flag an empty or too-short value on their own.
+      return null;
+    }
+    return docNumber.slice(-4) === aadhaarValue.slice(-4) ? null : { aadhaarLast4Mismatch: true };
+  };
+
  /** KYC Form */
  kycForm: UntypedFormGroup = this.formBuilder.group({
    hasPan: [true],
@@ -616,7 +645,8 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
      [
        Validators.required,
        Validators.pattern(/^[A-Za-z0-9\-\/\s]+$/),
-        Validators.maxLength(30)
+        Validators.maxLength(30),
+        this.aadhaarLast4MatchValidator
      ]
    ],
    kycDocIssueDate: [''],
@@ -739,6 +769,14 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
      this.kycForm.get('ecgcSalFlag')?.disable();
      this.kycForm.get('dormantFlag')?.disable();
    }
+
+    // aadhaarLast4MatchValidator (on kycDocumentNumber) reads this control's value directly rather
+    // than through its own valueChanges, so a re-check has to be triggered explicitly whenever the
+    // Aadhaar field itself changes - otherwise fixing aadhaarNumber after kycDocumentNumber was
+    // already entered would leave a stale mismatch error in place.
+    this.kycForm.get('aadhaarNumber')?.valueChanges.subscribe(() => {
+      this.kycForm.get('kycDocumentNumber')?.updateValueAndValidity({ onlySelf: true });
+    });
  }

  /** Seed the document-type picker from defaults (entity RBI docs vs. individual OVDs,
@@ -1009,6 +1047,9 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
    // Reset uploads + merged preview when document type changes
    this.kycDocFiles = { front: null, back: null };
    this.kycDocMergedPreview = null;
+    // aadhaarLast4MatchValidator only applies while Aadhaar Card is selected - re-check so switching
+    // to/away from it immediately picks up (or clears) the mismatch error.
+    this.kycForm.get('kycDocumentNumber')?.updateValueAndValidity({ onlySelf: true });
  }

  isKycDocSelected(proof: ProofType): boolean {
@@ -1189,6 +1230,9 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
          // Sync chip-picker selection with the prefilled document name
          if (data.kycDocumentName) {
            this.selectedKycDoc = this.findKycDocProofByName(data.kycDocumentName);
+            // patchValue above ran kycDocumentNumber's validators before selectedKycDoc was known,
+            // so aadhaarLast4MatchValidator needs a fresh check now that it is.
+            this.kycForm.get('kycDocumentNumber')?.updateValueAndValidity({ onlySelf: true });
          }
          // Set verification statuses from existing data
          if (data.panVerified) {
@@ -61,6 +61,7 @@ import { KycTabComponent } from './clients-view/kyc-tab/kyc-tab.component';
 import { CkycTabComponent } from './clients-view/ckyc-tab/ckyc-tab.component';
 import { Form60TabComponent } from './clients-view/form60-tab/form60-tab.component';
 import { Form121TabComponent } from './clients-view/form121-tab/form121-tab.component';
+import { tdsConfigResolver } from '../letter-mgmt/certificates/form-15gh/tds-config.service';
 import { EntityClassificationTabComponent } from './clients-view/entity-classification-tab/entity-classification-tab.component';
 import { AuthorizedSignatoriesTabComponent } from './clients-view/authorized-signatories-tab/authorized-signatories-tab.component';
 import { familyAllowedGuard, nomineeAllowedGuard } from './utils/family-nominee.guard';
@@ -198,6 +199,7 @@ const routes: Routes = [
            {
              path: 'form121',
              component: Form121TabComponent,
+              resolve: { tdsConfig: tdsConfigResolver },
              data: { title: 'Form 121 / TDS', breadcrumb: 'Form 121 / TDS', routeParamBreadcrumb: false }
            },
            {
@@ -202,9 +202,14 @@
                <div>
                  <strong>Already available</strong>
                  <span class="ckyc-existing__source">from {{ existing.ADDRESS_PROOF.source }}</span>
+                  @if (existing.ADDRESS_PROOF.previewUnavailable) {
+                    <span class="ckyc-existing__warn">stored file unavailable</span>
+                  }
                </div>
              </div>
-              @if (existing.ADDRESS_PROOF.previewUrl || existing.ADDRESS_PROOF.previewUrlBack) {
+              @if (
+                (existing.ADDRESS_PROOF.previewUrl || existing.ADDRESS_PROOF.previewUrlBack) && isImage('ADDRESS_PROOF')
+              ) {
                <div class="ckyc-existing__thumbs">
                  @if (existing.ADDRESS_PROOF.previewUrl) {
                    <img
@@ -222,6 +227,17 @@
                  }
                </div>
              }
+              @if (existing.ADDRESS_PROOF.previewUrl) {
+                <button
+                  mat-stroked-button
+                  type="button"
+                  class="ckyc-existing__view"
+                  (click)="openDocument('ADDRESS_PROOF')"
+                >
+                  <fa-icon icon="eye"></fa-icon>
+                  &nbsp;View document
+                </button>
+              }
              <div class="ckyc-existing__meta">
                <fa-icon icon="file-alt"></fa-icon>
                <span>{{ existing.ADDRESS_PROOF.name }}</span>
@@ -299,9 +315,12 @@
                <div>
                  <strong>Already available</strong>
                  <span class="ckyc-existing__source">from {{ existing.PHOTO_PROOF.source }}</span>
+                  @if (existing.PHOTO_PROOF.previewUnavailable) {
+                    <span class="ckyc-existing__warn">stored file unavailable</span>
+                  }
                </div>
              </div>
-              @if (existing.PHOTO_PROOF.previewUrl || existing.PHOTO_PROOF.previewUrlBack) {
+              @if ((existing.PHOTO_PROOF.previewUrl || existing.PHOTO_PROOF.previewUrlBack) && isImage('PHOTO_PROOF')) {
                <div class="ckyc-existing__thumbs">
                  @if (existing.PHOTO_PROOF.previewUrl) {
                    <img
@@ -319,6 +338,17 @@
                  }
                </div>
              }
+              @if (existing.PHOTO_PROOF.previewUrl) {
+                <button
+                  mat-stroked-button
+                  type="button"
+                  class="ckyc-existing__view"
+                  (click)="openDocument('PHOTO_PROOF')"
+                >
+                  <fa-icon icon="eye"></fa-icon>
+                  &nbsp;View document
+                </button>
+              }
              <div class="ckyc-existing__meta">
                <fa-icon icon="id-card"></fa-icon>
                <span>{{ existing.PHOTO_PROOF.name }}</span>
@@ -393,11 +423,25 @@
                <div>
                  <strong>Already available</strong>
                  <span class="ckyc-existing__source">from {{ existing.CLIENT_IMAGE.source }}</span>
+                  @if (existing.CLIENT_IMAGE.previewUnavailable) {
+                    <span class="ckyc-existing__warn">stored file unavailable</span>
+                  }
                </div>
              </div>
-              @if (existing.CLIENT_IMAGE.previewUrl) {
+              @if (existing.CLIENT_IMAGE.previewUrl && isImage('CLIENT_IMAGE')) {
                <img [src]="existing.CLIENT_IMAGE.previewUrl" alt="Client photo" class="ckyc-existing__thumb" />
              }
+              @if (existing.CLIENT_IMAGE.previewUrl) {
+                <button
+                  mat-stroked-button
+                  type="button"
+                  class="ckyc-existing__view"
+                  (click)="openDocument('CLIENT_IMAGE')"
+                >
+                  <fa-icon icon="eye"></fa-icon>
+                  &nbsp;View document
+                </button>
+              }
              <button
                mat-stroked-button
                type="button"
@@ -448,15 +492,29 @@
                <div>
                  <strong>Already available</strong>
                  <span class="ckyc-existing__source">from {{ existing.CLIENT_SIGNATURE.source }}</span>
+                  @if (existing.CLIENT_SIGNATURE.previewUnavailable) {
+                    <span class="ckyc-existing__warn">stored file unavailable</span>
+                  }
                </div>
              </div>
-              @if (existing.CLIENT_SIGNATURE.previewUrl) {
+              @if (existing.CLIENT_SIGNATURE.previewUrl && isImage('CLIENT_SIGNATURE')) {
                <img
                  [src]="existing.CLIENT_SIGNATURE.previewUrl"
                  alt="Client signature"
                  class="ckyc-existing__thumb ckyc-existing__thumb--wide"
                />
              }
+              @if (existing.CLIENT_SIGNATURE.previewUrl) {
+                <button
+                  mat-stroked-button
+                  type="button"
+                  class="ckyc-existing__view"
+                  (click)="openDocument('CLIENT_SIGNATURE')"
+                >
+                  <fa-icon icon="eye"></fa-icon>
+                  &nbsp;View document
+                </button>
+              }
              <div class="ckyc-existing__meta">
                <fa-icon icon="file-signature"></fa-icon>
                <span>{{ existing.CLIENT_SIGNATURE.name }}</span>
@@ -623,6 +623,35 @@
  }
 }

+/* Opens the uploaded artefact full size in a new tab. Sits directly under the thumbnail, and is
+   the only way to inspect a PDF - which cannot render as an inline <img>. */
+.ckyc-existing__view {
+  align-self: flex-start;
+  color: #1d6fd0;
+  border-color: #bcd8f5;
+  background: #fff;
+  font-size: 13px;
+  font-weight: 600;
+
+  &:hover {
+    background: #eef6ff;
+  }
+}
+
+/* Shown when a document row exists but its file could not be fetched from the content store,
+   so "Already available" is not silently misleading. */
+.ckyc-existing__warn {
+  display: inline-block;
+  margin-left: 8px;
+  padding: 1px 8px;
+  border-radius: 10px;
+  background: #fdecec;
+  border: 1px solid #f3c2c2;
+  color: #a12b2b;
+  font-size: 11px;
+  font-weight: 600;
+}
+
 .ckyc-existing {
  display: flex;
  flex-direction: column;
@@ -36,11 +36,41 @@ interface ExistingArtefact {
   *  already writes/reads for address proof; now shared by the photo/identity proof too. */
  description?: string;
  fileCount?: number;
+  /** Set when the stored file could not be fetched - the row exists but its content is gone. */
+  previewUnavailable?: boolean;
+  /** Stored MIME type, so the card knows whether it can render an inline thumbnail. */
+  mimeType?: string;
 }

 type ProofKind = 'ADDRESS_PROOF' | 'PHOTO_PROOF';
 type CkycDocKind = ProofKind | 'CLIENT_IMAGE' | 'CLIENT_SIGNATURE';

+/**
+ * Client-side upload guards, kept deliberately in step with the backend so a file that passes here
+ * is not rejected server-side:
+ *  - 5 MB matches `spring.servlet.multipart.max-file-size`
+ *  - the extension list is the intersection of the backend `fineract.content.regex-whitelist`
+ *    with what these cards can actually render.
+ * The dialog's `accept=` is only a file-picker hint and is trivially bypassed, so the real check
+ * runs here, on the file the dialog hands back, before anything is sent.
+ */
+const MAX_UPLOAD_BYTES = 5 * 1024 * 1024;
+const IMAGE_EXTENSIONS = [
+  'png',
+  'jpeg',
+  'jpg'
+];
+const DOCUMENT_EXTENSIONS = [
+  ...IMAGE_EXTENSIONS,
+  'pdf'
+];
+
+/** Cards that render an inline <img>, so a PDF would not display in them. */
+const IMAGE_ONLY_KINDS: CkycDocKind[] = [
+  'CLIENT_IMAGE',
+  'CLIENT_SIGNATURE'
+];
+
@Component({
  selector: 'mifosx-ckyc-tab',
  templateUrl: './ckyc-tab.component.html',
@@ -150,6 +180,11 @@ export class CkycTabComponent implements OnInit, OnDestroy {
  ngOnInit(): void {
    this.route.parent.params.subscribe((params: any) => {
      this.clientId = params['clientId'];
+      // Angular reuses this component when only the clientId in the route changes, and
+      // loadExistingArtefacts() only ever *assigns* what it finds - it has no "not found" branch.
+      // Without clearing first, a client with no photo (or no signature, or no proof) keeps showing
+      // the previous client's card.
+      this.resetArtefactState();
      this.loadClientInfo();
      this.loadAccounts();
      this.loadCkycData();
@@ -157,6 +192,46 @@ export class CkycTabComponent implements OnInit, OnDestroy {
    });
  }

+  /**
+   * Returns every per-client card to its empty state, so nothing from the client just viewed can
+   * survive into the next one. Covers all four cards plus the details staged for an upload - a file
+   * or document number left over from another client must never be submitted against this one.
+   */
+  private resetArtefactState(): void {
+    this.revokePreviewUrls();
+    this.existing = {
+      ADDRESS_PROOF: { present: false },
+      PHOTO_PROOF: { present: false },
+      CLIENT_IMAGE: { present: false },
+      CLIENT_SIGNATURE: { present: false }
+    };
+    this.selectedProofType = { ADDRESS_PROOF: null, PHOTO_PROOF: null };
+    this.docFiles = {
+      ADDRESS_PROOF: { front: null, back: null },
+      PHOTO_PROOF: { front: null, back: null }
+    };
+    this.documentDetails = {
+      ADDRESS_PROOF: { documentKey: '', issueDate: null, expiryDate: null },
+      PHOTO_PROOF: { documentKey: '', issueDate: null, expiryDate: null }
+    };
+    this.clientImageFile = null;
+    this.clientSignatureFile = null;
+    this.uploadErrors = {
+      ADDRESS_PROOF: null,
+      PHOTO_PROOF: null,
+      CLIENT_IMAGE: null,
+      CLIENT_SIGNATURE: null
+    };
+  }
+
+  /** Frees the blob URLs held by the current cards before their references are dropped. */
+  private revokePreviewUrls(): void {
+    Object.values(this.existing).forEach((e) => {
+      if (e.previewUrl?.startsWith('blob:')) URL.revokeObjectURL(e.previewUrl);
+      if (e.previewUrlBack?.startsWith('blob:')) URL.revokeObjectURL(e.previewUrlBack);
+    });
+  }
+
  private loadClientInfo(): void {
    this.route.parent.data.subscribe((data: any) => {
      const cv = data?.clientViewData;
@@ -280,19 +355,29 @@ export class CkycTabComponent implements OnInit, OnDestroy {
            present: true,
            source: 'Client registration',
            name: signatureDoc.fileName || 'Client signature',
-            documentId: signatureDoc.id
+            documentId: signatureDoc.id,
+            mimeType: signatureDoc.type
          };
-          // Fetch blob for preview
+          // Same endpoint getClientSignatureImage() uses, but opted out of the global error alert:
+          // a m_document row whose file is no longer in the content store returns 500, and the card
+          // below reports that itself. Without `silent` the interceptor pops an "Internal Server
+          // Error" modal on every page load, for a failure the user cannot act on.
          this.clientsService
-            .getClientSignatureImage(this.clientId, signatureDoc.id)
+            .downloadClientDocument(this.clientId, String(signatureDoc.id), true)
            .pipe(takeUntil(this.destroy$))
            .subscribe({
              next: (blob: any) => {
-                if (blob) {
+                if (blob && blob.size > 0) {
                  this.existing.CLIENT_SIGNATURE.previewUrl = URL.createObjectURL(blob);
+                } else {
+                  // A 200 with an empty body still means there is nothing to show. Without this the
+                  // card would claim "Already available" with no thumbnail and no explanation.
+                  this.existing.CLIENT_SIGNATURE.previewUnavailable = true;
                }
              },
-              error: () => undefined
+              error: () => {
+                this.existing.CLIENT_SIGNATURE.previewUnavailable = true;
+              }
            });
        }

@@ -364,6 +449,7 @@ export class CkycTabComponent implements OnInit, OnDestroy {
        const list = Array.isArray(docs) ? docs : [];
        if (!list.length) return;
        this.existing[kind].fileCount = list.length;
+        this.existing[kind].previewUnavailable = false;

        const byNewest = (a: any, b: any) => b.id - a.id;
        const label = (d: any) => (d?.name || d?.fileName || '').toString();
@@ -372,6 +458,9 @@ export class CkycTabComponent implements OnInit, OnDestroy {
          [...list].filter((d: any) => /front/i.test(label(d))).sort(byNewest)[0] ||
          [...list].filter((d: any) => d.id !== back?.id).sort(byNewest)[0];

+        // A proof can be scanned to PDF, which no <img> can render - remember what was stored so the
+        // card offers "View document" instead of a broken thumbnail.
+        if (front) this.existing[kind].mimeType = front.type;
        if (front) this.downloadIdentifierDocPreview(identifierId, front.id, kind, 'front');
        if (back && back.id !== front?.id) this.downloadIdentifierDocPreview(identifierId, back.id, kind, 'back');
      });
@@ -388,12 +477,19 @@ export class CkycTabComponent implements OnInit, OnDestroy {
      .pipe(takeUntil(this.destroy$))
      .subscribe({
        next: (blob: any) => {
-          if (!blob) return;
+          if (!blob || blob.size === 0) {
+            this.existing[kind].previewUnavailable = true;
+            return;
+          }
          const url = URL.createObjectURL(blob);
          if (slot === 'front') this.existing[kind].previewUrl = url;
          else this.existing[kind].previewUrlBack = url;
        },
-        error: () => undefined
+        // The row exists but its file is gone from the content store. Saying so on the card beats
+        // showing "Already available" next to a blank space.
+        error: () => {
+          this.existing[kind].previewUnavailable = true;
+        }
      });
  }

@@ -452,6 +548,18 @@ export class CkycTabComponent implements OnInit, OnDestroy {

    ref.afterClosed().subscribe((result: CkycUploadDialogResult | null) => {
      if (!result) return;
+
+      // The dialog's `accept=` filter is only a hint to the file picker and is trivially bypassed,
+      // so the size/type guard runs here on what actually came back. Catching it now turns a raw
+      // server rejection into a message on the card.
+      const rejection =
+        this.validationError(result.front, kind) ?? (result.back ? this.validationError(result.back, kind) : null);
+      if (rejection) {
+        this.uploadErrors[kind] = rejection;
+        return;
+      }
+      this.uploadErrors[kind] = null;
+
      if (isProofKind) {
        const proofKind = kind as ProofKind;
        this.selectedProofType[proofKind] = result.proofType || null;
@@ -470,6 +578,66 @@ export class CkycTabComponent implements OnInit, OnDestroy {
    });
  }

+  /** Extensions a given card can both store and render. */
+  private allowedExtensions(kind: CkycDocKind): string[] {
+    return IMAGE_ONLY_KINDS.includes(kind) ? IMAGE_EXTENSIONS : DOCUMENT_EXTENSIONS;
+  }
+
+  /**
+   * Rejects a file the backend would refuse (or the card could not render) before it is uploaded,
+   * so the user gets a clear message instead of a raw server error. Returns null when the file is
+   * acceptable.
+   */
+  private validationError(file: File | null | undefined, kind: CkycDocKind): string | null {
+    if (!file) {
+      return null;
+    }
+    const allowed = this.allowedExtensions(kind);
+    const extension = (file.name.split('.').pop() || '').toLowerCase();
+
+    if (!allowed.includes(extension)) {
+      return `Unsupported file type ".${extension}". Allowed: ${allowed.map((e) => e.toUpperCase()).join(', ')}.`;
+    }
+    if (file.size > MAX_UPLOAD_BYTES) {
+      const mb = (file.size / (1024 * 1024)).toFixed(1);
+      return `File is ${mb} MB. The maximum allowed size is 5 MB.`;
+    }
+    if (file.size === 0) {
+      return 'The selected file is empty.';
+    }
+    return null;
+  }
+
+  /**
+   * True when the stored file can be shown as an inline thumbnail. A PDF cannot, so its card falls
+   * back to the "View document" button alone rather than rendering a broken image.
+   */
+  isImage(kind: CkycDocKind): boolean {
+    const entry = this.existing[kind];
+    // The profile image arrives as a `data:image/...;base64,` URL, which declares its own type -
+    // it has neither a stored MIME type nor a file extension for the checks below to read.
+    if (entry?.previewUrl?.startsWith('data:')) {
+      return entry.previewUrl.startsWith('data:image/');
+    }
+    if (entry?.mimeType) {
+      return entry.mimeType.startsWith('image/');
+    }
+    // Older rows can have no stored MIME type - fall back to the file extension.
+    const extension = (entry?.name?.split('.').pop() || '').toLowerCase();
+    return IMAGE_EXTENSIONS.includes(extension);
+  }
+
+  /**
+   * Opens the uploaded document full size in a new tab. Uses the blob already fetched for the
+   * thumbnail, so it works for PDFs too and costs no extra request.
+   */
+  openDocument(kind: CkycDocKind): void {
+    const url = this.existing[kind]?.previewUrl;
+    if (url) {
+      window.open(url, '_blank', 'noopener');
+    }
+  }
+
  /** Reads back the "Issue date: yyyy-MM-dd, Expiry date: yyyy-MM-dd" convention this tab (and
   *  client-india-address-step, for address proof) writes into the identifier's description. */
  private parseDescriptionDates(description: string | undefined): { issueDate: Date | null; expiryDate: Date | null } {
@@ -533,6 +701,10 @@ export class CkycTabComponent implements OnInit, OnDestroy {
    request$.pipe(takeUntil(this.destroy$)).subscribe({
      next: () => {
        this.uploading[documentType] = false;
+        // The card is gated on `present`; without this a successful upload left it reading
+        // "Not uploaded yet". uploadProofDocument() sets the same flag for the proof cards.
+        this.existing[key].present = true;
+        this.existing[key].source = this.existing[key].source || 'CKYC upload';
        this.alertService.alert({ type: 'success', message: 'Document uploaded successfully.' });
        this.refreshPreview(documentType);
      },
@@ -653,13 +825,22 @@ export class CkycTabComponent implements OnInit, OnDestroy {
    if (this.existing[staleKey].previewUrlBack?.startsWith('blob:')) {
      URL.revokeObjectURL(this.existing[staleKey].previewUrlBack!);
    }
+    // The upload that triggered this refresh is what repairs a previously missing file, so the
+    // warning has to be cleared before the re-read - otherwise a fixed card keeps the old badge.
+    this.existing[staleKey].previewUrl = undefined;
+    this.existing[staleKey].previewUrlBack = undefined;
+    this.existing[staleKey].previewUnavailable = false;
    switch (documentType) {
      case 'CLIENT_IMAGE':
        this.clientsService
          .getClientProfileImage(this.clientId)
          .pipe(takeUntil(this.destroy$))
          .subscribe((photo: any) => {
-            if (photo) this.existing.CLIENT_IMAGE.previewUrl = photo;
+            if (photo) {
+              this.existing.CLIENT_IMAGE.previewUrl = photo;
+            } else {
+              this.existing.CLIENT_IMAGE.previewUnavailable = true;
+            }
          });
        break;
      case 'CLIENT_SIGNATURE':
@@ -672,11 +853,21 @@ export class CkycTabComponent implements OnInit, OnDestroy {
              ?.sort((a: any, b: any) => b.id - a.id)?.[0];
            if (!doc) return;
            this.existing.CLIENT_SIGNATURE.documentId = doc.id;
+            this.existing.CLIENT_SIGNATURE.mimeType = doc.type;
            this.clientsService
-              .getClientSignatureImage(this.clientId, doc.id)
+              .downloadClientDocument(this.clientId, String(doc.id), true)
              .pipe(takeUntil(this.destroy$))
-              .subscribe((blob: any) => {
-                if (blob) this.existing.CLIENT_SIGNATURE.previewUrl = URL.createObjectURL(blob);
+              .subscribe({
+                next: (blob: any) => {
+                  if (blob && blob.size > 0) {
+                    this.existing.CLIENT_SIGNATURE.previewUrl = URL.createObjectURL(blob);
+                  } else {
+                    this.existing.CLIENT_SIGNATURE.previewUnavailable = true;
+                  }
+                },
+                error: () => {
+                  this.existing.CLIENT_SIGNATURE.previewUnavailable = true;
+                }
              });
          });
        break;
@@ -690,10 +881,6 @@ export class CkycTabComponent implements OnInit, OnDestroy {
  ngOnDestroy(): void {
    this.destroy$.next();
    this.destroy$.complete();
-    // Release object URLs
-    Object.values(this.existing).forEach((e) => {
-      if (e.previewUrl?.startsWith('blob:')) URL.revokeObjectURL(e.previewUrl);
-      if (e.previewUrlBack?.startsWith('blob:')) URL.revokeObjectURL(e.previewUrlBack);
-    });
+    this.revokePreviewUrls();
  }
 }
@@ -55,7 +55,10 @@
      <div class="f121__note">
        <mat-icon>info_outline</mat-icon>
        <div>
-          @if (!dateOfBirth) {
+          @if (configMissing) {
+            TDS rates for FY {{ fy }} are not configured, so the tax cannot be computed. Set them up under Organization
+            › TDS Configuration.
+          } @else if (!dateOfBirth) {
            Date of birth is not on record, so the senior-citizen threshold cannot be determined. Add it on the Personal
            Data tab.
          } @else {
@@ -113,8 +116,8 @@
        <div class="f121__note f121__note--warn">
          <mat-icon>warning_amber</mat-icon>
          <div>
-            A Form 121 declaration is on record for this year, but withholding is still switched on for one or more
-            deposits. Turn it off on those accounts, or tax will keep being deducted.
+            A declaration is on record for this year, but one or more deposits still carry a tax group. Those accounts
+            deduct on their own and ignore the declaration — remove the tax group from them.
          </div>
        </div>
      }
@@ -189,20 +192,90 @@
              }
            </span>
          </div>
-          @if (declarationOnRecord && declarationFy) {
+          @if (declarationRecord; as d) {
            <div class="f121__kv-row">
              <span>Declared for</span>
-              <span>FY {{ declarationFy }}</span>
+              <span>FY {{ d.fy }} · Form {{ d.formType }}</span>
            </div>
-          }
-          @if (declarationOnRecord && !acceptanceDateKnown) {
-            <div class="f121__kv-row f121__kv-row--muted">
-              <span>Acceptance date</span>
+            <div class="f121__kv-row">
+              <span>Accepted on</span>
              <span>
-                Not captured — the declaration is treated as covering the whole year. A mid-year acceptance would change
-                the figures below.
+                {{ d.acceptedOn | date: 'd MMM y' }} — no TDS on interest credited from this day to 31 March. Interest
+                credited before it is taxed as usual.
              </span>
            </div>
+            @if (d.uin) {
+              <div class="f121__kv-row">
+                <span>UIN</span>
+                <span class="f121__mono">{{ d.uin }}</span>
+              </div>
+            }
+            <div class="f121__kv-row">
+              <span></span>
+              <span>
+                <button type="button" class="f121__btn f121__btn--warn" (click)="revokeDeclaration()">
+                  Withdraw declaration
+                </button>
+              </span>
+            </div>
+          } @else if (fy && !configMissing) {
+            <div class="f121__kv-row">
+              <span></span>
+              <span>
+                @if (!showDeclarationForm) {
+                  <button type="button" class="f121__btn" (click)="openDeclarationForm()" [disabled]="!panWellFormed">
+                    Record {{ formLabel }} for FY {{ fy }}
+                  </button>
+                  @if (!panWellFormed) {
+                    <div class="muted">A valid PAN must be on the KYC first — a declaration without one is void.</div>
+                  }
+                }
+              </span>
+            </div>
+            @if (showDeclarationForm) {
+              <div class="f121__decl-form">
+                <label>
+                  <span>Accepted on *</span>
+                  <input type="date" [(ngModel)]="newDeclaration.acceptedOn" />
+                </label>
+                <label>
+                  <span>UIN</span>
+                  <input type="text" [(ngModel)]="newDeclaration.uin" placeholder="Allotted on acceptance" />
+                </label>
+                <label>
+                  <span>Estimated income for the year (₹)</span>
+                  <input type="number" min="0" [(ngModel)]="newDeclaration.estimatedIncome" />
+                </label>
+                @if (declarationError) {
+                  <div class="f121__note f121__note--warn">
+                    <mat-icon>error_outline</mat-icon>
+                    <div>{{ declarationError }}</div>
+                  </div>
+                }
+                <div class="f121__decl-actions">
+                  <button type="button" class="f121__btn" (click)="showDeclarationForm = false">Cancel</button>
+                  <button
+                    type="button"
+                    class="f121__btn f121__btn--primary"
+                    (click)="saveDeclaration()"
+                    [disabled]="savingDeclaration"
+                  >
+                    {{ savingDeclaration ? 'Saving…' : 'Save declaration' }}
+                  </button>
+                </div>
+              </div>
+            }
+          }
+          @for (old of declarations; track old.id) {
+            @if (old.revoked && old.fy === fy) {
+              <div class="f121__kv-row f121__kv-row--muted">
+                <span>Withdrawn</span>
+                <span>
+                  Form {{ old.formType }} accepted {{ old.acceptedOn | date: 'd MMM y' }}, withdrawn
+                  {{ old.revokedOn | date: 'd MMM y' }} — {{ old.revokeReason }}
+                </span>
+              </div>
+            }
          }
          @if (eligibility) {
            @for (reason of eligibility.reasons; track reason) {
@@ -332,3 +332,61 @@
  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
  font-weight: 600;
 }
+
+/* ── Recording a declaration ── */
+.f121__btn {
+  padding: 6px 14px;
+  border: 1px solid #d1d5db;
+  border-radius: 6px;
+  background: #fff;
+  font: inherit;
+  font-size: 12.5px;
+  font-weight: 600;
+  cursor: pointer;
+
+  &:disabled {
+    opacity: 0.55;
+    cursor: not-allowed;
+  }
+
+  &--primary {
+    border-color: #1d4ed8;
+    background: #1d4ed8;
+    color: #fff;
+  }
+
+  &--warn {
+    border-color: #b45309;
+    color: #b45309;
+  }
+}
+
+.f121__decl-form {
+  display: grid;
+  gap: 10px;
+  padding: 12px 16px;
+
+  label {
+    display: grid;
+    gap: 4px;
+    font-size: 12px;
+
+    span {
+      color: #6b7280;
+      font-weight: 600;
+    }
+
+    input {
+      max-width: 280px;
+      padding: 6px 8px;
+      border: 1px solid #d1d5db;
+      border-radius: 6px;
+      font: inherit;
+    }
+  }
+}
+
+.f121__decl-actions {
+  display: flex;
+  gap: 8px;
+}
@@ -23,6 +23,8 @@ import { SavingsService } from 'app/savings/savings.service';
 import { FixedDepositsService } from 'app/deposits/fixed-deposits/fixed-deposits.service';
 import { RecurringDepositsService } from 'app/deposits/recurring-deposits/recurring-deposits.service';
 import { STANDALONE_SHARED_IMPORTS } from 'app/standalone-shared.module';
+import { TdsDeclarationRecord, TdsReportsService } from 'app/tds-reports/tds-reports.service';
+import { TdsDeductee } from 'app/tds-reports/tds-reports-data';

 /** Domain logic */
 import {
@@ -111,6 +113,7 @@ export class Form121TabComponent implements OnInit, OnDestroy {
  private savingsService = inject(SavingsService);
  private fixedDepositsService = inject(FixedDepositsService);
  private recurringDepositsService = inject(RecurringDepositsService);
+  private tdsService = inject(TdsReportsService);

  private destroy$ = new Subject<void>();

@@ -124,23 +127,25 @@ export class Form121TabComponent implements OnInit, OnDestroy {
  pan = '';
  panWellFormed = false;

-  // ── Declaration on record ──
-  declarationOnRecord = false;
+  // ── Declarations on record ──
+  /**
+   * Every declaration the customer has given, each for one year and from the day the branch
+   * accepted it. The KYC record only ever held a type and a year, which made a September
+   * declaration shield interest back to April and let last year's form run on.
+   */
+  declarations: TdsDeclarationRecord[] = [];
  /**
   * The form actually in force for the selected year. From FY 2026-27 a single
   * Form 121 replaced the 15G/15H split, so this is derived from the year rather
   * than from the payee's age.
   */
  declarationForm: DeclarationForm = '121';
-  /** Kind recorded at KYC, meaningful only for a pre-2026 year. */
-  declarationKind: '15G' | '15H' = '15G';
-  declarationFy = '';
-  /**
-   * The KYC step records only the year, not the date the branch accepted the
-   * declaration, so it has to be treated as covering the whole year. Surfaced on
-   * screen rather than hidden — a mid-year acceptance would change the figures.
-   */
-  acceptanceDateKnown = false;
+
+  // ── Recording a declaration ──
+  showDeclarationForm = false;
+  savingDeclaration = false;
+  declarationError = '';
+  newDeclaration = { acceptedOn: '', uin: '', estimatedIncome: null as number | null };

  eligibility: EligibilityResult | null = null;

@@ -153,11 +158,13 @@ export class Form121TabComponent implements OnInit, OnDestroy {
  schedule: TdsSchedule | null = null;
  actualTds = 0;
  tdsSaved = 0;
+  /** The selected year has no entry on Organization › TDS Configuration. */
+  configMissing = false;

  /** Raw account inputs, kept so the year selector can recompute cheaply. */
-  private accountInputs: (TdsAccountInput & { meta: Form121AccountRow })[] = [];
-  /** Withheld-tax postings by FY, from the ledger. */
-  private actualTdsByFy = new Map<string, number>();
+  private accountInputs: (TdsAccountInput & { meta: Form121AccountRow; taxLines: InterestCredit[] })[] = [];
+  /** This customer's FD/RD interest received in savings, and TDS taken there, per year. */
+  private platformByFy = new Map<string, TdsDeductee | null>();

  ngOnInit(): void {
    this.route.parent.params.pipe(takeUntil(this.destroy$)).subscribe((params: any) => {
@@ -180,13 +187,15 @@ export class Form121TabComponent implements OnInit, OnDestroy {
    forkJoin({
      client: this.clientsService.getClientData(this.clientId, true).pipe(catchError(() => of(null))),
      kyc: this.clientsService.getClientKyc(this.clientId, true).pipe(catchError(() => of(null))),
-      accounts: this.clientsService.getClientAccountData(this.clientId).pipe(catchError(() => of(null)))
+      accounts: this.clientsService.getClientAccountData(this.clientId).pipe(catchError(() => of(null))),
+      declarations: this.tdsService.getDeclarations(Number(this.clientId)).pipe(catchError(() => of([])))
    })
      .pipe(
        takeUntil(this.destroy$),
-        switchMap(({ client, kyc, accounts }) => {
+        switchMap(({ client, kyc, accounts, declarations }) => {
          this.applyClient(client);
          this.applyKyc(kyc);
+          this.declarations = declarations || [];
          const deposits = this.depositAccountsOf(accounts);
          return deposits.length ? forkJoin(deposits.map((a) => this.fetchAccount(a))) : of([] as any[]);
        }),
@@ -210,11 +219,8 @@ export class Form121TabComponent implements OnInit, OnDestroy {
  private applyKyc(kyc: any): void {
    this.pan = (kyc?.panNumber ?? '').toUpperCase();
    this.panWellFormed = isWellFormedPan(this.pan);
-    this.declarationOnRecord = !!kyc?.form15Applicable;
-    this.declarationKind = kyc?.form15Type === '15H' ? '15H' : '15G';
-    this.declarationForm = this.fy ? declarationFormFor(this.fy, this.dateOfBirth) : '121';
-    this.declarationFy = kyc?.form15FY ?? '';
-    this.acceptanceDateKnown = false;
+    this.declarationForm =
+      this.fy && FY_TAX_CONFIG[normaliseFy(this.fy)] ? declarationFormFor(this.fy, this.dateOfBirth) : '121';
  }

  /** Savings, FD and RD accounts — everything that can credit interest. */
@@ -248,7 +254,7 @@ export class Form121TabComponent implements OnInit, OnDestroy {
   */
  private ingest(details: any[]): void {
    this.accountInputs = [];
-    this.actualTdsByFy = new Map<string, number>();
+    this.platformByFy = new Map<string, TdsDeductee | null>();
    const fys = new Set<string>();
    const clientIdNum = Number(this.clientId);

@@ -269,6 +275,7 @@ export class Form121TabComponent implements OnInit, OnDestroy {
      };

      const credits: InterestCredit[] = [];
+      const taxLines: InterestCredit[] = [];
      let tdsDeducted = 0;

      for (const t of d.transactions ?? []) {
@@ -286,8 +293,7 @@ export class Form121TabComponent implements OnInit, OnDestroy {
        } else if (t.transactionType?.withholdTax) {
          const amount = t.amount ?? 0;
          tdsDeducted += amount;
-          const txnFy = fyOf(iso);
-          this.actualTdsByFy.set(txnFy, (this.actualTdsByFy.get(txnFy) ?? 0) + amount);
+          taxLines.push({ date: iso, amount, accountNo: ref.accountNo });
        }
      }

@@ -310,12 +316,13 @@ export class Form121TabComponent implements OnInit, OnDestroy {
        deducteeClientId: deductee
      };

-      this.accountInputs.push({ ...ref, credits, meta });
+      this.accountInputs.push({ ...ref, credits, taxLines, meta });
    }

    this.availableFys = [...fys].sort().reverse();
    if (!this.availableFys.includes(this.fy)) {
-      this.fy = this.availableFys[0] ?? (this.declarationFy ? normaliseFy(this.declarationFy) : '');
+      this.fy =
+        this.availableFys[0] ?? this.declarations[0]?.fy ?? Object.keys(FY_TAX_CONFIG).sort().reverse()[0] ?? '';
    }
  }

@@ -333,14 +340,37 @@ export class Form121TabComponent implements OnInit, OnDestroy {
    }

    const year = normaliseFy(this.fy);
+    this.configMissing = !FY_TAX_CONFIG[year];
+
+    // TDS is tracked on FD/RD interest once it reaches savings, and deducted there. Those figures live
+    // on the platform, not in the deposit's own transactions, so they are fetched once per year and
+    // the computation waits for them.
+    if (!this.platformByFy.has(year)) {
+      this.loadPlatformYear(year);
+      return;
+    }
+    const platform = this.platformByFy.get(year);
+    for (const a of this.accountInputs) {
+      if (!a.meta.tdsApplicable) {
+        continue;
+      }
+      const match = platform?.accounts.find((p) => p.accountNo === a.accountNo);
+      a.credits = match?.credits ?? [];
+      a.taxLines = match?.deductions ?? [];
+    }

    // Per-account interest for the selected year, for the three lists.
    for (const a of this.accountInputs) {
      a.meta.interest = a.credits.filter((c) => fyOf(c.date) === year).reduce((s, c) => s + c.amount, 0);
+      // The selected year only - this used to total every year the account had ever been taxed in.
+      a.meta.tdsDeducted = a.meta.tdsApplicable
+        ? a.taxLines.filter((c) => fyOf(c.date) === year).reduce((s, c) => s + c.amount, 0)
+        : 0;
    }
-    this.actualTds = this.actualTdsByFy.get(year) ?? 0;
+    // What was actually debited for this customer as deductee, wherever the savings account sits.
+    this.actualTds = this.accountInputs.filter((a) => a.meta.tdsApplicable).reduce((s, a) => s + a.meta.tdsDeducted, 0);

-    if (!this.dateOfBirth) {
+    if (!this.dateOfBirth || this.configMissing) {
      return;
    }

@@ -378,21 +408,95 @@ export class Form121TabComponent implements OnInit, OnDestroy {
    return applicable.some((a) => a.meta.mode === 'QUARTERLY') ? 'QUARTERLY' : 'ANNUAL';
  }

-  /** The declaration, but only when it was filed for the year being shown. */
-  private declarationForSelectedFy(): Declaration | null {
-    if (!this.declarationOnRecord || !this.fy) {
+  private loadPlatformYear(year: string): void {
+    this.tdsService
+      .getDepositInterest(Number(year.slice(0, 4)), Number(this.clientId))
+      .pipe(
+        catchError(() => of([])),
+        takeUntil(this.destroy$)
+      )
+      .subscribe((rows) => {
+        this.platformByFy.set(year, rows.find((r) => `${r.clientId}` === `${this.clientId}`) ?? null);
+        this.recompute();
+      });
+  }
+
+  /** The live declaration recorded for the year being shown, if any. */
+  get declarationRecord(): TdsDeclarationRecord | null {
+    if (!this.fy) {
      return null;
    }
    const year = normaliseFy(this.fy);
-    if (this.declarationFy && normaliseFy(this.declarationFy) !== year) {
+    return this.declarations.find((d) => d.fy === year && !d.revoked) ?? null;
+  }
+
+  get declarationOnRecord(): boolean {
+    return !!this.declarationRecord;
+  }
+
+  /** The declaration as the engine takes it — operative from the day it was accepted. */
+  private declarationForSelectedFy(): Declaration | null {
+    const d = this.declarationRecord;
+    if (!d) {
      return null;
    }
-    return {
-      kind: this.declarationKind,
-      // No acceptance date on record — treated as covering the whole year.
-      acceptedOn: `${year.slice(0, 4)}-04-01`,
-      fy: year
-    };
+    const kind = d.formType === '15H' ? '15H' : d.formType === '15G' ? '15G' : formKindFor(this.dateOfBirth, d.fy);
+    return { kind, acceptedOn: d.acceptedOn, fy: d.fy, uin: d.uin || undefined };
+  }
+
+  openDeclarationForm(): void {
+    this.newDeclaration = { acceptedOn: new Date().toISOString().slice(0, 10), uin: '', estimatedIncome: null };
+    this.declarationError = '';
+    this.showDeclarationForm = true;
+  }
+
+  saveDeclaration(): void {
+    if (!this.newDeclaration.acceptedOn) {
+      this.declarationError = 'Enter the date the branch accepted the form.';
+      return;
+    }
+    this.savingDeclaration = true;
+    this.declarationError = '';
+    this.tdsService
+      .createDeclaration({
+        clientId: Number(this.clientId),
+        fy: normaliseFy(this.fy),
+        formType: declarationFormFor(this.fy, this.dateOfBirth),
+        acceptedOn: this.newDeclaration.acceptedOn,
+        uin: this.newDeclaration.uin || undefined,
+        estimatedIncome: this.newDeclaration.estimatedIncome
+      })
+      .subscribe({
+        next: (rows) => {
+          this.savingDeclaration = false;
+          this.showDeclarationForm = false;
+          this.declarations = rows || [];
+          this.recompute();
+        },
+        error: (err: any) => {
+          this.savingDeclaration = false;
+          this.declarationError =
+            err?.error?.errors?.[0]?.defaultUserMessage || err?.error?.defaultUserMessage || 'Could not save.';
+        }
+      });
+  }
+
+  revokeDeclaration(): void {
+    const d = this.declarationRecord;
+    if (!d) {
+      return;
+    }
+    const reason = prompt('Why is this declaration being withdrawn? From today, TDS will be deducted again.');
+    if (!reason) {
+      return;
+    }
+    this.tdsService.revokeDeclaration(d.id, reason).subscribe({
+      next: (rows) => {
+        this.declarations = rows || [];
+        this.recompute();
+      },
+      error: (err: any) => alert(err?.error?.defaultUserMessage || 'Could not revoke the declaration.')
+    });
  }

  // ───────────────────────── Template helpers ─────────────────────────
@@ -411,7 +515,7 @@ export class Form121TabComponent implements OnInit, OnDestroy {

  /** The form the payee would file for the selected year. */
  get formLabel(): string {
-    if (!this.fy) {
+    if (!this.fy || this.configMissing) {
      return '—';
    }
    const form = declarationFormFor(this.fy, this.dateOfBirth);
@@ -470,11 +574,12 @@ export class Form121TabComponent implements OnInit, OnDestroy {
  }

  /**
-   * A declaration is on record but deposit accounts are still set to withhold —
-   * the branch has not switched them off.
+   * A declaration is on record but a deposit still carries a stock Fineract tax group. Those
+   * accounts withhold on their own rules and never consult the declaration record, so the form
+   * does not stop their deduction until the tax group is removed.
   */
  get declarationNotAppliedToAccounts(): boolean {
-    return !!this.declarationForSelectedFy() && this.liableAccounts.some((a) => a.withHoldTax);
+    return !!this.declarationForSelectedFy() && this.liableAccounts.some((a) => !!a.taxGroup);
  }

  /**
@@ -1247,9 +1247,7 @@
                    </div>

                    @if (!docScansLoading && !docScans.front && !docScans.back) {
-                      <div class="kyc-doc-scans__empty">
-                        No scan is on file for this document. Upload one below.
-                      </div>
+                      <div class="kyc-doc-scans__empty">No scan is on file for this document. Upload one below.</div>
                    }

                    <div class="kyc-doc-scans__sides">
@@ -182,7 +182,10 @@ export class KycTabComponent implements OnInit, OnDestroy {
  docScans: { front: DocScanSide | null; back: DocScanSide | null } = { front: null, back: null };

  /** The two sides, in display order, so the template loops rather than repeating itself. */
-  readonly docScanSlots: ('front' | 'back')[] = ['front', 'back'];
+  readonly docScanSlots: ('front' | 'back')[] = [
+    'front',
+    'back'
+  ];

  docScanOf(slot: 'front' | 'back') {
    return this.docScans[slot];
@@ -474,7 +477,8 @@ export class KycTabComponent implements OnInit, OnDestroy {
      adverseMediaMatch: !!v.adverseMediaMatch,
      // Blank stays null rather than becoming zero: an income nobody asked for is unknown, and a zero would read as a
      // customer who declared no income at all.
-      declaredAnnualIncome: v.declaredAnnualIncome === '' || v.declaredAnnualIncome == null ? null : v.declaredAnnualIncome,
+      declaredAnnualIncome:
+        v.declaredAnnualIncome === '' || v.declaredAnnualIncome == null ? null : v.declaredAnnualIncome,
      declaredAnnualTurnover:
        v.declaredAnnualTurnover === '' || v.declaredAnnualTurnover == null ? null : v.declaredAnnualTurnover
    };
@@ -519,7 +523,7 @@ export class KycTabComponent implements OnInit, OnDestroy {
      dateFormat: 'dd MMMM yyyy',
      ...this.buildDocumentFields(),
      ...this.buildRiskProfileFields(),
-        ...this.buildExceptionFields()
+      ...this.buildExceptionFields()
    };

    if (!this.kycId) {
@@ -766,7 +770,7 @@ export class KycTabComponent implements OnInit, OnDestroy {
      riskCategory: this.kycForm.value.riskCategory || 1,
      ...declarationFields,
      ...this.buildRiskProfileFields(),
-        ...this.buildExceptionFields()
+      ...this.buildExceptionFields()
    };

    this.clientsService
@@ -927,7 +931,7 @@ export class KycTabComponent implements OnInit, OnDestroy {
      riskCategory: this.kycForm.value.riskCategory || 1,
      ...receiptFields,
      ...this.buildRiskProfileFields(),
-        ...this.buildExceptionFields()
+      ...this.buildExceptionFields()
    };

    this.clientsService
@@ -1455,7 +1459,10 @@ I further confirm that:
      this.docScansLoading = false;
      // This runs again after every replace, so the previews being thrown away are revoked
      // rather than left holding their blobs.
-      for (const old of [this.docScans.front, this.docScans.back]) {
+      for (const old of [
+        this.docScans.front,
+        this.docScans.back
+      ]) {
        if (old?.previewUrl) {
          URL.revokeObjectURL(old.previewUrl);
        }
@@ -1497,7 +1504,10 @@ I further confirm that:
      }

      this.docScans = sides;
-      for (const key of ['front', 'back'] as const) {
+      for (const key of [
+        'front',
+        'back'
+      ] as const) {
        if (sides[key]) {
          this.loadScanPreview(sides[key]!);
        }
@@ -1558,7 +1568,9 @@ I further confirm that:
      error: (err: any) => {
        this.docScanUploading = null;
        this.docScanError =
-          err?.error?.defaultUserMessage || err?.error?.developerMessage || `Could not replace the ${label.toLowerCase()} side.`;
+          err?.error?.defaultUserMessage ||
+          err?.error?.developerMessage ||
+          `Could not replace the ${label.toLowerCase()} side.`;
      }
    });
  }
@@ -1741,7 +1753,10 @@ I further confirm that:
    this.destroy$.next();
    this.destroy$.complete();
    // Object URLs are held by the browser until revoked, so the scan blobs would outlive the tab.
-    for (const side of [this.docScans.front, this.docScans.back]) {
+    for (const side of [
+      this.docScans.front,
+      this.docScans.back
+    ]) {
      if (side?.previewUrl) {
        URL.revokeObjectURL(side.previewUrl);
      }
@@ -569,8 +569,19 @@ export class ClientsService {
    return this.http.get(`/clients/${clientId}/documents`);
  }

-  downloadClientDocument(parentEntityId: string, documentId: string) {
-    return this.http.get(`/clients/${parentEntityId}/documents/${documentId}/attachment`, { responseType: 'blob' });
+  /**
+   * Fetches a client document's stored file.
+   *
+   * `silent` opts the request out of ErrorHandlerInterceptor's alert. Pass it when the caller
+   * renders its own failure state - notably thumbnail fetches, where a `m_document` row whose file
+   * is no longer in the content store returns 500 and would otherwise pop a modal the user can do
+   * nothing about. The interceptor still rethrows, so the caller's error callback continues to run.
+   */
+  downloadClientDocument(parentEntityId: string, documentId: string, silent = false) {
+    return this.http.get(`/clients/${parentEntityId}/documents/${documentId}/attachment`, {
+      responseType: 'blob',
+      ...(silent ? { context: new HttpContext().set(SILENT_HTTP_ERROR, true) } : {})
+    });
  }

  uploadClientDocument(clientId: string, documentData: any) {
@@ -992,12 +1003,28 @@ export class ClientsService {
    return this.http.post(`/clients/${clientId}/entityclassification/${category}`, data);
  }

-  getClientCkyc(clientId: string): Observable<any> {
-    return this.http.get(`/clients/${clientId}/ckyc`);
+  /**
+   * Uploads a single CKYC artefact against the client, using the platform's generic document
+   * endpoint (DocumentApiResource, POST /v1/{entityType}/{entityId}/documents). There is no
+   * CKYC-specific document API on the backend - the earlier `/clients/{id}/ckyc/documents` path
+   * was never implemented and returned 404.
+   *
+   * The multipart body must carry `file`, `name` and `description`; the caller builds those so the
+   * stored document stays identifiable by CKYC artefact type. See ckyc-tab.component.ts.
+   */
+  uploadCkycDocument(clientId: string, formData: FormData): Observable<any> {
+    return this.http.post(`/clients/${clientId}/documents`, formData);
  }

-  uploadCkycDocument(clientId: string, formData: FormData): Observable<any> {
-    return this.http.post(`/clients/${clientId}/ckyc/documents`, formData);
+  /**
+   * Replaces the content of an existing client document in place (DocumentApiResource PUT
+   * /v1/{entityType}/{entityId}/documents/{documentId}), keeping the same document id.
+   *
+   * Used by the CKYC screen's "Upload new version" so a re-upload updates the existing artefact
+   * rather than adding another row. Takes the same multipart body as the create call.
+   */
+  replaceClientDocument(clientId: string, documentId: string, formData: FormData): Observable<any> {
+    return this.http.put(`/clients/${clientId}/documents/${documentId}`, formData);
  }

  /**
@@ -109,13 +109,7 @@
              </button>
            }
          </div>
-          <input
-            #sideInput
-            type="file"
-            hidden
-            accept="image/*,application/pdf"
-            (change)="onFilePicked($event, slot)"
-          />
+          <input #sideInput type="file" hidden accept="image/*,application/pdf" (change)="onFilePicked($event, slot)" />
        </div>
      }
    </div>