feat(#946): passport scan-image upload (single-slot on contacts.*, preserves #906)

apps/admin/src/app/contacts/[id]/_components/passport-scan.tsx

@@ -0,0 +1,123 @@
+'use client'
+
+/**
+ * #946: Passport SCAN IMAGE manager (admin contact record).
+ *
+ * Single-slot asset attached to the passport field-data on contacts.* (NOT a
+ * contact_documents row — preserves the #906 invariant). View (signed URL),
+ * upload, replace, delete. Camera capture (capture=environment) for tablets.
+ */
+
+import { useRef, useState } from 'react'
+import { Loader2, Upload, Camera, Trash2, FileText, ExternalLink } from 'lucide-react'
+import {
+  useContactPassportImage,
+  useUploadContactPassportImage,
+  useDeleteContactPassportImage,
+} from '@/hooks/use-contacts'
+import { Button } from '@/components/ui/button'
+import { useToast } from '@/hooks/use-toast'
+import { ApiError } from '@/lib/api'
+import { formatDateOnly } from '@/lib/date-utils'
+
+const MAX_MB = 10
+
+export function PassportScan({ contactId }: { contactId: string }) {
+  const { data, isLoading } = useContactPassportImage(contactId)
+  const uploadMutation = useUploadContactPassportImage()
+  const deleteMutation = useDeleteContactPassportImage()
+  const { toast } = useToast()
+  const fileInputRef = useRef<HTMLInputElement>(null)
+  const cameraInputRef = useRef<HTMLInputElement>(null)
+  const [error, setError] = useState('')
+
+  const pending = uploadMutation.isPending || deleteMutation.isPending
+
+  async function handleFile(e: React.ChangeEvent<HTMLInputElement>) {
+    const file = e.target.files?.[0]
+    e.target.value = '' // allow re-selecting the same file
+    if (!file) return
+    setError('')
+    if (file.size > MAX_MB * 1024 * 1024) {
+      setError(`File must be under ${MAX_MB}MB`)
+      return
+    }
+    try {
+      await uploadMutation.mutateAsync({ contactId, file })
+      toast({ title: 'Passport scan saved' })
+    } catch (err) {
+      if (err instanceof ApiError) {
+        toast({ title: 'Upload failed', description: err.message, variant: 'destructive' })
+        return
+      }
+      throw err
+    }
+  }
+
+  async function handleDelete() {
+    setError('')
+    try {
+      await deleteMutation.mutateAsync(contactId)
+      toast({ title: 'Passport scan removed' })
+    } catch (err) {
+      if (err instanceof ApiError) {
+        toast({ title: 'Delete failed', description: err.message, variant: 'destructive' })
+        return
+      }
+      throw err
+    }
+  }
+
+  const url = data?.url ?? null
+
+  return (
+    <div className="border-t border-ash-100 pt-3 mt-1">
+      <p className="text-xs font-medium text-ash-600 mb-2">Passport Scan</p>
+
+      <input ref={fileInputRef} type="file" accept="image/*,application/pdf" onChange={handleFile} className="hidden" />
+      {/* capture=environment opens the rear camera on mobile/tablet; ignored on desktop */}
+      <input ref={cameraInputRef} type="file" accept="image/*" capture="environment" onChange={handleFile} className="hidden" />
+
+      {isLoading ? (
+        <p className="text-sm text-ash-400">Loading…</p>
+      ) : url ? (
+        <div className="space-y-2">
+          <a
+            href={url}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="flex items-center gap-2 rounded-lg border border-ash-200 p-2 hover:bg-ash-50"
+          >
+            <FileText className="h-5 w-5 text-phoenix-gold-500 shrink-0" />
+            <span className="flex-1 text-sm text-ash-900">View passport scan</span>
+            <ExternalLink className="h-3.5 w-3.5 text-ash-400" />
+          </a>
+          {data?.uploadedAt && (
+            <p className="text-xs text-ash-500">Added {formatDateOnly(data.uploadedAt)}</p>
+          )}
+          <div className="flex gap-2">
+            <Button size="sm" variant="ghost" className="h-7 px-2" disabled={pending} onClick={() => fileInputRef.current?.click()}>
+              {uploadMutation.isPending ? <Loader2 className="h-3.5 w-3.5 mr-1 animate-spin" /> : <Upload className="h-3.5 w-3.5 mr-1" />}
+              Replace
+            </Button>
+            <Button size="sm" variant="ghost" className="h-7 px-2 text-red-600 hover:text-red-700" disabled={pending} onClick={handleDelete}>
+              <Trash2 className="h-3.5 w-3.5 mr-1" /> Delete
+            </Button>
+          </div>
+        </div>
+      ) : (
+        <div className="flex gap-2">
+          <Button size="sm" variant="outline" className="h-8" disabled={pending} onClick={() => fileInputRef.current?.click()}>
+            {uploadMutation.isPending ? <Loader2 className="h-3.5 w-3.5 mr-1 animate-spin" /> : <Upload className="h-3.5 w-3.5 mr-1" />}
+            Upload scan
+          </Button>
+          <Button size="sm" variant="outline" className="h-8" disabled={pending} onClick={() => cameraInputRef.current?.click()}>
+            <Camera className="h-3.5 w-3.5 mr-1" /> Take Photo
+          </Button>
+        </div>
+      )}
+
+      {error && <p className="text-xs text-red-600 mt-1">{error}</p>}
+    </div>
+  )
+}

apps/admin/src/app/contacts/[id]/page.tsx

@@ -64,6 +64,7 @@ import { RelationshipsSection } from './_components/relationships-section'
 import { LoyaltyProgramsSection } from './_components/loyalty-programs-section'
 import { LoyaltyProgramDialog } from './_components/loyalty-program-dialog'
 import { ContactDocumentsSection } from './_components/contact-documents-section'
+import { PassportScan } from './_components/passport-scan'
 import { ContactEmailsSection } from './_components/contact-emails-section'
 import { RecentEmailsCard } from './_components/recent-emails-card'
 import { NotesSection } from '@/components/notes/NotesSection'
@@ -1320,6 +1321,8 @@ export default function ContactDetailPage() {
                 ) : (
                   <p className="text-sm text-ash-500">No passport on file. Click <span className="font-medium">Add</span> to enter passport details.</p>
                 )}
