fix: 実運用に基づく重要な技術仕様の修正

修正内容：
1. Rails 8.0 のマイグレーション形式に修正（[7.2] → [8.0]）
2. global_club_id を UUID 文字列型に修正（bigint → string）
   - 実際の値: "18704b53-1042-4464-9d49-8820c6ff8c97"
3. NOT NULL 制約を追加（全 Dojo に必須）
4. APIトークン関連を削除（読み取り専用APIなので不要）
5. 新規登録時の運用フローを明確化
   - 申請フォームで global_club_id を必須入力
   - 一度スクリプトで全Dojoに設定後は常に必須

根拠のない内容の削除：
- リスク分析表（Issue #1616 に記載なし）
- 日本固有の課題（Issue に記載なし）
- テスト戦略の詳細（過剰な内容）
- ロールバック戦略（Issue に記載なし）
- 将来の拡張計画（憶測）
- トラブルシューティングガイド（Issue に記載なし）

Issue #1616 の実際の内容に忠実な設計に修正

Author: yasulab

doc/global_club_id_design.md

@@ -2,16 +2,17 @@
 
 ## 概要
 
-このドキュメントは、Raspberry Pi Foundation が管理する国際的な Clubs API データベースと CoderDojo Japan のデータベースを連携させる機能の設計と実装について記載しています。
+このドキュメントは、Raspberry Pi Foundation が管理する国際的な Clubs DB と CoderDojo Japan の Japan DB を連携させる機能の設計と実装について記載しています。
 
 ## 背景
 
-### 現状の課題
-- 新しい Dojo が追加されるたびに、DojoMap に表示させるために手動で CSV を更新する必要がある
-- この手動作業は時間がかかり、エラーが発生しやすい
+### 現状
+
+- Clubs DB（Global Clubs）と Japan DB（CoderDojo Japan）が独立している
+- 両者を紐付ける ID がない
 
 ### 解決策
-Global Clubs データベースの ID（`global_club_id`）を CoderDojo Japan の Dojo と紐付けることで、データの同期を自動化する。
+Clubs DB の ID（`global_club_id`）を Japan DB の Dojo と紐付ける。
 
 ## 設計決定
 
@@ -50,85 +51,130 @@ def fetch_global_clubs(organization_slug: 'coderdojo', after: nil)
 
 ### API エンドポイント
 - GraphQL: `https://clubs-api.raspberrypi.org/graphql`
-- 認証: Bearer token (OAuth flow)
+- 認証: 不要（読み取り専用）
 - レート制限: 60 req/min
 
 ### データモデル
 
 #### Dojo モデルの拡張
 ```ruby
-# マイグレーション
-add_column :dojos, :global_club_id, :bigint
-add_index :dojos, :global_club_id, unique: true, where: 'global_club_id IS NOT NULL'
+# マイグレーション（必要なのはこれだけ！）
+# UUID 文字列（例: "18704b53-1042-4464-9d49-8820c6ff8c97"）
+add_column :dojos, :global_club_id, :string, null: false
+add_index :dojos, :global_club_id, unique: true
 ```
 
-#### 同期管理テーブル
-```ruby
-create_table :global_club_syncs do |t|
-  t.bigint :global_club_id, null: false
-  t.datetime :last_seen_at
-  t.string :sync_status
-  t.timestamps
-end
-```
+### マッピング戦略
+
+#### 初期マッピング（一度だけ実行）
+1. Clubs DB から全 CoderDojo を取得
+2. 既存の Dojo と手動で照合：
+   - 名前は異なることが前提（Clubs DB は英語、Japan DB は日本語）
+   - Japan DB には位置情報がないため、地理的照合は不可
+3. 人間が判断して `global_club_id` を設定
 
-### 同期戦略
+**重要な仕様理解**:
+- **名前の違いは正常**: Clubs DB（英語話者向け）と Japan DB（日本語話者向け）で名前が異なるのは仕様
+- **位置情報**: Japan DB にはなく、Clubs DB のみに存在
+- **用途例**: DojoMap アプリで global_club_id を使って英語名→日本語名の変換を行う
 
-#### 増分同期
-- `updatedAt` フィールドを使用して、前回の同期以降に更新されたクラブのみを取得
-- 全データを毎回取得するのではなく、効率的な差分更新を実現
-- 冪等性を保証（同じ操作を複数回実行しても結果が同じ）
+## 実装タスク（Issue #1616 より）
 
-#### マッチングアルゴリズム
-1. `global_club_id` で既存の Dojo を検索
-2. 見つからない場合は、名前の類似度 + 地理的距離（1km 以内）で自動マッチング
-3. 曖昧な場合は手動レビューキューに追加
+1. **Dojo モデルに `global_club_id` カラムを追加**
+   ```ruby
+   class AddGlobalClubIdToDojos < ActiveRecord::Migration[8.0]
+     def change
+       # UUID 文字列（例: "18704b53-1042-4464-9d49-8820c6ff8c97"）
+       add_column :dojos, :global_club_id, :string, null: false
+       add_index :dojos, :global_club_id, unique: true
+     end
+   end
+   ```
 
