Feature/add circle graph and flask

.claude/rules/coding-style.md

@@ -26,6 +26,7 @@ Before writing new logic, decide which layer it belongs to. Run this check at pl
 - **Abbreviations**: avoid non-standard abbreviations (`res` → `response`, `btn` → `button`). When in doubt, spell it out.
 - **Lambda parameters**: no single-character names (e.g., use `placement`, `workbook`). Iterator index `i` is the only exception.
 - **`upsert`**: only use when the implementation performs both insert and update. For insert-only, use `initialize`, `seed`, or another accurate verb.
+- **Function verbs**: every function name must start with a verb. Noun-only names (`pointOnCircle`, `arcPath`) are ambiguous — use `calcPointOnCircle`, `buildArcPath`, etc. Common prefixes: `get` (read existing), `build`/`create` (construct new), `calc`/`compute` (derive by formula), `update`, `fetch`, `resolve`.
 - **`any`**: before using `any`, check the value's origin — adding a missing `@types/*` or `devDependency` often provides the correct type. When `any` seems unavoidable, use the narrowest alternative:
 
   | Situation                                                  | Alternative                                                              |
@@ -47,6 +48,7 @@ Before writing new logic, decide which layer it belongs to. Run this check at pl
 ### Syntax
 
 - **Braces**: always use braces for single-statement `if` blocks. Never `if () return;` — write `if () { return; }`.
+- **Domain types over `string`**: when the Prisma schema uses an enum (e.g. `grade: TaskGrade`), the corresponding app-layer type must use the same enum — not `string`. A loose `string` type hides misspellings in fixtures and forces `as TaskGrade` casts throughout the codebase. When a field comes from an external source (form data, query params), validate and narrow it at the boundary; inside the app it must always be the domain type.
 - **Plural type aliases**: define `type Placements = Placement[]` instead of using `Placement[]` directly in signatures and variables.
 - **Empty `catch` blocks**: never use `catch { }` or `catch (_e)` to silence errors. Every `catch` must re-throw, log, or contain an explanatory comment justifying the suppression. Silent swallowing hides bugs and makes failures untraceable.
 
@@ -126,15 +128,7 @@ Common identifiers: `typescript`, `svelte`, `sql`, `bash`, `mermaid`, `json`, `p
 
 ### Svelte 5: Prefer Official Docs Over Training Knowledge
 
-When Svelte 5 behavior is unclear, fetch the official docs directly via WebFetch instead of relying on training knowledge.
-
-URL pattern: `https://svelte.dev/docs/svelte/{section}`
-
-Examples:
-
-- `$effect` behavior → `https://svelte.dev/docs/svelte/$effect`
-- Stores usage → `https://svelte.dev/docs/svelte/stores`
-- Runes overview → `https://svelte.dev/docs/svelte/what-are-runes`
+When Svelte 5 behavior is unclear, fetch official docs via WebFetch — do not rely on training knowledge. URL pattern: `https://svelte.dev/docs/svelte/{section}` (e.g. `/$effect`, `/stores`, `/what-are-runes`).
 
 ## Security
 

.claude/rules/svelte-components.md

