Files
Dreierpack-Manager/docs/new_ui/desktop/post-match/PROVIDER.md
T

150 lines
7.2 KiB
Markdown

# Native post-match provider (by Codex)
The Modern UI can review its existing finite live recording through
`demo_post_match.hpp`. This is a read-only presentation component, not a match
engine, season driver or authoritative match report.
`make_demo_post_match(fixture, completed_sequence)` accepts only a validated
`openbmh-live-fixture@1` with `source=ui-demo-fixture`, its last sequence, a
`finished` final phase and the recorded full duration. The explicit sequence
acknowledges that the UI has reached the end of that recording. It cannot prove
that an engine match finished. Existing nine-frame recordings, their outcomes,
event IDs and owner IDs are unchanged.
The resulting `openbmh-post-match@1` review retains `fixture_id`,
`source_revision`, `completed_sequence`, world, date, role, surface, duration and
the original owner views. Match rows retain their original identities, teams,
owners and competition. Each adds:
- `final`: the exact final recorded match snapshot, including score, chances,
yellow/red cards, player counts and declared standings;
- `events`: only that match's original events;
- `attendance: null`, `attendance_reason: "not_recorded"`.
Club/outdoor review tabs are `results`, `report`, `eleven`, `overview`, `table`.
National/outdoor and club/indoor have only `results`, `report`, `overview`.
Durations remain 90/40 and active-player counts remain 11/6. National owners
retain the existing explicit POC club-roster basis; this does not create a
national selection or caps history.
`overview` sums final goals, chances and cards over the **unique recorded human
matches**, never once per human manager. Its `scope=recorded_human_matches`
distinguishes it from a whole-league matchday. Additional league fixtures and
crowds are not present in this native recording. `tables` deduplicates equal
existing final standings snapshots and retains their rows unchanged. Wins,
draws and losses are unknown; no season-ranking formula is introduced here.
`eleven={available:false,reason:"not_recorded",rows:[]}` explicitly reports the
missing nominations instead of deriving match ratings from catalogue strength.
### Optional supplied nominations
The additive three-argument overloads of both pure functions accept a separate
`records` object. The existing two-argument functions and the source hook retain
their original no-records behaviour. Records do not modify the live fixture:
```json
{
"schema": "openbmh-post-match-records@1",
"fixture_id": "the-original-fixture-id",
"source_revision": 1,
"eleven": {
"available": true,
"source": "supplied-records",
"notice": "Nominations supplied by the presentation data provider",
"formation": "3-4-3",
"rows": []
}
}
```
`rows` must contain exactly eleven unique player identities and a 1/3/4/3 split
of `position: "gk"|"def"|"mid"|"fwd"`. Each row contains exactly
`player:{id,name}`, `team:{id,name,role:"club"}`, `position` and `rating:null`.
The team must retain a known ID and name from the recording's match teams or
final standings. This validates presentation provenance and identity; it does
not independently prove an engine nomination. The supplying adapter is
responsible for that fact. No producer here selects players from their strength,
lineup position or goal events. Until an authoritative rating scale exists,
numeric ratings are rejected, including otherwise plausible values.
Records are accepted only for club/outdoor and must bind exactly to the same
fixture ID and source revision. Unknown fields, malformed UTF-8, foreign teams,
renamed teams, duplicate players, stale references or invalid formations fail
atomically. `source` is either `supplied-records` or
`synthetic-layout-fixture`; neither claims engine authority. National and
indoor remain three-tab reviews and reject nominations from this club-only
path. Available records replace only `eleven` and remove it from
`unknown_fields`. Scores, report events, timeline minutes, tables and all other
review facts remain unchanged. Missing records retain byte-identical defaults.
`tests/synthetic/modern_post_match_eleven.json` is an explicitly synthetic
standalone layout fixture containing `eleven` and its notice. It deliberately
contains no guessed fixture/revision binding. The core test binds it to its
actual synthetic recording; a document renderer test may use the same `eleven`
to cover a filled pitch/list without a product debug option or any change to
the nine-frame recording. These test names are not original game data.
For example, two recorded 2:1 matches shared by four human managers produce:
```json
{
"overview": {
"games": 2, "goals": 6, "chances": 28, "yellow": 2, "red": 0,
"attendance": null, "attendance_reason": "not_recorded",
"scope": "recorded_human_matches"
},
"eleven": {"available": false, "reason": "not_recorded", "rows": []}
}
```
## Report seeking
`query_demo_post_match(fixture, request)` takes that same retained live fixture,
not the review DTO. A report request is:
```json
{
"kind": "report", "completed_sequence": 8,
"fixture_id": "the-original-fixture-id", "revision": 1,
"match_id": "the-original-match-id", "minute": 61
}
```
`completed_sequence` is required. Optional `fixture_id` and `revision` must
match the recording. A report's `match_id` defaults to the first original
match; `minute` defaults to full duration. Both are local presentation choices.
The report returns `home`, `away`, `match`, `final`, `final_score`, cursor
`minute`, `recorded_minute`, `sequence`, `phase`, `score`, `chances`, `yellow`,
`red`, `players`, `standings`, past `events` and complete `timeline`.
Seeking picks the last existing frame at or before the cursor. In this
recording a seek to minute 61 therefore shows the recorded 46-minute 1:0;
minute 62 shows its recorded 1:1. No intermediate goal, assist, possession
percentage or ball time is calculated. Future timeline markers remain
available for the view to draw dimmed. Events retain their original fields;
they do not contain a known player actor. Report-level `actor`, `assists`,
`ratings` and `playing_minutes` are null.
`kind="review"` returns the complete review and rejects report-only fields.
Malformed queries, incomplete sequences, stale revisions/fixture IDs, foreign
match IDs and out-of-range minutes produce explicit `ok:false,error` values.
## Source boundary and ownership
`DataSource::read_post_match` defaults to `post_match_unavailable`. A later
authoritative adapter must independently confirm its actual completed state.
`DemoSource` explicitly binds its read to the current fixture and requires both
`revision` and `fixture_id`; a changed source rejects a stale read. The view can
still review its retained immutable completed recording through the pure API,
without rebinding old facts to another current team/person.
Reads never call `apply`, change revision/dirty state, create a match or save a
review into a career checkpoint. View-local tab, selected manager, match,
report minute and playback state must not modify the live recording cursor,
owner selection, intervention drafts or career owner.
`modern_post_match_ui_tests` uses a synthetic catalogue to check unique matches,
exact final values, seek boundaries, 5/3 tabs, missing facts, stale/invalid
requests, retained identities and source/checkpoint immutability. Existing
`modern_live_ui_tests` remains unchanged.