Deal detail page redesign

Replace the slide-out modal with a full-page deal detail view at /admin/queue/$dealId. Unify timeline + pipeline trail into one strip; promote the per-item view to a top-level Items section; add a VCC Appraisal card backed by the /api/Appraisal/appraisal-contents endpoint; move per-stage logs into a unified slide-up drawer with stage-boundary markers.

TL;DRSummary

§1Context

What exists

• web/src/routes/admin.production.queue.tsx — Digital Appraisal Queue list. Row click sets ?run=<uuid>, opens RunDetailSheet.
• web/src/components/queue/RunDetailSheet.tsx — Sheet-based modal with header + PipelineTrail + 4 tabs.
• web/src/components/queue/PipelineTrail.tsx — horizontal clickable stage bubbles. Will be folded into the new timeline.
• web/src/components/queue/tabs/{TimelineTab,IOTab,LogsTab,ErrorTab}.tsx — redundant with each other in places (TimelineTab vs PipelineTrail; LogsTab is per-stage when operators want one stream).
• web/src/components/queue/tabs/io/{Intake,Segmentation,Categorization,Appraisal}IO.tsx — per-stage IO panels. Kept but trimmed (items move out of CategorizationIO).
• web/src/components/queue/Lightbox.tsx — reused unchanged for full-size crop view.
• web/src/lib/api/adapters/deal-detail.ts — existing adaptDealDetail; ItemInfo extended with 9 new appraisal fields.
• backend/src/vcc_backend/features/deals/schemas.py — DealDetailResponse + DealItemBrief. Brief extended with nullable appraisal fields.
• backend/src/vcc_backend/integrations/vcc/client.py:262 — existing get_checked_in_deal as the pattern for the new get_appraisal_contents.
• checkin-pipeline/app/vcc_api.py:69-97 — legacy get_appraisal_contents documents VCC's quirky 500-with-"No Appraisal Found" semantics.
• checkin-pipeline/app/steps/appraise/_shared.py — canonical APPRAISE_SCHEMA; the new per-item brief fields mirror this shape.
• checkin-pipeline/app/templates/appraiser/partials/item_card.html — reference for visual content per item (read-only translation).

What does not exist yet

• No web/src/routes/admin.queue.$dealId.tsx.
• No appraisal_result JSONB column on deal_items. We don't add this yet — defer to sub-project B when the appraisal stage actually runs.
• No GET /admin/queue/deals/{deal_uuid}/appraisal route.
• No VccClient.get_appraisal_contents method.

§2Scope (in / out)

§3Architecture

Route topology

Data sources per page section

