test: define competition series history
This commit is contained in:
1 parent
075fb52848
commit
9f698a8fec
4 files changed
+900
No files matched your search
@@ -0,0 +1,122 @@
|
||||
# Implementation Plan: Series Result History UI
|
||||
|
||||
## Overview
|
||||
|
||||
Replace the existing completed-Game mini-card grid with a tested chronological
|
||||
Series result history. Keep data derivation pure, render responsive semantic rows,
|
||||
and preserve all current Competition/API contracts.
|
||||
|
||||
## Architecture Decisions
|
||||
|
||||
- Derive a local view model from `projection.series` and `projection.games`; no API
|
||||
or persistence change is required.
|
||||
- Anchor a played Series to its earliest accepted Game start. Anchor a game-less
|
||||
completed decision to its decision time only for grouping and sorting.
|
||||
- Keep the original narrowed Series and Game objects in each row so the UI does not
|
||||
duplicate domain state or collapse outcome semantics.
|
||||
- Use a native `details/summary` disclosure for Game history and omit it when a
|
||||
Series has no Games.
|
||||
- Extract the new UI from `CompetitionResults.tsx` so the format selector remains
|
||||
focused.
|
||||
|
||||
## Task List
|
||||
|
||||
### Phase 1: Result-History Contract
|
||||
|
||||
#### Task 1: Specify aggregation and chronology test-first
|
||||
|
||||
**Acceptance criteria:**
|
||||
|
||||
- [ ] Tests cover Series aggregation, ordinal Game order, KST date boundaries,
|
||||
chronological order, outcome variants, and deterministic fallbacks.
|
||||
- [ ] The focused test fails because the model module does not yet exist.
|
||||
|
||||
**Verification:**
|
||||
|
||||
- [ ] Run the focused Node test and record the expected RED failure.
|
||||
|
||||
**Files likely touched:**
|
||||
|
||||
- `apps/web/test/competition-series-history.test.ts`
|
||||
|
||||
#### Task 2: Implement the pure history model
|
||||
|
||||
**Acceptance criteria:**
|
||||
|
||||
- [ ] Only recorded in-progress and completed Series are returned.
|
||||
- [ ] Date grouping and format helpers are explicitly KST-aware.
|
||||
- [ ] Decision outcomes and missing legacy durations remain distinguishable.
|
||||
|
||||
**Verification:**
|
||||
|
||||
- [ ] Focused history tests pass.
|
||||
- [ ] Existing web tests still pass.
|
||||
|
||||
**Files likely touched:**
|
||||
|
||||
- `apps/web/src/components/competition/competition-series-history.ts`
|
||||
- `apps/web/test/competition-series-history.test.ts`
|
||||
|
||||
### Checkpoint: Model
|
||||
|
||||
- [ ] Pure tests pass without a React or browser dependency.
|
||||
|
||||
### Phase 2: Responsive Result UI
|
||||
|
||||
#### Task 3: Render date sections and Series rows
|
||||
|
||||
**Acceptance criteria:**
|
||||
|
||||
- [ ] Desktop uses a flat schedule-like row; mobile stacks metadata and matchup
|
||||
without horizontal scrolling.
|
||||
- [ ] Status and official winner are communicated with visible text and typography,
|
||||
not color alone.
|
||||
- [ ] Game-less decisions do not show fake start times or `0 : 0`.
|
||||
|
||||
**Verification:**
|
||||
|
||||
- [ ] Changed component files pass ESLint.
|
||||
- [ ] Web build succeeds.
|
||||
|
||||
**Files likely touched:**
|
||||
|
||||
- `apps/web/src/components/competition/CompetitionSeriesHistory.tsx`
|
||||
|
||||
#### Task 4: Integrate accessible Game disclosures
|
||||
|
||||
**Acceptance criteria:**
|
||||
|
||||
- [ ] Each Series with Games exposes a native keyboard-operable disclosure.
|
||||
- [ ] Games use Series-local ordinal, team-ID winner lookup, and omit unknown
|
||||
zero-duration values.
|
||||
- [ ] The old completed-Game mini-card block is removed.
|
||||
|
||||
**Verification:**
|
||||
|
||||
- [ ] Full web tests, lint, and build pass.
|
||||
- [ ] Source review checks heading order, disclosure semantics, and 320px layout.
|
||||
|
||||
**Files likely touched:**
|
||||
|
||||
- `apps/web/src/components/competition/CompetitionSeriesHistory.tsx`
|
||||
- `apps/web/src/components/competition/CompetitionResults.tsx`
|
||||
|
||||
### Checkpoint: Complete
|
||||
|
||||
- [ ] All specification success criteria are met.
|
||||
- [ ] Git diff contains only the feature spec, plan, tests, model, and UI integration.
|
||||
- [ ] Unrelated working-tree files are unchanged.
|
||||
|
||||
## Risks and Mitigations
|
||||
|
||||
| Risk | Impact | Mitigation |
|
||||
|---|---|---|
|
||||
| Game sides are mistaken for Series slots | High | Use Series A/B entries and outcome team IDs; test side swaps. |
|
||||
| Completion time is shown as start time | Medium | Track timestamp source and render a blank time for decisions. |
|
||||
| KST day changes by deploy environment | Medium | Use explicit `Intl.DateTimeFormat` timezone and boundary tests. |
|
||||
| Long team names break mobile rows | Medium | Use balanced minmax columns and allow wrapping. |
|
||||
| Existing dirty work is overwritten | High | Restrict patches and verification to named feature files. |
|
||||
|
||||
## Open Questions
|
||||
|
||||
None.
|
||||
@@ -0,0 +1,131 @@
|
||||
# Spec: Series Result History UI
|
||||
|
||||
## Objective
|
||||
|
||||
Replace the compact `Game N - winner` cards below Competition brackets with a
|
||||
chronological, Series-centric result history. Users should be able to scan when a
|
||||
Series was played, its round, participants, official result, and current score,
|
||||
then expand the row to inspect the accepted Games that produced that record.
|
||||
|
||||
This first version is a truthful activity/result history, not a future schedule.
|
||||
It uses only recorded Competition projection data and does not invent scheduled
|
||||
times, venues, replay links, or team logos.
|
||||
|
||||
## Approved Product Decisions
|
||||
|
||||
- Keep the bracket first as the topology view and place the chronological history
|
||||
below it.
|
||||
- Render one primary row per Series, never one primary row per Game.
|
||||
- Include a started `in-progress` Series when it has at least one accepted Game, so
|
||||
completed Games do not disappear while a best-of Series is still running.
|
||||
- Include every completed Series, including draw, walkover, forfeit, and
|
||||
administrative outcomes with no accepted Game.
|
||||
- Exclude inactive, waiting, ready, and game-less in-progress Series because they do
|
||||
not have a truthful result timestamp.
|
||||
- Use the earliest accepted Game `startedAt` as the Series activity time. For a
|
||||
game-less decision, group by `outcome.completedAt` but display no fake start time.
|
||||
- Group and format dates explicitly in `Asia/Seoul`.
|
||||
- Keep individual Games in a native, keyboard-accessible disclosure below the Series
|
||||
row.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- React 19 and TypeScript 6 under `apps/web`
|
||||
- Tailwind CSS 4 and daisyUI semantic tokens
|
||||
- Shared Competition contracts from `@lolympus/contracts`
|
||||
- Node's built-in test runner with TypeScript type stripping for pure model tests
|
||||
|
||||
## Commands
|
||||
|
||||
- Focused RED/GREEN test:
|
||||
`pnpm --filter web exec node --test --experimental-strip-types test/competition-series-history.test.ts`
|
||||
- Full web tests: `pnpm --filter web test`
|
||||
- Web lint: `pnpm --filter web lint`
|
||||
- Web build: `pnpm --filter web build`
|
||||
|
||||
## Project Structure
|
||||
|
||||
- `apps/web/src/components/competition/competition-series-history.ts` derives the
|
||||
stable, timezone-aware history view model without React.
|
||||
- `apps/web/src/components/competition/CompetitionSeriesHistory.tsx` renders the
|
||||
semantic date sections, responsive Series rows, and Game disclosures.
|
||||
- `apps/web/src/components/competition/CompetitionResults.tsx` replaces the existing
|
||||
completed-Game card grid with the new component.
|
||||
- `apps/web/test/competition-series-history.test.ts` specifies aggregation, ordering,
|
||||
outcome, and formatting behavior.
|
||||
|
||||
## Code Style
|
||||
|
||||
Use contract discriminators and team IDs as the source of truth:
|
||||
|
||||
```ts
|
||||
const shouldInclude =
|
||||
(series.status === "in-progress" && games.length > 0) ||
|
||||
series.status === "completed";
|
||||
|
||||
const winnerTeamId =
|
||||
series.status === "completed" && series.outcome.type !== "draw"
|
||||
? series.outcome.winnerTeamId
|
||||
: undefined;
|
||||
```
|
||||
|
||||
The UI uses flat, full-width rows and existing semantic tokens. It does not reuse
|
||||
the bordered bracket card layout or introduce new dependencies.
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
Develop the pure model test-first. Cover:
|
||||
|
||||
- Games aggregated by `seriesId` and ordered by Series-local `ordinal`;
|
||||
- Series score preserved from A/B entries even when blue/red sides change;
|
||||
- chronological ordering independent of projection graph order;
|
||||
- `Asia/Seoul` grouping across the UTC day boundary;
|
||||
- started in-progress Series and game-less completed decisions;
|
||||
- exclusion of unstarted and orphan data;
|
||||
- played, draw, walkover, forfeit, and administrative status semantics;
|
||||
- deterministic tie-breaking and legacy zero-duration formatting.
|
||||
|
||||
After unit tests, run full web tests, changed-file lint, and the TypeScript/Vite build.
|
||||
Review the markup for native keyboard interaction, heading order, visible status text,
|
||||
and mobile layouts down to 320px.
|
||||
|
||||
## Boundaries
|
||||
|
||||
### Always
|
||||
|
||||
- Use `series.entries` for A/B score and `outcome.winnerTeamId` for the official
|
||||
winner; never infer identity from score, array position, or blue/red side.
|
||||
- Keep game-less adjudications visible without presenting `0 : 0` as a played score.
|
||||
- Omit `durationSeconds === 0` because it represents missing legacy data.
|
||||
- Preserve all unrelated working-tree changes.
|
||||
|
||||
### Ask First
|
||||
|
||||
- Change the public Competition contract, database schema, or projector.
|
||||
- Add Series scheduling or external replay/venue data.
|
||||
- Add a frontend dependency or test framework.
|
||||
|
||||
### Never
|
||||
|
||||
- Present `completedAt` as a scheduled or actual start time.
|
||||
- Reuse free-text `match.schedule` as official Series scheduling data.
|
||||
- Parse `series.code` for identity, winner, or ordering.
|
||||
- Make status or winner understandable only through color.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- A completed `2 : 1` Series appears as one chronological row with both teams, the
|
||||
official score, round label, status, and an expandable three-Game history.
|
||||
- In-progress Series retain already accepted Games and display `진행 중`.
|
||||
- No-game decisions appear with the correct decision label and no misleading score
|
||||
or start time.
|
||||
- Date grouping and time display are stable in `Asia/Seoul` regardless of runtime
|
||||
timezone.
|
||||
- The layout is readable without horizontal scrolling at 320px and uses the wider
|
||||
double-elimination page naturally on desktop.
|
||||
- Focused/full tests, lint, and web build pass without modifying unrelated work.
|
||||
|
||||
## Open Questions
|
||||
|
||||
None. The user approved the Series-centric, result-history-first direction and
|
||||
requested implementation.
|
||||
Reference in new issue
Block a user