# TechTitans POS — Branded Reprint for Historical Invoices

**Date:** 2026-11-12 · **Branch:** `techtitans/integration` · Local commit only (no push/deploy).
NH POS / legacy portal untouched; no legacy PHP executed; sandbox (offline) dev data only. **No invoice amounts,
taxes, payment ledger, numbering or any stored/historical PDF bytes were changed.**

## Root cause (recap)

`InvoiceService` renders + stores a PDF **once** at issue time and `download()` streams those **immutable** bytes
on every subsequent request. **PF-2026-0015** was issued **2026-11-12 06:28** — before the tenant logo became
effective (~07:02), before the branded template redesign, and before the digital-fulfillment fix — so its frozen
bytes legitimately show no logo, "PRO FORMA INVOICE" + watermark, the old layout and "PICKUP". That is correct,
immutable accounting behaviour; the document must not be rewritten.

## Solution — a branded reprint that never touches the original

Two clearly-separated actions per invoice:

| Action | Route | What it returns |
|---|---|---|
| **View original** | `GET /orders/{order}/invoice` | the **exact stored bytes**, unchanged (immutable) |
| **Branded copy** | `GET /orders/{order}/invoice/branded-copy` | a **reprint** rendered live from the invoice's own frozen snapshot + the **current** logo, marked as a reprint; **nothing is stored or mutated** |

### Backend (`app/Invoices/InvoiceService.php`)
- `brandedReprint(Invoice): string` — renders the modern template from the invoice's **frozen snapshot** (number,
  document type, issue date, subtotal/tax/grand totals and the **recorded** `payment_status_snapshot`) plus the
  currently-configured tenant logo, with a reprint banner. It **never** stores a PDF, issues a document, or writes any
  order/payment/tax/invoice row.
- `currentDocument(Order): ?Invoice` — **read-only** lookup of the document "View Original" streams (mirrors
  `getOrIssue`'s selection but never issues/refreshes/mutates).
- `reprintFilename(Invoice)` → `reprint-<number>.pdf` (distinct from the original `proforma-/invoice-<number>.pdf`).
- `renderPdf(…, ?string $reprintAt)` now also **backfills** the display-only `fulfillment.physical` flag for legacy
  metadata (derived from the order source) so a reprint of an old **IPTV** invoice no longer shows a misleading
  "Pickup". This is presentation-only — stored metadata/amounts/identity are untouched.

### Controller + route
`OrderInvoiceController::brandedCopy` behind `permission.any:invoices.view` **and** order location scope (an
out-of-scope order is a 404, identical to the original download). It resolves the current document read-only, renders
the reprint, audits `order.invoice.reprinted`, and streams it `no-store`.

### Template (`resources/views/invoices/pdf.blade.php`)
A `@if($reprint_at)` **branded-reprint banner**: "BRANDED REPRINT — Generated {date}. A branded copy of {number}
({issue date}) reproduced from the recorded invoice data. The original issued document is unchanged; figures and the
payment status shown are as recorded on the original." The original **PRO FORMA** title + watermark are **preserved**
for genuine proformas — the reprint re-brands, it does not reclassify.

### Frontend (IPTV Account → Invoices)
Each row now offers **View original** and **Branded copy** (`iptvApi.invoiceBrandedBlobUrl`), with an explainer:
*"View original streams the exact issued PDF, unchanged. Branded copy regenerates it with the current logo & layout
and is clearly marked as a reprint — it never alters the original document or any amounts."*

## Accounting safeguards (all verified)

- **Original immutable:** the stored PDF bytes + `pdf_sha256` are unchanged after a reprint (proven: hash identical
  before/after), and the original download still returns the exact legacy bytes.
- **No new records:** reprint creates **no** order, invoice, payment or tax row (invoice count unchanged).
- **Identity/amounts preserved:** number, document type, issue date, subtotal/tax/grand totals and the recorded
  payment-status snapshot come from the invoice's own snapshot — the reprint shows the **recorded** status (not a
  re-derived current one), and is labelled a reprint, so it cannot misstate the original.