Two main page-level queries (detail and appraisal) load independently. Failure or slowness of one never blocks the other. Auto-poll applies to both at 3 s intervals while any stage is running (gated on the detail response's runs array).

Page layout mockup

§4Items grid & card

ItemCard content

Null fields produce no element on the card — no "—" placeholders. The card naturally collapses to category + thumbnail + status when the appraisal stage hasn't run yet.

§5Backend additions

VccClient.get_appraisal_contents

# vcc/client.py — additions

# Returns the JSON payload, or None when VCC reports "No Appraisal Found".
# Raises VccError on any other 4xx/5xx or transport failure.
async def get_appraisal_contents(self, hubspot_deal_id: str) -> dict[str, Any] | None:
    path = f"/api/Appraisal/appraisal-contents/D-{hubspot_deal_id}"
    url = f"{self._base_url}{path}"
    try:
        async with httpx.AsyncClient(timeout=self._timeout) as client:
            resp = await client.get(url, headers=self._headers)
    except httpx.HTTPError as exc:
        raise VccError(f"appraisal-contents transport error: {exc}") from exc

    if resp.status_code == 500:
        # VCC quirk: 500 with "No Appraisal Found" = deal not yet appraised.
        try:
            body = resp.json()
        except ValueError:
            body = {}
        if isinstance(body, dict) and "No Appraisal Found" in (body.get("detail") or ""):
            return None
        raise VccError(f"appraisal-contents 500", status=500, body=resp.text[:500])

    if resp.status_code >= 400:
        raise VccError(
            f"appraisal-contents {resp.status_code}",
            status=resp.status_code,
            body=resp.text[:500],
        )
    data: dict[str, Any] = resp.json()
    return data

Route GET /admin/queue/deals/{deal_uuid}/appraisal

# api/routers/admin.py — additions

@router.get(
    "/queue/deals/{deal_uuid}/appraisal",
    response_model=AppraisalContentsResponse | None,
)
async def get_admin_deal_appraisal(
    deal_uuid: UUID,
    session: AsyncSession = Depends(db_session),
    settings: Settings = Depends(get_settings),
) -> dict[str, Any] | None:
    deal = await session.scalar(select(Deal).where(Deal.id == deal_uuid))
    if deal is None:
        raise HTTPException(status_code=404, detail="deal not found")
    client = VccClient(
        api_key=settings.vcc_api_key.get_secret_value(),
        base_url=settings.vcc_api_base_url,
    )
    try:
        return await client.get_appraisal_contents(deal.hubspot_deal_id)
    except VccError as exc:
        raise HTTPException(status_code=502, detail=f"VCC error: {exc}") from exc

Schema extension — DealItemBrief

# features/deals/schemas.py — extension

class DealItemBrief(BaseModel):
    # existing fields...
    id: UUID
    crop_key: str
    source_image: str
    bbox: dict[str, float]
    width_cm: float | None
    height_cm: float | None
    status: ItemStatus
    category: str | None = None
    subcategory: str | None = None
    category_confidence: float | None = None
    subcategory_confidence: float | None = None
    # NEW (all nullable until the appraisal stage exists)
    ai_item_name: str | None = None
    condition: str | None = None
    material: str | None = None
    value_low: float | None = None
    value_high: float | None = None
    value_currency: str | None = None
    triage_route: Literal["no_value", "quantity", "fixed_price", "precious_metals", "red_bag"] | None = None
    signals: dict[str, bool] | None = None
    appraisal_status: Literal["pending", "appraised", "failed"] | None = None

§6Failure modes

§7Testing

Backend

• tests/test_vcc_client_appraisal_contents.py — NEW. respx-mocked unit tests for VccClient.get_appraisal_contents: happy path; 500 with "No Appraisal Found" → None; other 500 → VccError(status=500); 4xx → VccError; transport error → VccError; x-api-key header set.
• tests/test_appraisal_route.py — NEW. Route tests: unknown deal → 404; payload → 200 + body; None → 200 + null; VccError → 502.
• tests/test_deal_detail_schemas.py — EXTEND. Assert the 9 new fields exist; verify null serialization; round-trip a populated fixture.
• tests/test_deal_queue_service_detail.py — EXTEND. One case populating the new fields via direct ORM writes; assert they thread through to DealItemBrief.

Frontend (Vitest + RTL + MSW)

• DealHeader.test.tsx — identity / pipeline / VCC state; freshness hint; copy on click.
• DealTimeline.test.tsx — 6 nodes; correct status icons; click updates ?stage=; running shows live elapsed; failed shows ✗ + "—".
• ItemCard.test.tsx — three fixtures: (a) categorization-only, (b) full appraisal with all signal chips, (c) status=failed. Null fields collapse cleanly; triage badge color matches route.
• ItemsGrid.test.tsx — N cards; empty state; thumbnail click opens Lightbox.
• StageDetailPanel.test.tsx — dispatch by ?stage=; error block on failure; "Awaiting prior stage" when not run.
• VccAppraisalCard.test.tsx — payload renders; null → placeholder; 502 → error sub-state.
• LogsDrawer.test.tsx — opens via button; stage-boundary markers between entries with different extra.stage; Esc + close button work; ?logs=open pre-opens.
• admin.queue.$dealId.test.tsx — composition; auto-poll fires every 3 s while running; stops when terminal (vi.useFakeTimers); deep-link ?stage=segmentation&logs=open works; old ?run= URLs redirect.
• deal-detail.test.ts — adapter test: 9 new fields preserved through adaptation; imageById + sourceLabelFor unchanged.

Manual / smoke (not in CI)

• Click through queue row → land on detail page. Back returns to queue with state.
• Process a deal in docker compose; verify polling animates timeline; Items grid populates; drawer streams logs; VCC Appraisal card renders or shows the placeholder depending on real VCC state.
• Visual: 70+ items render correctly; cards collapse when appraisal fields are absent; triage badges have distinguishable colors.

§8Decisions made

1. Route: new /admin/queue/$dealId page replaces the slide-out. Backwards-compat shim redirects old ?run= URLs.
2. Macro layout: stacked vertical — Header → Timeline → Items → Selected-stage detail → VCC Appraisal → Logs button → Logs drawer (when open).
3. Timeline: single horizontal strip of 6 stage nodes. Replaces PipelineTrail + TimelineTab.
4. Items section: top-level, always visible. Replaces buried crops inside CategorizationIO.
5. Item card content: thumbnail + AI summary + triage route + signal chips + status. Read-only.
6. Stage panel: leaner. Only settings / LLM usage / errors. Items removed from per-stage IO.
7. Logs: slide-up drawer behind a button. Unified deal-wide stream with stage-boundary markers. Replaces per-stage LogsTab.
8. VCC Appraisal: new endpoint + new card. Separate granularity from our Items; not joined.
9. Customer details: not shown on the deal detail page; fetched transiently only at DOR submission.
10. Refresh: auto-poll 3 s while any stage is running; idle otherwise.
11. Default stage selection: latest with data. ?stage= overrides.
12. Appraisal fields on DealItem: schema additions, all nullable; no DB column yet (defer to sub-project B).
13. DB migrations: none in this slice.
14. VCC re-poll for status drift: deferred to sub-project D. Header shows "as of last ingest, N min ago".