Run: expert-earnings-summary

• branch: claude/tender-mendel-w9o8ro
• pr: #509

Stub: Expert earnings summary

• feature-slug: expert-earnings-summary
• epic: expert-dashboard-data
• personas: Expert
• initiative: Build the Bridge / objective: Q2 2026 Objective 3 — Validate Technical Infrastructure & Payout Flow
• depends-on: expert-workbench-foundation, sla-stage-targets
• sequence: 7 of 8

Problem

The earnings half of the Performance section (performance-section.tsx) is dummy: thisMonth, inProgress, atRisk, avgCompletionTime. The backing data exists — invoices (amount/total, paid, paidAt), quotes and milestones (percentage value) — but nothing aggregates it per expert for the workbench.

Proposed change

• Build an earnings aggregation in @sustentus/services/server for the signed-in expert:
  • thisMonth — invoices paid with paidAt in the current month (expert's currency).
  • inProgress — value of active-project work not yet paid (milestone value on active leads, or approved-but-unpaid invoices).
  • atRisk — value of work whose stage is SLA-breached / at-risk (from sla-stage-targets).
  • avgCompletionTime — mean elapsed time from project start to delivery/sign-off across the expert's completed leads.
• Wire the earnings cards to these figures, formatted in the expert's currency.

Acceptance criteria (rough)

• Each earnings figure is computed from real invoices/quotes/milestones for the signed-in expert, in their currency — no hard-coded amounts.
• atRisk reconciles with the at-risk items the SLA timing engine flags.
• avgCompletionTime derives from real start→completion durations.
• Zero-data expert renders zeros / "—", not mock values.

Out of scope (this feature)

• The quality half of the Performance section (feature 8).
• Defining SLA targets (consumed from feature 2 for the at-risk figure).
• Payout/invoice generation changes — read-only aggregation.

Notes for Define

• Reuse the same value-resolution helper as expert-work-queue / expert-active-projects (accepted quote total vs proposal price) so figures agree across sections.
• Currency: aggregate in the expert's currency; decide handling if leads span currencies.
• touches: packages/services/src/server (earnings aggregation over invoice/quote/milestone), apps/web/components/dashboard/expert/performance-section.tsx. </content> </invoke>

Spec: Expert earnings summary

• slug: expert-earnings-summary
• personas: Expert
• touches: apps/dashboards/components/dashboard/expert/performance-section.tsx, apps/dashboards/lib/mock/expert.ts
• complexity: standard

Problem

The expert workbench (apps/dashboards/.../expert/page.tsx) ends in a "Performance & earnings" section whose Earnings card shows only three raw figures — earned this month, in delivery, and revenue at risk — with no sense of what has actually been paid out, what is still awaiting payment, or how earnings are trending. The roles doc lists "earnings and payout tracking" as a core expert concern, and Q2-2026 Objective 3 ("Validate technical infrastructure & payout flow") makes payout visibility a priority — yet an expert can't currently see, at a glance, how their money is moving. A richer earnings summary in the place experts already look closes that gap and advances the "refine the bridge" goal of clearer dashboard reporting.

Proposed change

Expand the Earnings half of the existing "Performance & earnings" section on the expert workbench into a clearer earnings summary — in place, no new route. The summary stays read-only and is composed of aggregate cards/tiles only (no per-invoice list). It surfaces:

• Headline earned — money earned this month, with a comparison against the previous month (e.g. up/down vs last month) so there is a sense of trend.
• Payout state breakdown — a simple split of earnings by state: paid, awaiting payment, in delivery, and revenue at risk from delays — shown as labelled tiles (and a lightweight proportional bar built from existing primitives, no chart library).
• Average payout cycle time — surface the avgCompletionTime figure that already exists in the mock but is not currently displayed, framed as how long earnings take to land.

Mock data in lib/mock/expert.ts is extended with the few new aggregate fields this needs (paid, awaiting payment, previous-month earned) — summary aggregates only, no invoices array. Everything is built from the local dashboards UI primitives (Card, MetricTile, Typography, etc.); the Quality card in the same section is left unchanged.

Acceptance criteria

• The expert workbench "Performance & earnings" section shows an earnings summary that includes: earned this month, paid, awaiting payment, in delivery, and revenue at risk.
• Earned this month is shown alongside a comparison to the previous month (a trend indication, e.g. delta or up/down direction).
• Average payout cycle time is displayed (using the existing avgCompletionTime mock value).
• A lightweight proportional breakdown of earnings by state (paid / awaiting / in delivery / at risk) is shown, built only from existing local primitives — no charting library and no per-invoice table.
• lib/mock/expert.ts is extended with the new aggregate earnings fields only (no invoices array); no other persona mock files change.
• All text uses the local Typography component in sentence case, and all UI uses the local components/ui primitives — no import from @sustentus/ui, no new primitive/chart dependency.

Out of scope

• A dedicated /expert/earnings route or sidebar entry — the summary stays inside the existing workbench Performance section this run.
• A per-invoice table or invoice-level detail (status, dates, PDF, dispute/resubmit actions).
• Charted earnings trend lines / historical time-series charts.
• Any real data wiring — this is mock-data only, consistent with the dashboards app.
• Changes to the Quality card or other workbench sections.

Open questions

• none

Build notes: expert-earnings-summary

• commits: feat: expert-earnings-summary — enrich workbench earnings summary

What changed

• apps/dashboards/lib/mock/expert.ts: extended the earnings mock with aggregate-only fields (lastMonth, changePct, trend, paid, awaitingPayment, and a numeric breakdown for the proportional bar). No invoices array; no other persona mock files touched.
• apps/dashboards/components/dashboard/expert/performance-section.tsx: reworked the Earnings card on the workbench Performance section into a read-only earnings summary — headline earned-this-month with a month-on-month trend (up/down icon + delta), paid / awaiting payment / in delivery / at risk tiles, a lightweight proportional breakdown bar + legend built from plain divs (no chart library), and the average payout cycle time (surfacing the previously unused avgCompletionTime). The Quality card is unchanged.

Acceptance criteria status

• Earnings summary shows earned this month, paid, awaiting payment, in delivery, and revenue at risk — all present as tiles/headline.
• Earned this month shown with a comparison to the previous month — trend icon + changePct delta and a "vs … last month" line.
• Average payout cycle time displayed using the existing avgCompletionTime value.
• Lightweight proportional breakdown by state built only from local primitives (flex divs + Typography) — no charting library, no per-invoice table.
• lib/mock/expert.ts extended with aggregate fields only (no invoices array); no other persona mock files changed.
• All text uses the local Typography component in sentence case; UI uses local components/ui primitives only — no @sustentus/ui import, no new dependency.

Verify result

• mechanical checks (format · lint · typecheck · build) run in CI + the Vercel preview, not here. No check is expected to fail.

Notes for review

• The Earnings card is now taller than the Quality card beside it; on sm+ the two-column grid stretches both to equal height, which reads fine. Worth a glance on the preview.
• Breakdown bar widths are proportional to the numeric breakdown values (paid/awaiting/inDelivery/atRisk).

See your earnings at a glance

personas: [expert]

You can now see a clearer picture of your earnings right on your workbench. It shows what you have earned this month — alongside how that compares with last month — plus how much has been paid, how much is awaiting payment, how much is still in delivery, and how much revenue is at risk from delays. A simple bar breaks those down at a glance, and you can also see your average payout cycle time, so you know how long earnings typically take to land.

(Live entry: apps/help/app/changelog/2026-06-23-expert-earnings-summary/page.mdx)

Experts can now see their earnings at a glance

Who it's for: Experts What shipped: A clearer earnings summary on the expert workbench — money earned this month with a month-on-month trend, plus paid, awaiting payment, in delivery, at risk, and average payout cycle time. Why it matters: Advances Refine the Bridge — sharper reporting clarity that gives experts confidence in how their payouts are moving.

Dig deeper: <merged-PR URL> · <changelog entry URL>