アルバイトシフト管理

Google OAuth認証とExpress + SQLiteバックエンドによる高機能なシフト管理アプリケーションです。

概要

このアプリケーションは、アルバイトや小規模チームのシフト管理を効率化するWebアプリケーションです。Google のサービス群（Google Identity Services、Google Calendar）とExpress + TypeScript + SQLiteを活用し、認証からデータ管理、カレンダー連携まで統合的にサポートします。

主な特徴

• 統合バックエンド: Express + TypeScript + SQLiteによる一元管理
• リアルタイム管理: 即座に反映される空き枠と申請状況
• 直感的UI: カレンダーベースの視覚的なシフト管理
• 権限ベースアクセス: 一般ユーザー・管理者の役割分担
• 自動化: カレンダー連携による手作業削減

セットアップ手順

1. Google Cloud Consoleでの設定

1. Google Cloud Consoleにアクセス
2. 新しいプロジェクトを作成または既存のプロジェクトを選択
3. 「APIとサービス」→「認証情報」に移動
4. 「認証情報を作成」→「OAuth 2.0 クライアントID」を選択
5. アプリケーションの種類で「ウェブアプリケーション」を選択
6. 承認済みのJavaScript生成元に以下を追加：
   • http://localhost:3000
   • http://127.0.0.1:3000
   • その他必要なドメイン
7. クライアントIDをコピー

2. アプリケーションの設定

1. .envファイルを作成し、必要な環境変数を設定（.env.exampleを参照）
2. 取得したクライアントIDを .env の GOOGLE_CLIENT_ID に設定（フロントエンドは起動時に GET /api/config から実行時取得します。HTMLやJSへのハードコードは不要です）

3. アプリケーションの実行

ローカルサーバーを起動してテスト：

npm run dev

ブラウザで http://localhost:3000 にアクセス

機能

認証・アクセス制御

• Googleアカウントログイン: Google Identity Services (GSI) による安全な認証
• メールアドレス制限: 指定されたメールアドレスのみアクセス可能
• 管理者権限: 管理者ユーザーには追加機能を提供
• ユーザープロフィール表示: 名前、メール、プロフィール画像

シフト管理システム

• リアルタイム可用性表示: 人数設定と現在の申請数に基づく残り枠表示
• 30分単位の時間枠: 13:00-18:00の範囲で30分間隔の柔軟なシフト設定
• 重複申請防止: 同一ユーザーが同じ日時に複数申請することを防止
• シフトデータキャッシュ: 初回読み込み後はキャッシュを使用してパフォーマンス向上

ユーザー向け機能

• シフト申請: カレンダービューから直感的にシフト申請
• 自分のシフト一覧: 申請済みシフトの確認と管理
• 日付詳細モーダル: 各日付の詳細情報と申請可能枠を表示

管理者専用機能

• 全員のシフト一覧: カレンダー形式で全スタッフのシフトを一覧表示
• シフト詳細ダイアログ: 日付クリックで詳細なシフト情報を表示
  • 時間帯ごとのグループ化表示
  • スタッフ名、メールアドレス、備考の詳細表示
  • 各時間帯の人数カウント表示
• 人数設定管理: 日付・曜日別の必要人数設定
• カレンダー連携: 承認されたシフトをGoogleカレンダーに自動同期
• iCal購読URL: 全シフトをカレンダーアプリから購読できるURLを表示・コピー

データ管理・バックエンド

• SQLite統合: データの永続化にSQLiteを使用
• Express + TypeScript: 型安全なバックエンド処理
• RESTful API設計: GET/POST/PUT/DELETEリクエストによるデータ操作
• 環境変数管理: 設定情報の安全な保存

UI/UX機能

• レスポンシブデザイン: デスクトップとモバイルデバイス対応
• ローディング表示: データ読み込み中の視覚的フィードバック
• エラーハンドリング: 適切なエラーメッセージ表示
• 直感的なカレンダーUI: 月単位表示と簡単な日付選択

iCal購読

シフト予定を標準の iCal（.ics / RFC 5545）形式で公開し、Google Calendar・Apple カレンダー・Outlook などから購読できます。

セットアップ

.env に ICAL_TOKEN を設定します。推測困難なランダム文字列を使用してください。

# トークン生成例
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

ICAL_TOKEN=生成したトークン文字列

エンドポイント

URL	用途
GET /api/ical/all?token=<token>	全スタッフのシフト（管理者用）
GET /api/ical/user/{user_id}?token=<token>	特定ユーザーのシフト

購読URLの確認

管理者モードの「シフト一覧」タブ上部に購読URL（全シフト）が表示されます。「コピー」ボタンでクリップボードにコピーできます。

カレンダーアプリへの登録

Google Calendar

1. 左側「他のカレンダー」横の「+」→「URL で追加」
2. 購読URLを貼り付けて「カレンダーを追加」

Apple カレンダー

1. メニュー「ファイル」→「新規カレンダー購読」
2. 購読URLを貼り付けて「購読」

Outlook

1. 「カレンダーを追加」→「インターネットから」
2. 購読URLを貼り付けて「インポート」

仕様・注意事項

• 更新頻度: Pull 型のため、カレンダーアプリのポーリング間隔に依存します。Google Calendar・Outlook は約24時間、Apple カレンダーは約15分が目安です（リアルタイム更新は現行の Google Calendar 直接同期が適切）。
• 連続シフトの統合: 同一ユーザーの連続する30分シフトは1つのイベントにまとめて表示されます（例: 13:00-13:30 + 13:30-14:00 → 13:00-14:00）。
• 特別シフトも含む: 通常シフト（shifts）と特別シフト（special_shifts）の両方が含まれます。
• セキュリティ: URLに含まれる ICAL_TOKEN が認証情報です。漏洩した場合は .env のトークンを再生成してサーバーを再起動してください。

使用技術

フロントエンド

• HTML5: セマンティックなマークアップ
• CSS3: レスポンシブデザインとモダンなUI
• Vanilla JavaScript: フレームワークを使わない軽量な実装
• Google Identity Services (GSI): OAuth2認証

バックエンド

• Express.js: RESTful APIサーバー
• TypeScript: 型安全な開発
• SQLite: 軽量データベース（better-sqlite3）
• Google Calendar API: カレンダー連携
• Google Cloud Console: OAuth設定とAPI管理

開発ツール

• Nodemon: ホットリロード
• Jest: テストフレームワーク
• ESLint/Prettier: コード品質
• npm: パッケージ管理とスクリプト実行
• Git: バージョン管理

注意事項

セキュリティ

• HTTPSまたはlocalhostでのみ動作します（Google OAuth要件）
• 認証されたメールアドレスのみアクセス可能
• 本番環境では適切なセキュリティ対策を実装してください

運用・制限事項

• OAuth設定が必要です
• 開発サーバーはデフォルトでポート3000で起動します（.envで変更可能）
• SQLiteデータベースの定期的なバックアップを推奨

データバックアップ

• データはSQLiteファイル（data/shift.db、.env の DATABASE_PATH で変更可）に保存されます
• 定期的なバックアップを推奨
• Googleアカウントの2段階認証を有効にすることを推奨

テスト

テストの実行

# 全テストを実行
npm test

# カバレッジ付きで実行
npm run test:coverage

# ウォッチモードで実行
npm run test:watch