docs(tracker): フロー図を実装クラスとメソッドへ対応付ける

[ssaattww]

概要

Tracker/Design/Core/tracker-architecture-plan.md を、End-to-end の全体フローを起点に、各ブロックから実装クラス・メソッドへ直接辿れる構成へ更新しました。

文字だけでは理解しづらかった説明のうち、図や表で同じ意味を表現できる部分は置き換えています。一方、図で表現しきれない条件・例外・設定値・アルゴリズム要件・TDD 方針・タスク分割は削除せず、tracker-architecture-plan-details.md に従来の原文をそのまま保持しています。

今回の指摘への対応

• 11個のMermaid図すべてで、処理ブロックへ実在するClass.Method()を記載
• 保持状態はClass.field、契約型は(data type)として処理と区別
• 外部システムと将来未実装要素を明示し、架空の実装名を置かない
• F1-F7の各stageへ主なimplementation entry pointを追加
• 全体stage・役割・実装・詳細章の対応表を追加
• RuntimeHostとDebugHostで異なる受信経路を具体化
  • RuntimeVisionReceiverService.ExecuteAsync()
  • RuntimeHostOperationLoop.ProcessLatestPacket()
  • VisionReceiverService.ExecuteAsync()
  • TrackerCoordinator.ProcessPacket()
• Engine pipelineを責務別partial methodへ対応付け
  • event time / buffer: CreateBufferedDetection()、FlushCommittedFrames()、BuildDetectionGroups()
  • camera-local tracking: UpdateCameraBallTrackStates()、UpdateCameraRobotTrackStates()
  • merge: CollectMergedBallStates()、CollectMergedRobotStates()
  • domain metadata: UpdateKickState()、CreateBallContactState()、CreateBallLeftFieldState()
  • frame / event生成: CommitGroup()
• Result dispatchをTrackerCoordinator.DispatchResult()、PublishFrame()、NotifyObservers()へ対応付け
• Profile切替をfieldとmethodへ対応付け
  • desiredOptions / pendingRequest / inFlightRequest / appliedOptions
  • RequestProfileSwitch() / PromotePendingRequest() / ApplyProfileSwitch()
• Capture / comparisonを実装経路へ対応付け
  • VisionPacketCaptureWriter.Capture()
  • MultiTrackerManager.ProcessPacket()
  • TrackerPacketSnapshotLogWriter.Append()
  • TrackerSnapshotAlignmentLogWriter.WriteTimelineRecords()
  • TrackerSnapshotReplayReader.ReadSession()
  • TrackerDiagnosticsComparisonViewStateReader.Load()
  • CaptureReplayRunner.Run()

文書構成

tracker-architecture-plan.md

• システムコンテキストと実装component
• F1-F7 End-to-end全体フロー
• 全体stage・実装entry point・詳細図の対応表
• F1-F6 live tracking sequence
• F3.1-F3.8 engine pipelineと責務別method
• event-time / reorder / flushの詳細フロー
• camera-local tracking / multi-camera mergeの詳細フロー
• F3.8-F5 Core data model / output boundary
• F4 event dispatch順
• C1 profile switch state / sequence
• F7 Capture / replay / comparison flow
• 設定、UI / rule境界、詳細仕様対応表、不変条件チェックリスト

tracker-architecture-plan-details.md

• 変更前のtracker-architecture-plan.mdを全文保持
• proto入力型、sidecar record、alignment、legacy fallback、filter条件、設定値、テスト候補、タスク分割などを省略せず残す
• 図だけでは実装判断が一意にならない場合の詳細仕様として使用する

情報保持の基準

• 同じ意味を図・表で表現できる文章は置き換えてよい
• 条件、例外、境界、設定、順序、判断根拠は削除しない
• main documentから詳細仕様へ対応関係を辿れるようにする
• 詳細仕様の記述と図が競合する場合は詳細仕様を優先する

テストに関する扱い

• ドキュメント更新のためのテストファイル・テストケースは追加していない
• workflow、production code、既存テストコードの変更なし
• 変更対象はMarkdown 2ファイルのみ

検証

• 実装ファイルを確認し、図中のclass / method / field名を照合
• Markdownのcode fence対応を確認
• 全体stageと詳細図の番号対応を確認
• main...agent/improve-tracker-architecture-plan はahead 11 / behind 0
• GitHub Actions .NET tests run 26: success