+                {/* #946: passport scan image (single-slot, on contacts.* — no doc row) */}
+                <PassportScan contactId={contact.id} />
               </CardContent>
             </Card>
 

apps/admin/src/hooks/use-contacts.ts

@@ -288,3 +288,49 @@ export function useUpdateMarketingConsent() {
     },
   })
 }
+
+// ===========================================================================
+// #946 — Passport SCAN IMAGE (admin). Single-slot asset on contacts.* (signed
+// URL view, null-safe). NOT a contact_documents row (preserves #906 invariant).
+// ===========================================================================
+
+export interface PassportImageResult {
+  url: string | null
+  uploadedAt: string | null
+}
+
+const passportImageKey = (contactId: string) =>
+  [...contactKeys.detail(contactId), 'passport-image'] as const
+
+export function useContactPassportImage(contactId: string | null) {
+  return useQuery({
+    queryKey: passportImageKey(contactId || ''),
+    queryFn: () => api.get<PassportImageResult>(`/contacts/${contactId}/passport-image`),
+    enabled: !!contactId,
+  })
+}
+
+export function useUploadContactPassportImage() {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: ({ contactId, file }: { contactId: string; file: File }) => {
+      const formData = new FormData()
+      formData.append('file', file)
+      return api.postFormData<PassportImageResult>(`/contacts/${contactId}/passport-image`, formData)
+    },
+    onSuccess: (_, { contactId }) => {
+      queryClient.invalidateQueries({ queryKey: passportImageKey(contactId) })
+    },
+  })
+}
+
+export function useDeleteContactPassportImage() {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (contactId: string) =>
+      api.delete<{ deleted: boolean }>(`/contacts/${contactId}/passport-image`),
+    onSuccess: (_, contactId) => {
+      queryClient.invalidateQueries({ queryKey: passportImageKey(contactId) })
+    },
+  })
+}

apps/api/src/contacts/contact-documents.service.ts

@@ -5,10 +5,11 @@
  * Works with the contact_documents table.
  */
 
-import { Injectable } from '@nestjs/common'
-import { eq } from 'drizzle-orm'
+import { ConflictException, Injectable, Logger, NotFoundException } from '@nestjs/common'
+import { and, eq, isNull } from 'drizzle-orm'
 import { EventEmitter2 } from '@nestjs/event-emitter'
 import { DatabaseService } from '../db/database.service'
+import { StorageService } from '../trips/storage.service'
 import { AuditEvent } from '../activity-logs/events/audit.event'
 import { sanitizeForAudit, computeAuditDiff } from '../activity-logs/audit-sanitizer'
 
@@ -31,13 +32,127 @@ export interface ContactDocumentDto {
   uploadedBy: string | null
 }
 
