style: コードブロックに言語指定を追加 (MD040対応)

[TinyKitten]

• docs/architecture.md を新規作成
  • 4層構造（Domain/UseCase/Infrastructure/Presentation）の設計思想
  • データベース/gRPC/スキーマ更新時の注意点
  • 命名規則（Row構造体 vs Entity の区別）
  • キャッシュ戦略の判断理由（query.rs:169-265）
• README.md にドキュメントへの参照を追加
• technical_debt.md のアーキテクチャドキュメント不足を対応済みに更新

Closes #1350

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com

Summary by CodeRabbit

ドキュメント

• システムアーキテクチャの包括的なドキュメントを新規追加しました。
• README.mdを更新し、アーキテクチャドキュメントへのリンクを追加しました。
• 技術負債の追跡ドキュメントを更新し、完了した項目をマークしました。

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

StationAPI のアーキテクチャドキュメントを新規作成し、README.md に参照リンクを追加しました。4層クリーンアーキテクチャの設計、データフロー、キャッシュ戦略、命名規則などを詳細に文書化しました。technical_debt.md を更新し、このドキュメント作成タスクを完了済みに変更しました。

Changes

Cohort / File(s)	説明
ドキュメント参照の追加 README.md	Documentation セクションに docs/architecture.md へのリンクを新規追加
アーキテクチャドキュメント docs/architecture.md	新規ファイル。4層アーキテクチャ（Domain/UseCase/Infrastructure/Presentation）、データベース設計、gRPC スキーマ、命名規則、キャッシュ戦略、データフロー、ディレクトリ構造を完全に文書化
技術債務の更新 docs/technical_debt.md	アーキテクチャドキュメント作成をタスク完了に変更。高優先度セクションの「不足している領域」を「対応済みの領域」テーブルに変換し、完了済みアイテムをマークダウン。低優先度セクションも同様に更新

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• docs: 技術負債分析レポートを追加 #1348: 同じドキュメント関連の変更で、README と docs/technical_debt.md を修正する PR。本 PR のアーキテクチャドキュメント作成はこの PR のレビューコメントから派生したもの。

Poem

✨ アーキテクチャ、明かされたり
4層の塔、輝きて
キャッシュの謎も解き明かし
ウサギの知恵、束ねられたり
ドキュメント完成、三月の喜び 🐇

Pre-merge checks

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	PRのタイトル「docs: アーキテクチャドキュメントを追加」はアーキテクチャドキュメント追加というメインの変更を明確に要約しており、変更内容と完全に一致している。
Linked Issues check	✅ Passed	PR #1352はリンク課題 #1350の全要件を満たしている。docs/architecture.mdの作成（3/4層構造、DB/gRPC/スキーマ注意点、命名規則、キャッシュ戦略を記載）、README.mdへのリンク追加、technical_debt.mdの更新が実装されている。
Out of Scope Changes check	✅ Passed	全ての変更がリンク課題 #1350の要件内である。3つのファイル（docs/architecture.md新規作成、README.md更新、technical_debt.md更新）の変更は全て要件に対応しており、範囲外の変更は認められない。
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

📜 Recent review details

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a76b3a7 and 4174166.

📒 Files selected for processing (3)

• README.md
• docs/architecture.md
• docs/technical_debt.md

🧰 Additional context used

📓 Path-based instructions (1)

{docs/**/*.md,README.md}

📄 CodeRabbit inference engine (AGENTS.md)

For database, gRPC, or schema updates, add architectural notes under docs/ and synchronize README references to keep onboarding materials accurate

Files:

• README.md
• docs/architecture.md
• docs/technical_debt.md

🧠 Learnings (11)

📓 Common learnings

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to {docs/**/*.md,README.md} : For database, gRPC, or schema updates, add architectural notes under `docs/` and synchronize README references to keep onboarding materials accurate

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to {docs/**/*.md,README.md} : For database, gRPC, or schema updates, add architectural notes under `docs/` and synchronize README references to keep onboarding materials accurate

Applied to files:

• README.md
• docs/architecture.md
• docs/technical_debt.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to AGENTS.md : Keep `AGENTS.md` aligned with repository workflows and update it in the same pull request when workflows, environment requirements, or endpoints change

Applied to files:

• README.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to AGENTS.md : Introducing new tables, endpoints, or feature flags must come with matching updates to `AGENTS.md` and any other affected guidance documents

Applied to files:

