スケジュール最適化バックエンドの今後の進め方（疎結合・可搬性・調整容易性）

[masa10-f]

背景

スケジューリング最適化（OR-Tools CP-SAT）が humancompiler_api 内に直書きされており、調整・差し替え・テストが難しい。
直近のPRで humancompiler_optimizer サブパッケージへ移し、API側は必要情報を config + 変数で渡す形に整理した。

ゴール

• 最適化バックエンドを humancompiler_api から疎結合に保つ（DB/HTTP/Sessionへの依存を持たせない）
• 調整ポイント（重み・制約・タイムアウト等）を外部から安全に変更できるようにする
• バックエンド差し替え（OR-Tools/ヒューリスティック/将来の別ソルバー）を現実的な工数で可能にする

提案する進め方（チェックリスト）

1) API境界の固定（契約）

• humancompiler_optimizer の「入力/出力/Config」を明文化（README or docstring）
• 互換性ポリシー（破壊的変更のルール）を決める
• humancompiler_optimizer に最小限の契約テストを追加（入出力の型・必須フィールド・代表ケース）

2) 依存の分離（OR-Toolsをoptional化）

• OR-Tools依存を extras に分離（例: humancompiler-api[ortools] or humancompiler-optimizer[ortools]）
• OR-Toolsが無い環境の挙動を統一
  • 週次: 既にフォールバックあり（維持/改善）
  • 日次: フォールバック（ヒューリスティック） or 明示的な「利用不可」エラーを返す設計にする

3) 調整ポイントを外部化（Config設計）

• 日次: 目的関数の重み（優先度・種別一致・期限等）を DailySolverConfig に集約し、環境変数/設定から上書きできるようにする
• 週次: スケール係数・allocationの許容レンジ（0.95-1.05等）・bonus係数を WeeklySolverConfig に集約し、同様に外部化
• どのレイヤで設定を持つか決める（UserSettings / API request / env）

4) 観測性・デバッグ容易性

• 解の品質/制約違反/不採用理由の説明を増やす（特に日次の未割当理由）
• solverのメトリクス（solve time / objective / status / constraint summary）を標準化

5) 将来の分離（別パッケージ/別プロセス）に備える

• humancompiler_optimizer を独立Wheelに切り出せる構造（依存・エントリポイント）を整える
• 可能なら「別プロセス実行（CLI/HTTP）」のPoCを小さく作り、疎結合度を検証

オープンな論点（決めたいこと）

• 日次の依存関係（タスク/ゴール依存）の扱いを「ソルバーの制約」として強制するか、現状通り「API側のフィルタリング+順序制約」で良いか
• OR-Tools無し環境でのプロダクト要件（落ちても良い/フォールバック必須/機能制限をUIに出す 等）
• 日次/週次で「最適化」定義が違う（割当 vs 選択）。将来的に統一した抽象（backend interface）を作るか

受け入れ条件（Done）

• humancompiler_api から最適化バックエンドが疎結合である（DB/HTTP/Sessionに非依存）
• 調整が Config 変更で試せる（コード直書きでない部分が増えている）
• OR-Toolsの有無で挙動が明確で、テストで担保されている

🤖 Generated with Claude Code