Helidon + GitHub + Render + JavaFX + Gemini による学校データ公開・更新・AI相談システム構築（データ自動更新機能付き By Github Actions）

1. 目的

本仕組みの目的は、学校入試データを

Helidon Web アプリで公開
GitHub 経由で Render に自動反映
Mac 用 JavaFX デスクトップアプリで簡単に更新
Gemini API を用いた AI 相談機能を付加

できるようにすることです。

この構成により、次のような運用が可能になります。

少量修正は GUI で直接編集
大量更新は JSON ファイルを一括読み込み
Save / Publish により GitHub と Render まで一気通貫で更新
Render 公開ページを Desktop アプリからすぐ開ける
学校一覧ページ上で、AI に自然文で相談できる

2. 全体構成

公開用プロジェクト

/Users/Your_UserName/Downloads/myproject

役割:

Helidon SE アプリ
Render で公開
schools-v2.json を読み込んで一覧表示
検索 / ソート / ログイン機能
Gemini API を使った AI 相談機能

更新用 Desktop アプリ

/Users/Your_UserName/Downloads/school-data-editor

役割:

JavaFX GUI
schools-v2.json を編集
Save / Publish 実行
Render 公開ページを 1クリックで開く

データ専用 repo

/Users/Your_UserName/Downloads/school-data

GitHub:

Private repository: school-data

役割:

学校データ JSON のバックアップ
最新版管理
archive 保存

3. データ本体

公開用アプリ内のデータ

/Users/Your_UserName/Downloads/myproject/src/main/resources/data/schools-v2.json

この JSON が公開用 Helidon アプリの元データです。

バックアップ用データ repo

/Users/Your_UserName/Downloads/school-data/data/schools-v2.json

役割:

常に最新の JSON

/Users/Your_UserName/Downloads/school-data/archive/

役割:

過去版の保存

4. JSON構造

JSON のキーは英語のままにし、GUI / Web 表示時だけ日本語化します。

JSON 項目

schoolName
category
capacity
examDates
subjects
alternateSubjects
interview
englishQualificationBenefit
notes
infoLink

GUI / Web 表示名

学校名
入試分類
募集人数
試験日
試験科目
試験科目特記
面接有無
英語資格優遇
備考
学校リンク

5. DbInit.java の役割

DbInit.java は、JSON を読み込んで H2 の exam_school_v2 に投入するだけにします。

場所:

/Users/Your_UserName/Downloads/myproject/src/main/java/com/example/myproject/DbInit.java

役割:

テーブル作成
schools-v2.json 読み込み
JSON 各行を INSERT

この構成により、学校データ更新は Java ソース編集ではなく JSON 編集だけで済みます。

6. 公開用画面 / API

JSON API

/schools-v2

表形式画面

/schools-v2-table

ログイン画面

/login

ログアウト

/logout

Gemini 疎通確認 API

/ai/test

AI 推薦 API

/ai/recommend-schools

7. 公開画面の改善点（今回追加）

7.1 日本語列名化

/schools-v2-table の列名を英語から日本語へ変更しました。

7.2 検索機能

画面上部の検索ボックスで、学校名・入試分類・試験日・備考などを絞り込み可能にしました。

7.3 ソート機能

各列見出しクリックで昇順 / 降順ソート可能にしました。

7.4 日付表示変換

Render 側の画面表示では、日付を

YYYY-MM-DD
から
YYYY/MM/DD

へ変換表示するようにしました。

8. 簡易認証（パスワードのみ）

目的

公開ページを誰でも見られる状態ではなく、パスワードを知っている人だけ閲覧可能にするためです。

認証仕様

ユーザーID不要
パスワードのみ
正しいパスワード入力で Cookie 発行
/schools-v2-table はログイン済みユーザーだけ閲覧可能

環境変数

Render 側で次を設定します。

APP_PASSWORD=任意のパスワード

ローカルで未設定時の仮パスワード

changeme123

9. GitHub 経由で Render に公開

9.1 Helidon 公開アプリ repo

GitHub repository:

helidon-school-app

初回 push 例:

cd /Users/Your_UserName/Downloads/myproject
git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/<account>/helidon-school-app.git
git push -u origin main

9.2 Render 設定

Render Dashboard で:

New > Web Service
GitHub 接続
リポジトリ選択
Branch: main
Runtime: Docker

9.3 Render 環境変数

最低限、次を設定します。

APP_PASSWORD
GEMINI_API_KEY

9.4 現在の公開 URL

https://helidon-school-app.onrender.com/schools-v2-table
https://helidon-school-app.onrender.com/login

10. JavaFX Desktop アプリ

場所

/Users/Your_UserName/Downloads/school-data-editor

役割

JSON を GUI 編集
Save
Publish
Render 公開ページを 1クリックで開く

GitHub 管理

JavaFX アプリは Private repo に保存する。

例:

school-data-editor（Private）

11. JSON バックアップ運用

データ専用 Private repo

GitHub repository:

school-data

推奨構成

school-data/
  data/
    schools-v2.json
  archive/
    schools-v2_2026-03-18_v8.json
  README.md

運用ルール

data/schools-v2.json は常に最新
archive/ に日付付きスナップショットを保存
更新後は必ず commit / push

更新例

cd /Users/Your_UserName/Downloads/school-data
cp /Users/Your_UserName/Downloads/最新JSON.json data/schools-v2.json
cp /Users/Your_UserName/Downloads/最新JSON.json archive/schools-v2_YYYY-MM-DD_vX.json
git add .
git commit -m "Update schools-v2.json"
git push

