update

backend/app/deal_revenue.py

@@ -1,13 +1,13 @@
 """
-Quarterly recurring metrics in USD from won deals.
+Quarterly ARR (USD) roll-forward from won deals, using each PO line's billing interval.
 
-Uses deal **revenue_type** with PO line **subtotals** (same as won popover):
-  - mrr  — line amounts are **monthly** recurring totals → ARR = subtotal × 12
-  - qrr  — line amounts are **quarterly** recurring totals → ARR = subtotal × 4
-  - arr  — line amounts are **annual** recurring totals → ARR = subtotal
-  - one_time — no recurring MRR; one-time USD = sum of lines in win quarter
+Per line:
+  - monthly   → ARR contribution = amount × 12
+  - quarterly → ARR contribution = amount × 4
+  - annual    → ARR contribution = amount × 1
+  - one_time  → excluded from ARR; summed into one-time revenue for the win quarter
 
-Portfolio MRR = ARR ÷ 12 per deal. No FX; amounts are treated as USD ($).
+Legacy won snapshots without line billing_interval fall back to deal revenue_type (previous behavior).
 """
 
 from __future__ import annotations
@@ -35,28 +35,83 @@ def deal_line_subtotal(lines: list[dict[str, Any]]) -> float:
     return round(sum(line_amount_native(li) for li in lines), 2)
 
 
-def deal_recurring_arr_usd(revenue_type: str, lines: list[dict[str, Any]]) -> float:
-    """Annual recurring revenue (USD) implied by deal type + invoice lines."""
-    rt = (revenue_type or "arr").strip().lower()
-    sub = deal_line_subtotal(lines)
+def _lines_have_explicit_interval(lines: list[dict[str, Any]]) -> bool:
+    return any(isinstance(li, dict) and "billing_interval" in li for li in lines)
+
+
+def _norm_interval(raw: Any) -> str:
+    if raw is None:
+        return "monthly"
+    s = str(raw).strip().lower()
+    if s in ("one_time", "onetime", "one-time", "non-recurring"):
+        return "one_time"
+    if s in ("month", "monthly", "every month", "m"):
+        return "monthly"
+    if s in ("quarter", "quarterly", "every 3 months", "q"):
+        return "quarterly"
+    if s in ("year", "annual", "yearly", "every year", "a"):
+        return "annual"
+    return "monthly"
+
+
+def _legacy_deal_recurring_arr(lines: list[dict[str, Any]], deal_revenue_type: str) -> float:
+    """Old rows with no per-line billing_interval; use deal-level revenue type."""
+    rt = (deal_revenue_type or "arr").strip().lower()
     if rt == "one_time":
         return 0.0
+    sub = deal_line_subtotal(lines)
     if rt == "mrr":
         return round(sub * 12.0, 2)
     if rt == "qrr":
         return round(sub * 4.0, 2)
     if rt == "arr":
         return round(sub, 2)
-    return round(sub, 2)
+    return round(sub * 12.0, 2)
 
 
-def deal_recurring_mrr_usd(revenue_type: str, lines: list[dict[str, Any]]) -> float:
-    arr = deal_recurring_arr_usd(revenue_type, lines)
-    return round(arr / 12.0, 2)
+def _legacy_deal_onetime(lines: list[dict[str, Any]], deal_revenue_type: str) -> float:
+    rt = (deal_revenue_type or "arr").strip().lower()
+    if rt == "one_time":
+        return deal_line_subtotal(lines)
+    return 0.0
 
 
-def deal_onetime_usd(lines: list[dict[str, Any]]) -> float:
-    return deal_line_subtotal(lines)
+def deal_recurring_arr_usd(lines: list[dict[str, Any]], deal_revenue_type: str = "arr") -> float:
+    """Annual recurring revenue (USD) from recurring lines only."""
+    if not lines:
+        return 0.0
+    if not _lines_have_explicit_interval(lines):
+        return _legacy_deal_recurring_arr(lines, deal_revenue_type)
+
+    total = 0.0
+    for li in lines:
+        inv = _norm_interval(li.get("billing_interval"))
+        if inv == "one_time":
+            continue
+        amt = line_amount_native(li)
+        if inv == "monthly":
+            total += amt * 12.0
+        elif inv == "quarterly":
+            total += amt * 4.0
+        elif inv == "annual":
+            total += amt
+        else:
+            total += amt * 12.0
+    return round(total, 2)
+
+
+def deal_onetime_usd(lines: list[dict[str, Any]], deal_revenue_type: str = "arr") -> float:
+    """Non-recurring USD from one-time lines (and legacy all–one-time deals)."""
+    if not lines:
+        return 0.0
+    if not _lines_have_explicit_interval(lines):
+        return round(_legacy_deal_onetime(lines, deal_revenue_type), 2)
+
+    total = 0.0
+    for li in lines:
+        if _norm_interval(li.get("billing_interval")) == "one_time":
+            total += line_amount_native(li)
+    return round(total, 2)
 
 
 @dataclass(frozen=True)
