token-studio 4.8.0

package/src/client/review/ReviewApp.jsx

@@ -0,0 +1,507 @@
+/* =============================================================
+   /review — main app (real data via /api/data)
+   ============================================================= */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { U } from '../shared/utils.js';
+import { RU } from './utils.js';
+import { HeroSection, ProjectSection, CalendarSection } from './sections-1.jsx';
+import { ToolsSection, EfficiencySection, ClosureProgressSection, RoiEvidenceSection, SavingsSimulatorSection, RoiAdvisorSection, AdvisorActionSummarySection, ModelStrategySection, InsightsSection } from './sections-2.jsx';
+import { buildRoiAdvisor } from './roi-advisor.js';
+import { buildMarkdownReviewReport, buildReviewReportFilename } from './markdown-report.js';
+import { buildModelStrategy } from './model-strategy.js';
+import { buildReviewClosureProgress } from './closure-progress.js';
+import { buildRoiEvidence } from './roi-evidence.js';
+import { buildSavingsSimulation } from './savings-simulator.js';
+import './styles.css';
+
+export function ReviewApp() {
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    fetch('/api/data')
+      .then(r => { if (!r.ok) throw new Error('HTTP ' + r.status); return r.json(); })
+      .then(d => { setData(d); setLoading(false); })
+      .catch(e => { setError(e.message); setLoading(false); });
+  }, []);
+
+  if (loading) {
+    return (
+      <div style={{
+        display: 'flex', alignItems: 'center', justifyContent: 'center',
+        height: '100vh', flexDirection: 'column', gap: 16
+      }}>
+        <div style={{
+          width: 32, height: 32, borderRadius: '50%',
+          border: '3px solid var(--rule)', borderTopColor: 'var(--indigo)',
+          animation: 'spin 0.8s linear infinite'
+        }}/>
+        <div style={{color: 'var(--ink-soft)', fontSize: 14}}>加载数据中…</div>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div style={{
+        display: 'flex', alignItems: 'center', justifyContent: 'center',
+        height: '100vh', flexDirection: 'column', gap: 12
+      }}>
+        <div style={{fontSize: 32}}>⚠️</div>
+        <div style={{color: 'var(--ink)', fontWeight: 600}}>数据加载失败</div>
+        <div style={{color: 'var(--ink-soft)', fontSize: 13}}>{error}</div>
+        <button onClick={() => window.location.reload()} style={{
+          marginTop: 8, padding: '8px 18px', borderRadius: 8,
+          border: '1px solid var(--rule)', background: 'var(--paper-2)',
+          cursor: 'pointer', fontSize: 13
+        }}>重新加载</button>
+      </div>
+    );
+  }
+
+  return <ReviewDashboard rawData={data}/>;
+}
+
+function ReviewDashboard({ rawData }) {
+  const TODAY = new Date();
+  TODAY.setHours(0, 0, 0, 0);
+
+  const [periodId, setPeriodId] = useState('month');
+  const [activePageIndex, setActivePageIndex] = useState(0);
+  const [advisorActions, setAdvisorActions] = useState(rawData.advisorActions || []);
+  const pageRefs = useRef([]);
+  const period = useMemo(() => RU.getPeriod(periodId, TODAY, rawData.daily), [periodId, rawData.daily]);
+  const prevPeriod = useMemo(() => period.prev
+    ? { start: period.prev.start, end: period.prev.end }
+    : null, [period]);
+
+  const daily = useMemo(() => RU.filterByPeriod(rawData.daily, period), [rawData, period]);
+  const sessions = useMemo(() =>
+    rawData.sessions.filter(session =>
+      !session.lastActivity || (session.lastActivity >= period.start && session.lastActivity <= period.end)
+    )
+  , [rawData, period]);
+  const prevDaily = useMemo(() =>
+    prevPeriod ? RU.filterByPeriod(rawData.daily, prevPeriod) : []
+  , [rawData, prevPeriod]);
+
+  // Aggregate totals
+  const totals = useMemo(() => {
+    const total = RU.sumField(daily, 'totalTokens');
+    const input = RU.sumField(daily, 'inputTokens');
+    const output = RU.sumField(daily, 'outputTokens');
+    const cacheRead = RU.sumField(daily, 'cacheReadTokens');
+    const cacheCreation = RU.sumField(daily, 'cacheCreationTokens');
+    const reasoning = RU.sumField(daily, 'reasoningOutputTokens');
+    const cost = RU.sumField(daily, 'costUSD');
+    return {
+      total, input, output, cacheRead, cacheCreation, reasoning, cost,
+      cacheHitRate: total ? (cacheRead / total) * 100 : 0
+    };
+  }, [daily]);
+
+  const prevTotals = useMemo(() => prevDaily.length ? ({
+    total: RU.sumField(prevDaily, 'totalTokens'),
+    cost:  RU.sumField(prevDaily, 'costUSD')
+  }) : null, [prevDaily]);
+
+  // Hero stat strip
+  const heroStats = useMemo(() => {
+    const days = RU.dailyTotals(daily, period);
+    const active = days.filter(d => d.total > 0);
+    const peak = active.length ? [...active].sort((a, b) => b.total - a.total)[0] : null;
+    const tools = RU.aggregateBy(daily, 'source').sort((a, b) => b.totalTokens - a.totalTokens);
+    const projects = RU.aggregateBy(daily, 'projectPath').filter(p => p.key);
+    const topTool = tools[0];
+    return {
+      activeDays: active.length,
+      projectCount: projects.length,
+      sourceCount: tools.length,
+      peakDay: peak,
+      topTool: topTool ? {
+        key: topTool.key,
+        short: topTool.key.replace(/ CLI| Code/, ''),
+        totalTokens: topTool.totalTokens,
+        share: (topTool.totalTokens / (totals.total || 1)) * 100
+      } : null,
+      avgDailyCost: active.length ? totals.cost / active.length : 0
+    };
+  }, [daily, period, totals]);
+
+  // Insights
+  const insights = useMemo(() =>
+    RU.buildInsights(daily, period, prevDaily)
+  , [daily, period, prevDaily]);
+  const roiAdvice = useMemo(() =>
+    buildRoiAdvisor({ sessions, daily })
+  , [sessions, daily]);
+  const modelStrategy = useMemo(() =>
+    buildModelStrategy({ sessions })
+  , [sessions]);
+  const closureProgress = useMemo(() =>
+    buildReviewClosureProgress({ sessions, roiAdvice })
+  , [sessions, roiAdvice]);
+  const roiEvidence = useMemo(() =>
+    buildRoiEvidence({ sessions, workItems: rawData.workItems || [] })
+  , [sessions, rawData.workItems]);
+  const savingsSimulation = useMemo(() =>
+    buildSavingsSimulation({ sessions, daily, pricingMeta: rawData.meta?.officialPricing || null })
+  , [sessions, daily, rawData.meta]);
+  const markdownReport = useMemo(() =>
+    buildMarkdownReviewReport({ period, daily, sessions, workItems: rawData.workItems || [], roiAdvice, insights, savingsSimulation, advisorActions })
+  , [period, daily, sessions, rawData.workItems, roiAdvice, insights, savingsSimulation, advisorActions]);
+
+  useEffect(() => {
+    setAdvisorActions(rawData.advisorActions || []);
+  }, [rawData.advisorActions]);
+
+  const actionsByRule = useMemo(() => {
+    const map = new Map();
+    for (const action of advisorActions) {
+      if (action.periodStart === period.start && action.periodEnd === period.end && action.sourceRule) {
+        map.set(action.sourceRule, action);
+      }
+    }
+    return map;
+  }, [advisorActions, period]);
+  const periodAdvisorActions = useMemo(() =>
+    advisorActions.filter(action => action.periodStart === period.start && action.periodEnd === period.end)
+  , [advisorActions, period]);
+
+  const persistAdvisorAction = useCallback(async (payload) => {
+    const response = await fetch('/api/advisor-actions', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        periodStart: period.start,
+        periodEnd: period.end,
+        ...payload
+      })
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(error.error || `HTTP ${response.status}`);
+    }
+    const data = await response.json();
+    setAdvisorActions(current => {
+      const next = current.filter(item => item.id !== data.action.id);
+      next.unshift(data.action);
+      return next;
+    });
+    return data.action;
+  }, [period]);
+
+  const addAdvisorAction = useCallback((payload) =>
+    persistAdvisorAction({ ...payload, status: 'open' })
+  , [persistAdvisorAction]);
+
+  const setAdvisorActionStatus = useCallback((action, status) =>
+    persistAdvisorAction({ ...action, status })
+  , [persistAdvisorAction]);
+
+  // Period nav
+  const ORDER = ['week', 'month', 'prev', '90d', 'all'];
+  const idx = ORDER.indexOf(periodId);
+  const prevId = idx > 0 ? ORDER[idx - 1] : null;
+  const nextId = idx < ORDER.length - 1 ? ORDER[idx + 1] : null;
+
+  const exportCSV = () => {
+    U.downloadCSV(`token-review-${period.start}-${period.end}.csv`, daily, [
+      { title: 'date', field: 'usageDate' },
+      { title: 'source', field: 'source' },
+      { title: 'device', field: 'device' },
+      { title: 'model', field: 'model' },
+      { title: 'project', field: 'projectPath' },
+      { title: 'input', field: 'inputTokens' },
+      { title: 'output', field: 'outputTokens' },
+      { title: 'cache_read', field: 'cacheReadTokens' },
+      { title: 'cache_creation', field: 'cacheCreationTokens' },
+      { title: 'reasoning', field: 'reasoningOutputTokens' },
+      { title: 'total', field: 'totalTokens' },
+      { title: 'official_price_usd', field: 'costUSD' }
+    ]);
+  };
+
+  const exportMarkdown = () => {
+    U.downloadText(
+      buildReviewReportFilename(period),
+      markdownReport,
+      'text/markdown;charset=utf-8'
+    );
+  };
+
+  const reviewPages = useMemo(() => [
+    {
+      id: 'overview',
+      label: '总览',
+      className: 'page',
+      content: <HeroSection period={period} totals={totals} prevTotals={prevTotals} stats={heroStats}/>
+    },
+    {
+      id: 'evidence',
+      label: 'ROI 证据',
+      className: 'page',
+      content: <RoiEvidenceSection evidence={roiEvidence}/>
+    },
+    {
+      id: 'closure',
+      label: '闭环',
+      className: 'page',
+      content: <ClosureProgressSection progress={closureProgress}/>
+    },
+    {
+      id: 'projects',
+      label: '项目',
+      className: 'page',
+      content: <ProjectSection daily={daily} totalTokens={totals.total}/>
+    },
+    {
+      id: 'calendar',
+      label: '日历',
+      className: 'page-wide',
+      innerClassName: 'review-page-narrow',
+      content: <CalendarSection daily={daily} period={period}/>
+    },
+    {
+      id: 'tools',
+      label: '工具',
+      className: 'page-wide',
+      innerClassName: 'review-page-narrow',
+      content: <ToolsSection daily={daily} totalTokens={totals.total}/>
+    },
+    {
+      id: 'efficiency',
+      label: '效率',
+      className: 'page',
+      content: <EfficiencySection daily={daily} period={period}/>
+    },
+    {
+      id: 'savings',
+      label: '节省模拟',
+      className: 'page',
+      content: <SavingsSimulatorSection
+        simulation={savingsSimulation}
+        actionsByRule={actionsByRule}
+        onAddAction={addAdvisorAction}
+        onSetActionStatus={setAdvisorActionStatus}
+      />
+    },
+    {
+      id: 'advisor',
+      label: 'ROI 建议',
+      className: 'page',
+      content: <RoiAdvisorSection
+        suggestions={roiAdvice}
+        actionsByRule={actionsByRule}
+        onAddAction={addAdvisorAction}
+        onSetActionStatus={setAdvisorActionStatus}
+      />
+    },
+    {
+      id: 'actions',
+      label: '行动清单',
+      className: 'page',
+      content: <AdvisorActionSummarySection
+        actions={periodAdvisorActions}
+        period={period}
+        onSetActionStatus={setAdvisorActionStatus}
+      />
+    },
+    {
+      id: 'strategy',
+      label: '模型策略',
+      className: 'page',
+      content: <ModelStrategySection strategy={modelStrategy}/>
+    },
+    {
+      id: 'insights',
+      label: '洞察',
+      className: 'page',
+      content: <InsightsSection insights={insights}/>
+    }
+  ], [period, totals, prevTotals, heroStats, roiEvidence, closureProgress, daily, roiAdvice, savingsSimulation, modelStrategy, insights, actionsByRule, periodAdvisorActions, addAdvisorAction, setAdvisorActionStatus]);
+
+  const goToReviewPage = useCallback((index) => {
+    const nextIndex = Math.max(0, Math.min(reviewPages.length - 1, index));
+    const reducedMotion = typeof window !== 'undefined'
+      && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+    setActivePageIndex(nextIndex);
+    pageRefs.current[nextIndex]?.scrollIntoView({
+      behavior: reducedMotion ? 'auto' : 'smooth',
+      block: 'start'
+    });
+  }, [reviewPages.length]);
+
+  useEffect(() => {
+    pageRefs.current = pageRefs.current.slice(0, reviewPages.length);
+  }, [reviewPages.length]);
+
+  useEffect(() => {
+    const nodes = pageRefs.current.filter(Boolean);
+    if (!nodes.length || typeof IntersectionObserver === 'undefined') return;
+
+    const observer = new IntersectionObserver((entries) => {
+      const visible = entries
+        .filter(entry => entry.isIntersecting)
+        .sort((a, b) => b.intersectionRatio - a.intersectionRatio)[0];
+
+      if (!visible) return;
+      const nextIndex = Number(visible.target.dataset.reviewPageIndex);
+      if (Number.isInteger(nextIndex)) setActivePageIndex(nextIndex);
+    }, {
+      root: null,
+      rootMargin: '-32% 0px -48% 0px',
+      threshold: [0.2, 0.4, 0.6]
+    });
+
+    nodes.forEach(node => observer.observe(node));
+    return () => observer.disconnect();
+  }, [reviewPages.length]);
+
+  return (
+    <>
+      <style>{`@keyframes spin { to { transform: rotate(360deg); } }`}</style>
+      <nav className="review-nav">
+        <div className="review-nav-inner">
+          <div className="brand-line">
+            <span className="brand-dot"/>
+            <span className="brand-name">Token Studio</span>
+            <div className="page-switch">
+              <a href="/" className="page-chip">看板</a>
+              <span className="page-chip active">复盘</span>
+              <a href="/live" className="page-chip">实时</a>
+            </div>
+          </div>
+          <div className="period-switch">
+            {ORDER.map(id => (
+              <button key={id}
+                className={`period-chip ${periodId === id ? 'active' : ''}`}
+                onClick={() => setPeriodId(id)}>
+                {RU.PERIOD_LABELS[id]}
+              </button>
+            ))}
+          </div>
+          <div className="nav-actions">
+            <button className="nav-btn primary" onClick={exportMarkdown}>
+              <svg width="13" height="13" viewBox="0 0 13 13" fill="none">
+                <path d="M6.5 1.5v6M4 5l2.5 2.5L9 5M2.5 10.5h8" stroke="currentColor" strokeWidth="1.35" strokeLinecap="round" strokeLinejoin="round"/>
+              </svg>
+              导出报告
+            </button>
+            <button className="nav-btn" onClick={() => window.print()}>
+              <svg width="13" height="13" viewBox="0 0 13 13" fill="none">
+                <rect x="2.5" y="4.5" width="8" height="6" rx="1" stroke="currentColor" strokeWidth="1.3"/>
+                <path d="M4 4.5V2h5v2.5M4 8.5h5" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round"/>
+              </svg>
+              打印
+            </button>
+          </div>
+        </div>
+      </nav>
+
+      <ReviewPageControls
+        pages={reviewPages}
+        activeIndex={activePageIndex}
+        onPrevious={() => goToReviewPage(activePageIndex - 1)}
+        onNext={() => goToReviewPage(activePageIndex + 1)}
+        onJump={goToReviewPage}
+      />
+
+      {reviewPages.map((page, index) => {
+        const content = page.innerClassName
+          ? <div className={page.innerClassName}>{page.content}</div>
+          : page.content;
+        return (
+          <div
+            key={page.id}
+            ref={(node) => { pageRefs.current[index] = node; }}
+            data-review-page-index={index}
+            className={`${page.className} review-page ${activePageIndex === index ? 'active' : ''}`}
+          >
+            {content}
+          </div>
+        );
+      })}
+
+      <footer className="review-footer">
+        <div className="review-footer-inner">
+          <div className="period-jump">
+            <button disabled={!prevId} onClick={() => prevId && setPeriodId(prevId)}>
+              <svg width="12" height="12" viewBox="0 0 12 12" fill="none">
+                <path d="M8 2l-4 4 4 4" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+              </svg>
+              {prevId ? RU.PERIOD_LABELS[prevId] : '更早'}
+            </button>
+            <div className="period-current">{period.pretty}</div>
+            <button disabled={!nextId} onClick={() => nextId && setPeriodId(nextId)}>
+              {nextId ? RU.PERIOD_LABELS[nextId] : '更晚'}
+              <svg width="12" height="12" viewBox="0 0 12 12" fill="none">
+                <path d="M4 2l4 4-4 4" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+              </svg>
+            </button>
+          </div>
+          <button className="export-btn" onClick={exportCSV}>
+            <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+              <path d="M7 1v8M4 6l3 3 3-3M2 12h10" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+            </svg>
+            导出 CSV
+          </button>
+          <button className="export-btn" onClick={exportMarkdown}>
+            <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+              <path d="M7 1v8M4 6l3 3 3-3M2 12h10" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+            </svg>
+            导出复盘报告
+          </button>
+        </div>
+      </footer>
+    </>
+  );
+}
+
+function ReviewPageControls({ pages, activeIndex, onPrevious, onNext, onJump }) {
+  const current = pages[activeIndex] || pages[0];
+  return (
+    <div className="review-page-controls" aria-label="复盘页面导航">
+      <button
+        type="button"
+        className="review-page-btn"
+        disabled={activeIndex <= 0}
+        onClick={onPrevious}
+      >
+        <svg width="13" height="13" viewBox="0 0 13 13" fill="none" aria-hidden="true">
+          <path d="M8.5 2.5l-4 4 4 4" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+        </svg>
+        上一页
+      </button>
+      <div className="review-page-current">
+        <strong>{activeIndex + 1}/{pages.length}</strong>
+        <span>{current?.label || '复盘'}</span>
+      </div>
+      <div className="review-page-dots" aria-label="复盘章节">
+        {pages.map((page, index) => (
+          <button
+            key={page.id}
+            type="button"
+            className={`review-page-dot ${index === activeIndex ? 'active' : ''}`}
+            aria-label={`跳到${page.label}`}
+            aria-current={index === activeIndex ? 'step' : undefined}
+            onClick={() => onJump(index)}
+          />
+        ))}
+      </div>
+      <button
+        type="button"
+        className="review-page-btn primary"
+        disabled={activeIndex >= pages.length - 1}
+        onClick={onNext}
+      >
+        下一页
+        <svg width="13" height="13" viewBox="0 0 13 13" fill="none" aria-hidden="true">
+          <path d="M4.5 2.5l4 4-4 4" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+        </svg>
+      </button>
+    </div>
+  );
+}

