124 lines
6.1 KiB
Markdown
124 lines
6.1 KiB
Markdown
|
---
|
||
|
|
phase: 02-ranking-dashboard-ui
|
||
|
|
plan: 02
|
||
|
|
subsystem: ui
|
||
|
|
tags: [react, dnd-kit, trpc, ranking, drag-and-drop, sheet-panel]
|
||
|
|
|
||
|
|
# Dependency graph
|
||
|
|
requires:
|
||
|
|
- phase: 02-01
|
||
|
|
provides: RankingDashboard stub, saveReorder mutation, Ranking tab entry point
|
||
|
|
provides:
|
||
|
|
- Full RankingDashboard component with drag-and-drop reorder, AI vs override visual states, and Sheet-based juror evaluation detail panel
|
||
|
|
affects: [02-03-advance-projects]
|
||
|
|
|
||
|
|
# Tech tracking
|
||
|
|
tech-stack:
|
||
|
|
added: []
|
||
|
|
patterns:
|
||
|
|
- "useRef init guard: initialized.current prevents localOrder re-init from server data on every re-render — eliminates snap-back"
|
||
|
|
- "Fire-and-forget mutation inside setLocalOrder callback: setLocalOrder runs synchronously first, mutation fires async, no onSuccess invalidation"
|
||
|
|
- "Double cast via unknown: Prisma JsonValue cast to RankedProjectEntry[] requires (json ?? []) as unknown as RankedProjectEntry[]"
|
||
|
|
- "getFullDetail response shape: { project, assignments, stats } — title accessed as projectDetail.project.title"
|
||
|
|
|
||
|
|
key-files:
|
||
|
|
created: []
|
||
|
|
modified:
|
||
|
|
- src/components/admin/round/ranking-dashboard.tsx
|
||
|
|
|
||
|
|
key-decisions:
|
||
|
|
- "Double cast (as unknown as RankedProjectEntry[]) required for Prisma JsonValue — direct cast rejected by TypeScript strict mode"
|
||
|
|
- "getFullDetail returns { project, assignments, stats } shape, not flat — project title accessed via .project.title"
|
||
|
|
- "saveReorder mutation has no onSuccess invalidation — avoids triggering re-fetch that would reset localOrder"
|
||
|
|
|
||
|
|
patterns-established:
|
||
|
|
- "SortableProjectRow sub-component defined above export in same file (no separate file needed for inline sub-components)"
|
||
|
|
- "Per-category drag context: separate DndContext per category prevents cross-category drag"
|
||
|
|
|
||
|
|
requirements-completed: [DASH-01, DASH-02, DASH-03, DASH-04]
|
||
|
|
|
||
|
|
# Metrics
|
||
|
|
duration: 8min
|
||
|
|
completed: 2026-02-27
|
||
|
|
---
|
||
|
|
|
||
|
|
# Phase 2 Plan 02: Full RankingDashboard Component Summary
|
||
|
|
|
||
|
|
**Full RankingDashboard with per-category drag-and-drop (dnd-kit), AI vs override rank badges, snap-back-proof localOrder state, and lazy-loaded Sheet detail panel showing per-juror evaluation breakdown**
|
||
|
|
|
||
|
|
## Performance
|
||
|
|
|
||
|
|
- **Duration:** ~8 min
|
||
|
|
- **Started:** 2026-02-27T08:40:00Z
|
||
|
|
- **Completed:** 2026-02-27T08:48:11Z
|
||
|
|
- **Tasks:** 1
|
||
|
|
- **Files modified:** 1
|
||
|
|
|
||
|
|
## Accomplishments
|
||
|
|
|
||
|
|
- Replaced RankingDashboard stub with full 486-line implementation
|
||
|
|
- DASH-01: Ranked project list per category (STARTUP / BUSINESS_CONCEPT) with composite score, pass rate, and evaluator count displayed per row
|
||
|
|
- DASH-02: Drag-and-drop reorder via GripVertical handle using dnd-kit (DndContext + SortableContext + useSortable), fire-and-forget saveReorder mutation
|
||
|
|
- DASH-03: localOrder stored in useState with useRef guard (`initialized.current`) — init fires once on first snapshot load, never re-initialized from server data; no snap-back
|
||
|
|
- DASH-04: Sheet panel opens on row click, lazy-loads `trpc.project.getFullDetail` (enabled only when selectedProjectId is set), displays stats summary and per-juror evaluation list filtered to SUBMITTED assignments for the current round
|
||
|
|
- AI-order rows display dark-blue rank badge (#N); admin-reordered rows display amber `#N (override)` badge
|
||
|
|
- "Run Ranking" button in header card calls `triggerAutoRank`, resets `initialized.current` to allow re-init on new snapshot
|
||
|
|
- Empty categories show a placeholder message instead of an empty drag zone
|
||
|
|
- TypeScript strict mode: 0 errors; build: PASSED
|
||
|
|
|
||
|
|
## Task Commits
|
||
|
|
|
||
|
|
| Task | Name | Commit | Files |
|
||
|
|
|------|------|--------|-------|
|
||
|
|
| 1 | Build full RankingDashboard component | 6512e4e | src/components/admin/round/ranking-dashboard.tsx |
|
||
|
|
|
||
|
|
## Files Created/Modified
|
||
|
|
|
||
|
|
- `src/components/admin/round/ranking-dashboard.tsx` — Full component replacing stub (486 lines → includes SortableProjectRow sub-component + RankingDashboard main export)
|
||
|
|
|
||
|
|
## Decisions Made
|
||
|
|
|
||
|
|
- **Double cast via unknown**: `(json ?? []) as unknown as RankedProjectEntry[]` — TypeScript strict mode rejects direct cast from Prisma `JsonValue`; intermediate `unknown` is required. Matches pattern from Phase 01-03.
|
||
|
|
- **getFullDetail response shape**: The procedure returns `{ project, assignments, stats }` (not flat) — `projectDetail.project.title`, not `projectDetail.title`.
|
||
|
|
- **No onSuccess invalidation in saveReorder**: Calling `utils.ranking.getSnapshot.invalidate()` in `onSuccess` would trigger a re-fetch that resets `localOrder` to server data, causing snap-back. Mutation only shows toast on error.
|
||
|
|
- **Per-category DndContext**: Separate `DndContext` per category prevents accidental cross-category drags.
|
||
|
|
|
||
|
|
## Deviations from Plan
|
||
|
|
|
||
|
|
None — plan executed exactly as written. All type errors encountered were auto-fixed inline (Rule 1 — double cast pattern, Rule 1 — response shape).
|
||
|
|
|
||
|
|
### Auto-fixed Issues
|
||
|
|
|
||
|
|
**1. [Rule 1 - Bug] Prisma JsonValue cast requires double cast via unknown**
|
||
|
|
- **Found during:** Task 1 (typecheck)
|
||
|
|
- **Issue:** `(snapshot.startupRankingJson ?? []) as RankedProjectEntry[]` — TypeScript strict mode rejects because `JsonValue` and `RankedProjectEntry[]` don't sufficiently overlap
|
||
|
|
- **Fix:** Changed to `as unknown as RankedProjectEntry[]` (identical pattern used in Phase 01-03)
|
||
|
|
- **Files modified:** ranking-dashboard.tsx
|
||
|
|
- **Commit:** 6512e4e (same task commit)
|
||
|
|
|
||
|
|
**2. [Rule 1 - Bug] getFullDetail response shape — title not on root**
|
||
|
|
- **Found during:** Task 1 (typecheck)
|
||
|
|
- **Issue:** `projectDetail?.title` — getFullDetail returns `{ project, assignments, stats }`, not a flat object
|
||
|
|
- **Fix:** Changed to `projectDetail?.project.title`
|
||
|
|
- **Files modified:** ranking-dashboard.tsx
|
||
|
|
- **Commit:** 6512e4e (same task commit)
|
||
|
|
|
||
|
|
## Issues Encountered
|
||
|
|
|
||
|
|
None beyond the two auto-fixed type errors above.
|
||
|
|
|
||
|
|
## User Setup Required
|
||
|
|
|
||
|
|
None.
|
||
|
|
|
||
|
|
## Next Phase Readiness
|
||
|
|
|
||
|
|
- RankingDashboard fully functional — admin can view ranked projects, drag to reorder, see juror-level evaluation details in Sheet panel
|
||
|
|
- Plan 03 can now add the "Advance Projects" action button to the dashboard header
|
||
|
|
- saveReorder mutation is append-only audit log — Plan 03 can read latest reorder per category to determine final advance order
|
||
|
|
- Build and typecheck both pass with 0 errors
|
||
|
|
|
||
|
|
---
|
||
|
|
*Phase: 02-ranking-dashboard-ui*
|
||
|
|
*Completed: 2026-02-27*
|