# Event History: Maintenance Reference

Use this document for later modifications. Read only the linked contract matching the change; do not re-analyze unrelated pages, models, sources, or templates.

## File Map

| Area | Location | Contract |
| --- | --- | --- |
| Route | `src/pages/routes.php` | Public `event-statistics` only |
| Orchestration | `src/pages/public/event-statistics/event-statistics.controller.php` | Strict hierarchy, 404, partial selection, caches, CSV dispatch |
| Shell/partials | `src/pages/public/event-statistics/` | Common table/profile classes; separate four states |
| Formatting | `classes/EventStatisticsPresenter.php` | Escaping, duration, `No Guild`, detail fields |
| Export | `classes/EventStatisticsCsv.php` | Stable CSV format and permanent cache |
| Data API | `src/model/base/event-history.model.php` | Snapshot-only CMS queries and totals |
| Model bridge | `src/model/cms/event-history.model.php` | Thin base extension; no source override |
| Database source | `Docs/temp/event-history-data.md` | Server/schema persistence contract |

## Change Routing

| Requested change | Read/inspect |
| --- | --- |
| Add/change a displayed statistic | [data-contract.md](data-contract.md), base model aliases, presenter, affected partial |
| Change drill-down or validation | [page-contract.md](page-contract.md), main controller |
| Change list columns/order | Relevant partial, model ordering, presenter |
| Change CSV fields/encoding | CSV section in [page-contract.md](page-contract.md), `EventStatisticsCsv`, base model output |
| Change cache lifetime/key | Cache section in [page-contract.md](page-contract.md), controller/CSV class |
| Add server columns | Original schema doc, [data-contract.md](data-contract.md), model, presenter, detail, CSV contract |
| Add navigation link | Active theme/config only when explicitly requested; outside the original scope |

## Invariants

- Historical identity always comes from snapshot columns.
- Every child lookup is scoped by its parent IDs.
- `in_progress` data is list-only.
- `guild_id=0` remains a real navigable/exportable group.
- HTML and CSV totals use one formula contract.
- Hours never wrap after 24.
- Permanent CSV files require immutable completed snapshots.
- CSV header/order changes are compatibility changes: version the cache key or explicitly invalidate old files.
- Adding an event-wide or player export is a product-contract change, not a refactor.

## Search Discipline

Start with these symbols/strings using codebase-memory-mcp:

```text
EventHistoryModel
EventHistoryBaseModel
EventStatisticsPresenter
EventStatisticsCsv
event-statistics
times_revived
revives_given
```

Skip `src/CuteNews/`, assets, bundled themes, source-specific models, live entity/guild models, payment/order modules, and server code unless the requested change explicitly crosses those boundaries.

## Diagrams

```mermaid
flowchart LR
    DB[Snapshot tables] --> M[EventHistoryModel]
    M --> C[Main controller]
    C --> V1[Event partial]
    C --> V2[Guild partial cache 15m]
    C --> V3[Player partial cache 15m]
    C --> V4[Player detail]
    C --> X[Guild CSV permanent cache]
```

```mermaid
flowchart TD
    SC[Schema/statistic change] --> DC[Update data contract]
    DC --> MA[Update model aliases/API]
    MA --> UI[Update presenter and views]
    MA --> CSV[Update CSV contract/class]
    CSV --> CK{Existing permanent files compatible?}
    CK -->|yes| KEEP[Keep cache key]
    CK -->|no| VER[Version key or invalidate explicitly]
```