システム工学研究会の部室にある「シス研商店」の決済・購買管理アプリです。 部室の Raspberry Pi 5 + 5インチタッチモニター(800x480・横向き)で、無人のレジとして動いています。
- 商品のバーコードを読んで、スマホに保存したシス研Payバーコードで支払う
- 残高のチャージは、役員が立ち会って行う
- 商品・ユーザーの登録は、管理者(役員)が行う
読む人に合わせて、次のどちらかへ進んでください。
支払いには、スマホに保存したバーコードを使います(学生証では払えません)。最初に1回だけ、役員にバーコードを発行してもらってください。
- 役員に声をかけ、学生証を渡す(新しく登録する人は、名前の登録のあとそのまま続けて発行されます)
- 端末の画面に QR コードが出ます。2分で消えるので、すぐスマホのカメラで読み取ってください
- スマホはインターネットにつながっている必要があります(部室の Wi-Fi の中だけでは開けません)
- 開いたページで、バーコードの画像を保存(画像を長押し)します
- 余裕があれば Wallet に入れておくと、すぐ出せて便利です
- iPhone:Wallet の「パスを作成」(iOS 27 以降)
- Android:Google ウォレットの「写真からパスを作成」
バーコードの画像を他の人に渡さないでください。渡した人もあなたの残高で払えてしまいます。
- 商品のバーコードを読み取り機にかざす(カートに入ります)。複数あれば続けてかざす
- カートの画面で、スマホのシス研Payバーコードをかざす
- すぐに購入されて、完了画面に名前・金額・残高が出ます(5秒でホームに戻ります)
- 現金で払う場合:カートの画面で「現金で払う」を押して、現金箱に入れてください
- 残高が足りないとき:「残高が ¥○ 足りません」と出ます。カートはそのままなので、チャージするか、現金で払ってください
- 「利用停止されています」と出たとき:役員に伝えてください
- 「使えないバーコード」と出たとき:バーコードを作り直した後の古い画像かもしれません。新しい画像を使ってください
- 学生証をかざしても「学生証は使えません」と出ます。スマホのバーコードを使ってください
チャージは役員が立ち会って行います。役員に声をかけ、現金を渡してください。
- 役員が管理者パスワードかチャージ用パスワードを入れる
- スマホのシス研Payバーコードを読み取る
- 金額(500 / 1,000 / 2,000 円)を選んでチャージ
| 困りごと | どうする |
|---|---|
| スマホを無くした・機種変更した | 役員に「バーコード再発行」を頼む。新しく発行すると古いバーコードは使えなくなる。残高と履歴はそのまま引き継がれる |
| 画像を他人に見られた・渡した | すぐ役員に再発行を頼む(古いバーコードが止まる) |
| スマホを忘れた・電池が切れた | その日は買えません(部室に充電器があります)。現金払いは使えます |
| 退部・卒業する | 役員に言えば、残高を現金で返金してもらえます |
| 登録した名前・学籍番号を直したい | 役員に頼む |
| 構成 | 場所 | 内容 |
|---|---|---|
| フロント | sysken-pay-front |
React 19 + TypeScript + Vite。ラズパイの Chromium キオスク(全画面)で表示 |
| バック | sysken-pay-backend |
Go + chi の API と MySQL 8(docker compose)。API はラズパイの中(127.0.0.1)からだけ届く |
| スマホ用ページ | sysken-pay-qr |
バーコード画像を作る静的サイト(https://qr.pay.sysken.net)。通信はせず、スマホの中で画像を作る |
| 運用ファイル | deploy/raspberry-pi/ |
キオスク・サービス・日本語入力のスクリプト |
設計・手順の詳細は次のファイルにあります。
- スマホ支払いの設計・決定事項 →
docs/phone-payment.md - ラズパイのセットアップ・更新の手順 →
docs/raspberry-pi-setup.md - バックエンド(環境変数・認証・バックアップ・マイグレーション)→
sysken-pay-backend/README.md - フロントの構成 →
sysken-pay-front/src/docs/ARCHITECTURE.md - API 仕様 →
sysken-pay-backend/docs/openapi.yaml
ホーム画面の右上の歯車 → 管理者パスワードを入れると管理メニューに入れます。
| メニュー | できること |
|---|---|
| ユーザー設定 → 登録 | 新しい部員を登録する。登録したら続けて QR が出る(スマホ登録) |
| ユーザー設定 → バーコード再発行 | 登録済みの人の学生証を読んで、新しい QR を出す(古いバーコードは止まる) |
| ユーザー設定 → 一覧 | 「全員/未返金/卒業候補」の切り替え。人をタップすると詳細(下記) |
| 商品設定 → 登録 | 新しい商品を登録する |
| 商品設定 → 一覧 | 商品の一覧。タップで更新 |
ユーザーの詳細でできること
- 使える人:返金 / 利用停止 / バーコード再発行 / 名前・学籍番号の変更
- 止めた人:返金 / 利用を再開(再開後に続けて QR を出す)
- 停止中の人の整理:削除(購入・チャージ・返金の記録が1件もない人だけ)、非表示(残高 0 の人だけ。記録は残る)
チャージはチャージ用パスワード(CHARGE_PASSWORD)でも入れます。チャージしかできないので、立ち会う人にはこちらを使うとよいです。
| 場面 | 操作 |
|---|---|
| 新入部員 | ユーザー登録 → そのまま QR を出して、部員のスマホで読み取ってもらう(2分以内) |
| スマホ紛失・機種変更 | 「バーコード再発行」。学籍番号は変わらないので残高・履歴は引き継がれる |
| 年度途中の退部 | その場で返金(現金)+利用停止 |
| 年度末(受け取りに来た卒業生) | 返金 + 利用停止 |
| 年度末(来なかった卒業生) | 利用停止だけ(残高は残す)。「未返金」の一覧に出る |
| 遅れて受け取りに来た人 | 「未返金」の一覧から返金だけ |
| 年度末の整理 | 「卒業候補」の一覧を見て、1人ずつチェックを付けてまとめて停止(自動では止めない) |
- 返金額はその人の残高ちょうど。現金を渡してから「現金を渡した」を押す
- ユーザー・購入履歴・チャージ・返金の記録は消さない(会計の記録のため)
| パスワード | 設定場所 | できること |
|---|---|---|
| 管理者 | バックの .env の ADMIN_PASSWORD |
管理者画面のすべて(チャージも可) |
| チャージ | バックの .env の CHARGE_PASSWORD |
チャージだけ |
.envの中身をチャットや issue に貼らない。リポジトリにコミットしない- ラズパイの IP アドレスも、このリポジトリ(公開)には書かず、部の管理表を見る
一から入れる手順は docs/raspberry-pi-setup.md(Docker → Node.js/pnpm → バック → フロント → キオスク → 毎日バックアップ → IP 固定 → QR の行き先設定)。
1行ずつ打ちます(pnpm install の ERR_PNPM_IGNORED_BUILDS で && の後ろが実行されなくなるため)。
cd ~/sysken-pay/sysken-pay-backend
make backup # 先にバックアップ
cd ~/sysken-pay
git pull
cd sysken-pay-backend
docker compose up -d --build
cd ../sysken-pay-front
pnpm install --frozen-lockfile
pnpm build # ✓ built と出ること
sudo systemctl restart sysken-pay-frontsysken-pay-backend/db/migrations/ にファイルが増えたときは、docker compose up の前に make migrate-up を打ちます(まだのものだけ、番号の順に当たります。途中を飛ばすと API が 500 になります)。事前に make migrate-status で何が当たるか見られます。初めて使うときだけ、sysken-pay-backend/README.md の「最初の1回だけ」(make migrate-baseline)が要ります。
cd sysken-pay-backend
make backup # backups/ に保存(新しい順に30件)
make restore FILE=backups/sysken_pay-<日時>.sql.gz- 毎日 3:00 に cron で自動で取る設定は、セットアップ手順の「7.」
- バックアップは部員の個人情報と残高を含みます。SD カードが壊れたときのため、USB メモリなどラズパイの外にもコピーしてください
- DB のデータは docker ボリューム
mysql_dataにあります。docker compose down -vとdocker volume rmは全データが消えるので使わない
| 症状 | 見るもの |
|---|---|
| 画面が真っ白・崩れた・ボタンが押せない | sysken-pay-front/.claude/skills/front-safe-rollback/SKILL.md |
| API エラー・残高がおかしい・データが消えた | sysken-pay-backend/.claude/skills/back-safe-rollback/SKILL.md |
| 全画面を止めて保守したい | touch ~/.kiosk-disabled && pkill -f chromium(戻すときは rm ~/.kiosk-disabled して再起動) |
- 本番に反映する前は
front-go-live-checklist/back-go-live-checklistの監査、定期点検はfront-health-check/back-health-check
# フロント(sysken-pay-front)
pnpm install
pnpm dev # 開発サーバー(800x480 の枠で表示)
pnpm exec vitest run src/test # 単体テスト
pnpm lint
pnpm build
pnpm generate:api # docs/openapi.yaml から型を生成
# バック(sysken-pay-backend)
cp .env.sample .env # 値を設定してから
make up # API と MySQL を起動
go vet ./...
go test ./...- 画面は 800x480 のタッチ画面。長さは
remで書き、100vh/100vwは使わない - API を変えたら
docs/openapi.yamlを更新し、フロントでpnpm generate:api - 金額・残高を変える処理は、二重送信・途中失敗(トランザクション)・負の値をテストで確かめる
- AI エージェント向けの安全ルールは
AGENTS.md(破壊的コマンドの禁止、.envを扱わない、など)