Welfare TIME

現代の大学生活のための、福利厚生の時間と情報ナビ（Welfare Time & Information for Modern Education）です。

京都産業大学の食堂・コンビニ・ショップ・ATM、および日替わりで出店するキッチンカーの営業情報を自動収集し、ウェブサイトと JSON API として公開しています。情報がPDFや外部サイトに散らばっているため、これらを統合して一箇所で確認できるようにすることを目的としています。

• サイト: https://tamadalab.github.io/welfare-time/
• APIリファレンス: https://tamadalab.github.io/welfare-time/help/api/

データソース

2つの情報源から取得し、正規化して静的な JSON API として配信します。

1. 学食スケジュール: 大学サイトが公開するPDFのメニュー表から抽出します。
2. キッチンカー: SHOP STOP のページをスクレイピングします。

データパイプライン

すべて just から実行します。

段階	コマンド	処理	出力先
Fetch	just fetch_pdf	大学サイトからPDFを取得	data/pdfs/
Fetch	just fetch_kitchencar	Playwright でJS描画後のHTMLを取得	data/kitchencars/raw.html
Parse	just parse_pdf	PDFを解析	data/cafeterias/*.json
Scrape	just parse_kitchencar	HTMLを解析	data/kitchencars/scraped.json
Generate	just generate	統合してAPIと公開用PDFを生成	static/api/, static/daily/
Commit source data	GitHub Actions	PDF・メタデータ・キッチンカー履歴を保存	main
Publish	just build_html	Tailwind CSS と Hugo でサイトを生成	gh-pages

data/cafeterias/ と data/kitchencars/ は解析時に作る中間データです。static/ 以下のAPIとPDFも生成物で、mainにはコミットせず、Hugoでサイトと一緒に gh-pages へ公開します。

毎朝の自動更新

GitHub Actions が毎日 JST 7時（UTC 22時）と手動実行でパイプラインを動かします。実行の混雑により、実際の更新時刻は日によって前後します。同時に複数の更新が走らないよう、実行を直列化しています。

更新では、大学サイトから取得したPDFと data/pdfs/.metadata.json、および data/kitchen_cars_past.json を main にコミットします。PDFは、大学サイトからリンクが外れた後も次回以降のAPI再生成に使えるよう保持します。キッチンカーの情報源は過去の出店情報をすぐ削除するため、アーカイブは「その日に何が出店していたか」の唯一の記録です。

main への保存後、今回生成した日別APIと gh-pages で公開中の日別APIを比較します。過去日（JST）の食堂について、店舗・場所・営業時間・注記の記録が生成結果から欠けていれば、既存の公開APIを置き換えずに更新を失敗させます。検査を通った場合だけ、生成済みのAPIをサイトとPDFと一緒に gh-pages へ公開します。公開済みの daily/ のPDFは累積し、APIは毎回作り直します。

蓄積には次の不変条件があります。

• 過去（date < today）のエントリは凍結し、削除も変更もしない
• 当日以降はスクレイプ結果を正とし、出店の取りやめや時間変更を反映する
• スクレイプ結果が0件のときはフェッチ失敗の可能性があるため、アーカイブに手を加えない

なお夏期休暇中はキッチンカーの出店自体がないため、0件が正常な状態です。

開発環境

以下が必要です。バージョンは ワークフロー で使用しているものです。

• Python 3.11
• Hugo 0.168.0（extended）— サイト生成に加え、just generate がベースURLの取得に使います
• Node 26 — Tailwind CSS のビルドに使います
• just — タスクの実行に使います（brew install just などで入れてください）

セットアップ

pip install -r requirements.txt
playwright install chromium
npm ci

playwright install chromium は just fetch_kitchencar に必要です。

ローカルでの確認

just generate
just serve

just serve は Hugo の開発サーバーを起動します（http://localhost:1313/welfare-time/）。

コンテナでの確認

Python や Hugo を手元に入れずに、コンテナでサイトを確認することもできます。docker か podman が必要です。

just start

just start は Containerfile からイメージを作り、コンテナを起動します。コンテナの中で API と CSS を生成してから Hugo の開発サーバーが起動するので、少し待ってから http://localhost:1313/welfare-time/ を開いてください。進み具合は docker logs -f welfare-time で確認できます。止めるときは just stop を実行します。

podman を使うときは、just CONTAINER=podman start のように指定します。

コンテナでは、次の点に注意してください。

• リポジトリをコンテナにマウントして使います。手元でテンプレートや Markdown を編集すると、ブラウザの表示が自動で更新されます。
• データは、リポジトリにある食堂のPDFとキッチンカーのアーカイブから生成します。大学サイトやキッチンカーのページからの取得は行わないので、git pull した時点の最新のデータになります。
• 生成物は手元の static/ と data/ に書き出されます（どれも .gitignore の対象です）。
• Tailwind CSS は起動時に1回だけビルドします。新しいクラスを使ったときは、just stop と just start で起動し直してください。
• ポートは 1313 に固定しています。just serve と同時には使えません。

テスト

just test

食堂PDFのパーサ、キッチンカーのスクレイパー、API生成、過去の食堂データの欠落を検出する検証の回帰テストを実行します。just の PYTHON 変数が指すインタプリタで動くため、依存関係を入れた環境を指定してください。

just PYTHON=/path/to/venv/bin/python test

その他のコマンド

just help で一覧を表示します。just stale_api は、gh-pages で配信されているが現在は生成されなくなったAPIファイルを検出します。

バージョン

機能と変更点は CHANGELOG.md にまとめています。サイトでは、ヘルプの 変更履歴 のページにこのファイルの内容をそのまま表示します。

バージョン番号は package.json の version だけで管理し、サイトのフッタはこの値を表示します。フッタのコード最終更新日時は、just build_html の実行時に main の履歴から求めます。data/ だけを変更したコミットは対象外なので、毎朝の自動更新では変わりません。

リリースのあとにコードを変更してそのまま公開されたときは、フッタのバージョンの後ろに、最後にコードを変更したコミットの短いハッシュ値が v0.4.1+2335122 の形で付きます。リリースのタグが付いたコードでは、v0.4.1 だけになります。

リリースの手順は 仕様書の「バージョン管理」 にあります。

ディレクトリ構成

パス	内容
scripts/	データ収集・変換・生成用のPythonスクリプトとテスト
scripts/facilities.json	施設のマスターデータ（正式ID・URL・カテゴリなど）
content/	Hugo のコンテンツ（ヘルプ、APIリファレンス）
layouts/	Hugo のテンプレート
assets/	Tailwind CSS のソース
static/	静的ファイルと生成物。APIと公開用PDFは追跡対象外
data/	取得・保存するPDFとメタデータ、キッチンカーのアーカイブ。data/extra/ は臨時店舗のJSON
testdata/	テスト用のPDFとHTMLフィクスチャ
resources/spec/	仕様書と開発の規約
resources/	発表用のスライドやポスター
.github/workflows/	毎朝のデータ更新ワークフロー

public/ は Hugo の出力先かつ gh-pages のワークツリーで、リポジトリには含まれません。

公開API

すべてGETリクエストで取得できます。詳細は APIリファレンス を参照してください。

エンドポイント	内容
/api/schedule/today	当日の営業情報。tomorrow, yesterday も利用可能
/api/schedule/YYYY-MM-DD	指定日の営業情報
/api/shops	全店舗のマスター情報と営業スケジュール履歴
/api/shops/{shop-id}	指定店舗の営業日時の一覧
/api/status	データセット全体の更新状況と範囲

リンク集

• 仕様書 (resources/spec/): システム構成、データの規約と不変条件、APIの設計方針、サイトの規約、開発の進め方。
• 利用規約・ライセンス: プロジェクトのライセンス情報。