# V2 Patch Notes System

This runbook covers `TODOS.phase-72.72.12.2.11`: a patch notes system with
structured patch notes for balance, bug fixes, and new content displayed
in-game.

The service package is `@v2/patch-notes-service` at
`apps/v2/patch-notes-service/`. Its contract is
`V2/ue/Content/V2/LiveOps/PatchNotes_V2_Contract.json`, and the focused gate is
`V2/ue/Tools/check-v2-patch-notes.py`.

## Runtime Contract

Primary APIs:

- `buildV2PatchNotesSurface`
- `buildV2PatchNotesInGamePayload`

Service endpoints:

- `GET /v2/live-ops/patch-notes`
- `GET /v2/live-ops/patch-notes/{patchVersion}`
- `GET /v2/live-ops/patch-notes/{patchVersion}/in-game`

Each release is keyed by `patchVersion` and `locale`, includes an ISO
`publishedAt`, a `minClientVersion`, and structured entries. The required
categories are:

- `balance`
- `bug-fixes`
- `new-content`

Every entry includes an `entryId`, category, title, body, impacted systems, and
positive `displayPriority`. The service rejects duplicate release keys,
duplicate entry ids, missing categories, invalid timestamps, invalid locales,
and missing impacted systems before the payload can be displayed in-game.

## In-Game Display

`buildV2PatchNotesInGamePayload` returns a compact payload for the game client:

- category summaries for balance, bug fixes, and new content
- `entriesByCategory` grouped by the structured category
- `displayCards` sorted by category and priority
- `structuredPatchNotes: true`
- `displayedInGame: true`
- `requiresClientPatch: false`

The game client should show this payload from
`GET /v2/live-ops/patch-notes/{patchVersion}/in-game`. Missing patch versions or
locales should fail closed and leave the previous patch notes card in place.

## Required Gates

- `patch-notes-package`
- `patch-notes-structured`
- `patch-notes-balance`
- `patch-notes-bug-fixes`
- `patch-notes-new-content`
- `patch-notes-in-game-display`
- `patch-notes-validation`
- `patch-notes-ci-wired`

## Verification

```sh
pnpm --filter @v2/patch-notes-service test
pnpm --filter @v2/patch-notes-service typecheck
pnpm --filter @v2/patch-notes-service lint
pnpm --filter @v2/patch-notes-service build
python3 V2/ue/Tools/check-v2-patch-notes.py
```