-## 実装計画
+2. **db/dojos.yaml の全 Dojo に `global_club_id` を追加**
+
+3. **Clubs DB と Dojo ID を紐付ける仕組みを作成**
 
-### フェーズ 1: 基盤整備
-1. データベーススキーマの更新（`global_club_id` カラム追加）
-2. YAML ファイルの構造更新
-3. モデルのバリデーション追加
 
-### フェーズ 2: API 統合
-1. `GlobalClubs::Client` クラスの実装
-2. GraphQL クエリの実装
-3. 認証設定（Rails credentials）
 
-### フェーズ 3: 同期機能
-1. `GlobalClubs::SyncService` の実装
-2. マッチングロジックの実装
-3. エラーハンドリングとリトライ機構
 
-### フェーズ 4: 運用
-1. 定期実行ジョブの設定
-2. 監視とアラートの実装
-3. 手動レビュー機能（将来的に）
 
 ## セキュリティ考慮事項
 
-- Bearer token は Rails credentials に保存
-- API 通信は HTTPS のみ
-- レート制限に対応（指数バックオフでリトライ）
+- HTTPS 通信（読み取り専用 API）
 
 ## 運用上の注意点
 
 ### データの整合性
-- ソフトデリート: Global Clubs API から削除されたクラブは `global_club_id = nil` に設定（Dojo レコードは削除しない）
-- 重複チェック: ユニーク制約により、同じ `global_club_id` を持つ複数の Dojo は作成できない
+- **ユニーク制約**: 同じ `global_club_id` を持つ複数の Dojo は作成できない
+- **NOT NULL 制約**: すべての Dojo に `global_club_id` が必須
+- **手動修正可能**: 必要に応じて管理画面から修正
+
+
+## 成功指標
+
+1. **global_club_id カラムの追加完了**
+2. **既存 Dojo への ID 設定完了**
+3. **DojoMap への自動反映の実現**（Issue #1616 の目的）
+
+## シンプルなワークフロー
 
-### エラー処理
-- ネットワークエラー: 自動リトライ（最大 3 回）
-- API エラー: エラーログに記録し、次回の同期で再試行
-- マッチング失敗: 手動レビューキューに追加
+### 新規 Dojo 追加時（申請フォームで対応）
+
+```
+1. 申請時に Clubs DB での登録状況を確認してもらう
+2. global_club_id を申請フォームに記入（必須）
+3. db/dojos.yaml に global_club_id 付きで追加
+```
+
+### 初期マッピング（一度だけ実行するスクリプト）
+
+```ruby
+# scripts/map_global_clubs.rb
+# 既存の全 Dojo に global_club_id を設定
+
+clubs = GlobalClubs.fetch_all_coderdojo_clubs  # 読み取り専用 API
+dojos = Dojo.active
+
+puts "Clubs DB: #{clubs.count} clubs"
+puts "Japan DB: #{dojos.count} dojos"
+puts ""
+puts "Manual mapping needed:"
+puts "Clubs DB (English)         | Japan DB (Japanese)"
+puts "---------------------------|--------------------"
+
+clubs.each do |club|
+  # club.id は UUID 文字列（例: "18704b53-1042-4464-9d49-8820c6ff8c97"）
+  puts "#{club.name.ljust(26)} | ???"
+end
+
+# 手動で db/dojos.yaml に global_club_id を追加
+# 例: global_club_id: "18704b53-1042-4464-9d49-8820c6ff8c97"
+```
 
-## 今後の拡張可能性
 
-- DojoMap との直接連携
-- リアルタイム同期（Webhook 対応）
-- 他の組織のクラブとの連携
 
 ## 更新履歴
 
 - 2025-01-20: 初版作成（設計決定まで確定、技術仕様以降は暫定版）
+- 2025-08-18: YAGNI原則に基づく大幅簡素化
+  - 不要なカラム削除（confidence, last_sync）
+  - 継続的同期を削除（一度きりのマッピングに変更）
+  - 複雑な監視・測定機能を削除
+  - シンプルなワークフローに変更
+  - CoderDojo運用の実態に合わせた現実的な設計に修正
+
+## 実装チェックリスト
+
+### 必要最小限の実装
+- [ ] `global_club_id` カラムの追加（string型、NOT NULL、UUID）
+- [ ] 読み取り専用の Clubs API クライアント実装
+- [ ] 既存 Dojo への一括マッピングスクリプト
+- [ ] 申請フォームに global_club_id 入力欄追加（必須）
+
+### やらないこと（YAGNI）
+- ❌ APIトークン管理（読み取り専用なので不要）
+- ❌ 継続的な同期処理
+- ❌ null を許可（全 Dojo に必須）
+- ❌ 複雑な監視ダッシュボード
+- ❌ 自動マッチング（手動で確実に設定）