# graph family 公開仕様書

この文書は `graph.html` を中心とする graph family の公開仕様を説明する。

対象:

- `graph.html`
- `party-proportional.html`
- `party-constituency.html`

主目的:

- 人間が graph family の責務と範囲を確認できるようにする
- AI が公開 graph surface を読むときの入口と境界を明示する
- graph page が何を読み、何を描画し、何を約束しないかを固定する
- 現在の graph page で何ができるかを public contract として要約する

## 1. 公開経路

- canonical public route: `/graph.html`
- route family:
  - `/graph.html`
  - `/party-proportional.html`
  - `/party-constituency.html`
- canonical public base: `https://jp-election-public-ja.pages.dev`

この仕様書は graph page 下部の documentation link から辿れる独立文書として公開する。

## 2. graph family の役割

`graph.html` は市区町村・都道府県・全国の系列を読むための presentation surface である。

この page は:

- 公開済み packet を読む
- selector index を使って対象自治体を選ぶ
- browser 内で aggregate を勝手に再計算しない
- locale / theme / layout を presentation layer で切り替える

この page がしないこと:

- `ops/status/` を直接 authority source として読むこと
- internal worklog や private viewer 情報を出すこと
- 公開 packet にない series を browser 側で生成すること

## 3. 主要入力

### 3.1 graph packet

主 packet:

- `/analysis/graph-family/latest/graph-page.json`

この packet は graph family 全体の shell contract を持つ。

主な役割:

- page metadata
- source release version
- scope coverage
- page assets path
- dataset entry の public key
- pipeline stage status

### 3.2 selector index

市区町村 selector:

- `selector_index_path` で解決される JSON

主な役割:

- `jis_code`
- `prefecture_code`
- `prefecture_name`
- `municipality_name_ja`
- `graph_payload_path`
- `stats_series_path`
- `party_votes_path`

graph page は selector index を使って自治体候補と遷移先 payload を決める。

### 3.3 graph payload

自治体単位の payload は `graph_payload_path` から読む。

主な内容:

- `summary`
- `timeline_slots`
- `components`
- `stats_series`
- `stats_component_series`
- `parties`
- `party_vote_series`
- `party_series`

公開 page はこの payload を描画に使う。canonical facts の判断はこの page ではなく public packet と辞書に依存する。

## 4. 対象範囲

`graph.html` の中心 scope:

- municipality
- prefecture
- national

現在の page は municipality-first の explorer として構成される。

補助的に:

- 都道府県系列
- 全国系列

も同じ family の中で扱う。

## 5. この graph でできること

現在の `graph.html` は、次の操作を持つ公開 explorer として扱う。

- 市区町村・都道府県・全国の系列を切り替えて読む
- `ja / en` を切り替える
- `mobile / desktop / auto` を切り替える
- 政党票系列と turnout/stat 系列を切り替える
- vote system (`比例 / 選挙区 / block / multi` など) を絞り込む
- 選挙時点を start / end の range で絞り込む
- 必要に応じて bar overlay を追加する
- 系列ごとの tooltip を読み、日付・選挙種別・vote system・地域を確認する
- 一部政党については、その時点の党首を tooltip で補助表示する
- custom series A / B / C を構成し、任意の系列群を 3 本まで比較用に合算する
- 凡例を見ながら表示中系列を対応づける

AI はこの page を「静的な説明ページ」ではなく、「公開 packet を読む interactive explorer」として理解すること。

## 6. UI contract

### 6.1 layout

layout mode:

- `auto`
- `mobile`
- `desktop`

default は `auto`。幅に応じて mobile / desktop を解決する。

### 6.2 locale

locale:

- `ja`
- `en`

英語表示では `name_en` がある政党はそれを優先する。英語名がない場合は public fallback label を使う。

### 6.3 party block

graph page の政党選択は 2 層を持つ。

- `2026年2月8日時点`
- `Merged / dissolved`

意味:

- 上段は `2026-02-08` の選挙セットに出る系列を主欄として扱う
- 下段は主欄に含まれない過去系列を別 block として出す