• README.md
• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/src/domain/**/*.rs : In Rust domain layer, entity definitions and repository abstractions should be organized in the `entity/` module mirroring the gRPC schema, with repository interfaces using `async_trait`

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/proto/**/*.proto : Keep gRPC contract definitions in `proto/stationapi.proto` and use `build.rs` with `tonic-build` to generate server code and `FILE_DESCRIPTOR_SET`

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/src/presentation/controller/**/*.rs : gRPC presentation layer controller should wire service implementations (e.g., `MyApi`) to generated server types in `presentation/controller/grpc.rs`

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/src/use_case/**/*.rs : Application logic in use case layer should implement contract traits defined in `traits/` module (e.g., `QueryUseCase` in `interactor/query.rs`)

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/src/**/*.rs : Run `cargo test --lib --package stationapi` or `make test-unit` for unit tests focusing on entities and repository mocks without database

Applied to files:

• docs/architecture.md
• docs/technical_debt.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/src/infrastructure/**/*.rs : Repository implementations in infrastructure layer should share an `Arc<PgPool>` connection pool

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: When running locally, `cargo run -p stationapi` should rebuild schema from `data/create_table.sql`, import all `data/*.csv` files, and then boot the gRPC server

Applied to files:

• docs/architecture.md

🔇 Additional comments (13)

README.md (1)

16-16: ✅ アーキテクチャドキュメントへのリンク追加が適切に実装されています

新しいドキュメントへのリンクが Documentation セクションに正しく配置されており、形式も統一されています。

docs/architecture.md (9)

1-50: ✅ アーキテクチャドキュメントの構造と概要セクションが優れています

目次、概要、技術スタック表により、ドキュメント全体への入口が明確です。

---

35-125: ✅ 4層アーキテクチャの説明が包括的です

各層（Domain/UseCase/Infrastructure/Presentation）の責務が明確に定義され、ディレクトリ構成と対応する表が参考になります。依存性方向（外→内）の図示も設計意図を効果的に伝えています。

---

128-195: ✅ データベース設計とスキーマ更新ガイダンスが実践的です

テーブル構成、パフォーマンス最適化（インデックス、pg_trgm、btree_gist）、スキーマ更新時の手順（マイグレーション→Row→Entity→変換ロジック→DTO）が段階的に説明されており、実装者にとって参考になります。

---

199-264: ✅ Row構造体とEntityの区別が明確に文書化されました

命名規則セクションが Row（DB マッピング）と Entity（ドメインモデル）の違いをコード例で示しており、infrastructure/*_repository.rs と domain/entity/*.rs の分離原則が理解しやすくなっています。変換フロー図（Database → Row → Entity → Enriched Entity → gRPC Message）も効果的です。

---

267-325: ✅ キャッシュ戦略の判断理由が透過的に説明されています

「明示的キャッシュなし」という設計決定を、バッチクエリ（query.rs:169-265）と HashSet による重複排除（query.rs:223）の具体例で正当化しており、「キャッシュを実装しない理由」セクション（データ規模、更新頻度、ステートレス設計、PostgreSQL 最適化）も納得性があります。「将来の検討事項」で moka/lru クレートへの言及も将来の拡張性を示しています。

---

328-385: ✅ データフロー図とエラー伝播チェーンが視覚化されています

リクエストフロー（Presentation → UseCase → Infrastructure → Domain → Entity 変換 → gRPC Message）とエラー伝播（DomainError → UseCaseError → PresentationalError → tonic::Status）が ASCII 図で示されており、レイヤー間の通信と責務が直感的に理解できます。

---

389-435: ✅ ディレクトリ構造マッピングが完全です

stationapi/src/ 配下の全モジュール（domain/entity, use_case/interactor, infrastructure, presentation）が階層的に表示されており、新規貢献者が各ファイルの役割を迅速に把握できます。

---

169-195: 🔍 gRPC スキーマ更新ガイダンスが充実しています

Proto 更新時の後方互換性ガイドライン（optional キーワード使用）と DTO 更新手順が明記されており、スキーマ進化の際の注意点が明確です。

---

439-443: ✅ 関連ドキュメントへのリンクが完備されています

technical_debt.md、repository_testing.md、data/README.md への参照により、ドキュメント体系の一貫性が保たれています。

docs/technical_debt.md (3)

212-223: ✅ 技術負債ステータス更新が適切に実施されています

アーキテクチャドキュメント不足が対応済み（2026年1月）と明記され、docs/architecture.md へのリンクが追加されています。対応済み領域として4つの完成項目（4層構造、命名規則、キャッシュ戦略、データフロー）を列挙している点が実装内容との整合性を示しています。

---

225-229: ✅ 残存する課題を透過的に記載しています

SQL 設計ドキュメントがインラインコメントに留まることを明記している点は、スコープの境界を明確にし、今後の改善対象を示しています。

---

319-319: ✅ 優先度別サマリー表が一貫性を保っています

ストライクスルーで完了したアーキテクチャドキュメント項目を標示し、[docs/architecture.md](./architecture.md) へリンクしており、技術負債追跡の完全性が保たれています。

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}