Cross-Realm Refactor PR Report

[yusuke0610]

Summary

• OLLAMA_* 環境変数名を backend/app/core/env_keys.py に正本化し、ollama_client.py の生リテラル参照を env_keys 経由へ置換（CLAUDE.md / security.md の「生リテラル os.getenv 禁止」へ準拠）。
• DTO 二重定義のドリフト検知不在（Medium）は、CLAUDE.md の「技術判断は ADR 起票後に実装」に従い ADR-0007（Proposed）を起票。openapi-typescript パイプライン実装と型移行は本 ADR が定義する後続 PR に分離。
• ドキュメント重複（README セットアップ / tofu 実行例）を正本（docs/development.md・docs/deployment.md）へのリンク参照に寄せた。
• OLLAMA 以外の env 名散在（Low）は実コードのドリフト無しを確認し、現状維持（HCL/YAML は Python 定数を import 不可のため機械化不要）。

SSoT Consolidations

High

• 観点: 環境変数名（OLLAMA_*）の SSoT 不在＋生リテラル参照
• SSoT に据えた場所: backend/app/core/env_keys.py:74-80（# --- LLM --- セクションに OLLAMA_BASE_URL / OLLAMA_MODEL / OLLAMA_TIMEOUT を追加）
• 更新した参照元:
  • backend/app/services/intelligence/llm/ollama_client.py:9,22-24（from ....core import env_keys を追加し os.environ.get(env_keys.OLLAMA_*, ...) へ置換）
  • docker-compose.yml:24-27（OLLAMA_* の名前正本が env_keys.py である旨をコメントで明記）
• 判断: OLLAMA_KEEP_ALIVE（docker-compose.yml の ollama サービス側、30m 固定）は backend が一切参照しない Ollama サーバ自身の設定のため env_keys.py には追加しない（追加すると未使用定数になる）。レポートの「必要なら」に対し不要と判断し、その旨を env_keys.py のコメントに残した。
• 互換性配慮: 環境変数名・既定値は不変。docker-compose / CI / Cloud Run の注入は変更なし（OLLAMA は本番 Cloud Run に元々未注入）。休眠インフラ（[[project_llm_stack_dormant]]）の温存方針とも矛盾しない（削除ではなく正本化）。

Medium

• 観点: DTO 二重定義（BE schemas/** ↔ FE types.ts / api/*.ts）のドリフト検知不在
• SSoT に据えた場所: 本 PR では実装せず。判断記録として docs/adr/0007-openapi-typescript-codegen.md（ステータス: Proposed）を起票。
• 内容: backend Pydantic schema を DTO の SSoT とし、FastAPI の OpenAPI → openapi-typescript で frontend/src/api/generated.ts を生成、CI で git diff --exit-code によりドリフトを検知する案。Phase 0（基盤）→ Phase 1（api/shared.ts パイロット）→ Phase 2/3（github_link / resume / blog / master_data 移行）の段階移行プランを定義。
• 互換性配慮: api/client.ts の 401/CSRF/Cookie ロジック、api/paths.ts（API パス SSoT）、errorCodes 型縛りはいずれも対象外として維持。命名差（CareerResumeResponse ↔ ResumeResponse）は再エクスポートで吸収。
• 本 PR で実装しなかった理由: 本 skill（XR_apply）が「OpenAPI codegen は本 PR の対象外（別 PR）」と明記し、レポートも「重い投資のため Medium 据え置き / 別 PR」と判断。依存追加・make ターゲット・全 DTO 移行を env/docs 修正と束ねるとレビュー不能になるため、ADR 起票（CLAUDE.md が義務付ける第一ステップ）までを本 PR のスコープとした。

Low

• 観点: env 名の正本（env_keys.py）↔ 注入経路（cloud_run/main.tf・docker-compose.yml・ci.yml）の散在（OLLAMA 以外）
• 対応: 実コード変更なし（現状維持）。
• 確認結果: infra/modules/cloud_run/main.tf の env 名（18 件）はすべて env_keys.py に存在しドリフト無し。.github/workflows/ci.yml の PROJECT_ID / REGION は GCP デプロイ用変数で Python から参照不可、VITE_APP_VERSION は frontend ビルド変数。いずれも env_keys.py の対象外で問題なし。env_keys.py の「4 箇所同期」手順コメントが SSoT として機能していることを確認。

Documentation Consolidations

• 正本: docs/development.md（初回セットアップ・make ci）
  • リンク参照に置換した箇所: README.md「クイックスタート」（make setup / make ci スニペット重複を削除しリンク + 再掲しない理由を明記）
• 正本: docs/deployment.md（OpenTofu 実行手順・GCS backend 認証）
  • リンク参照に置換した箇所: docs/data-model.md「OpenTofu で DB を作成」（一般 tofu 手順をリンク参照化し、Turso DB 固有手順のみ残置）、.claude/rules/infra/opentofu.md:14（実行手順は deployment.md を正本参照する旨を追記）
  • 残置した重複: .claude/rules/infra/test.md の make infra-validate 系コマンド列。これは「いつ検証を回すか（infra テスト方針）」という別目的であり、変更理由が異なる（偶発的重複）ため duplication.md の方針に従い抽出しない。

Skipped

• DTO codegen のパイプライン実装・型移行（Medium）: 上記理由により後続 PR へ分離。ADR-0007 を Accepted に昇格させた上で Phase 0 から着手する。
• OLLAMA 以外の env 名の機械化（Low）: HCL/YAML は Python 定数を import できず、機械化すると逆に不整合源になるため見送り（レポートも「機械化不要」と判断）。

Validation

• make lint-backend: pass（All checks passed!）
• make test-backend: pass（443 passed, 2 warnings / 30.40s）
  • tests/test_llm_clients.py 単体: 14 passed
• make lint-frontend / make build-frontend: 未実行（frontend のコード変更なし。変更は markdown=README/ADR のみ）
• make infra-fmt-check / make infra-validate: 未実行（infra の .tf 変更なし。変更は markdown=rules/docs のみ）
• make dupe-check: before 56 clones → after 56 clones（cross-realm clone 0 件を維持。新規重複なし。env_keys/ollama_client の変更はリテラル重複を削減する方向）
• E2E: 未実行（API 契約・ルート・認証・サイドバーいずれも変更なし。env_keys 内部参照の置換と markdown のみ）

Follow-ups

• ADR-0007 を Accepted へ昇格し、別 PR で OpenAPI→TS codegen パイプライン（Phase 0: export_openapi.py / openapi-typescript / make codegen-types / CI ドリフト検知）を構築。
• パイプライン構築前に backend 全 router の response_model 付与状況を棚卸し（未設定だと OpenAPI に型が出ないため）。

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6cb15829-d8ea-4f9b-ac95-12d20502cab4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/backend/deadcode

---

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