nbc-bot

Appearance

概要 ​

nbc-bot は、部室や研究室などで運用されている 物理鍵の貸出・返却 を Discord 上で管理する Bot です。

何をするBotか ​

  • Discord のボタン（🔓鍵取り／🔐鍵返却）またはスラッシュコマンド /key で、その場で鍵の貸出・返却を打刻できます。
  • 打刻内容は Google スプレッドシートに自動で記録され、専用チャンネルには操作ログと「現在の貸し出しステータス」を表示する常設メッセージが更新されます。
  • 返却期限（18:30 JST）を過ぎても返却されていない場合、自動でアラートを投稿します。
  • 打刻を忘れた場合に備え、/backdate（過去の打刻を遡って記録）・/backdate-fix（直近の打刻時刻を修正）コマンドも用意されています。
  • 任意で Microsoft Teams の Webhook にも通知を転送できます。

全体の流れ ​

  1. ユーザーが Discord 上でボタンを押す、またはスラッシュコマンドを実行する
  2. Discord から nbc-bot の HTTP エンドポイント（POST /）に Interaction が送られる
  3. nbc-bot は 3 秒以内に「受理しました」という deferred response を返し、実処理はバックグラウンドの goroutine で継続する
  4. 現在の貸出状況を Google スプレッドシートから読み取り、鍵取り・鍵返却のどちらとして扱うかを判定する
  5. スプレッドシートに記録（月別シート＋年別ログシート）
  6. 鍵取りの場合は返却期限アラートをスケジュール（SQLite に永続化）
  7. ログチャンネルへの投稿、常設ステータスメッセージの更新、（設定されていれば）Teams への通知
  8. 最後に Discord 側の応答メッセージを確定内容に書き換える

詳しくは アーキテクチャ を参照してください。

前提条件 ​

  • Go 1.26 以上（ローカルで動かす場合）
  • Discord Bot（Application ID / Bot Token / Public Key）と、Interactions Endpoint URL の設定
  • 書き込み権限を持つ Google スプレッドシートと、それにアクセスできるサービスアカウント
  • （任意）Microsoft Teams の Incoming Webhook URL

クイックスタート ​

bash
git clone <このリポジトリ>
cd nbc-bot
cp .env.example .env   # 実際は各自で用意した値を設定
go run ./cmd/server

環境変数の詳細は 設定（環境変数） を参照してください。

起動したら、初回のみ以下の2つのエンドポイントを一度ずつ叩いてセットアップします。

bash
curl -X POST http://localhost:8080/register-command   # スラッシュコマンドをDiscordに登録
curl -X POST http://localhost:8080/send-button         # ボタン付きメッセージ＋ステータスメッセージを投稿

実際に外部（Discord）からWebhookを受けるには、ローカルサーバーを公開URLでトンネリングするか、デプロイ して Discord Developer Portal の Interactions Endpoint URL に設定してください。