♻️ Clubs との突合を dojo2dojo.csv から global_club_id に切り替える (#42)

クラブ名を手で対応付ける dojo2dojo.csv (301 行) をやめ、coderdojo.jp の
global_club_id で直接突き合わせる。CSV は削除した。

名前での突合には次の問題があった。

- 新しい Dojo を追加するたび CSV に 1 行足す運用が必要で、実際に漏れていた
- Clubs 側で改名されると追従できない（那覇の登録名が変わっていた）
- 同名クラブが二重登録されていると、先に現れた方を拾ってしまう（流山・古河）

active な全エントリが global_club_id を持つことは coderdojo.jp 側の spec が
保証しているため、名前で救済する経路は置いていない。

## 同じ入力データで新旧の出力を比較した結果

- 日本のマーカー 195 -> 202 件。地図から消えた Dojo は 0 件
- 増えた 7 件は CSV に行が無く漏れていたもの
- 流山・古河は約 0.1km 移動。Clubs 側の同名二重登録のうち、coderdojo.jp が
  指定した UUID のクラブを選ぶようになったため

## あわせて整理したもの

- tmp/unmatched_dojos.json と Slack 通知を追加。CSV が無くなった今、Clubs 側の
  削除・ID 変更を検知できるのはこれだけになる
- deploy_to_pages.yml のデータ取得に Japan 側の件数・UUID 数チェックを追加
- 突合の情報源が Japan DB 自体になり到達不能となったガードを削除 (#43)
- /dojo2dojo.json を /dojos.json に改名（dojo2dojo は CSV に由来する名前）
- _plugins/build_hooks.rb が生成タスクの終了コードを見ていなかったため、
  失敗しても古い地図が出荷されていた。exception: true で止める
- PR でもビルドとテストを走らせる (deploy_to_pages.yml -> ci.yml)。
  これまで rake test は main への push 後にしか走っていなかった

Author: yasulab

.github/workflows/deploy_to_pages.yml .github/workflows/ci.yml.github/workflows/deploy_to_pages.yml renamed to .github/workflows/ci.yml

@@ -1,13 +1,21 @@
-name: Deploy to GitHub Pages
+name: CI
 on:
   push:
     branches: ["main"]
 
+  # PR でもビルドとテストを走らせる。デプロイはしない (最後の 🚀 の if を参照)。
+  # これを足す前は rake test が main への push 後にしか走らず、テストが落ちるのは
+  # マージした後だった。日本のマーカーが静かに消える回帰は、この rake test でしか
+  # 検出できない (tests/dojo_matching_test.rb)。
+  # cf. https://github.com/coderdojo-japan/map.coderdojo.jp/pull/42
+  pull_request:
+
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
 jobs:
   deploy:
+    name: 🧪 Build, Test & Deploy
     runs-on: ubuntu-latest
     steps:
     - name: 📥 Download codes from GitHub
@@ -26,9 +34,9 @@ jobs:
 
     # Jekyll のビルドは _data/*.json から GeoJSON を再生成するが、データの再取得は
     # しない。そのため取得なしでビルドすると、コミット済みの古いデータで地図が
-    # 出荷される。新しい Dojo を dojo2dojo.csv に追加して push した直後は、その
-    # Dojo が _data/dojos_japan.json に必ず未反映なので、地図に出ないまま配信
-    # されてしまう (upsert_dojos_geojson.rb のガードによりスキップされるため)。
+    # 出荷される。coderdojo.jp に新しい Dojo が追加された直後は、その Dojo が
+    # _data/dojos_japan.json に未反映なので、地図に出ないまま配信されてしまう
+    # (upsert_dojos_geojson.rb のガードによりスキップされるため)。
     #
     # ここで最新データを取れれば push 直後から正しく描画できる。ただし取得は外部
     # API に依存するため、失敗してもデプロイは止めない (continue-on-error)。
@@ -37,8 +45,12 @@ jobs:
     # 従来どおり (古いデータでのビルド) に落とす。
     #
     # データのコミットはしない。それは scheduler_daily.yml の責務。
+    #
+    # PR では取得しない。コミット済みのデータだけでビルドすることで、PR の結果が
+    # 外部 API の状態で揺れなくなり、リポジトリの中身そのものを検証できる。
     - name: 🌐 Fetch latest data (best-effort)
       id: fetch
+      if: github.event_name != 'pull_request'
       continue-on-error: true
       run: |
         bundle exec rake get_data_from_earth
@@ -49,6 +61,20 @@ jobs:
         fi
         bundle exec rake get_data_from_japan
 
+        # Japan 側も件数を確かめる。ここを素通りさせると、取得は成功したが中身が
+        # 劣化していた場合に下の復元パスへ落ちず、後段の rake test でデプロイ全体が
+        # 止まる。Geolonia 障害時の緊急デプロイを外部 API の状態に左右させないため、
+        # ここで失敗させてコミット済みデータへ戻す。
+        # 突合は global_club_id で行うので、件数だけでなく UUID の数も見る。
+        # 下限は tests/dojo_matching_test.rb と揃えている。
+        NUMBER_OF_DOJOS=$(ruby -rjson -e 'puts JSON.parse(File.read("_data/dojos_japan.json")).size')
+        NUMBER_OF_UUIDS=$(ruby -rjson -e 'puts JSON.parse(File.read("_data/dojos_japan.json")).count { |d| d["global_club_id"] }')
+        if [ "$NUMBER_OF_DOJOS" -lt "300" ] || [ "$NUMBER_OF_UUIDS" -lt "150" ] ; then
+          echo "ERROR: NUMBER_OF_DOJOS=$NUMBER_OF_DOJOS NUMBER_OF_UUIDS=$NUMBER_OF_UUIDS"
+          echo "These numbers should be 300+ / 150+. Something went wrong."
+          exit 1
+        fi
+
     - name: ♻️ Restore committed data if the fetch failed
       if: steps.fetch.outcome == 'failure'
       run: |
@@ -65,7 +91,10 @@ jobs:
     # This is NOT for security reason but for others, especially who fork,
     # to easier find out which API key they need to replace with their own.
     # Check out the official tutorial for details: https://docs.geolonia.com/tutorial
+    # PR では注入しない。デプロイしないので不要で、fork からの PR には
+    # そもそも secrets が渡らない。
     - name: 🔑 Pass Geolonia YOUR-API-KEY from secrets
+      if: github.event_name != 'pull_request'
       env:
         GEOLONIA_API_KEY: ${{ secrets.GEOLONIA_API_KEY }}
       run: |

.github/workflows/scheduler_daily.yml

@@ -51,6 +51,16 @@ jobs:
       run: |
         bundle exec rake get_data_from_japan
 
+        # 日本のマーカーは global_club_id での突合に依存している。取得に失敗して
+        # 空や欠損のデータが入ると、海外のマーカーだけが残った地図がデプロイされる。
+        # Earth 側と同じく、入口で件数を確かめる
+        NUMBER_OF_DOJOS=$(ruby -rjson -e 'puts JSON.parse(File.read("_data/dojos_japan.json")).size')
+        if [ "$NUMBER_OF_DOJOS" -lt "300" ] ; then
+          echo "ERROR: NUMBER_OF_DOJOS=$NUMBER_OF_DOJOS"
+          echo "This number should be 300+. Something went wrong."
+          exit 1
+        fi
+
     - name: 🔧 Build data to render DojoMap
       run: |
         # Jekyll plugin automatically runs upsert_dojos_geojson and compact_geojson
@@ -88,6 +98,52 @@ jobs:
       env:
         GITHUB_TOKEN:
 
+    # 地図に載らなかった active な Dojo を検知する。
+    #
+    # 意図的な設計:
+    # - デプロイの「後」に置く。1 つの Dojo が Clubs 側で消えただけで日次更新
+    #   全体を止めるのは割に合わない
+    # - continue-on-error でジョブ自体は失敗させない
+    # - 通知するのは uuid_not_in_clubs と no_uuid の 2 つ。
+    #   uuid_not_in_clubs は Japan 側が UUID を持っているのに Clubs 側にその
+    #   クラブが無い状態で、削除か UUID 変更が起きている。
+    #   no_uuid は coderdojo.jp 側の spec が防いでいるはずの状態なので、ここに
+    #   出たら上流の保証が破れている。
+    # - club_excluded_by_status_or_coordinates は Clubs 側の登録内容の問題で、
+    #   こちらからは直せないためログのみに留める
+    - name: 🔎 Check unmatched dojos
+      id:   unmatched
+      continue-on-error: true
+      run: |
+        cat tmp/unmatched_dojos.json
+        ruby -rjson -e '
+          critical = JSON.parse(File.read("tmp/unmatched_dojos.json"))
+                         .select { |d| %w[uuid_not_in_clubs no_uuid].include?(d["reason"]) }
+          exit 0 if critical.empty?
+          critical.each { |d| warn "#{d["name"]} (id=#{d["id"]}): #{d["reason"]} #{d["global_club_id"]}" }
+          exit 1
+        '
+
+    - name: 🔔 Notify unmatched dojos to Slack (if any)
+      if:   steps.unmatched.outcome == 'failure'
+      uses: slackapi/slack-github-action@v3.0.5
+      with:
+        webhook:      ${{ secrets.SLACK_WEBHOOK_URL }}
+        webhook-type: incoming-webhook
+        payload: |
+          {
+            "text": "<@yasulab> 地図に載らなかった Dojo があります。",
+            "blocks": [
+              {
+                "type": "section",
+                "text": {
+                  "type": "mrkdwn",
+                  "text": "<@yasulab> *地図に載らなかった Dojo があります。* coderdojo.jp 側の `global_club_id` が Clubs DB のクラブと結びついていません。提携先での削除・ID 変更か、`global_club_id` の未設定が考えられます。\n\n*対応:* `db/dojos.yml` の `global_club_id` を現在の値に更新してください。該当 Dojo 名と理由はログに出ています。\n\n<https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}|» 詳細を見る (GitHub)>"
+                }
+              }
+            ]
+          }
+
     # This is NOT for security reason but for others, especially who fork,
     # to easier find out which API key they need to replace with their own.
     # Check out the official tutorial for details: https://docs.geolonia.com/tutorial

CLAUDE.md

@@ -73,7 +73,7 @@ bundle exec rake test
 
 **メリット**:
 - ✅ ローカル開発でも本番環境でも一貫した動作
-- ✅ `dojo2dojo.csv`更新後、`jekyll build`だけで自動反映
+- ✅ `_data/*.json` 更新後、`jekyll build`だけで自動反映
 - ✅ 手動でのRakeタスク実行が不要
 
 **実行ログ例**:
@@ -100,8 +100,8 @@ GitHub Actionsで毎日自動更新（日本時間 5:59）:
 # scheduler_daily.yml（データ更新＋デプロイ）
 gh workflow run scheduler_daily.yml
 
-# deploy_to_pages.yml（デプロイのみ）
-gh workflow run deploy_to_pages.yml
+# ci.yml（ビルド・テスト・デプロイ。PR ではデプロイせずテストまで）
+gh workflow run ci.yml
 
 # 実行状況確認
 gh run list --workflow=scheduler_daily.yml --limit 3
@@ -118,8 +118,8 @@ gh run watch  # リアルタイム監視
 - `_data/dojos_earth.json`: Clubs APIから取得した全世界のDojoデータ
 - `_data/dojos_japan.json`: CoderDojo Japan APIから取得した日本のDojoデータ
 - `_data/events_japan.json`: 日本のイベントデータ
-- `_data/dojo2dojo.json`: dojo2dojo.csvから生成されたマッピングデータ
-- `dojo2dojo.csv`: Japan APIとClubs APIの名前マッピング（編集可能）
+- `_data/dojos.json`: 地図に載った日本のDojo一覧（生成物）。`/dojos.json` として配信し、掲載後の反映確認に使う
+- `tmp/unmatched_dojos.json`: 地図に載らなかったactiveなDojoと、その理由（生成物）
 - `dojos.geojson`: 地図表示用の統合データ（GeoJSON形式、人間が読める形式）
 - `dojos.min.geojson`: 圧縮版GeoJSON（本番環境で使用、22.9%削減）
 - `_plugins/build_hooks.rb`: Jekyllビルド時の自動データ更新フック
@@ -208,8 +208,8 @@ mcp__o3__o3-search "GitHub Actions Pages deploy Jekyll JEKYLL_ENV production 202
 # 複数データソース統合時の名前マッチング問題
 mcp__o3__o3-search "GeoJSON data integration name mapping mismatch multiple sources 2025"
 
-# CSVベースのマッピングファイル管理
-mcp__o3__o3-search "CSV mapping file data integration best practices version control 2025"
+# ID ベースでのデータ突合
+mcp__o3__o3-search "stable identifier vs name matching data integration best practices 2025"
 
 # データ不整合のデバッグ手法
 mcp__o3__o3-search "multi-source data integration debugging missing records troubleshooting 2025"
@@ -226,59 +226,47 @@ o3の検索結果を使用する際は必ず：
 
 ### データ統合で特定のDojoが地図に表示されない場合
 
-この問題は主にdojo2dojo.csvのマッピング不一致が原因です。以下の手順で調査・修正してください：
+Clubs DB と Japan DB は `global_club_id` (UUID) で突合している。表示されない場合、
+ほぼ全て「UUID が一致していない」ことが原因なので、まず生成物の診断結果を見る。
 
-1. **データソースの確認**
+1. **地図に載らなかった Dojo と理由を確認する**
    ```bash
-   # Clubs APIのデータ確認
-   grep "対象Dojo名" dojos_earth.json
-   
-   # Japan APIのデータ確認
-   grep "対象Dojo名" dojos_japan.json
+   bundle exec rake upsert_dojos_geojson
+   cat tmp/unmatched_dojos.json
    ```
 
-2. **マッピングファイルの確認**
-   ```bash
-   # dojo2dojo.csvでのマッピング確認
-   grep "対象Dojo名" dojo2dojo.csv
-   ```
+   `reason` の意味は次のとおり。
 
-3. **問題の特定と修正**
-   - Clubs APIでの登録名と完全一致するようにdojo2dojo.csvを修正
-   - 例：「Coderdojo Saga」vs「Saga」のような不一致を修正
+   | reason | 意味 | 対応 |
+   |---|---|---|
+   | `uuid_not_in_clubs` | coderdojo.jp の `global_club_id` が指すクラブが Clubs DB に無い | Clubs 側で削除・ID 変更が起きている。`db/dojos.yml` の値を現在のものに更新する |
+   | `club_excluded_by_status_or_coordinates` | クラブはあるが、座標が無いか活動中ではない | Clubs 側の登録内容を直す（提携先の管理画面） |
+   | `no_uuid` | coderdojo.jp 側に `global_club_id` が無い | `db/dojos.yml` に設定する。通常は向こうの CI が防ぐ |
 
-4. **マッピング追加とGeoJSON再生成**
+2. **Clubs DB 側の現在の UUID を調べる**
    ```bash
-   # dojo2dojo.csvに追加（例: すぎなみ）
-   echo "すぎなみ	Suginami" >> dojo2dojo.csv
-
-   # jekyll buildで自動的にGeoJSON再生成（推奨）
-   bundle exec jekyll build
-
-   # または個別実行
-   bundle exec rake upsert_dojos_geojson
-   bundle exec rake compact_geojson
+   ruby -rjson -e 'JSON.parse(File.read("_data/dojos_earth.json")).select { |c| c["countryCode"] == "JP" && c["name"].include?("対象名") }.each { |c| puts "#{c["id"]} #{c["name"]} #{c["status"]}" }'
    ```
 
-5. **結果の確認**
-   ```bash
-   # GeoJSONに含まれているか確認
-   grep "対象Dojo名" dojos.geojson
+3. **coderdojo.jp 側を直す**
 
-   # ローカルで地図表示確認
-   bundle exec jekyll server
-   # http://localhost:4000/ で確認
-   ```
+   `db/dojos.yml` の `global_club_id` を更新し、PR を出す。地図側のリポジトリで
+   修正することはない（名前で突合していた頃と違い、こちらに手動のマッピングは無い）。
 
-6. **変更をコミット**
+4. **反映を確認する**
    ```bash
-   git add dojo2dojo.csv _data/dojo2dojo.json dojos.geojson
-   git commit -m "CoderDojo XXXのマッピングを追加"
-   git push origin main
+   bundle exec rake get_data_from_japan   # coderdojo.jp のデプロイ完了後に実行
+   bundle exec rake upsert_dojos_geojson
+   bundle exec rake test_matching
    ```
 
-### よくあるマッピング問題
-- **プレフィックスの不一致**: "Coderdojo XXX" vs "XXX"
-- **スペースの不一致**: "CoderDojo" vs "Coderdojo"
-- **記号の不一致**: "@" や "、" の有無
-- **日本語・英語の混在**: 漢字・ひらがな・カタカナ・ローマ字の不一致
+### 名前での突合をやめた理由
+
+以前は `dojo2dojo.csv` で「Japan 登録名 → Clubs 登録名」を手で対応付けていたが、
+次の理由で UUID 突合に切り替えた。
+
+- 新しい Dojo を追加するたび CSV に 1 行足す運用が必要で、実際に漏れていた
+- Clubs 側で改名されると追従できない（那覇の登録名が変わっていた）
+- 同名クラブが二重登録されていると、先に現れた方を拾ってしまう（流山・古河）
+- 表記ゆれ（"Coderdojo XXX" vs "XXX"、"@" や "、" の有無、ローマ字と日本語）に
+  そのつど対応する必要があった

README.md

@@ -1,4 +1,4 @@
-[![Deploy to GitHub Pages](https://github.com/coderdojo-japan/map.coderdojo.jp/actions/workflows/deploy_to_pages.yml/badge.svg)](https://github.com/coderdojo-japan/map.coderdojo.jp/actions/workflows/deploy_to_pages.yml) [![pages-build-deployment](https://github.com/coderdojo-japan/map.coderdojo.jp/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/coderdojo-japan/map.coderdojo.jp/actions/workflows/pages/pages-build-deployment) [![Daily Update](https://github.com/coderdojo-japan/map.coderdojo.jp/actions/workflows/scheduler_daily.yml/badge.svg)](https://github.com/coderdojo-japan/map.coderdojo.jp/actions/workflows/scheduler_daily.yml)
+[![CI](https://github.com/coderdojo-japan/map.coderdojo.jp/actions/workflows/ci.yml/badge.svg)](https://github.com/coderdojo-japan/map.coderdojo.jp/actions/workflows/ci.yml) [![pages-build-deployment](https://github.com/coderdojo-japan/map.coderdojo.jp/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/coderdojo-japan/map.coderdojo.jp/actions/workflows/pages/pages-build-deployment) [![Daily Update](https://github.com/coderdojo-japan/map.coderdojo.jp/actions/workflows/scheduler_daily.yml/badge.svg)](https://github.com/coderdojo-japan/map.coderdojo.jp/actions/workflows/scheduler_daily.yml)
 
 # :japan: DojoMap - 地図で CoderDojo を探す
 

Rakefile

@@ -12,6 +12,11 @@ task(:compact_geojson)      { ruby '_tasks/compact_geojson.rb'      }
 desc 'Run GeoJSON data and map-marker integrity tests'
 task(:test_markers) { ruby 'tests/markers_integrity_test.rb' }
 
+# Clubs DB と Japan DB の突合が壊れていないかのテスト (minitest)
+# 日本のマーカーだけが静かに消える回帰を防ぐ。詳細は tests/dojo_matching_test.rb 参照。
+desc 'Run dojo matching (global_club_id) integrity tests'
+task(:test_matching) { ruby 'tests/dojo_matching_test.rb' }
+
 # Geolonia スプライト サーバの健全性を手動確認するテスト (minitest)。
 # 外部サービス状態に CI を依存させないため、`test` には含めず手動実行する:
 #   GEOLONIA_API_KEY=xxxx bundle exec rake test_sprite
@@ -21,7 +26,7 @@ task(:test_sprite) { ruby 'tests/sprite_status_test.rb' }
 # GitHub - gjtorikian/html-proofer
 # https://github.com/gjtorikian/html-proofer
 require 'html-proofer'
-task test: [:build, :test_markers] do
+task test: [:build, :test_markers, :test_matching] do
   #require './tests/custom_checks'
   options = {
     #checks: ['Links', 'Images', 'Scripts', 'OpenGraph', 'Favicon', 'CustomChecks'],

_config.yml

@@ -26,7 +26,6 @@ exclude:
   - README.md
   - LICENSE.md
   - CODE_OF_CONDUCT.md
-  - dojo2dojo.csv
 
 # See the official README for more options:
 # https://github.com/digitalsparky/jekyll-minifier