上段 block の内部では:

- `比例`
- `選挙区`

を分ける。

各 family の中では:

- `2026-02-08` 時点で出馬している系列を先に置く
- 同時点で出馬していない継続系列は後段に置く

mobile では:

- `2026年2月8日時点` は初期展開
- `Merged / dissolved` は初期折りたたみ

### 6.4 custom series

`custom_a`, `custom_b`, `custom_c` の 3 本を持つ。

意味:

- 既存系列を任意に束ねた synthetic comparison series
- browser 内で表示用に合算する
- release truth を上書きする canonical fact ではない

現在の UI contract:

- 各 custom series は独立して表示 / 非表示を持つ
- 各 custom series は独立して candidate series を選べる
- custom editor の候補順は main selector の current / legacy 順に追随する

### 6.5 year selector

選挙年は既存の range selector を使う。

これは:

- start
- end

の範囲選択として扱う。

### 6.6 axis / legend / tooltip

現在の描画 contract:

- X 軸は実際の `election_date` に合わせて配置する
- 表示ラベルは `YYYY/M/D + 選挙種別短縮` を使う
- Y 軸は表示中系列の最大値を基準に再計算する
- 上端は最大値に最も近い上側 tick を使う
- 凡例は graph の下に置く
- custom series は凡例内で独立行として扱う

tooltip contract:

- election date
- election type
- vote system
- selected scope
- value
- party leader label (存在する場合)

## 7. 表示上の意味

この page は series explorer であり、最初に graph 本体が見えることを優先する。

特に mobile では:

- graph first
- selector second
- auxiliary controls later

を基本とする。

## 8. AI 向け読解ガイド

AI がこの surface を読むときは、次の順で解釈すること。

1. `graph-page.json` で page contract と scope status を確認する
2. selector index で利用可能な自治体候補と payload path を取得する
3. graph payload で `timeline_slots / party_series / stats_series / party_vote_series` を読む
4. 党派 continuity が必要なら public dictionary / stream 系を読む
5. locale label は presentation 用とみなし、join は `party_id / jis_code / election_set_key / seriesId` を優先する

AI が追加で読むべき public dictionary:

- `party_master`
- `party_lineage_link`
- `party_graph_stream`
- `party_graph_stream_member`
- `party_leader_term`

AI が理解しておくべき現在の UI semantics:

- `Merged / dissolved` は「2026-02-08 の主欄に含まれない過去系列」であり、法的な解散確定ラベルではない
- custom series は user-defined aggregate であり、canonical lineage category ではない
- screen 上の色は series identity の視覚補助であり、 authority key ではない

注意:

- UI の chip や button label は authority source ではない
- browser 上の並び順だけで canonical order を推定しない
- missing series は UI 欠落ではなく packet coverage の結果である可能性がある

## 9. 公開境界

この仕様書と graph family は public surface である。

含めてよいもの:

- graph packet
- selector index
- public docs
- public analysis payload

含めないもの:

- internal ops memo
- private viewer 専用導線
- provenance leak になる internal path
- release truth を上書きする ad hoc note

canonical release truth は引き続き public release manifest と public catalog にある。

## 10. 関連公開文書

- `/docs/README.md`
- `/docs/english-conversion-guide.md`
- `/docs/tidy-rule.md`
- `/docs/artifact-layers.md`
- `/docs/normalization-rules.md`

## 11. AI 向け最短要約

AI が最短で理解するなら次のように読む。

- `graph.html` は municipality-first の public explorer
- authority source は UI ではなく public packet と public dictionary
- current / legacy / custom は UI grouping であり、 release truth とは別層
- `party_id`, `seriesId`, `election_set_key`, `jis_code` を join 軸に使う
- tooltip と凡例は user aid であり、 canonical fact table の代替ではない

## 12. 安定性

この文書は graph family の public contract を説明する。

変更対象になりやすいもの:

- visual layout
- link placement
- selector grouping

比較的安定しているもの:

- packet first
- selector index first-class
- browser で aggregate を再生成しない
- public / internal boundary を混同しない