Log Parser Architecture

ゲームログを解析して試合情報（BAN/PICK / 勝敗 / 統計）を抽出するエンジンの構成。code-split-and-coverage spec で 3 層 + finalize + statistics に分割した。

ファイル構成

src/utils/logAnalyzer/
├── LogParser.ts              # 一括解析モード（バッチ用 facade）
├── StreamLogParser.ts        # 旧ストリーム実装（互換のため残置）
├── CharacterService.ts       # キャラ ID ↔ 名前変換
├── StatisticsCalculator.ts   # 統計集計の facade
├── statistics/
│   └── aggregate.ts          # 純関数の試合統計集計（spec で抽出）
├── core/
│   ├── LogParserCore.ts      # 一括解析オーケストレータ
│   ├── StreamLogParserV2.ts  # ストリーム解析（リアルタイム用、StreamFsm 内蔵）
│   ├── line/
│   │   └── LineParser.ts     # 純粋な行パーサ（regex / 抽出関数 / MARKER）
│   ├── fsm/
│   │   └── StreamFsm.ts      # phase の状態機械
│   ├── aggregator/
│   │   └── Aggregator.ts     # picks / bans / players の集約
│   ├── finalize/
│   │   └── finalizeMatchData.ts  # 集計結果の最終整形
│   └── bp/                   # BP 関連の追加ロジック置き場（拡張用）
├── battleType/               # BattleType の数値 ↔ 文字列マッピング
├── matchFilters.ts
├── timeUtils.ts
└── types.ts

scripts/analyze-log/ は CLI 解析スクリプト群（同じエンジンを使う薄いラッパ）。

レイヤー構成

層	ファイル	責務	依存
line	`core/line/LineParser.ts`	1 行を `ParsedLine` に変換する純粋関数群（regex / 抽出関数 / MARKER）	なし
fsm	`core/fsm/StreamFsm.ts`	phase の状態保持・遷移・onChange リスナー	line（型のみ）
aggregator	`core/aggregator/Aggregator.ts`	重複排除 / ソート / Normal 戦キャラ抽出	line（型のみ）/ `CharacterServiceLike` (DI)
finalize	`core/finalize/finalizeMatchData.ts`	rank / type 推定 / 整形	aggregator
statistics	`statistics/aggregate.ts`	試合配列から KPI を集計（純関数）	finalize 後の MatchData 配列

状態機械（StreamFsm）

リアルタイム解析時の phase 遷移。StreamLogParserV2.ts が内蔵する。

各状態の役割:

状態	入力で受け付ける主なマーカー	出力 / 次状態
`IDLE`	試合開始系マーカー	`BP` へ
`BP`	`BP数据日志` (Rank), プレイヤー BAN/PICK	aggregator に push
`LOADING`	`匹配成功开始加载战斗`	`INGAME` へ（タイムアウトすれば `IDLE`）
`INGAME`	`ON GAME START`, `ON BATTLE END PUSH`	`RESULT` へ
`RESULT`	`upload sdk battle player`	`MatchData` を確定し `IDLE` へ

実遷移表は core/fsm/StreamFsm.ts の transition() メソッドに 明示的に列挙 されている。

ログマーカー

BP フェーズ関連

マーカー	説明	出現条件
`BP数据日志`	BAN/PICK 詳細（プレイヤー名 / キャラ ID 等）	Rank のみ
`匹配成功开始加载战斗`	マッチング成功 → BP フェーズ終了	両方
`PageBattleBanPick2V2.prefab`	BP 画面 UI ログ	Rank のみ

試合進行関連

マーカー	説明
`ON GAME START`	ゲーム開始
`ON BATTLE END PUSH`	バトル終了
`upload sdk battle player`	試合結果（プレイヤー名・勝敗）

マッチタイプマーカー

マーカー	説明
`TYPE:Rank_2v2`	ランク 2v2
`TYPE:Rank_1v1`	ランク 1v1
`TYPE:Normal_2v2`	ノーマル 2v2
`TYPE:Normal_1v1`	ノーマル 1v1
`TYPE:Custom`	カスタム

