feat(dashboard): D5 热力图效率维度 + R3 结束仪式 + R9 成就证书

Author: Aparencia

client/src/features/dashboard/components/HeatmapChart.tsx

@@ -28,25 +28,52 @@ function parseColor(v: string): [number, number, number] {
   return m ? [+m[1], +m[2], +m[3]] : [0, 0, 0];
 }
 
-/** 线性插值两个 hex 颜色 */
-function lerp(a: [number, number, number], b: [number, number, number], t: number) {
-  return `rgb(${Math.round(a[0] + (b[0] - a[0]) * t)},${Math.round(a[1] + (b[1] - a[1]) * t)},${Math.round(a[2] + (b[2] - a[2]) * t)})`;
+/** RGB 三元组线性插值（供多段混色链使用，避免 string 中间态） */
+function mix(a: [number, number, number], b: [number, number, number], t: number): [number, number, number] {
+  return [
+    Math.round(a[0] + (b[0] - a[0]) * t),
+    Math.round(a[1] + (b[1] - a[1]) * t),
+    Math.round(a[2] + (b[2] - a[2]) * t),
+  ];
+}
+
+/** RGB 三元组 → CSS 颜色串 */
+function toCss(c: [number, number, number]): string {
+  return `rgb(${c[0]},${c[1]},${c[2]})`;
 }
 
 const HeatmapChart: React.FC<Props> = ({ data, loading }) => {
-  const [tip, setTip] = useState<{ day: string; hour: number; val: number; x: number; y: number } | null>(null);
+  const [tip, setTip] = useState<{ day: string; hour: number; val: number; eff: number | null; peak: boolean; x: number; y: number } | null>(null);
 
-  const { max, bg, brand } = useMemo(() => {
+  const { max, bg, brand, gold } = useMemo(() => {
     const mx = Math.max(...data.map((c) => c.value), 1);
     const s = getComputedStyle(document.documentElement);
-    return { max: mx, bg: parseColor(s.getPropertyValue('--kb-bg-tertiary')), brand: parseColor(s.getPropertyValue('--kb-brand-500')) };
+    return {
+      max: mx,
+      bg: parseColor(s.getPropertyValue('--kb-bg-tertiary')),
+      brand: parseColor(s.getPropertyValue('--kb-brand-500')),
+      gold: parseColor(s.getPropertyValue('--kb-accent-400') || 'rgb(251,191,36)'),
+    };
+  }, [data]);
+
+  // D5 效率维度：有效样本的完成率均值（0-1），无样本为 null
+  const { maxEff, minEff } = useMemo(() => {
+    const effs = data.map((c) => c.efficiency).filter((e): e is number => e != null);
+    if (effs.length === 0) return { maxEff: 1, minEff: 0 };
+    return { maxEff: Math.max(...effs, 1), minEff: Math.min(...effs, 0) };
   }, [data]);
 
-  const cellColor = useCallback((v: number) => lerp(bg, brand, v / max), [bg, brand, max]);
+  // D5 单元格配色：亮度=分钟数（原语义），色相=效率（高→品牌金，低→灰蓝）
+  const cellColor = useCallback((c: HeatmapCell) => {
+    const base = mix(bg, brand, c.value / max);
+    if (c.efficiency == null) return toCss(base);
+    const t = maxEff === minEff ? 0.5 : (c.efficiency - minEff) / (maxEff - minEff);
+    return toCss(mix(base, gold, Math.min(1, Math.max(0, t)) * 0.55));
+  }, [bg, brand, gold, max, maxEff, minEff]);
 
   const onEnter = useCallback((e: React.MouseEvent, c: HeatmapCell) => {
     const r = (e.currentTarget as HTMLElement).getBoundingClientRect();
-    setTip({ day: DAYS[c.dayOfWeek], hour: c.hour, val: c.value, x: r.left + r.width / 2, y: r.top });
+    setTip({ day: DAYS[c.dayOfWeek], hour: c.hour, val: c.value, eff: c.efficiency ?? null, peak: c.peak ?? false, x: r.left + r.width / 2, y: r.top });
   }, []);
   const onLeave = useCallback(() => setTip(null), []);
 
@@ -75,7 +102,11 @@ const HeatmapChart: React.FC<Props> = ({ data, loading }) => {
               <div
                 key={`${c.dayOfWeek}-${c.hour}`}
                 className="h-[14px] rounded-[2px] cursor-pointer transition-opacity duration-150 hover:opacity-80"
-                style={{ backgroundColor: cellColor(c.value) }}
+                style={{
+                  backgroundColor: cellColor(c),
+                  // D5 黄金时段标注：高峰档格子加金色描边，突出个人高效窗口
+                  boxShadow: c.peak && c.value > 0 ? 'inset 0 0 0 1px rgba(251,191,36,0.55)' : undefined,
+                }}
                 onMouseEnter={(e) => onEnter(e, c)}
                 onMouseLeave={onLeave}
               />
@@ -84,6 +115,16 @@ const HeatmapChart: React.FC<Props> = ({ data, loading }) => {
         </div>
       </div>
 
+      {/* D5 图例：分钟数 + 黄金时段 */}
+      <div className="mt-2 flex flex-wrap items-center gap-x-4 gap-y-1 text-[10px] text-text-tertiary">
+        <span>颜色深浅 = 专注分钟数</span>
+        <span>颜色偏金 = 完成率更高</span>
+        <span className="flex items-center gap-1">
+          <span className="inline-block w-3 h-3 rounded-[2px]" style={{ boxShadow: 'inset 0 0 0 1px rgba(251,191,36,0.55)', backgroundColor: 'rgba(251,191,36,0.15)' }} />
+          黄金时段（个人高峰档）
+        </span>
+      </div>
+
       {/* Tooltip */}
       {tip && (
         <div
@@ -92,6 +133,10 @@ const HeatmapChart: React.FC<Props> = ({ data, loading }) => {
         >
           <span className="text-text-secondary">{tip.day} {tip.hour}:00</span>
           <span className="text-text-primary font-medium ml-1.5">{tip.val}分钟</span>
+          {tip.eff != null && (
+            <span className="text-text-secondary ml-1.5">完成率 {Math.round(tip.eff * 100)}%</span>
+          )}
+          {tip.peak && <span className="text-amber-400 ml-1.5">✦ 黄金时段</span>}
         </div>
       )}
     </div>

client/src/features/dashboard/components/StartupRitual.tsx

@@ -22,6 +22,7 @@ import { RitualStepGoal } from './ritual/RitualStepGoal';
 import { RitualStepIntention } from './ritual/RitualStepIntention';
 import { RitualStepBreathing } from './ritual/RitualStepBreathing';
 import { RitualComplete } from './ritual/RitualComplete';
+import { ClosingCeremony } from './ritual/ClosingCeremony';
 import { RitualSkipMenu } from './ritual/RitualSkipMenu';
 import { RitualFooter } from './ritual/RitualFooter';
 
@@ -59,6 +60,10 @@ export default function StartupRitual(props: Props) {
   const [triggerTime, setTriggerTime] = useState('');
   const [cycleLit, setCycleLit] = useState(false);
   const [done, setDone] = useState(false);
+  // R3 结束仪式分支：RitualComplete 定格后追加 closingCeremony（总结+复习卡闭环）
+  const [closing, setClosing] = useState(false);
+  // 进入结束仪式时冻结仪式用时（不把用户在结束仪式的停留计入 durationMs）
+  const finalDurationMsRef = useRef<number | null>(null);
   const [sound, setSound] = useState(soundOn);
   const cardRef = useRef<HTMLDivElement>(null);
 
@@ -86,7 +91,7 @@ export default function StartupRitual(props: Props) {
       goal: goalText.trim() ? ({ text: goalText.trim(), tags: pickedTags } as MicroGoal) : undefined,
       masteryMark: mastery ?? undefined,
       intention,
-      durationMs: machine.getElapsedMs(),
+      durationMs: finalDurationMsRef.current ?? machine.getElapsedMs(),
       planVariant: machine.planVariant,
     };
   }, [goalText, pickedTags, mastery, machine, intentionIf, intentionThen, buildTriggerAt]);
@@ -96,6 +101,18 @@ export default function StartupRitual(props: Props) {
     machine.next();
   }, [machine]);
 
+  /** R3 结束仪式：RitualComplete 定格完成后进入 closing 分支（不直接落库） */
+  const handleCompleteEnter = useCallback(() => {
+    // 冻结仪式用时：不含用户在结束仪式上的停留时间
+    finalDurationMsRef.current = machine.getElapsedMs();
+    setClosing(true);
+  }, [machine]);
+
+  /** 结束仪式收尾：页面层经 onComplete 落库 + 复习卡闭环 */
+  const handleClosingClose = useCallback(() => {
+    onComplete(buildOutcome());
+  }, [onComplete, buildOutcome]);
+
   const handlePickTag = useCallback((tag: QuickTag) => {
     setGoalText(tag.text);
     setPickedTags((prev) => (prev.includes(tag.text) ? prev : [...prev, tag.text]));
@@ -138,12 +155,22 @@ export default function StartupRitual(props: Props) {
         <BreathingProvider onPhaseChange={onPhaseChange} onCycleComplete={onCycleComplete}>
           <div className="relative px-8 pt-10 pb-8 flex flex-col gap-6">
             {done ? (
-              <RitualComplete
-                goal={buildOutcome().goal}
-                masteryMark={mastery ?? undefined}
-                streakDays={streakDays}
-                onEnter={() => onComplete(buildOutcome())}
-              />
+              closing ? (
+                <ClosingCeremony
+                  goal={buildOutcome().goal}
+                  masteryMark={mastery ?? undefined}
+                  streakDays={streakDays}
+                  durationMs={machine.getElapsedMs()}
+                  onClose={handleClosingClose}
+                />
+              ) : (
+                <RitualComplete
+                  goal={buildOutcome().goal}
+                  masteryMark={mastery ?? undefined}
+                  streakDays={streakDays}
+                  onEnter={handleCompleteEnter}
+                />
+              )
             ) : (
               <>
                 {machine.currentStep === 'review' && (

client/src/features/dashboard/components/deep-sea/creatures/AnglerfishAchievements.tsx

@@ -6,25 +6,26 @@
 import { useEffect, useState } from 'react';
 import { motion } from 'framer-motion';
 import {
-  Timer, Layers, Lightbulb, FileText, Flame, Trophy, Medal,
+  Timer, Layers, Lightbulb, FileText, Flame, Trophy, Medal, Repeat, ListChecks, Award,
   type LucideIcon,
 } from 'lucide-react';
 import { cn } from '@/lib/utils';
 import { db } from '@/lib/storage/database';
 import { ACHIEVEMENT_DEFS } from '@/lib/achievements/definitions';
 import type { Achievement } from '@/types/models';
 import { useReducedMotion } from '@/hooks/useReducedMotion';
+import { useNavigate } from 'react-router-dom';
 
-const ICON_MAP: Record<string, LucideIcon> = { Timer, Layers, Lightbulb, FileText, Flame, Trophy, Medal };
+const ICON_MAP: Record<string, LucideIcon> = { Timer, Layers, Lightbulb, FileText, Flame, Trophy, Medal, Repeat, ListChecks };
 
 function formatDate(date: Date): string {
   const d = new Date(date);
   return `${d.getMonth() + 1}/${d.getDate()}`;
 }
 
 export default function AnglerfishAchievements() {
+  const navigate = useNavigate();
   const [unlockedMap, setUnlockedMap] = useState<Record<string, Achievement>>({});
-  const [loading, setLoading] = useState(true);
   const prefersReduced = useReducedMotion();
 
   useEffect(() => {
@@ -34,8 +35,7 @@ export default function AnglerfishAchievements() {
         const map: Record<string, Achievement> = {};
         achievements.forEach((a) => { map[a.key] = a; });
         setUnlockedMap(map);
-      })
-      .finally(() => setLoading(false));
+      });
   }, []);
 
   const unlockedCount = Object.keys(unlockedMap).length;
@@ -50,7 +50,17 @@ export default function AnglerfishAchievements() {
       {/* 标题 */}
       <div className="flex items-center justify-between mb-2">
         <h3 className="text-[10px] font-medium text-cyan-200/60">灯笼鱼成就</h3>
-        <span className="text-[9px] text-amber-300/50">{unlockedCount}/{ACHIEVEMENT_DEFS.length}</span>
+        <div className="flex items-center gap-2">
+          <span className="text-[9px] text-amber-300/50">{unlockedCount}/{ACHIEVEMENT_DEFS.length}</span>
+          {/* R9 成就证书入口：跳转打印页生成证书 */}
+          <button
+            onClick={() => navigate('/certificate')}
+            className="flex items-center gap-0.5 text-[9px] text-cyan-200/50 hover:text-cyan-200 transition-colors"
+            title="生成成就证书"
+          >
+            <Award className="w-3 h-3" strokeWidth={1.5} /> 证书
+          </button>
+        </div>
       </div>
 
       {/* 成就网格 */}

client/src/features/dashboard/components/ritual/ClosingCeremony.test.tsx

@@ -0,0 +1,60 @@
+/**
+ * ClosingCeremony 组件测试 / Tests for the R3 closing ceremony branch
+ *
+ * @ai-context: 覆盖结束仪式契约——总结卡（目标/掌握/用时/连续天数）渲染、
+ * 复习卡闭环三态文案（模糊/未掌握→已安排、已掌握→无需、未标记→引导）、
+ * 开始学习按钮触发 onClose。
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, screen, cleanup, fireEvent } from '@testing-library/react';
+import { ClosingCeremony } from './ClosingCeremony';
+
+afterEach(() => {
+  cleanup();
+});
+
+describe('ClosingCeremony (R3)', () => {
+  it('should render summary card with goal, mastery, duration and streak', () => {
+    render(
+      <ClosingCeremony
+        goal={{ text: '搞懂傅里叶变换', tags: [] }}
+        masteryMark="fuzzy"
+        streakDays={3}
+        durationMs={125_000}
+        onClose={() => {}}
+      />,
+    );
+    expect(screen.getByText(/今日仪式完成/)).toBeInTheDocument();
+    expect(screen.getByText(/今日目标：搞懂傅里叶变换/)).toBeInTheDocument();
+    expect(screen.getByText(/上次掌握度：模糊/)).toBeInTheDocument();
+    expect(screen.getByText(/仪式用时：2 分 5 秒/)).toBeInTheDocument();
+    expect(screen.getByText(/连续 3 天/)).toBeInTheDocument();
+  });
+
+  it('should announce review card planned for fuzzy mark (closure loop)', () => {
+    render(<ClosingCeremony masteryMark="fuzzy" streakDays={1} durationMs={1000} onClose={() => {}} />);
+    expect(screen.getByText(/已为你安排 1 张复习卡/)).toBeInTheDocument();
+  });
+
+  it('should announce review card planned for unmastered mark', () => {
+    render(<ClosingCeremony masteryMark="unmastered" streakDays={1} durationMs={1000} onClose={() => {}} />);
+    expect(screen.getByText(/已为你安排 1 张复习卡/)).toBeInTheDocument();
+  });
+
+  it('should not plan review card when mastered', () => {
+    render(<ClosingCeremony masteryMark="mastered" streakDays={1} durationMs={1000} onClose={() => {}} />);
+    expect(screen.getByText(/已掌握的内容无需额外复习卡/)).toBeInTheDocument();
+  });
+
+  it('should guide user when mastery not marked', () => {
+    render(<ClosingCeremony streakDays={1} durationMs={1000} onClose={() => {}} />);
+    expect(screen.getByText(/标记掌握度后可为模糊内容安排复习卡/)).toBeInTheDocument();
+  });
+
+  it('should call onClose when start button clicked', () => {
+    const onClose = vi.fn();
+    render(<ClosingCeremony streakDays={1} durationMs={1000} onClose={onClose} />);
+    fireEvent.click(screen.getByRole('button', { name: /开始学习/ }));
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+});