1. 概要

flowchart LR
  IN["Scenario シナリオ
candidates 候補一覧
beacons 場所カタログ
profiles プロフィール"] --> CORE["run_matching
マッチング実行"]
  CORE --> E["exclusions
除外一覧"]
  CORE --> P["pair_scores
ペア点数"]
  CORE --> G["groups
採用グループ"]
  E --> OUT["print_report
結果レポート出力"]
  P --> OUT
  G --> OUT
  IN --> OUT
        

図 1 — 入力から標準出力（stdout）への報告までの全体像

2. ファイル構成（8 ブロック）

flowchart TB
  FILE["matching_demo.py"]
  FILE --> B1["① CONFIG
設定定数（重み・閾値）"]
  FILE --> B2["② TYPES
型定義（dataclass）"]
  FILE --> B3["③ SCENARIOS
埋め込みシナリオ A〜E"]
  FILE --> B4["④ TIME UTILS
時間ユーティリティ"]
  FILE --> B5["⑤ SCORING
採点関数群"]
  FILE --> B6["⑥ PIPELINE
処理パイプライン"]
  FILE --> B7["⑦ REPORT
レポート出力"]
  FILE --> B8["⑧ main
起動入口"]
  B1 --> B6
  B2 --> B6
  B3 --> B8
  B4 --> B5
  B5 --> B6
  B6 --> B7
  B7 --> B8
        

図 2 — 依存は下位（設定・純関数）からパイプライン、最後に CLI（コマンドライン起動）

3. 実行パイプライン

sequenceDiagram
  participant CLI as main（起動）
  participant Run as run_matching（実行）
  participant Gate as filter_eligible（資格）
  participant Pair as score_pair（ペア採点）
  participant Form as form_groups（編成）
  participant Rep as print_report（表示）

  CLI->>Run: scenario（シナリオ入力）
  Run->>Gate: candidates（候補一覧）
  Gate-->>Run: eligible（通過者）+ exclusions（除外）
  loop 全ペア
    Run->>Pair: (a,b) + profiles（プロフィール）+ beacons（場所）
    Pair-->>Run: PairScore（ペア点）または None
  end
  Run->>Form: edges（合格ペア）+ duplicate sets（重複集合）
  Form-->>Run: MatchedGroup（採用グループ）
  CLI->>Rep: scenario + MatchingResult（結果一式）
  Rep-->>CLI: stdout 4セクション（標準出力）
        

図 3 — 呼び出し関係

4. 除外ゲート filter_eligible（資格フィルタ）

flowchart TD
  C["Candidate
候補1人"] --> Q1{"expires_at > now?
有効期限が現在より後か"}
  Q1 -->|No| X1["inactive_status
期限切れ"]
  Q1 -->|Yes| Q2{"intervals あり?
空き時間区間があるか"}
  Q2 -->|No| X2["NO_AVAILABILITY
空き時間なし"]
  Q2 -->|Yes| Q3{"prep 後の残り ≥ 30分?
準備時間後も30分以上あるか"}
  Q3 -->|No| X3["insufficient_remaining_time
残り時間不足"]
  Q3 -->|Yes| Q4{"適合 Beacon が存在?
使える場所があるか"}
  Q4 -->|No| X4["no_suitable_beacon
適合場所なし"]
  Q4 -->|Yes| Q5{"singleton が duplicate でない?
単独重複ブロックでないか"}
  Q5 -->|No| X5["duplicate_candidate_event
重複候補イベント"]
  Q5 -->|Yes| OK["eligible
通過（採点対象）"]
        

図 4 — 個人ゲート（グループ単位の duplicate＝重複集合チェックは form_groups 側）

5. ペア採点 score_pair（2人の相性点）

共通時間が最小イベント長に満たない、または適合 Beacon（場所）がない場合は None（辺なし＝ペア不成立）。 それ以外は 7 要因を重み付き合計し、0.00〜1.00 の matching_score（マッチング総合点）を返します。 辺として採用されるのは ≥ 0.60（ペア合格閾値）のペアです。

要因重み（合計 1.00）

flowchart LR
  A["Candidate A
候補A"] --> S["score_pair
ペア採点"]
  B["Candidate B
候補B"] --> S
  S --> F["FactorScores × weights
要因点×重み"]
  F --> T["matching_score
総合点"]
  T --> G{"≥ 0.60?
ペア合格閾値"}
  G -->|Yes| EDGE["pair_score_map に登録
合格ペア辞書へ"]
  G -->|No| DROP["グループ候補の辺にしない"]
        

図 5 — ペア辺（合格した2人関係）の生成

6. グループ形成 form_groups（チーム編成）

flowchart TD
  E["eligible + pair edges
通過者＋合格ペア辺"] --> C["combinations size 2..5
2〜5人の全組合せ"]
  C --> D{"集合が duplicate?
重複候補集合か"}
  D -->|Yes| Skip["skip スキップ"]
  D -->|No| V{"全ペア ≥ 0.60
共通時間・Beacon OK
group score ≥ 0.70?
グループ総合点"}
  V -->|No| Skip
  V -->|Yes| Rank["selection_score でソート
選定スコア順"]
  Rank --> Pick["貪欲採用・非再利用"]
  Pick --> G["MatchedGroup[]
採用グループ配列"]
        

図 6 — グループ候補の列挙と貪欲選択

selection_score（選定スコア） ＝ matching_score（総合点） ＋ size_bonus（人数ボーナス） （2人で +0.00、以降1人あたり +0.02、最大 +0.06）。

7. 関数一覧

時間ユーティリティ

スコアリング

パイプライン / I/O（入出力）

8. 出力セクション（現行）

flowchart TB
  R["print_report
結果レポート"] --> S1["[1] Participants 参加者
空き時間・場所・学科・友人・重み"]
  R --> S2["[2] Exclusions 除外
reason_code 理由コード"]
  R --> S3["[3] Pair scores ペア点
factors 要因 / weighted 寄与 / inputs 入力"]
  R --> S4["[4] Groups グループ
members メンバー / scores 点数 / beacon 場所"]
        

図 7 — 検証しやすいよう属性と寄与を明示

9. 埋め込みシナリオ

10. 実行方法

関連: シナリオ解説 A〜E · 想定構成 · やさしい解説 · 本番対応 backend/app/services/matching_service.py（マッチングサービス）