Rank 判定ロジック（finalize/finalizeMatchData.ts）

集計後 (Aggregator 出力時点) は rank/normal 判定が確定していないことがある。finalizeMatchData で以下の 優先順位 で確定する。

優先度	判定基準	信頼度
1	`TYPE:` マーカー（試合結果の前 500 行以内）	確定
2	BP区間内に `BP数据日志` がある	Rank と推定
3	プレイヤー数（2 = 1v1, 4 = 2v2）+ 既定 Normal	フォールバック

一括解析 vs ストリーム解析

種別	エントリ	用途
一括	`LogParser` → `LogParserCore`	既存ログファイルの解析（DB インポート時）
ストリーム	`StreamLogParserV2`	リアルタイムログ監視 (`LogWatcherService`)

両方とも内部では同じ line / aggregator / finalize を使う。違いは fsm の有無のみ:

Statistics 集計（純関数）

statistics/aggregate.ts は MatchData[] を入力に取る純関数群。StatisticsCalculator の facade から呼ばれる。

主な集計関数（抜粋）:

aggregatePlayerStats(matches)
aggregateCharacterPickStats(matches)
aggregateCharacterBanStats(matches)
aggregateMatchupStats(matches, focusUid)

純関数なので vitest で簡単にテストでき、statistics/aggregate.test.ts で 15 ケース。

CharacterService

キャラの ID / DB 名 / 画像名 の対応を管理する。reseponses/characters_by_rolecode.json を読み込み、nameAliases で DB 名と画像ファイル名のずれを吸収する。

新規キャラ追加時の手順は Add New Character を参照。

テスト

層	テストファイル	主なケース
line	`core/__tests__/LineParser.test.ts`	regex の table-driven
fsm	`core/__tests__/StreamFsm.test.ts`	全遷移を網羅
aggregator	`core/__tests__/Aggregator.test.ts`	fixture ベース
finalize	`core/finalize/finalizeMatchData.test.ts`	rank/type 推定 10 ケース
statistics	`statistics/aggregate.test.ts`	KPI 集計 15 ケース
一括	`core/__tests__/LogParserCore.test.ts`	大規模 fixture
ストリーム	`core/StreamLogParserV2.test.ts` + `regression.test.ts`	統合シナリオ

CLI ツール

bash

yarn analyze-log                  # デフォルト UID で解析
npx tsx scripts/analyze-log/index.ts "path/to/log.txt"

# 特定マーカー確認
grep -n "BP数据日志" scripts/testData/.../Log_*.txt | head -10
grep -n "TYPE:" scripts/testData/.../Log_*.txt | head -30

解析結果の出力内容

試合基本情報

試合 ID / タイムスタンプ
マッチタイプ（Rank_2v2 / Normal_1v1 等）
ゲーム開始・終了時刻 / duration

プレイヤー情報

名前 / UID
勝敗 / チーム（A or B）
使用キャラ / 所持キャラ枠

BAN/PICK 情報（Rank のみ）

BAN されたキャラ + BAN したプレイヤー
PICK されたキャラ + PICK したプレイヤー

統計情報（statistics/aggregate）

プレイヤー別勝敗数・勝率
キャラ別 BAN/PICK 回数 / 勝率
対戦相手分析

Log Parser Architecture ​

ファイル構成 ​

レイヤー構成 ​

状態機械（StreamFsm） ​

ログマーカー ​

BP フェーズ関連 ​

試合進行関連 ​

マッチタイプマーカー ​

Rank 判定ロジック（finalize/finalizeMatchData.ts） ​

一括解析 vs ストリーム解析 ​

Statistics 集計（純関数） ​

CharacterService ​

テスト ​

CLI ツール ​

解析結果の出力内容 ​

試合基本情報 ​

プレイヤー情報 ​

BAN/PICK 情報（Rank のみ） ​

統計情報（statistics/aggregate） ​

関連ドキュメント ​