package/src/client/review/closure-progress.js

@@ -0,0 +1,165 @@
+import {
+  aggregateSessions,
+  missingReviewAttributionFields,
+  sessionProjectLabel
+} from '../dashboard/attribution.js';
+
+const PRODUCTIVE_STATUSES = new Set(['已完成', '已发布']);
+const LABELING_CATEGORY = '补标注';
+
+export function buildReviewClosureProgress({
+  sessions = [],
+  roiAdvice = [],
+  targetAttributedSessions = 10,
+  targetOutputLinks = 3,
+  targetNonLabelAdvice = 1,
+  topGapLimit = 5
+} = {}) {
+  const attributedSessions = sessions.filter(isClosureAttributedSession)
+    .sort(compareCostThenTokens);
+  const manualSessions = attributedSessions.filter(isManualConfirmedSession);
+  const autoHighSessions = attributedSessions.filter(isAutoHighConfidenceSession);
+  const usableAttributionCount = manualSessions.length + autoHighSessions.length;
+  const autoTarget = Math.ceil(sessions.length * 0.8);
+  const outputSessions = sessions.filter(hasClosureOutputLink)
+    .sort(compareCostThenTokens);
+  const nonLabelAdvice = roiAdvice.filter(item => (item.category || '') !== LABELING_CATEGORY);
+  const topGaps = buildClosureGapRows(sessions).slice(0, Math.max(1, topGapLimit));
+
+  const checks = [
+    {
+      id: 'real-attribution',
+      label: '人工确认归因',
+      current: manualSessions.length,
+      target: Math.max(1, targetAttributedSessions),
+      unit: 'sessions',
+      complete: manualSessions.length >= Math.max(1, targetAttributedSessions),
+      detail: '需要项目别名、任务类型、产出状态、工作目的、工作阶段和产出价值全部补齐。',
+      action: topGaps.length
+        ? formatGapAction(topGaps[0])
+        : '继续抽查高成本 session 的项目和价值是否真实。'
+    },
+    {
+      id: 'lazy-auto-attribution',
+      label: '懒人模式可用覆盖',
+      current: usableAttributionCount,
+      target: Math.max(1, autoTarget),
+      unit: 'sessions',
+      complete: manualSessions.length >= Math.max(1, targetAttributedSessions)
+        || usableAttributionCount >= Math.max(1, autoTarget),
+      detail: '人工确认和自动高置信完整归因都计入可用覆盖；自动归因不是人工事实。',
+      action: '在看板使用“一键自动填高置信度”，再抽查最高成本的低置信待确认 session。'
+    },
+    {
+      id: 'output-links',
+      label: '产出链接',
+      current: outputSessions.length,
+      target: Math.max(1, targetOutputLinks),
+      unit: 'links',
+      complete: outputSessions.length >= Math.max(1, targetOutputLinks),
+      detail: '只统计已完成或已发布 session 上保存的 URL；不抓取链接内容。',
+      action: '补充产出链接：给已完成或已发布的高价值 session 补 PR、commit、文章、部署、文档或截图 URL。'
+    },
+    {
+      id: 'non-label-advice',
+      label: '非补标注 Advisor',
+      current: nonLabelAdvice.length,
+      target: Math.max(1, targetNonLabelAdvice),
+      unit: 'items',
+      complete: nonLabelAdvice.length >= Math.max(1, targetNonLabelAdvice),
+      detail: '至少出现一条模型切换、上下文压缩、止损、保留策略或未定价模型建议。',
+      action: '补齐真实归因后重新查看 ROI Advisor，确认建议不再只停留在“先补标注”。'
+    }
+  ];
+
+  const completedChecks = checks.filter(check => check.complete).length;
+  const remainingChecks = checks.length - completedChecks;
+  const aggregate = aggregateSessions(sessions);
+
+  return {
+    status: remainingChecks === 0 ? 'complete' : 'needs-work',
+    completedChecks,
+    totalChecks: checks.length,
+    remainingChecks,
+    completionShare: checks.length ? completedChecks / checks.length : 0,
+    checks,
+    annotatedSessions: attributedSessions.slice(0, 10),
+    manualSessions: manualSessions.slice(0, 10),
+    autoHighSessions: autoHighSessions.slice(0, 10),
+    outputSessions: outputSessions.slice(0, 10),
+    nonLabelAdvice,
+    topGaps,
+    totals: {
+      sessionCount: sessions.length,
+      totalTokens: aggregate.totalTokens,
+      costUSD: aggregate.costUSD
+    },
+    nextActions: checks
+      .filter(check => !check.complete)
+      .map(check => check.action)
+  };
+}
+
+export function isClosureAttributedSession(session = {}) {
+  return Boolean(String(session.projectAlias || '').trim())
+    && missingReviewAttributionFields(session).length === 0;
+}
+
+export function isManualConfirmedSession(session = {}) {
+  const source = String(session.annotationSource || 'manual');
+  return isClosureAttributedSession(session)
+    && (source === 'manual' || source === 'imported');
+}
+
+export function isAutoHighConfidenceSession(session = {}) {
+  return isClosureAttributedSession(session)
+    && session.annotationSource === 'auto'
+    && Number(session.annotationConfidence || 0) >= 80;
+}
+
+export function hasClosureOutputLink(session = {}) {
+  const url = String(session.outputUrl || '').trim();
+  return PRODUCTIVE_STATUSES.has(session.outputStatus)
+    && /^https?:\/\//i.test(url);
+}
+
+function buildClosureGapRows(sessions = []) {
+  return sessions
+    .filter(session => !isClosureAttributedSession(session))
+    .map(session => ({
+      session,
+      device: session.device || '',
+      source: session.source || '',
+      project: sessionProjectLabel(session),
+      projectPath: session.projectPath || '',
+      sessionId: session.sessionId || '',
+      model: session.model || '',
+      lastActivity: session.lastActivity || '',
+      missingFields: missingClosureFields(session),
+      totalTokens: session.totalTokens || 0,
+      costUSD: session.costUSD || 0
+    }))
+    .sort(compareCostThenTokens);
+}
+
+function missingClosureFields(session = {}) {
+  const fields = [];
+  if (!String(session.projectAlias || '').trim()) fields.push('项目别名');
+  fields.push(...missingReviewAttributionFields(session));
+  return fields;
+}
+
+function formatGapAction(row) {
+  const subject = row.sessionId && row.sessionId !== row.project
+    ? `${row.project} 的 ${row.sessionId}`
+    : row.project || row.sessionId || '最高成本 session';
+  const fields = row.missingFields.length ? `，补齐${row.missingFields.join('、')}` : '';
+  return `先处理 ${subject}${fields}。`;
+}
+
+function compareCostThenTokens(a, b) {
+  const left = a.session || a;
+  const right = b.session || b;
+  return (right.costUSD || 0) - (left.costUSD || 0)
+    || (right.totalTokens || 0) - (left.totalTokens || 0);
+}