Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

シス研Pay

システム工学研究会の部室にある「シス研商店」の決済・購買管理アプリです。 部室の Raspberry Pi 5 + 5インチタッチモニター(800x480・横向き)で、無人のレジとして動いています。

  • 商品のバーコードを読んで、スマホに保存したシス研Payバーコードで支払う
  • 残高のチャージは、役員が立ち会って行う
  • 商品・ユーザーの登録は、管理者(役員)が行う

読む人に合わせて、次のどちらかへ進んでください。


利用する人(部員)向け

最初にやること:シス研Payバーコードをスマホに入れる

支払いには、スマホに保存したバーコードを使います(学生証では払えません)。最初に1回だけ、役員にバーコードを発行してもらってください。

  1. 役員に声をかけ、学生証を渡す(新しく登録する人は、名前の登録のあとそのまま続けて発行されます)
  2. 端末の画面に QR コードが出ます。2分で消えるので、すぐスマホのカメラで読み取ってください
    • スマホはインターネットにつながっている必要があります(部室の Wi-Fi の中だけでは開けません)
  3. 開いたページで、バーコードの画像を保存(画像を長押し)します
  4. 余裕があれば Wallet に入れておくと、すぐ出せて便利です
    • iPhone:Wallet の「パスを作成」(iOS 27 以降)
    • Android:Google ウォレットの「写真からパスを作成」

バーコードの画像を他の人に渡さないでください。渡した人もあなたの残高で払えてしまいます。

買い物のしかた

  1. 商品のバーコードを読み取り機にかざす(カートに入ります)。複数あれば続けてかざす
  2. カートの画面で、スマホのシス研Payバーコードをかざす
  3. すぐに購入されて、完了画面に名前・金額・残高が出ます(5秒でホームに戻ります)
  • 現金で払う場合:カートの画面で「現金で払う」を押して、現金箱に入れてください
  • 残高が足りないとき:「残高が ¥○ 足りません」と出ます。カートはそのままなので、チャージするか、現金で払ってください
  • 「利用停止されています」と出たとき:役員に伝えてください
  • 「使えないバーコード」と出たとき:バーコードを作り直した後の古い画像かもしれません。新しい画像を使ってください
  • 学生証をかざしても「学生証は使えません」と出ます。スマホのバーコードを使ってください

チャージ(残高を増やす)

チャージは役員が立ち会って行います。役員に声をかけ、現金を渡してください。

  1. 役員が管理者パスワードかチャージ用パスワードを入れる
  2. スマホのシス研Payバーコードを読み取る
  3. 金額(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-front

sysken-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 を扱わない、など)

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages