外部連携仕様（山梨大 Worker）

§1 連携境界・FB データ

0. 環境の整理（2026-06-15）

0.1 FB 件数と DB の要否

想定: 月 100 件以下。この規模ではファイル中心（DB レス）でも運用可能ですが、Phase1 では PostgreSQL + feedbacks が既に稼働しているため、当面は DB を維持しパターン A で進める方針です。役場 PC 移設時に DB レスへ簡略化するか再検討します。

山梨大（AI Worker・iPhone アプリ）と役場側（FB 受信インフラ）の役割分担を決めるためのたたき案です。 会議で質問表（§5）を埋め、合意内容を本ページに反映していきます。

1. 現状（Phase1 実装済み）

2. 想定 ER 図（たたき案）

実線枠 = 実装済み、点線 = 合意後に追加候補。 Phase 2 テーブル（training_jobs 等）は 参照 §2 DB の案のまま保留可能です。

        erDiagram
          feedbacks {
            varchar id PK "UUID"
            varchar image_path "Storage 上のパス"
            text inference_result "端末推論 JSON"
            timestamptz created_at "受信日時"
            timestamptz consumed_at "提案: 学習取込済み"
            timestamptz archived_at "提案: アーカイブ移動日"
          }
          training_jobs {
            varchar id PK
            varchar status "pending/running/completed/failed"
            timestamptz started_at
            timestamptz completed_at
            int feedback_count
          }
          feedback_training {
            varchar feedback_id FK
            varchar training_job_id FK
          }
          feedbacks ||--o{ feedback_training : "used_in"
          training_jobs ||--o{ feedback_training : "uses"
                

consumed_at / archived_at / feedback_training は提案列・提案テーブルです。 Worker が「DB から条件付きで一覧取得」するなら、最低限 consumed_at IS NULL のようなフラグが必要になります。

3. AI Worker の動き（想定フロー）

月次（または手動）トリガーで Worker が FB を学習に使う流れの一例です。数値（60 日等）は会議で決めます。

3.1 データ取得〜学習

        sequenceDiagram
          autonumber
          participant Cron as スケジューラ / 手動
          participant WK as AI Worker（山梨大）
          participant DB as PostgreSQL
          participant ST as Storage（data/storage）
          participant GHA as GitHub Actions
        
          Cron->>WK: 学習ジョブ開始
          WK->>DB: SELECT 未使用 FB
例: consumed_at IS NULL
AND created_at >= 前回以降
          DB-->>WK: id, image_path, inference_result
          loop 各 FB 件
            WK->>ST: image_path のファイルを読込
            ST-->>WK: 画像バイト
          end
          WK->>WK: 学習実行
          WK->>DB: training_jobs 登録・更新（任意）
          WK->>DB: consumed_at = NOW() を更新
          WK->>GHA: repository_dispatch（model-updated）
                

3.2 取得方式の 3 パターン（会議で 1 つ選択）

3.3 画像ライフサイクル（たたき案 — 60 日削除）

画像は DB には入れず Storage 上のファイルとして保持します。 「DB の定石」としては、メタデータ（いつ・学習に使ったか・いつ消すか）を DB に持ち、実ファイルは Storage ジョブで削除するのが一般的です。

        stateDiagram-v2
          [*] --> Active: FB 受信（feedbacks 行 + storage ファイル）
          Active --> Consumed: Worker が学習に取込
consumed_at 設定
          Consumed --> Archived: ファイルを archive/ へ移動
archived_at 設定
          Archived --> Deleted: 保持期限経過（例: 60 日）
Storage 削除 + DB 行削除 or 匿名化
          Active --> Deleted: 未使用のまま TTL（例: 180 日）
ポリシー次第
                

4. 全体配置（誰が何を触るか）

        flowchart TB
          subgraph Yamanashi["山梨大（開発・運用）"]
            iOS[iPhone アプリ]
            WK[AI Worker]
            GHAiOS[iOS GHA 将来]
          end
          subgraph Yakuba["役場 PC + Cloudflare"]
            App[Android アプリ]
            API[FastAPI FB API]
            DB[(PostgreSQL)]
            ST[(Storage)]
            Tunnel[cloudflared]
            GHAand[Android GHA]
          end
          App -->|HTTPS Bearer| Tunnel --> API
          iOS -->|HTTPS Bearer| Tunnel --> API
          API --> DB
          API --> ST
          WK -.->|方式 A/B/C| DB
          WK -.-> ST
          WK -->|repository_dispatch| GHAand
          WK --> GHAiOS
                

5. 会議用 質問表（山梨大 × 役場）

回答欄は会議後に記入してください。印刷または画面共有用です。

6. 会議の進め方（推奨）

はい、本資料 + 質問表を持って調整会議を開くのがよい進め方です。

1. 現状共有（10 分） — §1。Phase1 で何が動いていて、Worker がまだ FB を読んでいないこと
2. 方式選択（20 分） — §3.2 の A/B/C と Q2・Q5
3. データ条件・ライフサイクル（20 分） — §3.3 と Q4・Q6・Q9（60 日は仮のためその場で数字を決める）
4. DB スコープ（15 分） — §2 と Q7。feedbacks 拡張だけ先に / Phase 2 は後回し
5. 次のアクション（5 分） — 合意を本ページに追記 → WBS 3.1.3 / 3.2 のタスク化

参加者の目安: 山梨大（Worker・アプリ担当）、役場（インフラ・運用）、必要なら開発支援。 成果物: 質問表の「合意メモ」列が埋まった状態 + 本 HTML の版数更新。

7. 先行構築の仮定パターン（会議待ちせず進める）

質問がすべて埋まるまでステータスを止めないため、以下を仮定して構築を先行します。 会議（§6）で別方式に変わった場合は差分だけ吸収します。パターンごとの試作は Git ブランチで分岐可能（B は API 実装済み）。

7.1 パターン A — Worker（本番正）

-- 学習バッチ（例）
SELECT id, image_path, inference_result
FROM feedbacks
WHERE consumed_at IS NULL AND archived_at IS NULL
ORDER BY created_at;

-- 取込後
UPDATE feedbacks SET consumed_at = NOW() WHERE id IN (...);

画像は image_path から Storage を直接読みます。本番では Worker・DB・Storage が同一役場 PC 上に載る想定です。

7.2 パターン B — Export API（代替・実装済み）

いずれも Authorization: Bearer <FEEDBACK_API_KEY> 必須（SEC-01）。

# マイグレーション（既存 DB）
        .\scripts\apply-feedback-lifecycle.ps1
        
        # 疎通例（ローカル）
        curl -H "Authorization: Bearer $KEY" "http://localhost:8000/api/v1/feedback/pending"
        curl -H "Authorization: Bearer $KEY" -o sample.jpg "http://localhost:8000/api/v1/feedback/{id}/image"
        curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
          -d '{"ids":["..."]}' "http://localhost:8000/api/v1/feedback/consume"

会議で A（DB 直） が正のまま確定した場合、B API は使わず SQL で足ります。 遠隔開発期のみ B を使う選択も可。

8. 関連資料

• DB スキーマ — 現行 DDL と Phase 2 案
• 山梨大 GHA 連携 — dispatch のみ確定済み
• 本番導入計画 — コンポーネント Step
• WBS 3.1.1〜3.2
• K-31 全体構成図

§2 GHA 連携ガイド

学習完了後に GitHub Actions（Android / 将来 iOS ビルド）を起動するための 共有 Python モジュールの使い方です。 山梨大側の AI Worker コードから数行で組み込めます。

1. 提供モジュール

2. セットアップ

pip install -r integrations/requirements.txt

integrations/.env.example を .env にコピーし、PAT を設定します。

3. 最小コード例（学習完了時）

from integrations.github_actions_client import GitHubActionsClient
        from integrations.notifier import DeveloperNotifier
        import os
        
        def on_training_complete(model_version: str, model_path: str) -> None:
            """
            山梨大 AI Worker の学習完了ハンドラから呼び出す。
            model_version: 例 "v3"
            model_path: models/ からの相対パス 例 "versions/v3/horse_model.coreml"
            """
            client = GitHubActionsClient(
                token=os.environ["GITHUB_TOKEN"],
                repository=os.environ["GITHUB_REPOSITORY"],
            )
            result = client.trigger_model_updated(
                model_version=model_version,
                model_path=model_path,
                # iOS 用 workflow を分ける場合は extra_payload で拡張可能
            )
        
            DeveloperNotifier.from_env().send(
                title="Training complete → GHA triggered",
                message=f"{result.event_type} HTTP {result.status_code}",
                level="info",
                context={
                    "model_version": model_version,
                    "model_path": model_path,
                },
            )

4. 送信される payload

GitHub API POST /repos/{owner}/{repo}/dispatches に以下が送られます。

{
          "event_type": "model-updated",
          "client_payload": {
            "model_version": "v3",
            "model_path": "versions/v3/horse_model.tflite"
          }
        }

受信側ワークフロー: .github/workflows/android-build.yml（将来 ios-build.yml 追加可）。 成功時は HTTP 204（ボディなし）。

5. エラー時の扱い

例外時は DeveloperNotifier で level="error" 通知を推奨します。

6. フォルダの持ち込み方

• 推奨: 本リポジトリを clone し、学習 Worker から integrations/ を import
• 代替: integrations/ フォルダだけを山梨大リポジトリにコピー（依存: httpx のみ）

7. 関連資料

• Phase1 Worker 手順 — スタブでの動作確認
• K-22 — PAT 発行場所（ユーザー Settings）
• DB スキーマ — training_jobs / model_versions 設計