pdf-invoicing-snapshots

name	pdf-invoicing-snapshots
description	Use this skill when you work on invoices or PDFs draft→finalize, immutable invoice snapshots, numbering, and PDF rendering/export.

Invoice Finalization & PDF Skill

Use this skill for invoice creation, finalization, snapshots, and PDF export.

Rules

• Draft invoices are editable. Finalization creates immutable snapshot and locks edits.
• Snapshot must include: seller/workspace details, client details, line items (qty, unit price, tax), totals, currency, locale, template version, render hash (if cached).
• Finalized PDFs must render from snapshot only. Draft preview can render live state.
• Numbering: unique per workspace, generated at finalization.

Workflow (finalize)

1. Guard: derive tenant/workspace server-side (via your tenant guard helper) and scope invoice to workspace_id (or your equivalent tenant column).
2. Compute/assign next invoice number (workspace-scoped).
3. Build snapshot JSON from current invoice + items + client/workspace data.
4. Persist snapshot in invoice_snapshots tied to invoice_id.
5. Mark invoice status issued (or finalized), set finalizedAt.
6. Revalidate invoice list/detail paths.

PDF route handler

• Your PDF export endpoint (often a Route Handler, e.g., GET /api/invoices/[id]/pdf) should authorize by tenant/workspace, then:
  • If draft: render from current invoice state.
  • If finalized: render from snapshot only.
• Mark route dynamic = "force-dynamic" if needed.

Cost & performance notes

• Snapshots are not only correctness—they reduce render-time DB work. Prefer rendering finalized PDFs from a single snapshot read.
• Consider storing a deterministic render_hash (snapshot + template version) to enable safe caching later.
• Stream PDFs and avoid loading/serializing unnecessary related data (client/workspace details should already be inside the snapshot).

For broader caching/invalidation guidance: nextjs-cost-performance skill

Money/time rules

• Store amounts in integer cents; include currency code.
• Store timestamps UTC; format per locale/timezone at render.

Edge cases

• Do not mutate snapshot after finalization; create new draft for changes.
• Handle missing snapshot gracefully (but should not occur after finalize).
• Ensure totals recompute before snapshot to avoid stale values.

Testing

• Add tests for: snapshot immutability, correct totals, numbering uniqueness per workspace, PDF stability after data changes.

References

• Product spec: your PRD/spec doc (if present)
• DB schema: your schema module(s)
• PDF endpoint: your PDF export route/handler