12. Gemini API の導入

12.1 方針

AI 機能は Helidon 自体にあるのではなく、Helidon から Gemini API を REST で呼び出す形です。

12.2 課金方針

Gemini は Free Tier 前提 で利用開始する。

重要:

Cloud Billing を紐づけない
無料枠を超えた場合は制限エラー側に倒れる想定
課金を有効化しない限り、青天井課金を避けやすい

12.3 API キー

ローカルでは環境変数で設定します。

export GEMINI_API_KEY='あなたのAPIキー'

12.4 疎通確認

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Say hello in Japanese."
          }
        ]
      }
    ]
  }'

13. AI 相談機能

13.1 `/ai/test`

Gemini と Helidon の疎通確認用 API。

13.2 `/ai/recommend-schools`

本命 API。

役割:

ユーザーの自然文質問を受け取る
SchoolV2 一覧を Gemini に渡す
候補校と理由を日本語で返す

入力例

{"question":"英検準1級を保持しているが、ライティングが弱いし、算数とか国語も苦手です。帰国入試でも英語受験でも相性が良さそうな学校候補を挙げてください。"}

出力例

{"answer":"候補校: ..."}

注意

この段階では、学校データをそのまま Gemini に渡しています。
将来的には、Helidon 側で候補校を先に絞ってから Gemini に渡す方が効率的です。

追記案：13. GitHub Actions による週1自動更新

13.1 目的

school-data リポジトリ内の data/schools-v2.json を、毎週自動でチェック・更新する。
手動更新の代わりに、GitHub Actions で定期実行し、差分があればログや更新候補を残す。
失敗した学校があっても全体処理は止めず、エラーだけ記録して次へ進む。

13.2 追加するファイル

school-data/.github/workflows/update-schools.yml
school-data/scripts/update_schools.py
school-data/requirements.txt

update_schools.py では、requests と BeautifulSoup を使って各学校ページを巡回し、状態確認やタイトル取得、差分確認を行う。

13.3 実行スケジュール

毎週1回、GitHub Actions で自動実行する。
workflow は UTC 基準の cron で指定でき、必要なら timezone も併用できる。(GitHub Docs)

例：月曜 3:00 JST に実行したい場合

on:
  schedule:
    - cron: '0 18 * * 0'
  workflow_dispatch:

13.4 workflow の例

name: Weekly school data update

on:
  schedule:
    - cron: '0 18 * * 0'
  workflow_dispatch:

permissions:
  contents: write

jobs:
  update:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Run updater
        run: |
          python scripts/update_schools.py \
            --input data/schools-v2.json \
            --output data/schools-v2.json \
            --pretty

      - name: Commit and push if changed
        run: |
          if git diff --quiet; then
            echo "No changes"
            exit 0
          fi

          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add data/schools-v2.json
          git commit -m "Update schools JSON"
          git push

13.5 更新の考え方

自動更新は「何でも自動で書き換える」より、まずは以下の順で運用する。

学校ページにアクセスできるか確認する
ページタイトルや更新状況を記録する
エラーは学校単位でスキップする
差分が出た学校だけを確認対象にする
問題なければ data/schools-v2.json を更新する

13.6 JSON の保存運用

自動更新後は、これまで通り data/schools-v2.json を最新データとして扱う。
必要に応じて archive/ に日付付きのスナップショットを残す。
この運用により、手動更新と自動更新を同じバックアップ方針で管理できる。(Qiita)

必要なら、この追記を含めて記事全体の見出し構成を整えた「完成版の全文」もそのまま書けます。

14. AI相談ボックス（Web画面）

/schools-v2-table の画面上に、AI相談ボックスを追加しました。

機能

自然文質問入力
「AIに相談する」ボタン
回答表示

相談例

英検準1級を持っているが、ライティングが弱い
算数や国語が苦手
帰国入試か英語受験で相性の良い学校を知りたい

15. ローカル確認手順

Helidon アプリ

cd /Users/Your_UserName/Downloads/myproject
mvn clean package
java -jar target/myproject.jar

確認 URL

http://localhost:8080/login
http://localhost:8080/schools-v2-table
http://localhost:8080/ai/test

16. Render への反映手順

16.1 GitHub に push

cd /Users/Your_UserName/Downloads/myproject
git add .
git commit -m "Add AI recommendation feature"
git push origin main

16.2 Render 側

Render Dashboard で:

Environment に GEMINI_API_KEY を追加
Environment に APP_PASSWORD を追加
必要なら Manual Deploy 実行

16.3 公開確認

https://helidon-school-app.onrender.com/login
https://helidon-school-app.onrender.com/schools-v2-table

17. 今後の改善候補

今後さらに改善する場合は、次が有力です。

Helidon 側で候補校を先に絞る
同じ質問への回答をキャッシュ
1ユーザーあたりの問い合わせ回数制限
AI推薦した学校の行をハイライト
推薦結果に学校リンクを表示
/schools-v2 の JSON API も認証保護

18. まとめ

本システムにより、以下が実現できています。

Helidon による学校一覧公開
GitHub + Render による自動公開
JavaFX による簡易更新
JSON のバックアップ運用
パスワード付き閲覧制限
Gemini API を使った AI 学校相談

この構成により、学校データの公開・更新・相談支援を一体化した運用が可能になっています。