@@ -68,6 +68,20 @@ Define snippets at the **top level**, outside component tags. Inside a tag = nam
 <Dialog>{#snippet footer()}...{/snippet}</Dialog>
 ```
 
+## `{#snippet}` Parameter Types
+
+Snippet parameters do not infer types from call sites — always annotate explicitly or TypeScript will error with "implicitly has an 'any' type":
+
+```svelte
+<!-- Bad: implicit any → svelte-check error -->
+{#snippet segmentLabel(segment)}
+
+<!-- Good -->
+{#snippet segmentLabel(segment: DonutSegment)}
+```
+
+Import the type in `<script lang="ts">` as usual.
+
 ## Snippet vs Component
 
 Prefer `{#snippet}` when: (1) needs direct `$state` access, (2) pure display only, (3) same-file DRY.

.claude/rules/testing.md

@@ -58,6 +58,10 @@ E2E test files must use the `.spec.ts` extension. `playwright.config.ts` matches
 - For DB query tests, assert `orderBy`, `include`, and other significant parameters with `expect.objectContaining` — not just `where`. When a returned field (e.g. `authorName`) depends on an `include` relation, that `include` clause must be part of the assertion, or a regression in the query shape will go undetected
 - Enum membership: `in` traverses the prototype chain; use `Object.hasOwn(Enum, value)` instead
 
+## Test Stubs
+
+Test stub parameter types must match the production function's signature — use domain types (e.g. `TaskGrade`), not `string`; a mismatch compiles silently but lets the stub accept inputs the real function would reject.
+
 ## Test Data
 
 - Use realistic fixture values (real task IDs, grade names) instead of placeholders like `'t1'`
@@ -118,8 +122,6 @@ try {
 }
 ```
 
-This is not needed for standard service unit tests that use Prisma mocks.
-
 ### File Split for Testability
 
 When a service file mixes DB operations and pure functions, split it into two files:

src/features/tasks/fixtures/contest-table/contest_table_provider.ts

@@ -1,4 +1,4 @@
-import type { TaskResult, TaskResults } from '$lib/types/task';
+import { TaskGrade, type TaskResult, type TaskResults } from '$lib/types/task';
 
 // Default task result with minimal initialization.
 // Most fields are empty strings as they're not relevant for these tests.
@@ -26,7 +26,7 @@ const defaultTaskResult: Readonly<TaskResult> = {
   task_table_index: '',
   task_id: '',
   title: '',
-  grade: '',
+  grade: TaskGrade.PENDING,
   updated_at: new Date(0), // Use the Unix epoch as the default value.
 };
 

src/features/votes/components/VotableGrade.svelte

@@ -5,10 +5,11 @@
 
   import { Dropdown, DropdownItem, DropdownDivider } from 'flowbite-svelte';
   import Check from '@lucide/svelte/icons/check';
+  import FlaskConical from '@lucide/svelte/icons/flask-conical';
 
   import { TaskGrade, getTaskGrade, type TaskResult } from '$lib/types/task';
   import { getTaskGradeLabel } from '$lib/utils/task';
-  import { nonPendingGrades } from '$features/votes/utils/grade_options';
+  import { nonPendingGrades, resolveDisplayGrade } from '$features/votes/utils/grade_options';
   import { SIGNUP_PAGE, LOGIN_PAGE, EDIT_PROFILE_PAGE } from '$lib/constants/navbar-links';
   import { errorMessageStore } from '$lib/stores/error_message';
 
@@ -20,18 +21,15 @@
     isLoggedIn: boolean;
     // undefined means the prop was not passed — treat as verified to maintain backward compatibility.
     isAtCoderVerified?: boolean;
-    estimatedGrade?: string;
+    estimatedGrade?: TaskGrade | null;
   }
 
   let { taskResult, isLoggedIn, isAtCoderVerified, estimatedGrade }: Props = $props();
 
   // 表示用のグレード（投票後に画面リロードなしで差し替えるためのローカル状態）
   // PENDING かつ estimatedGrade（集計済み中央値）があればそれを優先表示。
   // DBグレード付与済みの場合はそちらを優先。
-  const initialGrade =
-    taskResult.grade === TaskGrade.PENDING
-      ? (estimatedGrade ?? taskResult.grade)
-      : taskResult.grade;
+  const initialGrade = resolveDisplayGrade(taskResult.grade, estimatedGrade);
   let displayGrade = $state<TaskGrade | string>(initialGrade);
 
   // Use task_id as a deterministic component ID to avoid SSR/hydration mismatches.
@@ -43,6 +41,10 @@
   let showForm = $state(false);
   let formElement = $state<HTMLFormElement | undefined>(undefined);
 
+  const isProvisional = $derived(
+    taskResult.grade === TaskGrade.PENDING && displayGrade !== TaskGrade.PENDING,
+  );
+
   let isOpening = $state(false);
   let votedGrade = $state<TaskGrade | null>(null);
 
@@ -137,22 +139,34 @@
 </script>
 
 <!-- Grade Icon（全問題で投票ドロップダウンを表示） -->
-<button
-  id={`update-grade-dropdown-trigger-${componentId}`}
-  class="relative group shrink-0 cursor-pointer"
-  type="button"
-  tabindex="0"
-  aria-label="Vote grade"
-  onclick={() => onTriggerClick()}
->
-  <GradeLabel taskGrade={displayGrade} defaultPadding={0.25} defaultWidth={6} reducedWidth={6} />
-
-  <!-- Overlay -->
-  <span
-    aria-hidden="true"
-    class="pointer-events-none absolute inset-0 rounded-lg bg-gray-200 dark:bg-gray-700 mix-blend-multiply opacity-0 transition-opacity duration-150 group-hover:opacity-100"
-  ></span>
-</button>
+<div class="inline-flex items-center gap-1">
+  {#if isProvisional}
+    <FlaskConical
+      class="w-3.5 h-3.5 shrink-0 text-gray-400 dark:text-gray-500"
+      aria-label="暫定グレード"
+    />
+  {/if}
+
+  <button
+    id={`update-grade-dropdown-trigger-${componentId}`}
+    class="relative group shrink-0 cursor-pointer"
+    type="button"
+    tabindex="0"
+    onclick={() => onTriggerClick()}
+  >
+    <span class="sr-only">
+      Voted grade: {getTaskGradeLabel(displayGrade)}{isProvisional ? ', provisional' : ''}
+    </span>
+
+    <GradeLabel taskGrade={displayGrade} defaultPadding={0.25} defaultWidth={6} reducedWidth={6} />
+
+    <!-- Overlay -->
+    <span
+      aria-hidden="true"
+      class="pointer-events-none absolute inset-0 rounded-lg bg-gray-200 dark:bg-gray-700 mix-blend-multiply opacity-0 transition-opacity duration-150 group-hover:opacity-100"
+    ></span>
+  </button>
+</div>
 
 <!-- Dropdown Menu -->
 {#if isLoggedIn && isAtCoderVerified !== false}

src/features/votes/components/VoteDonutChart.svelte

@@ -0,0 +1,194 @@
+<script lang="ts">
+  import type { VotedGradeCounter } from '@prisma/client';
+  import { TaskGrade } from '$lib/types/task';
+  import type { DonutSegment } from '$features/votes/types/donut_graph';
+
+  import { getTaskGradeColor, getTaskGradeLabel } from '$lib/utils/task';
+  import { nonPendingGrades } from '$features/votes/utils/grade_options';
+  import {
+    buildDonutSegments,
+    buildArcPath,
+    calcPointOnCircle,
+  } from '$features/votes/utils/donut_chart';
+
+  type VotedGradeCounters = VotedGradeCounter[];
+
+  interface Props {
+    counters: VotedGradeCounters;
+    totalVotes: number;
+    /** Median grade to indicate with a radial line. Omit when stats are unavailable. */
+    medianGrade?: TaskGrade | null;
+    /** The grade the current user voted for. Shows a ✅ on the matching segment. */
+    votedGrade?: TaskGrade | null;
+  }
+  let { counters, totalVotes, medianGrade = null, votedGrade = null }: Props = $props();
+
+  const CX = 160;
+  const CY = 155;
+  const OUTER_RADIUS = 120;
+  const INNER_RADIUS = 50;
+  const RING_MID_RADIUS = (INNER_RADIUS + OUTER_RADIUS) / 2;
+
+  const segments = $derived(
+    buildDonutSegments(nonPendingGrades, counters, getTaskGradeColor, getTaskGradeLabel),
+  );
+</script>
+
+<svg viewBox="0 0 320 310" class="w-full max-w-lg mx-auto" role="img" aria-label="投票分布円グラフ">
+  <title>投票分布</title>
+  <defs>
+    <!-- Metallic gradient for D6 segment, matching the vote button style.
+         objectBoundingBox ensures the gradient spans the segment itself. -->
+    {@render metallicGradient()}
+  </defs>
+
+  {#if totalVotes >= 1}
+    {#each segments as segment (segment.grade)}
+      {@render segmentPath(segment)}
+    {/each}
+
+    <!-- Median grade indicator line: the chart starts at the top and the median
+         always falls at the 50% cumulative mark, which is fixed at the bottom. -->
+    {#if medianGrade}
+      {@render medianIndicator()}
+    {/if}
+
+    {#each segments as segment (segment.grade)}
+      {@render segmentLabel(segment)}
+    {/each}
+  {:else}
+    <!-- Show empty ring when there are no votes -->
+    {@render emptyRing()}
+  {/if}
+
+  {@render totalVotedCount()}
+</svg>
+
+{#snippet metallicGradient()}
+  <linearGradient id="d6-metallic" x1="0%" y1="0%" x2="100%" y2="100%">
+    <stop offset="0%" stop-color="#432414" />
+    <stop offset="40%" stop-color="rgb(120, 113, 108)" />
+    <stop offset="70%" stop-color="rgb(217, 119, 6)" />
+    <stop offset="100%" stop-color="#432414" />
+  </linearGradient>
+{/snippet}
+
+{#snippet segmentPath(segment: DonutSegment)}
+  <path
+    d={buildArcPath(
+      { x: CX, y: CY },
+      OUTER_RADIUS,
+      INNER_RADIUS,
+      segment.startAngle,
+      segment.endAngle,
+    )}
+    fill={segment.grade === TaskGrade.D6 ? 'url(#d6-metallic)' : segment.color}
+  />
+{/snippet}
+
+{#snippet medianIndicator()}
+  <line
+    x1={CX}
+    y1={CY + INNER_RADIUS}
+    x2={CX}
+    y2={CY + OUTER_RADIUS}
+    stroke="black"
+    stroke-width="2.5"
+    stroke-linecap="round"
+    class="dark:stroke-white"
+  />
+  <text
+    x={CX}
+    y={CY + OUTER_RADIUS + 14}
+    text-anchor="middle"
+    class="fill-gray-700 dark:fill-gray-300"
+    font-size="11">中央値</text
+  >
+{/snippet}
+
+{#snippet segmentLabel(segment: DonutSegment)}
+  {@const labelPoint = calcPointOnCircle({ x: CX, y: CY }, RING_MID_RADIUS, segment.midAngle)}
+  {@const labelX = labelPoint.x}
+  {@const labelY = labelPoint.y}
+  {@const label = segment.grade === votedGrade ? `✅ ${segment.label}` : segment.label}
+
+  {#if segment.percentage >= 10}
+    <text
+      x={labelX}
+      y={labelY - 7}
+      text-anchor="middle"
+      dominant-baseline="middle"
+      fill="white"
+      stroke="rgba(0,0,0,0.55)"
+      stroke-width="2.5"
+      paint-order="stroke"
+      font-size="11"
+      font-weight="bold"
+    >
+      {label}
+    </text>
+    <text
+      x={labelX}
+      y={labelY + 8}
+      text-anchor="middle"
+      dominant-baseline="middle"
+      fill="white"
+      stroke="rgba(0,0,0,0.55)"
+      stroke-width="2"
+      paint-order="stroke"
+      font-size="9.5"
+    >
+      {segment.count}票 ({segment.percentage}%)
+    </text>
+  {:else if segment.percentage >= 5}
+    <text
+      x={labelX}
+      y={labelY}
+      text-anchor="middle"
+      dominant-baseline="middle"
+      fill="white"
+      stroke="rgba(0,0,0,0.55)"
+      stroke-width="2.5"
+      paint-order="stroke"
+      font-size="11"
+      font-weight="bold"
+    >
+      {label}
+    </text>
+  {/if}
+{/snippet}
+
+{#snippet emptyRing()}
+  <circle
+    cx={CX}
+    cy={CY}
+    r={RING_MID_RADIUS}
+    fill="none"
+    stroke="currentColor"
+    stroke-width={OUTER_RADIUS - INNER_RADIUS}
+    class="text-gray-200 dark:text-gray-700"
+    opacity="0.5"
+  />
+{/snippet}
+
+{#snippet totalVotedCount()}
+  <text
+    x={CX}
+    y={CY - 6}
+    text-anchor="middle"
+    class="fill-gray-800 dark:fill-gray-200"
+    font-size="28"
+    font-weight="bold"
+  >
+    {totalVotes}
+  </text>
+  <text
+    x={CX}
+    y={CY + 16}
+    text-anchor="middle"
+    class="fill-gray-500 dark:fill-gray-400"
+    font-size="13"
+  >
+    票
+  </text>
+{/snippet}