Matt
81a98c6695
Lays out the plan to replace pdfme with @react-pdf/renderer, add unpdf for berth-PDF tier-2 rasterization, and add port-level logo upload (sharp normalization + react-image-crop UI + svgo sanitization + rasterize-SVG-to-PNG-on-upload). Scope locked to internal-only PDFs (reports, expenses, record exports). Invoice + admin TipTap-to-PDF removed entirely; in-app EOI pathway (pdf-lib AcroForm fill) stays untouched. 14 commits planned. Single source of truth for tokens. Three orthogonal PDF paths post-migration with no overlap. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
492 lines
35 KiB
Markdown
492 lines
35 KiB
Markdown
# PDF Stack Overhaul — Design
|
||
|
||
**Date:** 2026-05-12
|
||
**Branch:** `feat/documents-folders`
|
||
**Status:** Design approved; pending user review of spec; implementation planned via writing-plans skill.
|
||
|
||
## Goal
|
||
|
||
Replace `pdfme` (3 deps, 8 hand-coded coordinate templates, 571-line TipTap-to-pdfme bridge) with `@react-pdf/renderer` (JSX components, real layout primitives). Add `unpdf` for berth-PDF tier-2 rasterization. Add port-level logo upload with quality safeguards. Migrate only the internal-only PDF surfaces; remove invoice and admin-TipTap PDF generation entirely (they violate the new "no client-facing CRM-generated PDFs" rule).
|
||
|
||
## Scope (locked)
|
||
|
||
### KEEP & migrate to `@react-pdf/renderer` (internal-only)
|
||
|
||
| Surface | Current location | Caller |
|
||
| ----------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------- |
|
||
| Activity report | `src/lib/pdf/templates/reports/activity-report.ts` | `src/lib/services/reports.service.ts` |
|
||
| Revenue report | `src/lib/pdf/templates/reports/revenue-report.ts` | same |
|
||
| Pipeline report | `src/lib/pdf/templates/reports/pipeline-report.ts` | same |
|
||
| Occupancy report | `src/lib/pdf/templates/reports/occupancy-report.ts` | same |
|
||
| Client summary export | `src/lib/pdf/templates/client-summary-template.ts` | `src/lib/services/record-export.ts` |
|
||
| Berth spec export | `src/lib/pdf/templates/berth-spec-template.ts` | same |
|
||
| Interest summary export | `src/lib/pdf/templates/interest-summary-template.ts` | same |
|
||
| Expense sheet | `src/lib/services/expense-pdf.service.ts` (currently uses pdfme indirectly via `expense-export.ts`) | same |
|
||
|
||
### REMOVE entirely
|
||
|
||
| Removal | Reason |
|
||
| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| `src/lib/pdf/templates/invoice-template.ts` + `generatePdf` call in `invoices.ts:604` + API route `/api/v1/invoices/[id]/generate-pdf` | Invoices are client-facing; no CRM-generated client-facing PDFs. Future invoice rendering will use the deferred AcroForm-fill admin-template feature. |
|
||
| `src/lib/pdf/tiptap-to-pdfme.ts` (571 lines) + API route `/api/v1/admin/templates/preview` + `generatePdf` block in `document-templates.ts:516` | TipTap document templates are Documenso seed bodies; CRM does not render them to PDF anymore. |
|
||
| `src/lib/pdf/templates/eoi-standard-inapp.ts` (337 lines, HTML seed) + seed-data references | Only used as the seed `bodyHtml` text on a `document_templates` row. The in-app EOI is rendered by `fill-eoi-form.ts` (pdf-lib), not from this HTML. Safe to drop. |
|
||
| `src/lib/pdf/generate.ts` (24 lines) | Pdfme wrapper; replaced by `src/lib/pdf/render.ts`. |
|
||
| Deps: `@pdfme/common`, `@pdfme/generator`, `@pdfme/schemas` | Replaced by `@react-pdf/renderer`. |
|
||
|
||
### STAYS UNTOUCHED
|
||
|
||
- `src/lib/pdf/fill-eoi-form.ts` (pdf-lib AcroForm fill on `assets/eoi-template.pdf`) — the in-app EOI pathway.
|
||
- `src/lib/services/berth-pdf-parser.ts` tier-1 (pdf-lib AcroForm read) and tier-3 (AI fallback). Tier-2 (Tesseract OCR) gets `unpdf` for PDF→image rasterization.
|
||
- `pdf-lib` dep (still needed by `fill-eoi-form.ts` and `berth-pdf-parser.ts`).
|
||
- All Documenso integration code.
|
||
|
||
## Architecture
|
||
|
||
Three orthogonal PDF paths post-migration, each with a single owner:
|
||
|
||
```
|
||
┌──────────────────────────┐ ┌──────────────────────────┐ ┌────────────────────────┐
|
||
│ react-pdf (this phase) │ │ pdf-lib AcroForm fill │ │ Documenso (external) │
|
||
│ Internal only │ │ Standardized + signing │ │ Client-facing signed │
|
||
│ │ │ │ │ docs │
|
||
│ • Reports (×4) │ │ • In-app EOI │ │ │
|
||
│ • Expenses │ │ • Future admin-upload │ │ (handled outside our │
|
||
│ • Record exports (×3) │ │ invoice templates │ │ system) │
|
||
│ • Future internal lists │ │ (deferred) │ │ │
|
||
└────────────┬─────────────┘ └────────────┬─────────────┘ └────────────────────────┘
|
||
│ │
|
||
▼ ▼
|
||
src/lib/pdf/render.ts src/lib/pdf/fill-eoi-form.ts
|
||
(renderToBuffer + (unchanged this phase)
|
||
renderToStream)
|
||
│
|
||
▼
|
||
src/lib/pdf/brand-kit/
|
||
├─ DocumentShell.tsx
|
||
├─ Header.tsx
|
||
├─ Footer.tsx
|
||
├─ DataTable.tsx
|
||
├─ KeyValueGrid.tsx
|
||
├─ Section.tsx
|
||
├─ Badge.tsx
|
||
├─ charts/{Bar,Line,Pie,Funnel}Chart.tsx
|
||
├─ tokens.ts
|
||
└─ logo.ts
|
||
```
|
||
|
||
### Module boundaries
|
||
|
||
- **`brand-kit/`** — pure presentation primitives. No DB access, no CRM domain knowledge. Each component has typed props and renders react-pdf elements.
|
||
- **`templates/`** — one `.tsx` per document type. Imports brand-kit primitives + receives typed data props. No DB access; data fetching stays in the calling service.
|
||
- **`render.ts`** — the only module that touches `@react-pdf/renderer`'s `renderToBuffer` / `renderToStream`. Services call `renderPdf(<MyTemplate {...data} />)` or `renderPdfStream(<MyTemplate {...data} />)`.
|
||
- **`logo.ts`** — `resolvePortLogo(portId)` reads `system_settings.port_logo_file_id` and returns `{ source, buffer, mimeType }`. Cached per request via React `cache()`.
|
||
- **Chart rendering** — pure SVG components emitting react-pdf's native `<Svg>` primitive. No JSDOM, no headless Chrome, no canvas. Server-rendered like any other PDF component.
|
||
- **Photo embedding** (expense PDFs) — `sharp` (existing dep) compresses each receipt to ~150KB JPEG before embed. Stream-renders pages so memory stays bounded with hundreds of entries.
|
||
|
||
### Header layout constraint
|
||
|
||
The brand-kit `<Header>` reserves a fixed logo slot:
|
||
|
||
```
|
||
maxWidth: 200 (≈ 56mm)
|
||
maxHeight: 60 (≈ 17mm)
|
||
objectFit: contain // letterbox, never stretch
|
||
align: left, vertically centered within the dark header band
|
||
fallback: when resolvePortLogo returns 'fallback', render <Text style={bold}>{port.name}</Text>
|
||
at the same slot. The port-name + doc-title combination keeps the header visually balanced.
|
||
```
|
||
|
||
This is enforced inside `<Header>`, not at upload time, so the upload pipeline can accept any 200-1200px logo and trust the layout to letterbox correctly.
|
||
|
||
### Brand kit tokens
|
||
|
||
```ts
|
||
// src/lib/pdf/brand-kit/tokens.ts
|
||
export const PDF_TOKENS = {
|
||
colors: {
|
||
text: '#111111',
|
||
textMuted: '#666666',
|
||
border: '#e5e7eb',
|
||
headerBand: '#0f172a', // dark slate — matches CRM sidebar
|
||
headerText: '#ffffff',
|
||
accentBlue: '#1d4ed8',
|
||
zebra: '#f9fafb',
|
||
success: '#16a34a',
|
||
warning: '#d97706',
|
||
danger: '#dc2626',
|
||
},
|
||
fonts: {
|
||
sans: 'Helvetica',
|
||
sansBold: 'Helvetica-Bold',
|
||
mono: 'Courier',
|
||
},
|
||
sizes: {
|
||
docTitle: 18,
|
||
sectionH: 13,
|
||
body: 10,
|
||
small: 8,
|
||
caption: 7,
|
||
},
|
||
spacing: {
|
||
pagePadding: 36,
|
||
sectionGap: 18,
|
||
rowGap: 6,
|
||
},
|
||
} as const;
|
||
```
|
||
|
||
Single source of truth. Future design pass = edit this file, every PDF updates.
|
||
|
||
## Logo handling
|
||
|
||
### Layer 1 — Server-side sharp normalization (required)
|
||
|
||
```
|
||
upload → magic-byte check via sharp metadata (PNG | JPEG | WEBP | SVG | HEIC | HEIF | AVIF)
|
||
→ reject animated GIF / multi-frame PNG / multi-page TIFF
|
||
→ size cap 5MB raw
|
||
→ if SVG:
|
||
sanitize first via svgo (strip <script>, on*=, <foreignObject>, external href)
|
||
reject if sanitization removed dangerous nodes
|
||
rasterize to PNG via sharp(buf, { density: 300 }) // 300 DPI from vector
|
||
→ standard pipeline:
|
||
sharp(buf)
|
||
.extract({ left: cropX, top: cropY, width: cropW, height: cropH }) ← from client crop
|
||
.trim({ threshold: 10 })
|
||
.resize({ width: 1200, height: 1200, fit: 'inside', withoutEnlargement: true })
|
||
.toColorspace('srgb')
|
||
.removeAlpha()-if-jpeg-source-and-near-white
|
||
.png({ compressionLevel: 9, palette: true }) ← palette where possible for smaller files
|
||
.toBuffer()
|
||
→ reject if final > 1MB
|
||
→ reject if min dimension after trim < 200px
|
||
→ store via getStorageBackend().put()
|
||
→ set system_settings.port_logo_file_id = files.id (atomic upsert)
|
||
→ soft-archive previous logo's files row (archivedAt = now)
|
||
→ write audit_logs entry: action=branding.logo.uploaded, by=user.id
|
||
→ collect warnings: [trimmed, resized, noAlpha, jpegSource, svgRasterized, heicConverted]
|
||
```
|
||
|
||
**Why rasterize SVGs to PNG at upload time:** react-pdf's `<Svg>` primitive supports a subset of SVG (Path, Rect, Circle, Line, Text, gradients, clip-paths) but not filters, animations, embedded fonts, or all the quirks of a designer-exported SVG. Sharp rasterizes via librsvg at 300 DPI on upload, eliminating runtime surprises. Single PNG to embed at render time. The vector source is captured-in-time; if the admin later needs higher resolution, they re-upload.
|
||
|
||
**Why HEIC/AVIF support:** iPhone photo exports default to HEIC; common admin pain point. Sharp handles both natively via libheif; converts to PNG in the pipeline. Less common but worth supporting.
|
||
|
||
### Layer 2 — Live upload UI
|
||
|
||
Admin opens **Port Settings → Branding → Logo**. The dialog shows:
|
||
|
||
1. **Rules above the dropzone:**
|
||
- Use PNG or SVG with a transparent background
|
||
- Minimum 200×200px; recommended 600×200px (wide) or 400×400px (square)
|
||
- Max 5MB; we'll auto-trim and optimize
|
||
- Avoid JPEGs unless the background is solid white
|
||
|
||
2. **`react-image-crop` cropper** with aspect-ratio toggle (Wide 3:1 / Square 1:1 / Freeform).
|
||
|
||
3. **Live HTML preview** rendering the actual brand-kit `<Header>` React component beside the cropper, with the user's logo. Two preview swatches: dark header band (where the logo actually appears) and a colored background (to spot the "white box" problem with non-transparent JPEGs).
|
||
|
||
4. **Post-upload warnings** displayed in the preview:
|
||
- "JPEG with no alpha channel — white background will show on dark headers"
|
||
- "Logo trimmed to remove whitespace borders"
|
||
- "Resized from 4000×4000 to 1200×1200"
|
||
|
||
5. **"Test with sample PDF" button** — hits a sample-PDF endpoint that renders a minimal report header and streams it back. Browser opens in a new tab.
|
||
|
||
### Layer 3 — `react-image-crop` integration
|
||
|
||
Client renders the original image inside `react-image-crop` with a constrained aspect ratio. On save:
|
||
|
||
1. Client sends `multipart/form-data` with `file` + `{ cropX, cropY, cropW, cropH }` JSON sidecar.
|
||
2. Server runs the sharp pipeline above with the crop applied as the first step.
|
||
|
||
This keeps sharp as the single source of truth (no canvas-tainted-CORS issues client-side; the actual crop happens server-side using the user-provided coordinates).
|
||
|
||
### Storage path
|
||
|
||
Logos use the existing pluggable storage backend (`src/lib/storage/`). Object key shape:
|
||
|
||
```
|
||
ports/{portId}/branding/logo-{uuid}.png
|
||
```
|
||
|
||
The same backend currently serves brochures, berth PDFs, gdpr exports, etc. — `s3` for prod, `filesystem` for single-node dev. Logos inherit whatever's configured; no special routing. Trivial-image-inline-in-DB would save one S3 round-trip per PDF render but break consistency with every other file artifact; not worth it.
|
||
|
||
### Permission gating
|
||
|
||
The upload endpoint is wrapped with `withAuth(withPermission('port_settings', 'manage', …))` (same gate currently used for brochures admin, send-from accounts, etc.). Audit trail goes to `audit_logs` (`action: branding.logo.uploaded`, `entityType: port`, `entityId: portId`). Soft-archive of the prior logo file row is logged as `branding.logo.archived`.
|
||
|
||
### Resolution at render time
|
||
|
||
```ts
|
||
// src/lib/pdf/brand-kit/logo.ts
|
||
export const resolvePortLogo = cache(
|
||
async (
|
||
portId: string,
|
||
): Promise<{
|
||
source: 'logo' | 'fallback';
|
||
buffer: Buffer | null;
|
||
mimeType: 'image/png' | 'image/svg+xml' | null;
|
||
}> => {
|
||
const setting = await getSystemSetting(portId, 'port_logo_file_id');
|
||
if (!setting) return { source: 'fallback', buffer: null, mimeType: null };
|
||
const file = await db.query.files.findFirst({ where: eq(files.id, setting) });
|
||
if (!file || file.archivedAt) return { source: 'fallback', buffer: null, mimeType: null };
|
||
const backend = await getStorageBackend();
|
||
const buffer = await backend.get(file.storageKey);
|
||
return { source: 'logo', buffer, mimeType: file.mimeType as 'image/png' | 'image/svg+xml' };
|
||
},
|
||
);
|
||
```
|
||
|
||
Brand-kit `<DocumentShell>` internally calls this and passes the buffer down through context. Every template that wraps in `<DocumentShell port={port}>...</DocumentShell>` gets the logo automatically. No per-template wiring. When no logo is set, the header renders the port name as bold text instead.
|
||
|
||
## Per-template designs
|
||
|
||
### Reports — shared shell
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ [LOGO] PORT NAME REPORT TITLE │
|
||
│ generated 2026-05-12 18:44 Date-range badge │
|
||
├──────────────────────────────────────────────────────────────────┤
|
||
│ Summary cards (3-4 KPI stat boxes) │
|
||
│ ┌──────┬──────┬──────┐ │
|
||
│ │
|
||
│ ◌ CHART (full-width SVG) │
|
||
│ │
|
||
│ Detail Table (zebra rows, columns vary per report) │
|
||
├──────────────────────────────────────────────────────────────────┤
|
||
│ Port Name · Confidential · Page 1 of 3 · Generated … │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
| Report | Summary stat cards | Chart | Detail table columns |
|
||
| --------- | ---------------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------- |
|
||
| Activity | total events, top action, top user, busiest day | Stacked bar — events per day by action | date · action · entity type · entity · user |
|
||
| Revenue | total revenue, paid, outstanding, avg invoice | Line — revenue per month + small pie paid/outstanding | invoice # · client · issued · due · amount · status |
|
||
| Pipeline | total interests, win rate, avg cycle days, top stage | Funnel — count per stage | interest · client · stage · lead category · days in stage |
|
||
| Occupancy | total berths, occupied %, available %, under-offer % | Time-series — occupancy % over period + small pie current status | berth # · status · current interest · last change |
|
||
|
||
### Expense PDF
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ [LOGO] PORT NAME — Expense Sheet │
|
||
│ Period: 2026-04-01 → 2026-04-30 · 247 entries │
|
||
├──────────────────────────────────────────────────────────────────┤
|
||
│ Summary cards: total · by category · by status │
|
||
├──────────────────────────────────────────────────────────────────┤
|
||
│ Expense entries (one row per entry, multi-page) │
|
||
│ ┌──┬──────────┬──────────┬────────┬─────────┬─────────┐ │
|
||
│ │# │ Date │ Category │ Vendor │ Amount │ Receipt │ │
|
||
│ │ │ Notes: <inline notes line, optional> │ │
|
||
│ │ │ [receipt photo, max 200×200, ~150KB JPEG] │ │
|
||
│ └──┴──────────┴──────────┴────────┴─────────┴─────────┘ │
|
||
│ Page break inserted between entries when remaining vertical │
|
||
│ space < 200px (no orphan partial rows) │
|
||
├──────────────────────────────────────────────────────────────────┤
|
||
│ Page 1 of 47 · Total: $48,232 · 247 entries │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
Critical: **stream-render via `renderToStream`** because 247 entries × ~150KB photos = 37MB peak memory if all loaded at once. Stream renders one page at a time, freeing buffers as it goes. Each photo passes through `sharp.resize(800, 800, { fit: 'inside' }).jpeg({ quality: 70 })` once and is cached for the lifetime of the request.
|
||
|
||
### Record exports
|
||
|
||
- **Client Summary** — brand shell + key/value grid for client info + table for yachts + table for interests + activity timeline at bottom.
|
||
- **Berth Spec** — brand shell + two-column key/value grid (info / dimensions / pricing / tenure) + infrastructure table + waiting-list table + maintenance-log table.
|
||
- **Interest Summary** — brand shell + stage badge in header + key/value grids for client/yacht/berth + notes block + activity timeline.
|
||
|
||
## Data flow
|
||
|
||
### Caller migration pattern
|
||
|
||
Before:
|
||
|
||
```ts
|
||
import { generatePdf } from '@/lib/pdf/generate';
|
||
import {
|
||
activityReportTemplate,
|
||
buildActivityInputs,
|
||
} from '@/lib/pdf/templates/reports/activity-report';
|
||
const inputs = buildActivityInputs(data, port.name);
|
||
const pdfBytes = await generatePdf(activityReportTemplate, inputs);
|
||
```
|
||
|
||
After:
|
||
|
||
```ts
|
||
import { renderPdf } from '@/lib/pdf/render';
|
||
import { ActivityReportPdf } from '@/lib/pdf/templates/reports/activity-report';
|
||
const pdfBytes = await renderPdf(<ActivityReportPdf port={port} data={data} />);
|
||
```
|
||
|
||
### Render module
|
||
|
||
```ts
|
||
// src/lib/pdf/render.ts
|
||
import { renderToBuffer, renderToStream } from '@react-pdf/renderer';
|
||
import type { ReactElement } from 'react';
|
||
import { logger } from '@/lib/logger';
|
||
|
||
export async function renderPdf(element: ReactElement): Promise<Buffer> {
|
||
try {
|
||
return await renderToBuffer(element);
|
||
} catch (err) {
|
||
logger.error({ err }, 'PDF render failed');
|
||
throw new Error('Failed to render PDF');
|
||
}
|
||
}
|
||
|
||
export async function renderPdfStream(element: ReactElement): Promise<NodeJS.ReadableStream> {
|
||
return renderToStream(element);
|
||
}
|
||
```
|
||
|
||
### Chart rendering (sketch)
|
||
|
||
```tsx
|
||
// src/lib/pdf/brand-kit/charts/BarChart.tsx
|
||
import { Svg, Line, Rect, Text as SvgText } from '@react-pdf/renderer';
|
||
import { PDF_TOKENS } from '../tokens';
|
||
|
||
export function BarChart({
|
||
data,
|
||
width = 480,
|
||
height = 200,
|
||
color = PDF_TOKENS.colors.accentBlue,
|
||
}) {
|
||
const max = Math.max(...data.map((d) => d.value));
|
||
const barW = (width - 60) / data.length;
|
||
return (
|
||
<Svg width={width} height={height}>
|
||
<Line
|
||
x1={40}
|
||
y1={20}
|
||
x2={40}
|
||
y2={height - 30}
|
||
strokeWidth={1}
|
||
stroke={PDF_TOKENS.colors.border}
|
||
/>
|
||
<Line
|
||
x1={40}
|
||
y1={height - 30}
|
||
x2={width - 10}
|
||
y2={height - 30}
|
||
strokeWidth={1}
|
||
stroke={PDF_TOKENS.colors.border}
|
||
/>
|
||
{data.map((d, i) => {
|
||
const h = (d.value / max) * (height - 60);
|
||
return (
|
||
<Rect
|
||
key={i}
|
||
x={50 + i * barW}
|
||
y={height - 30 - h}
|
||
width={barW - 4}
|
||
height={h}
|
||
fill={color}
|
||
/>
|
||
);
|
||
})}
|
||
{data.map((d, i) => (
|
||
<SvgText
|
||
key={i}
|
||
x={50 + i * barW + (barW - 4) / 2}
|
||
y={height - 14}
|
||
textAnchor="middle"
|
||
fontSize={7}
|
||
>
|
||
{d.label}
|
||
</SvgText>
|
||
))}
|
||
</Svg>
|
||
);
|
||
}
|
||
```
|
||
|
||
Same pattern for LineChart / PieChart / FunnelChart. ~60-100 lines each.
|
||
|
||
## Error handling
|
||
|
||
| Failure mode | Detection | Surface |
|
||
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| Logo file missing at render time | `resolvePortLogo` returns `source: 'fallback'` | Header renders port-name text only; structured log warning. |
|
||
| Logo file corrupt | `sharp` throws on load | 500 via `errorResponse(InternalError)`; structured log; admin sees "Logo file is unreadable, please re-upload." |
|
||
| Chart data empty | Component prop validation in template | Render "No data for selected period" placeholder; no crash. |
|
||
| Receipt photo missing (expense PDF) | Storage backend `get` throws | Skip photo for that entry; render "Receipt unavailable" placeholder text; continue; collect into `warnings[]` and log. |
|
||
| Receipt photo unprocessable by sharp | `sharp` throws on resize | Same as above. |
|
||
| Stream-render aborted mid-page | `renderToStream` rejects | Caller drains stream into try/catch; surface `errorResponse(error)`; partial bytes not stored. |
|
||
| OOM on huge expense PDF | Heap monitor | Stream-render keeps peak bounded; cap entries at 1000 per PDF; prompt admin to split into multiple periods. |
|
||
| Sharp pipeline rejects upload | Specific error code | 422 `ValidationError` with the rejection reason ("file > 5MB", "dimension < 200px", "unsupported format: GIF animated"). |
|
||
| SVG with embedded JS or external href | `svgo` strips scripts; post-sanitize node-count check | Reject with `ValidationError('SVG contained disallowed nodes')`. |
|
||
| Concurrent logo uploads (admin clicks save twice / two browser tabs) | Last-writer-wins via atomic `system_settings` upsert | Both `files` rows persist; only newer is pointed at. Soft-archive doesn't race because it operates on the OLD setting's file_id captured before the upsert. |
|
||
| Mid-render logo upload | `resolvePortLogo` reads at render-start | In-flight PDF uses whichever logo was current when the request entered. Next request gets the new one. No mid-PDF logo swap. |
|
||
| Logo dimensions wildly off the header aspect ratio | Brand-kit `<Header>` constrains logo to `maxWidth: 200, maxHeight: 60` with `objectFit: contain` | Logo letterboxes inside its slot; never distorts. |
|
||
| Cropper coords out of bounds | Server-side validation against image metadata before sharp extract | 422 `ValidationError('Crop coordinates out of image bounds')`. |
|
||
| File mime header lies (claims PNG, bytes are HTML) | Sharp's `metadata()` reads actual magic bytes, ignores declared mime | Sharp throws → 422 `ValidationError('File contents do not match a supported image format')`. |
|
||
| Storage backend `put` fails (network glitch) | Catch around `backend.put` | Roll back: do not insert files row, do not change system_settings; return 503 with retry hint. |
|
||
| `port_logo_file_id` setting points at archived/deleted file | `resolvePortLogo` checks `archivedAt` | Treat as missing; fall back to text header; structured log warning so ops notices. |
|
||
|
||
## Testing
|
||
|
||
### Unit (vitest)
|
||
|
||
- `brand-kit/charts/*.test.tsx` — snapshot SVG output for known inputs.
|
||
- `brand-kit/logo.test.ts` — `resolvePortLogo` with fixtures for: configured / missing / archived / corrupt.
|
||
- `pdf/render.test.ts` — round-trip a tiny `<Page>` and verify the output starts with `%PDF-`.
|
||
- `services/logo-upload.test.ts` — sharp pipeline for: PNG-with-alpha (passes) / JPEG (warning) / undersized (rejects) / oversized (resizes) / SVG (passthrough) / animated GIF (rejects) / SVG with script tag (rejects).
|
||
|
||
### Integration (vitest)
|
||
|
||
- Each template renders to bytes without throwing, given representative fixtures from seed data.
|
||
- `reports.service.test.ts` — generate each of the 4 reports for a seeded port; assert PDF magic byte + non-zero length.
|
||
- `record-export.test.ts` — generate client / berth / interest summaries for seeded entities.
|
||
- `expense-export.test.ts` — generate expense PDF for 250 seeded entries; assert pages > 5; assert peak heap delta < 200MB (proxy for stream-render working).
|
||
|
||
### Playwright (smoke)
|
||
|
||
- New spec: `branding-logo-upload.spec.ts` — upload PNG, see preview, save, generate sample PDF, assert PDF downloads.
|
||
- New spec: `reports-pdf-export.spec.ts` — for each of the 4 reports, click export, assert PDF downloads.
|
||
- Existing specs: anywhere clicking "export PDF" was tied to pdfme, update assertion.
|
||
|
||
### Visual regression (existing visual project)
|
||
|
||
- 4 new baselines (one per report) using seed port's logo.
|
||
- 3 new baselines (client / berth / interest summary).
|
||
- 1 new baseline (expense PDF, first 2 pages).
|
||
- Snapshots stored as PNG (rendered from PDF via first-page extraction).
|
||
|
||
## Migration sequence
|
||
|
||
| # | Commit | Files touched | Verifies |
|
||
| --- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
|
||
| 1 | Foundation: install deps + brand kit | +`@react-pdf/renderer`, +`unpdf`, +`react-image-crop`, +`svgo`; new `src/lib/pdf/brand-kit/*`, `src/lib/pdf/render.ts` | brand kit unit tests pass; nothing wired yet |
|
||
| 2 | Logo upload feature | new `src/lib/services/logo.service.ts`, `src/app/api/v1/admin/branding/logo/*`, admin UI in port settings, `system_settings.port_logo_file_id` key | upload + preview + sample-PDF test work in dev |
|
||
| 3 | Migrate activity report | port `activity-report.ts` → `activity-report.tsx`; rewire `reports.service.ts` caller; visual baseline | report exports work; visual diff approved |
|
||
| 4 | Migrate revenue report | same shape | same |
|
||
| 5 | Migrate pipeline report | same shape | same |
|
||
| 6 | Migrate occupancy report | same shape | same |
|
||
| 7 | Migrate client summary | port `client-summary-template.ts` → `.tsx`; rewire `record-export.ts` | same |
|
||
| 8 | Migrate berth spec | same | same |
|
||
| 9 | Migrate interest summary | same | same |
|
||
| 10 | Migrate expense PDF | port `expense-pdf.service.ts` to react-pdf streaming; sharp photo compression | 250-entry seed test passes |
|
||
| 11 | Remove invoice PDF generation | delete `invoice-template.ts`, the `generatePdf` call in `invoices.ts`, the API route `/api/v1/invoices/[id]/generate-pdf`; remove UI link | invoice list still works minus PDF button |
|
||
| 12 | Remove TipTap-→-pdfme bridge | delete `tiptap-to-pdfme.ts`, the preview route, the `generatePdf` block in `document-templates.ts:516`, the `getStandardEoiTemplateHtml` seed reference | admin template editor still saves; preview removed |
|
||
| 13 | Add unpdf to berth parser tier-2 | wire `unpdf` into `berth-pdf-parser.ts` for PDF→image rasterization; keep tesseract.js | berth PDF upload still parses |
|
||
| 14 | Cleanup: drop pdfme deps | remove `@pdfme/common`, `@pdfme/generator`, `@pdfme/schemas` from package.json; delete `generate.ts`, `eoi-standard-inapp.ts`; clean up unused validators | `pnpm install` clean; no remaining imports |
|
||
|
||
Total: 14 commits. Most are small (5-15 file diffs). Commits 2, 10, and 12 are the heaviest. Vitest + tsc stay green throughout; each commit only flips behavior after its tests pass.
|
||
|
||
## Deferred (added to BACKLOG)
|
||
|
||
- Admin-uploaded PDF templates with AcroForm-fill (the invoice template-fill pattern). Needs: new `pdf_templates` table + field-mapping editor + admin upload UI + generalized `fillAcroForm()` utility. Likely ~1 week solo.
|
||
- Port brand color tokens (admin sets brand color → flows into PDF accent color). ~2h.
|
||
- Per-template logo override (different logo for invoices vs reports). YAGNI unless asked.
|
||
- Optical receipt-photo rotation/deskew (auto-rotate phone-upload receipts to readable orientation). ~half day.
|
||
- Replace tesseract.js with cloud OCR (AWS Textract / Google Vision) for berth parsing tier-2. Out of scope.
|
||
|
||
## Open questions
|
||
|
||
None blocking. Implementation can begin after user spec review.
|