+/** #946: passport scan-image result shape (signed URL view; null when none). */
+export interface PassportImageDto {
+  url: string | null
+  uploadedAt: string | null
+}
+
 @Injectable()
 export class ContactDocumentsService {
+  private readonly logger = new Logger(ContactDocumentsService.name)
+
   constructor(
     private readonly db: DatabaseService,
     private readonly eventEmitter: EventEmitter2,
+    private readonly storageService: StorageService,
   ) {}
 
+  // ===========================================================================
+  // #946 — Passport SCAN IMAGE (single-slot asset on contacts.*, NOT a
+  // contact_documents row — preserves the #906 invariant). Stores the R2 key;
+  // signs on read. Shared by the admin endpoint and (mirrored) the portal one.
+  // ===========================================================================
+
+  /** Upload/replace the contact's passport scan. Returns a signed view URL. */
+  async setPassportImage(
+    contactId: string,
+    file: { buffer: Buffer; originalName: string; mimeType: string },
+  ): Promise<PassportImageDto> {
+    const [contact] = await this.db.client
+      .select({ id: this.db.schema.contacts.id, passportImageKey: this.db.schema.contacts.passportImageKey })
+      .from(this.db.schema.contacts)
+      .where(eq(this.db.schema.contacts.id, contactId))
+      .limit(1)
+    if (!contact) throw new NotFoundException(`Contact ${contactId} not found`)
+
+    const oldKey = contact.passportImageKey
+    // Upload NEW first (no data loss if the DB write fails).
+    const newKey = await this.storageService.uploadDocument(
+      file.buffer,
+      `contacts/${contactId}/passport`,
+      file.originalName,
+      file.mimeType,
+    )
+    const uploadedAt = new Date()
+    let updated: { id: string }[]
+    try {
+      // Compare-and-set: only claim the slot if it still holds the key we read.
+      // Guards against a concurrent replace silently orphaning the loser's blob.
+      updated = await this.db.client
+        .update(this.db.schema.contacts)
+        .set({ passportImageKey: newKey, passportImageUploadedAt: uploadedAt, updatedAt: uploadedAt })
+        .where(
+          and(
+            eq(this.db.schema.contacts.id, contactId),
+            oldKey
+              ? eq(this.db.schema.contacts.passportImageKey, oldKey)
+              : isNull(this.db.schema.contacts.passportImageKey),
+          ),
+        )
+        .returning({ id: this.db.schema.contacts.id })
+    } catch (error) {
+      // Roll back the orphaned upload on DB failure.
+      try { await this.storageService.deleteDocument(newKey) } catch (e) {
+        this.logger.warn(`Failed to clean up orphaned passport upload for contact ${contactId}: ${e}`)
+      }
+      throw error
+    }
+    // A concurrent replace won the slot — delete OUR new blob rather than
+    // orphaning the winner's, and signal the caller to retry.
+    if (updated.length === 0) {
+      try { await this.storageService.deleteDocument(newKey) } catch (e) {
+        this.logger.warn(`Failed to clean up superseded passport upload for contact ${contactId}: ${e}`)
+      }
+      throw new ConflictException('Passport image was updated concurrently; please retry')
+    }
+    // Best-effort delete of the replaced scan.
+    if (oldKey && oldKey !== newKey) {
+      try { await this.storageService.deleteDocument(oldKey) } catch (e) {
+        this.logger.warn(`Failed to delete previous passport scan for contact ${contactId}: ${e}`)
+      }
+    }
+    const url = await this.storageService.getSignedUrl(newKey).catch(() => null)
+    return { url, uploadedAt: uploadedAt.toISOString() }
+  }
+
+  /** Signed view URL for the contact's passport scan (null when none). */
+  async getPassportImage(contactId: string): Promise<PassportImageDto> {
+    const [contact] = await this.db.client
+      .select({
+        passportImageKey: this.db.schema.contacts.passportImageKey,
+        passportImageUploadedAt: this.db.schema.contacts.passportImageUploadedAt,
+      })
+      .from(this.db.schema.contacts)
+      .where(eq(this.db.schema.contacts.id, contactId))
+      .limit(1)
+    if (!contact) throw new NotFoundException(`Contact ${contactId} not found`)
+    if (!contact.passportImageKey) return { url: null, uploadedAt: null }
+    const url = await this.storageService.getSignedUrl(contact.passportImageKey).catch(() => null)
+    return { url, uploadedAt: contact.passportImageUploadedAt?.toISOString() ?? null }
+  }
+
+  /** Remove the contact's passport scan (DB + best-effort R2). */
+  async deletePassportImage(contactId: string): Promise<{ deleted: boolean }> {
+    const [contact] = await this.db.client
+      .select({ id: this.db.schema.contacts.id, passportImageKey: this.db.schema.contacts.passportImageKey })
+      .from(this.db.schema.contacts)
+      .where(eq(this.db.schema.contacts.id, contactId))
+      .limit(1)
+    if (!contact) throw new NotFoundException(`Contact ${contactId} not found`)
+    const key = contact.passportImageKey
+    await this.db.client
+      .update(this.db.schema.contacts)
+      .set({ passportImageKey: null, passportImageUploadedAt: null, updatedAt: new Date() })
+      .where(eq(this.db.schema.contacts.id, contactId))
+    if (key) {
+      try { await this.storageService.deleteDocument(key) } catch (e) {
+        this.logger.warn(`Failed to delete passport scan for contact ${contactId} from storage: ${e}`)
+      }
+    }
+    return { deleted: true }
+  }
+
   async findByContactId(contactId: string): Promise<ContactDocumentDto[]> {
     const documents = await this.db.client
       .select()