feat: enrich internal match game analysis

This commit is contained in:
dahyeon committed 2026-07-13 09:35:25 +00:00
1 parent 9f698a8fec
commit aa675199af
22 files changed
+3123 -241

No files matched your search

+170
View File
@@ -0,0 +1,170 @@
# 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.