- **Classification preserved (Task 4):** historical proformas keep PRO FORMA; the already-shipped lifecycle fix
  (commit `0a8e61e`) means newly-issued IPTV invoices are **TAX INVOICE** with the payment state shown separately
  (Pay Now / Pay Later / Partial / later settlement all handled — an unpaid issued invoice is never auto-proforma).
- **Isolation + auth:** `invoices.view` required; another tenant gets 404.

## Tests

- **Backend** (`tests/Feature/Orders`) → **30 passed**:
  - `InvoicePdfTest::test_branded_reprint_preserves_the_original_immutable_document` — reprint is a valid, logo-bearing
    PDF distinct from the original; original bytes + `pdf_sha256` unchanged; no new invoice; type/number preserved.
  - `OrderInvoiceNotificationTest` — branded-copy route streams a `reprint-…pdf` without changing the original row/PDF;
    requires `invoices.view` (403 without); tenant-isolated (404 cross-tenant).
- **Frontend** (`IptvPages.test.tsx`) → **24 passed**: "View original" hits `/invoice`; "Branded copy" hits
  `/invoice/branded-copy` and does **not** call the original route.
- **Pint** + **PHPStan** (`app/Invoices`, `app/Http/Controllers/Api/V1/Orders`) clean; `tsc -b`, `eslint`,
  `npm run build` clean.

## Live verification — the exact document PF-2026-0015 (Playwright, real route)

On IPTV account **IPTV-2026-0003** → Invoices, the PF-2026-0015 row shows **View original** + **Branded copy**
(`screenshots/invoice-reprint/ui-view-original-and-branded-copy.png`). Clicking the **real "Branded copy" button**
fired `GET /orders/01a1ce71…/invoice/branded-copy` → **200**. Replaying both authed requests:

| | Route | Bytes | Logo | Filename |
|---|---|---|---|---|
| **Original** | `/invoice` | 880,267 | **no** | `proforma-PF-2026-0015.pdf` |
| **Branded** | `/invoice/branded-copy` | 892,908 | **YES** | `reprint-PF-2026-0015.pdf` |

Rendered PDFs (`screenshots/invoice-reprint/`):
- `original-PF-2026-0015-unchanged.png` — the untouched legacy document (no logo, old layout, PICKUP, PRO FORMA).
- `branded-reprint-PF-2026-0015.png` — the reprint: **TechTitans logo**, modern aligned 6-column layout, the
  **BRANDED REPRINT banner**, original number **PF-2026-0015** + issue date **2026-11-12**, **PRO FORMA** title +
  watermark preserved, recorded **PAYMENT PENDING** status, and **no misleading "Pickup"**.

0 console errors. Multi-page documents reprint through the same template (repeated header + "Page X of Y", covered by
`InvoicePdfTest`'s long-description/pagination test).

## Files changed

| File | Change |
|---|---|
| `app/Invoices/InvoiceService.php` | `brandedReprint`, `currentDocument`, `reprintFilename`; `renderPdf` reprint flag + legacy `physical` backfill. |
| `app/Http/Controllers/Api/V1/Orders/OrderInvoiceController.php` | `brandedCopy` action (invoices.view + scope, no-store, audit). |
| `routes/api.php` | `GET orders/{order}/invoice/branded-copy`. |
| `resources/views/invoices/pdf.blade.php` | reprint banner + style. |
| `frontend/src/lib/api/iptv.ts` | `invoiceBrandedBlobUrl`. |
| `frontend/src/pages/iptv/IptvDetailPage.tsx` + `iptv.css` | View original + Branded copy actions + explainer. |
| tests | backend reprint/route tests; frontend branded-copy test. |

## Commits (no push)

- **Backend:** `7973370` — reprint service/route/template/tests + this report + screenshots.
- **Frontend:** `b0888ba` — View original / Branded copy actions + API + test.