システムWorkers仕様書 (system-workers)

1. 概要

system-workers は蒼翔祭システムの各機能を担当するCloudflare Workersの集合である。 gateway-worker がリクエストをルーティングし、各専門Workerがビジネスロジックを処理する。

アーキテクチャ

Note: BFF（Pages Functions）はService Binding経由でWorkerを直接呼び出す。 外部からのHTTPアクセスは v3.api.soshosai.com（Gateway）経由。

---

2. Worker一覧

Worker	パス	用途	認証
gateway-worker	/	リクエストルーティング	なし
staff-worker	/staffs	スタッフ管理	スタッフ必須
visitor-worker	/groups, /guests	来場者管理	ゲスト可
events-worker	/events	イベント管理	ゲスト可
locations-worker	/locations	場所管理	ゲスト可
analytics-worker	/analytics	分析データ	スタッフ必須
line-messaging-worker	/messages	LINE通知	スタッフ必須
equipment-worker	/equipments	備品管理	スタッフ必須

---

3. コンポーネント詳細

3.1 gateway-worker

リクエストを各Workerにルーティングする。

// ルーティング定義
createRoutes('/events', 'EVENTS_WORKER');
createRoutes('/locations', 'LOCATIONS_WORKER');
createRoutes('/analytics', 'ANALYTICS_WORKER');
createRoutes('/messages', 'LINE_MESSAGING_WORKER');
createRoutes('/staffs', 'STAFF_WORKER');
createRoutes('/groups', 'VISITOR_WORKER');
createRoutes('/guests', 'VISITOR_WORKER');
createRoutes('/equipments', 'EQUIPMENT_WORKER');

システムエンドポイント:

Method	Path	説明
GET	/health	ヘルスチェック
GET	/system/info	システム情報

---

3.2 staff-worker

スタッフ情報の管理を担当。

エンドポイント:

Method	Path	説明	認証
GET	/	スタッフ一覧	スタッフ必須
POST	/	スタッフ登録	スタッフ必須
GET	/login/discord	Discord認証経由ログイン	スタッフ必須
GET	/login/QR	QRトークン生成	スタッフ必須
POST	/login/QR	QRログイン実行	なし

QRログインフロー:

1. スタッフがWebからQRトークンを生成（GET /login/QR）
2. ハンディ端末でQRスキャン
3. トークンでログイン（POST /login/QR、5分有効）
4. JWT発行

---

3.3 visitor-worker

来場者（グループ・ゲスト）の管理を担当。

エンドポイント:

Method	Path	説明
GET	/groups	グループ一覧
POST	/groups	グループ作成
GET	/groups/:id	グループ詳細
GET	/guests	ゲスト一覧
POST	/guests	ゲスト登録
GET	/guests/:id	ゲスト詳細

---

3.4 events-worker

イベントの管理を担当。

エンドポイント:

Method	Path	説明
GET	/	イベント一覧
POST	/	イベント作成
PUT	/:eventId	イベント更新
DELETE	/:eventId	イベント削除（論理）
GET	/:eventId/attendees	参加者一覧
POST	/:eventId/attendees	参加登録
GET	/attended/:guestId	ゲストの参加イベント

---

3.5 locations-worker

場所マスターの管理を担当。

エンドポイント:

Method	Path	説明
GET	/	場所一覧
POST	/	場所作成
PUT	/:id	場所更新
DELETE	/:id	場所削除

---

3.6 analytics-worker

分析データの集計・提供を担当。

エンドポイント:

Method	Path	説明
GET	/summary	サマリーデータ
GET	/visitors	来場者統計
GET	/events	イベント統計

---

3.7 line-messaging-worker

LINE通知の送信を担当。

エンドポイント:

Method	Path	説明
POST	/send	メッセージ送信
POST	/broadcast	一斉送信
GET	/permissions	権限確認

---

3.8 equipment-worker

備品管理を担当。詳細は備品管理システム仕様書を参照。

---

4. 認証パターン

4.1 認証ミドルウェア

// スタッフ専用（ゲスト不可）
createAuthMiddleware<{ Bindings: Env }>({ allowGuest: false });

// ゲストもアクセス可能
createAuthMiddleware<{ Bindings: Env }>({ allowGuest: true });

4.2 認証フロー

---

5. 環境変数

5.1 共通

変数名	説明
DB	D1 Database Binding
AUTH_SERVICE	unified-auth-worker Binding
JWT_SECRET	JWT署名シークレット

5.2 gateway-worker

変数名	説明
EVENTS_WORKER	events-worker Binding
LOCATIONS_WORKER	locations-worker Binding
ANALYTICS_WORKER	analytics-worker Binding
LINE_MESSAGING_WORKER	line-messaging-worker Binding
STAFF_WORKER	staff-worker Binding
VISITOR_WORKER	visitor-worker Binding
EQUIPMENT_WORKER	equipment-worker Binding
LOGGER	logger-worker Binding（オプション）

---

6. デプロイ

Service Bindingの依存関係上、以下の順序でデプロイ：

# 1. 認証系（依存なし）
cd packages/api/auth-workers/unified-auth-worker && wrangler deploy

# 2. 各機能Worker（認証に依存）
cd packages/api/system-workers/events-worker && wrangler deploy
cd packages/api/system-workers/locations-worker && wrangler deploy
cd packages/api/system-workers/analytics-worker && wrangler deploy
cd packages/api/system-workers/line-messaging-worker && wrangler deploy
cd packages/api/system-workers/staff-worker && wrangler deploy
cd packages/api/system-workers/visitor-worker && wrangler deploy
cd packages/api/system-workers/equipment-worker && wrangler deploy

# 3. Gateway（全Workerに依存）
cd packages/api/system-workers/gateway-worker && wrangler deploy