feat: enrich internal match game analysis
This commit is contained in:
1 parent
9f698a8fec
commit
aa675199af
22 files changed
+3123
-241
No files matched your search
@@ -0,0 +1,78 @@
|
||||
# Implementation Plan: Internal Match Game Analysis P0/P1
|
||||
|
||||
## Overview
|
||||
|
||||
Deliver three independently verifiable slices: P0 existing-data UI, P1-A timeline
|
||||
checkpoints and lane comparison, and P1-B unified notable events. Preserve the
|
||||
existing detail endpoint and use builder/cache versioning to refresh old projections.
|
||||
|
||||
## Task List
|
||||
|
||||
### Phase 1: P0 Existing Data
|
||||
|
||||
- [x] Add tested objective normalization, chart markers, an accessible event list,
|
||||
and move game flow above the detail tabs.
|
||||
- [x] Add a complete objective comparison strip with conservative dragon-type
|
||||
fallback behavior.
|
||||
- [x] Label KP and add participant gold/GPM to the combined CS/economy presentation.
|
||||
|
||||
### Checkpoint: P0
|
||||
|
||||
- [x] Web tests, lint, and production build pass.
|
||||
- [x] Desktop and mobile layouts retain all existing scoreboard/build behavior.
|
||||
|
||||
### Phase 2: P1-A Lane Checkpoints
|
||||
|
||||
- [x] Parse the remaining participant event identifier fields and project tested
|
||||
participant checkpoints at 10 and 15 minutes.
|
||||
- [x] Persist and expose optional checkpoint fields, reject stale caches, and bump
|
||||
the match-stats builder/detail-response versions.
|
||||
- [x] Replace final-state lane comparisons with tested role-based 10/15-minute
|
||||
GD/CSD/XPD and K/D/A comparisons.
|
||||
|
||||
### Checkpoint: P1-A
|
||||
|
||||
- [x] Focused API tests and builds pass.
|
||||
- [x] Web tests and production build pass.
|
||||
- [x] Short and missing-timeline games show unavailable states rather than zeros.
|
||||
|
||||
### Phase 3: P1-B Unified Events
|
||||
|
||||
- [x] Project objectives, champion kills, towers, and inhibitors into a deterministic
|
||||
tested event stream.
|
||||
- [x] Expose `timelineEvents` while retaining `objectiveEvents` compatibility and
|
||||
bump persisted/cache versions as required.
|
||||
- [x] Add accessible event filtering and chart selection with objective-only fallback.
|
||||
- [x] Coalesce concurrent hydration and short-cache incomplete results so transient
|
||||
failures retry without rebuilding on every sequential page request.
|
||||
|
||||
### Checkpoint: Complete
|
||||
|
||||
- [x] API and web focused suites pass without skipped tests.
|
||||
- [x] API and web production builds pass.
|
||||
- [x] Responsive runtime review passes at 320px, 390px, 768px, 1024px, and 1440px.
|
||||
- [x] P0/P1 edits exclude unrelated Competition/bracket modifications already in
|
||||
the shared worktree.
|
||||
|
||||
## Risks and Mitigations
|
||||
|
||||
| Risk | Impact | Mitigation |
|
||||
|---|---|---|
|
||||
| Missing or delayed Riot frames misrepresent @10/@15 | High | Use only a frame at/before the target within one frame interval and expose its actual timestamp. |
|
||||
| Building events attribute the destroyed team's side as the scorer | High | Prefer killer participant side; otherwise invert the destroyed `teamId`; cover both paths in tests. |
|
||||
| Old cached shapes hide new fields | High | Increment builder and response cache versions and strengthen completeness validation. |
|
||||
| A kill-heavy game makes the page excessively long | Medium | Add event-category filters and a bounded scroll region. |
|
||||
| Mobile chart remains hard to reach | Medium | Move flow directly below the summary before any participant cards. |
|
||||
| Existing dirty work is accidentally included | High | Restrict edits and verification to the named game-analysis files and inspect the final diff by path. |
|
||||
|
||||
## Dependencies
|
||||
|
||||
```text
|
||||
P0 event normalization -> P0 objective strip
|
||||
P1 checkpoint projector -> response contract -> lane UI
|
||||
P1 checkpoint identifiers -> event projector -> response contract -> event UI
|
||||
```
|
||||
|
||||
## Open Questions
|
||||
|
||||
None.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user