171 lines
7.3 KiB
Markdown
171 lines
7.3 KiB
Markdown
# Spec: Internal Match Game Analysis P0/P1
|
|
|
|
## Objective
|
|
|
|
Make an internal-match game result explain both the final numbers and how the game
|
|
reached them. P0 exposes data already present in the detail response: objective
|
|
events, complete team objectives, participant gold/GPM, and explicitly labelled
|
|
kill participation. P1 projects Riot Match-V5 timeline frames into real 10- and
|
|
15-minute lane checkpoints and a unified event stream for kills and structures.
|
|
|
|
The primary user is a tournament participant or organizer reviewing a completed
|
|
game on desktop or mobile. Success means the user can identify the major objective
|
|
sequence before reading ten player cards, compare lane state at 10/15 minutes, and
|
|
trace kills and building events without mistaking unavailable data for zero.
|
|
|
|
## Approved Product Decisions
|
|
|
|
- Place game flow immediately after the game summary and before detail tabs.
|
|
- Render chart events as both visual markers and a keyboard-readable text list.
|
|
- Keep the existing gold/XP toggle and runes/build experience.
|
|
- Show tower, dragon, inhibitor, Baron, Rift Herald, Void Grub, and Elder Dragon
|
|
totals; derive dragon type labels only when objective events are available.
|
|
- Combine participant CS and economy instead of adding another wide table column.
|
|
- Label kill participation explicitly as `KP`.
|
|
- Replace final-state values in the lane tab with 10/15-minute checkpoints; default
|
|
to 15 minutes and pair players by `teamPosition`, never array position.
|
|
- Keep `objectiveEvents` for compatibility and add `timelineEvents` for the unified
|
|
P1 stream.
|
|
- Treat missing checkpoints and events as unavailable, not zero.
|
|
- Do not add an opaque MVP/rating or new external data feed in this scope.
|
|
|
|
## Tech Stack
|
|
|
|
- React 19, TypeScript 6, Recharts 3, Tailwind CSS 4, and daisyUI under `apps/web`
|
|
- NestJS 11, TypeScript 5, Mongoose 9, and Jest under `apps/api`
|
|
- Riot Match-V5 match and timeline payloads already cached in `RiotMatchModel`
|
|
- Node's built-in test runner for pure web transformations
|
|
|
|
## Commands
|
|
|
|
- Focused web tests: `pnpm --filter web test`
|
|
- Web lint: `pnpm --filter web lint`
|
|
- Web production build: `pnpm --filter web build:prod`
|
|
- Focused API tests: `pnpm --filter api test -- --runInBand riot-match.service.spec.ts match-stats-fragment.builder.spec.ts community-stats.service.spec.ts`
|
|
- API build: `pnpm --filter api build`
|
|
- Development web server: `pnpm --filter web start:dev`
|
|
|
|
## Project Structure
|
|
|
|
- `apps/web/src/pages/MatchGameDetailPage.tsx` owns the result summary,
|
|
participant scoreboard, flow chart, and accessible event list.
|
|
- `apps/web/src/components/InternalGameAnalysisTabs.tsx` owns the lane and build
|
|
tabs.
|
|
- `apps/web/src/lib/internal-match-timeline.ts` owns pure event normalization,
|
|
labels, filtering, and chart projection.
|
|
- `apps/web/src/lib/internal-game-matchups.ts` owns pure role pairing and checkpoint
|
|
comparisons.
|
|
- `apps/web/test/` contains Node unit tests for the pure web transformations.
|
|
- `apps/api/src/modules/riot/` parses trusted fields from Riot match timelines.
|
|
- `apps/api/src/modules/community-stats/match-stats-fragment.builder.ts` projects
|
|
stored Riot payloads into cached internal-match records.
|
|
- `apps/api/src/modules/community-stats/community-stats.service.ts` maps persisted
|
|
records into the public detail response and versions response caches.
|
|
- `apps/api/src/modules/global/database/schema.ts` defines persisted TypeScript
|
|
shapes; nested `gameDetails` remains a Mongoose Mixed array.
|
|
|
|
## Data Contract
|
|
|
|
Participant checkpoint data is additive and optional for legacy/fallback games:
|
|
|
|
```ts
|
|
interface MatchStatsCheckpoint {
|
|
timestamp: number;
|
|
gold: number;
|
|
cs: number;
|
|
xp: number;
|
|
kills: number;
|
|
deaths: number;
|
|
assists: number;
|
|
}
|
|
|
|
interface MatchStatsParticipantCheckpoints {
|
|
at10?: MatchStatsCheckpoint;
|
|
at15?: MatchStatsCheckpoint;
|
|
}
|
|
```
|
|
|
|
Each detailed participant gains optional `participantId` and `checkpoints`. Each
|
|
game gains optional `timelineEvents`, whose `type` is an existing objective type or
|
|
`championKill`, `tower`, or `inhibitor`. Actor IDs, assists, monster subtype, and
|
|
tower subtype are optional fields appropriate to the event type.
|
|
|
|
For a 10/15-minute target, use the latest frame at or before the target only when it
|
|
is less than one `frameInterval` old. Persist the actual selected timestamp. CS is
|
|
`minionsKilled + jungleMinionsKilled`; checkpoint K/D/A includes champion-kill
|
|
events through the selected timestamp. A game ending before a target has no value
|
|
for that checkpoint.
|
|
|
|
## Code Style
|
|
|
|
Keep timeline calculations independent from React and use discriminated event
|
|
types with conservative fallbacks:
|
|
|
|
```ts
|
|
const events = game.timelineEvents?.length
|
|
? game.timelineEvents
|
|
: game.objectiveEvents;
|
|
|
|
const checkpoint = participant.checkpoints?.at15;
|
|
if (!checkpoint) return { kind: "unavailable" };
|
|
```
|
|
|
|
Use existing semantic color tokens and square bordered panels. Dynamic chart
|
|
coordinates may use numeric props; spacing, colors, and typography remain in the
|
|
existing Tailwind/daisyUI system.
|
|
|
|
## Testing Strategy
|
|
|
|
- Develop pure event normalization, checkpoint selection, role pairing, and metric
|
|
comparison test-first.
|
|
- Builder tests cover exact and missing checkpoints, jungle CS, cumulative K/D/A,
|
|
executes, objective fallback, building ownership, and deterministic event order.
|
|
- Service tests reject stale cached response shapes and verify additive mapping.
|
|
- Browser verification covers 320px, 390px, 768px, 1024px, and 1440px; the event
|
|
text list is the accessible equivalent of decorative chart markers.
|
|
- Verify the supplied production-like game as well as a short game and a game with
|
|
no timeline.
|
|
|
|
## Boundaries
|
|
|
|
### Always
|
|
|
|
- Preserve existing `objectiveEvents`, runes/builds, and match-detail routes.
|
|
- Derive participant checkpoint values from stored Riot timeline frames.
|
|
- Pair lanes by normalized `teamPosition` and show unavailable states explicitly.
|
|
- Communicate team/event meaning with text as well as color.
|
|
- Increment the match-stats builder and detail-response cache versions whenever a
|
|
persisted or cached response shape changes.
|
|
|
|
### Ask First
|
|
|
|
- Add a frontend or backend dependency.
|
|
- Change the public route or remove compatibility fields.
|
|
- Add a database migration or make a bulk external Riot API fetch.
|
|
- Deploy, push, or alter CI configuration.
|
|
|
|
### Never
|
|
|
|
- Infer absent checkpoint data as zero.
|
|
- Pair opponents by array order.
|
|
- Claim that a nearby objective caused a gold swing.
|
|
- Expose unparsed arbitrary Riot event fields.
|
|
- Modify unrelated Competition/bracket work already present in the worktree.
|
|
|
|
## Success Criteria
|
|
|
|
- Game flow appears before player details and includes objective markers plus an
|
|
equivalent textual sequence on desktop and mobile.
|
|
- Summary shows all currently projected objective totals and available dragon types.
|
|
- Every participant shows labelled KP, gold, GPM, CS, and CS/min without breaking
|
|
the responsive scoreboard.
|
|
- The lane tab defaults to 15 minutes, can switch to 10 minutes, and presents
|
|
GD/CSD/XPD and checkpoint K/D/A for correctly paired roles.
|
|
- The unified timeline can filter and display objectives, champion kills, towers,
|
|
and inhibitors, while falling back to objective-only data during rolling updates.
|
|
- Focused API/web tests, lint, and production builds pass.
|
|
|
|
## Open Questions
|
|
|
|
None. The user reviewed the P0/P1 task plan and requested implementation.
|