@@ -123,9 +178,6 @@ def build_quarterly_board(
     deals: list[dict[str, Any]],
     max_quarters: int = 10,
 ) -> dict[str, Any]:
-    """
-    deals: each dict needs revenue_type, won_line_items (list), won_at (optional).
-    """
     if not deals:
         return {
             "currency_display": "USD",
@@ -165,7 +217,7 @@ def build_quarterly_board(
         quarters = quarters[-max_quarters:]
 
     rows: list[dict[str, Any]] = []
-    prev_total_mrr = 0.0
+    prev_total_arr = 0.0
     prev_total_contracts = 0
 
     for qs in quarters:
@@ -177,12 +229,12 @@ def build_quarterly_board(
                 return False
             return start <= won_at <= end
 
-        new_mrr = 0.0
+        new_arr = 0.0
         new_contracts = 0
-        one_time_usd = 0.0
+        one_time_sum = 0.0
         one_time_deals: list[dict[str, Any]] = []
 
-        total_mrr_end = 0.0
+        total_arr_end = 0.0
         total_contracts_end = 0
 
         for deal in normalized:
@@ -190,35 +242,34 @@ def build_quarterly_board(
             rt = deal["revenue_type"]
             won_at = deal["won_at"]
 
-            if rt == "one_time":
-                if won_at and won_at <= end:
-                    ot = deal_onetime_usd(lines)
-                    if in_quarter(won_at):
-                        one_time_usd += ot
-                        one_time_deals.append(
-                            {
-                                "deal_id": deal["id"],
-                                "name": deal["name"],
-                                "amount_usd": ot,
-                                "won_at": won_at.isoformat() if won_at else None,
-                            }
-                        )
-                continue
+            arr_r = deal_recurring_arr_usd(lines, rt)
+            ot_amt = deal_onetime_usd(lines, rt)
 
-            mrr = deal_recurring_mrr_usd(rt, lines)
             if won_at is None or won_at > end:
                 continue
-            total_mrr_end += mrr
-            total_contracts_end += 1
-
-            if in_quarter(won_at):
-                new_mrr += mrr
-                new_contracts += 1
 
-        existing_mrr = prev_total_mrr
+            if arr_r > 0:
+                total_arr_end += arr_r
+                total_contracts_end += 1
+                if in_quarter(won_at):
+                    new_arr += arr_r
+                    new_contracts += 1
+
+            if ot_amt > 0 and in_quarter(won_at):
+                one_time_sum += ot_amt
+                one_time_deals.append(
+                    {
+                        "deal_id": deal["id"],
+                        "name": deal["name"],
+                        "amount_usd": ot_amt,
+                        "won_at": won_at.isoformat() if won_at else None,
+                    }
+                )
+
+        existing_arr = prev_total_arr
         existing_contracts = prev_total_contracts
 
-        portfolio_check = round(existing_mrr + new_mrr, 2)
+        portfolio_check = round(existing_arr + new_arr, 2)
         rows.append(
             {
                 "label": qs.label,
@@ -226,28 +277,23 @@ def build_quarterly_board(
                 "quarter": qs.quarter,
                 "start": start.isoformat(),
                 "end": end.isoformat(),
-                "mrr": {
-                    "existing": round(existing_mrr, 2),
-                    "new": round(new_mrr, 2),
-                    "total": round(total_mrr_end, 2),
-                },
-                "arr_usd": {
-                    "existing": round(existing_mrr * 12, 2),
-                    "new": round(new_mrr * 12, 2),
-                    "total": round(total_mrr_end * 12, 2),
+                "arr": {
+                    "existing": round(existing_arr, 2),
+                    "new": round(new_arr, 2),
+                    "total": round(total_arr_end, 2),
                 },
                 "contracts": {
                     "existing": existing_contracts,
                     "new": new_contracts,
                     "total": total_contracts_end,
                 },
-                "one_time_usd_quarter": round(one_time_usd, 2),
+                "one_time_usd_quarter": round(one_time_sum, 2),
                 "one_time_deals": one_time_deals,
-                "portfolio_matches_rollforward": abs(portfolio_check - round(total_mrr_end, 2)) < 0.02,
+                "portfolio_matches_rollforward": abs(portfolio_check - round(total_arr_end, 2)) < 0.02,
             }
         )
 
-        prev_total_mrr = total_mrr_end
+        prev_total_arr = total_arr_end
         prev_total_contracts = total_contracts_end
 
     return {

backend/app/main.py

@@ -18,6 +18,7 @@ import asyncio
 import math
 import re
 from datetime import datetime, timedelta
+from calendar import monthrange
 
 from .database import (
     get_db,
@@ -550,6 +551,41 @@ def _deal_access_or_403(row: CrmDeal, t: TenantContext) -> None:
         raise HTTPException(status_code=403, detail="You do not have access to this deal")
 
 
+def _dashboard_period_bounds_utc(period: str) -> Optional[tuple[datetime, datetime]]:
+    """Bounds for filtering won deals by won_at (dashboard date presets). None = all time."""
+    p = (period or "all").strip().lower()
+    if p in ("", "all"):
+        return None
+    now = datetime.utcnow()
+    if p == "month":
+        start = datetime(now.year, now.month, 1)
+        last = monthrange(now.year, now.month)[1]
+        end = datetime(now.year, now.month, last, 23, 59, 59)
+        return start, end
+    if p == "quarter":
+        qi = (now.month - 1) // 3
+        sm = qi * 3 + 1
+        start = datetime(now.year, sm, 1)
+        em = sm + 2
+        if em == 12:
+            end = datetime(now.year, 12, 31, 23, 59, 59)
+        else:
+            end = datetime(now.year, em + 1, 1) - timedelta(microseconds=1)
+        return start, end
+    if p == "year":
+        return datetime(now.year, 1, 1), datetime(now.year, 12, 31, 23, 59, 59)
+    return None
+
+
+def _won_at_within_bounds(won_at: Optional[datetime], bounds: Optional[tuple[datetime, datetime]]) -> bool:
+    if bounds is None:
+        return True
+    if won_at is None:
+        return False
+    wdt = won_at.replace(tzinfo=None) if getattr(won_at, "tzinfo", None) else won_at
+    return bounds[0] <= wdt <= bounds[1]
+
+
 def _deal_to_dict(d: CrmDeal) -> dict:
     fv = None
     if d.deal_value is not None and d.close_probability is not None:
@@ -2795,11 +2831,12 @@ async def list_deals(
 async def quarterly_recurring_metrics(
     owner_user_id: Optional[int] = Query(None),
     max_quarters: int = Query(12, ge=1, le=24),
+    period: str = Query("all"),
     t: TenantContext = Depends(get_tenant_context),
 ):
     """
-    Won deals → recurring MRR/ARR (USD) by calendar quarter: Existing / New / Total roll-forward,
-    plus one-time USD in quarter (revenue_type one_time). Uses deal Revenue type + PO line subtotals.
+    Won deals → ARR (USD) roll-forward by calendar quarter from PO lines (interval per line + one-time lines).
+    Optional period=all|month|quarter|year filters by won_at (same presets as the sales dashboard).
     """
     db = t.db
     q = db.query(CrmDeal).filter(
@@ -2811,15 +2848,19 @@ async def quarterly_recurring_metrics(
     elif owner_user_id is not None:
         q = q.filter(CrmDeal.owner_user_id == int(owner_user_id))
     rows = q.all()
+    bounds = _dashboard_period_bounds_utc(period)
     deals_payload = []
     for r in rows:
+        wa = getattr(r, "won_at", None)
+        if not _won_at_within_bounds(wa, bounds):
+            continue
         deals_payload.append(
             {
                 "id": r.id,
                 "name": r.name or "",
                 "revenue_type": (getattr(r, "revenue_type", None) or "arr"),
                 "won_line_items": _won_line_items_list(r),
-                "won_at": getattr(r, "won_at", None),
+                "won_at": wa,
             }
         )
     return build_quarterly_board(deals_payload, max_quarters=max_quarters)

backend/app/models.py

@@ -102,8 +102,8 @@ class WonLineItemIn(BaseModel):
     description: str = Field(default="", max_length=4000)
     qty: float = Field(..., gt=0, le=1_000_000)
     rate: float = Field(..., ge=0, le=1_000_000_000)
-    # Recurring revenue / spreadsheet columns: amount per interval × annualization (matches manual ARR sheet).
-    billing_interval: Literal["monthly", "quarterly", "annual"] = "monthly"
+    # Per-line cadence for ARR vs one-time (dashboard uses these; legacy deals may omit).
+    billing_interval: Literal["monthly", "quarterly", "annual", "one_time"] = "monthly"
     currency: Literal["CAD", "USD"] = "USD"
 
     @field_validator("product_service", mode="before")
@@ -126,6 +126,8 @@ class WonLineItemIn(BaseModel):
         if v is None:
             return "monthly"
         s = v.strip().lower() if isinstance(v, str) else "monthly"
+        if s in ("one_time", "onetime", "one-time", "non-recurring"):
+            return "one_time"
         if s in ("month", "monthly", "every month", "m"):
             return "monthly"
         if s in ("quarter", "quarterly", "every 3 months", "q"):

frontend/src/components/workspace/WonBillingModal.jsx

@@ -358,17 +358,20 @@ export default function WonBillingModal({ dealName, busy, onCancel, onSubmit, gm
                                                 >
                                                     <SelectTrigger className="h-8 bg-white text-xs">
                                                         <span className="truncate">
-                                                            {row.billing_interval === 'quarterly'
-                                                                ? 'Every 3 mo'
-                                                                : row.billing_interval === 'annual'
-                                                                  ? 'Every year'
-                                                                  : 'Every month'}
+                                                            {row.billing_interval === 'one_time'
+                                                                ? 'One-time'
+                                                                : row.billing_interval === 'quarterly'
+                                                                  ? 'Every 3 mo'
+                                                                  : row.billing_interval === 'annual'
+                                                                    ? 'Every year'
+                                                                    : 'Every month'}
                                                         </span>
                                                     </SelectTrigger>
                                                     <SelectContent>
                                                         <SelectItem value="monthly">Every month</SelectItem>
                                                         <SelectItem value="quarterly">Every 3 months</SelectItem>
                                                         <SelectItem value="annual">Every year</SelectItem>
+                                                        <SelectItem value="one_time">One-time</SelectItem>
                                                     </SelectContent>
                                                 </Select>
                                             </td>

frontend/src/pages/SalesDashboard.jsx

@@ -48,10 +48,11 @@ function startOfQuarter(d) {
     return new Date(m.getFullYear(), q * 3, 1, 0, 0, 0, 0);
 }
 
-/** Global dashboard date filter: deal created_at must fall in range (all widgets). */
+/** Dashboard date filter: open pipeline deals by created_at; Won deals by won_at when present. */
 function dealInDashboardPeriod(deal, period) {
     if (period === DASHBOARD_PERIOD_ALL) return true;
-    const iso = deal.created_at;
+    const iso =
+        normalizeStage(deal.stage) === 'won' && deal.won_at ? deal.won_at : deal.created_at;
     if (!iso) return false;
     const dt = new Date(iso);
     if (Number.isNaN(dt.getTime())) return false;
@@ -393,6 +394,7 @@ export default function SalesDashboard() {
         let cancelled = false;
         const params = new URLSearchParams();
         params.set('max_quarters', '12');
+        params.set('period', dashboardPeriod);
         if (isAdmin && ownerFilter !== 'all') {
             params.set('owner_user_id', ownerFilter);
         }
@@ -411,7 +413,7 @@ export default function SalesDashboard() {
         return () => {
             cancelled = true;
         };
-    }, [isAdmin, ownerFilter, me?.user_id]);
+    }, [isAdmin, ownerFilter, me?.user_id, dashboardPeriod]);
 
     useEffect(() => {
         if (!isAdmin) setOwnerFilter('all');
@@ -606,7 +608,7 @@ export default function SalesDashboard() {
     const dateRangeSub =
         dashboardPeriod === DASHBOARD_PERIOD_ALL
             ? 'All deals in view'
-            : 'Deal created in selected range';
+            : 'Open deals by created date · Won deals by won date';
 
     const subtitle = isAdmin
         ? ownerFilter === 'all'
@@ -625,11 +627,13 @@ export default function SalesDashboard() {
                 <div className="space-y-6">
                     <div className="flex flex-wrap items-center justify-between gap-3">
                         <p className="text-sm text-slate-600 max-w-3xl">
-                            Charts use the same deal fields as the pipeline board. Actual revenue uses deal
-                            value on <strong className="font-medium text-slate-800">won</strong> deals (there is
-                            no separate &quot;actual value&quot; column yet). Revenue-by-month uses{' '}
-                            <strong className="font-medium text-slate-800">expected close</strong> when set,
-                            otherwise <strong className="font-medium text-slate-800">created date</strong>.
+                            Date range and team filters apply to the charts below. Open pipeline deals use{' '}
+                            <strong className="font-medium text-slate-800">created date</strong>;{' '}
+                            <strong className="font-medium text-slate-800">won</strong> deals use{' '}
+                            <strong className="font-medium text-slate-800">won date</strong> when present (same as the
+                            ARR boards). Actual revenue sums deal value on won deals in view. Revenue-by-month uses{' '}
+                            <strong className="font-medium text-slate-800">expected close</strong> when set, otherwise
+                            created date.
                         </p>
                         <div
                             className="flex shrink-0 flex-wrap items-center justify-end gap-2"
@@ -708,23 +712,6 @@ export default function SalesDashboard() {
                         />
                     </div>
 
-                    <div className="rounded-xl border border-indigo-100 bg-indigo-50/50 px-4 py-3 text-sm text-slate-700">
-                        <p className="font-semibold text-slate-900">Quarterly recurring revenue ($ USD)</p>
-                        <p className="mt-1 text-xs leading-relaxed text-slate-600">
-                            Uses <strong className="font-medium text-slate-800">won</strong> deals and the same PO line
-                            subtotals as the win popover. Recurring math follows deal{' '}
-                            <strong className="font-medium text-slate-800">Revenue</strong>:{' '}
-                            <strong className="font-medium text-slate-800">MRR</strong> = lines are monthly totals;
-                            <strong className="font-medium text-slate-800"> QRR</strong> = quarterly totals;
-                            <strong className="font-medium text-slate-800"> ARR</strong> = annual totals;
-                            <strong className="font-medium text-slate-800"> One-time</strong> = non-recurring (sum of
-                            lines). Portfolio <strong className="font-medium text-slate-800">MRR</strong> is monthly
-                            equivalent; <strong className="font-medium text-slate-800">Existing</strong> carries from
-                            the prior quarter; <strong className="font-medium text-slate-800">New</strong> is closed in
-                            that quarter. Attribution uses the <strong className="font-medium text-slate-800">won date</strong>.
-                        </p>
-                    </div>
-
                     {quarterlyLoading ? (
                         <div className="flex items-center justify-center gap-2 py-10 text-slate-600">
                             <Loader2 className="h-5 w-5 animate-spin shrink-0" aria-hidden />
@@ -734,8 +721,8 @@ export default function SalesDashboard() {
                         <div className="space-y-4">
                             <div className="grid grid-cols-1 gap-4 xl:grid-cols-2">
                                 <CardShell
-                                    title="Recurring MRR (USD)"
-                                    hint="Roll-forward like your deck: Total = portfolio at quarter end; Existing = prior quarter total; New = sum of monthly-equivalent MRR from deals won in the quarter. All amounts USD ($)."
+                                    title="Annual recurring revenue (ARR)"
+                                    hint="USD ($). From won PO lines: monthly ×12, quarterly ×4, annual ×1; one-time lines excluded. Total / Existing / New roll-forward by quarter. Respects team + date range filters."
                                     className="min-h-0"
                                 >
                                     <div className="overflow-x-auto -m-1 p-1">
@@ -755,7 +742,7 @@ export default function SalesDashboard() {
                                                     <td className="py-2 pr-3 font-medium text-slate-800">TOTAL</td>
                                                     {quarterColumns.map((q) => (
                                                         <td key={q.label} className="px-2 py-2 text-right font-semibold">
-                                                            {fmtMoney(q.mrr?.total)}
+                                                            {fmtMoney(q.arr?.total)}
                                                         </td>
                                                     ))}
                                                 </tr>
@@ -763,7 +750,7 @@ export default function SalesDashboard() {
                                                     <td className="py-2 pr-3 text-slate-600">EXISTING</td>
                                                     {quarterColumns.map((q) => (
                                                         <td key={q.label} className="px-2 py-2 text-right text-slate-700">
-                                                            {fmtMoney(q.mrr?.existing)}
+                                                            {fmtMoney(q.arr?.existing)}
                                                         </td>
                                                     ))}
                                                 </tr>
@@ -771,21 +758,17 @@ export default function SalesDashboard() {
                                                     <td className="py-2 pr-3 text-slate-600">NEW</td>
                                                     {quarterColumns.map((q) => (
                                                         <td key={q.label} className="px-2 py-2 text-right text-slate-700">
-                                                            {fmtMoney(q.mrr?.new)}
+                                                            {fmtMoney(q.arr?.new)}
                                                         </td>
                                                     ))}
                                                 </tr>
                                             </tbody>
                                         </table>
                                     </div>
-                                    <p className="mt-3 text-xs text-slate-500">
-                                        ARR (USD) = MRR × 12 (API field <span className="font-mono text-slate-600">arr_usd</span>
-                                        ).
-                                    </p>
                                 </CardShell>
                                 <CardShell
                                     title="Recurring contracts"
-                                    hint="Count of recurring (non–one-time) won deals in the portfolio at quarter end; New = deals whose won date falls in the quarter. Amounts are USD."
+                                    hint="Won deals with at least one recurring PO line (not one-time only). Respects team + date filters."
                                     className="min-h-0"
                                 >
                                     <div className="overflow-x-auto -m-1 p-1">
@@ -831,8 +814,8 @@ export default function SalesDashboard() {
                                 </CardShell>
                             </div>
                             <CardShell
-                                title="One-time revenue (USD)"
-                                hint="Deals with revenue type One-time: invoice subtotal (sum of lines), recognized in the quarter the deal was marked won."
+                                title="One-time revenue"
+                                hint="Sum of PO lines marked One-time in the win popover; recognized in the quarter the deal was marked won. USD ($). Same filters as above."
                                 className="min-h-0"
                             >
                                 <div className="overflow-x-auto -m-1 p-1">
@@ -886,14 +869,14 @@ export default function SalesDashboard() {
                         </div>
                     ) : (
                         <p className="rounded-xl border border-dashed border-slate-200 bg-slate-50/50 px-4 py-8 text-center text-sm text-slate-600">
-                            No closed-won deals yet — quarterly MRR / contracts will appear after you mark deals won
-                            (with billing lines and billing interval per line).
+                            No matching closed-won deals for this scope — ARR / contracts / one-time update when deals
+                            are won with PO lines (billing interval per line).
                         </p>
                     )}
 
                     <CardShell
                         title="Pipeline conversion"
-                        hint="Uses the global date range (deal created date) and team scope from the top of the page. Bars: blue through Negotiation, green for Won. Shaded bands connect stages. Step % = next ÷ previous. Conversion to Won = Won ÷ New."
+                        hint="Uses date range and team from the top right (open deals by created date; won deals by won date). Bars: blue through Negotiation, green for Won. Step % = next ÷ previous."
                         headerExtra={
                             <div
                                 className="flex flex-wrap items-center gap-1 sm:gap-1.5"