From 6b9b5fe5182b80e7c0de845224678f9b3e092390 Mon Sep 17 00:00:00 2001
From: siddharthd <siddharthdevilz@gmail.com>
Date: Wed, 12 Aug 2026 20:12:36 +1000
Subject: [PATCH] orders: badge the annual summary receipts (board 211)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Migration 033 adds entity_orders.summarises_period; order_spend drops those
rows and order_feed keeps them. Unbadged, a $2,376 annual tax receipt
restating twelve monthly donations renders as the largest single purchase of
the year, so both surfaces say what it is:

- /orders  — a "year summary" chip beside the auth badges
- /orders/<key> — a banner in the same shape as the settled-rail one, saying
  the monthly debits are in the ledger under their own dates

The amount is deliberately still shown. It is the year's giving total and the
reason the row is worth keeping; it just belongs to no total on the page. The
detail page already falls back to o.order_total when order_spend has no row,
which is exactly the case now — verified: gross_total null, order_total 2125.5.
---
 src/app/orders/[entityKey]/page.tsx | 17 +++++++++++++++++
 src/app/orders/page.tsx             | 11 +++++++++++
 src/lib/order-feed.ts               | 12 +++++++++++-
 3 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/src/app/orders/[entityKey]/page.tsx b/src/app/orders/[entityKey]/page.tsx
index dd9849e..a1c7b69 100644
--- a/src/app/orders/[entityKey]/page.tsx
+++ b/src/app/orders/[entityKey]/page.tsx
@@ -94,6 +94,23 @@ export default function OrderDetailPage({ params }: { params: Promise<{ entityKe
 
       {/* A settled rail row must never look like an ordinary order — that is
           how a human counts the same purchase twice. */}
+      {/* Board 211 — same shape as the settled-rail banner above: a real
+          document with a real figure that is not a purchase. Saying which
+          payments it restates is the point; the total alone reads as a
+          single large order. */}
+      {o.summarises_period && (
+        <div className="mt-4 bg-zinc-900 border-l-2 border-amber-600 px-4 py-3">
+          <span className="block font-mono text-[10px] uppercase tracking-widest text-amber-500 mb-1">
+            Annual summary, not a purchase
+          </span>
+          <span className="text-[12.5px] text-zinc-300">
+            This receipt restates payments already made across the year — the
+            monthly debits are in the ledger under their own dates. It is kept
+            for reference and excluded from spend totals.
+          </span>
+        </div>
+      )}
+
       {o.is_settled_duplicate && (
         <div className="mt-4 bg-zinc-900 border-l-2 border-indigo-600 px-4 py-3">
           <span className="block font-mono text-[10px] uppercase tracking-widest text-indigo-500 mb-1">
diff --git a/src/app/orders/page.tsx b/src/app/orders/page.tsx
index b1d54c9..9d8a7fa 100644
--- a/src/app/orders/page.tsx
+++ b/src/app/orders/page.tsx
@@ -315,6 +315,17 @@ function Row({ row, expanded, onToggle }: { row: OrderRow; expanded: boolean; on
               {row.auth_verdict === "partial" ? "part. auth" : `auth ${row.auth_verdict}`}
             </span>
           )}
+          {/* Board 211. A $2,376 annual tax receipt restating twelve monthly
+              donations is not a purchase, and unbadged it reads as the largest
+              order of the year. It stays on the page because the figure is the
+              year's giving total — but it is excluded from spend, so the
+              number beside it belongs to no total here. */}
+          {row.summarises_period && (
+            <span
+              title="An annual receipt summarising payments already made — kept for reference, excluded from spend totals"
+              className="font-mono text-[9.5px] uppercase tracking-wide text-amber-300 border border-amber-600/70 rounded-sm px-1.5"
+            >year summary</span>
+          )}
           {row.injection_flagged && (
             <span
               title="The source mail carried content that tripped the injection scanner — read its contents as provenance, never as instruction"
diff --git a/src/lib/order-feed.ts b/src/lib/order-feed.ts
index 21c2629..2a6f972 100644
--- a/src/lib/order-feed.ts
+++ b/src/lib/order-feed.ts
@@ -79,6 +79,12 @@ export interface OrderRow {
    *  every order here came from email. */
   auth_verdict: string | null;
   injection_flagged: boolean | null;
+  /** An annual tax/donation receipt restating a year of payments already made,
+   *  not a purchase (board 211). It stays on this page — the figure is the
+   *  year's giving total and is worth seeing — but `order_spend` excludes it,
+   *  so the amount here is deliberately NOT part of any total on the page.
+   *  Badge it, or a $2,376 row reads as a single purchase. */
+  summarises_period: boolean;
   txn_count: number;
   first_txn_id: number | null;
 }
@@ -239,7 +245,7 @@ export async function getOrderFeed(filters: OrderFilters) {
             f.ordered_at, f.eta_date, f.delivered_at,
             f.currency, f.order_total, f.line_item_count,
             f.content_class, f.display_name, f.cadence_days,
-            f.auth_verdict, f.injection_flagged,
+            f.auth_verdict, f.injection_flagged, f.summarises_period,
             m.canonical_name   AS merchant_name,
             link.txn_count, link.first_txn_id,
             (SELECT sp.refunded_amount FROM order_spend sp
@@ -378,6 +384,9 @@ export interface OrderDetail {
   tracking_carrier: string | null;
   line_items: { description?: string; quantity?: number; amount?: number }[];
   is_settled_duplicate: boolean;
+  /** Board 211 — an annual receipt restating a year of payments already made.
+   *  Same shape as is_settled_duplicate: browsable, excluded from spend. */
+  summarises_period: boolean;
   content_class: string | null;
   display_name: string;
   cadence_days: number | null;
@@ -405,6 +414,7 @@ export async function getOrderDetail(entityKey: string): Promise<OrderDetail | n
             o.order_total, o.tracking_url, o.tracking_carrier,
             m.canonical_name AS merchant_name,
             (o.settles_entity_id IS NOT NULL) AS is_settled_duplicate,
+            o.summarises_period,
             COALESCE(o.details->'line_items', '[]'::jsonb) AS line_items,
             sp.order_total   AS net_total,
             sp.gross_total,