make_post_sell/docs/notifications.md

# MPS Notification System

Every transactional email in MPS now pairs with an in-app notification
row in `mps_notification`. The user has a permanent inbox even if they
never opened the email, and the navbar surfaces an unread count badge.

## Data Model

`MpsNotification` (`mps_notification`, migration
`5d01b163b805`):

| Column | Type | Notes |
|---|---|---|
| `id` | UUID | primary key |
| `user_id` | UUID | recipient (FK `mps_user.id`) |
| `shop_id` | UUID nullable | shop this is about (FK `mps_shop.id`) |
| `kind` | string(64) | discriminator — see kinds below |
| `subject` | string(256) | one-line headline |
| `body` | text | denormalized snippet (survives source deletion) |
| `link_url` | string(512) | primary click-through |
| `offer_id` | UUID nullable | breadcrumb FK |
| `auction_id` | UUID nullable | breadcrumb FK |
| `invoice_id` | UUID nullable | breadcrumb FK |
| `created_timestamp` | bigint | ms |
| `updated_timestamp` | bigint | ms |
| `read` | bool, default `False` | drives the unread badge |
| `read_timestamp` | bigint nullable | when dismissed |

Composite index on `(user_id, read, created_timestamp)` for cheap
unread-count queries.

## Kinds

Defined in `make_post_sell/models/notification.py` (stable strings —
templates and tests assume them). Every kind has matching email logic
in `lib/mail.py`; the notification persist lives in `lib/notifications.py`.

| Kind | Trigger | Recipient(s) | Source FKs |
|---|---|---|---|
| `offer_received` | buyer opens offer (PENDING) | shop owners | `offer_id` |
| `offer_accepted` | auto-accept / seller-accept | buyer | `offer_id` |
| `offer_countered` | either party counters | the other party | `offer_id` |
| `offer_declined` | seller manually declines | buyer | `offer_id` |
| `offer_withdrawn` | buyer withdraws pre-accept | shop owners | `offer_id` |
| `offer_buyer_cancelled` | buyer cancels post-accept | shop owners | `offer_id` |
| `offer_expired` | offer_tick → EXPIRED | buyer + shop owners | `offer_id` |
| `purchase` | cart pays | buyer | `invoice_id` |
| `sale` | cart pays | shop owners | `invoice_id` |
| `auction_outbid` | new bid bumps prior leader | prior bidder | `auction_id` |
| `auction_won` | auction_tick → ENDED + winner | winner | `auction_id` |
| `auction_ended_no_winner` | auction_tick → ENDED, no winner | shop owners | `auction_id` |
| `auction_cancelled` | reserved (no call site yet) | bidders + watchers | `auction_id` |

## Breadcrumbs

`MpsNotification.breadcrumbs` returns an ordered `[(label, url)]`
walk back from the notification to its source:

  Shop → Product → (Offer | Auction | Invoice)

The template iterates this for the breadcrumb chain under each row.
Each step is optional — only entities whose FK is set get rendered.

For offer/auction kinds the product comes from `offer.product` /
`auction.product`. For purchase/sale kinds it comes from the first
invoice line item.

## Wiring

**Orchestration:** `make_post_sell/lib/notifications.py` exports one
helper per event class. Each helper accepts either a Pyramid request
*or* a SQLAlchemy session — `_resolve_session()` extracts the right
one, so the same orchestrator works in views and in tick jobs.

**Offer transitions** drop their notifications inline in
`views/offer.py` (alongside the existing `send_offer_*_email` sends).
Each handler snapshots state pre-action, runs the action, and only
emits on the actual transition.

**Cart completion** drops `purchase` + `sale` rows from every
checkout completion path:

  - `views/cart.py` ×3 (Stripe / PayPal-create / Adyen)
  - `views/webhooks.py` ×4 (PayPal capture, approved, Stripe, Adyen)
  - `lib/crypto_watcher/__init__.py` ×3 (Monero, Dogecoin,
    confirmed-duplicate path) — gated on
    `crypto_payment.sales_email_sent` so a rescan can't
    write duplicates.

**Auction transitions** in `lib/auction_tick.py`:

  - ACTIVE → ENDED with winner → `notify_auction_won`
  - ACTIVE → ENDED without winner → `notify_auction_ended_no_winner`
  - bid placement bumps prior leader → `notify_auction_outbid`
    (in `views/auction.py`)

**Offer auto-expiry** in `lib/offer_tick.py` calls
`notify_offer_expired` for both pre-accept and post-accept windows.

## UI

- **Badge** (`templates/base.j2` + `request.unread_notification_count`,
  reified): pill next to the profile name in the navbar. Same pill
  appears on the `/u/settings` "Notifications" button.
- **List** at `/u/notifications` (`templates/user_notifications.j2`):
  newest first, kind label + relative time + subject + body +
  breadcrumb nav. Unread rows carry an `alert-info-bg` left-border
  accent; **read rows stay in the list** but fade to `opacity: 0.65`
  so the unread set visually dominates.
- **Mark-read endpoints**:
  - `POST /u/notifications/{id}/read` — single row
  - `POST /u/notifications/read-all` — bulk-dismiss all unread

## Read semantics (important)

Marking a notification read **does not delete it**. The row stays in
the DB and stays in the list, just less prominent. The unread *count*
drops because `count_unread_notifications` filters
`read == False`. This was explicit feedback from fox: users want a
permanent audit log of every event, not a self-emptying inbox.

## Non-fatal by design

Every notification persist is wrapped in `_safe_add` — if the DB
write fails the exception is logged but the HTTP response (and the
corresponding email send) is not interrupted. The same pattern applies
to the email-side `_safe_email` wrapper. Notification persist and
email send are now **independent**: an SMTP outage cannot block
notification creation (and vice versa).