コンテンツにスキップ

Design

Context

現在、Admin画面（AdminPage.jsx）はCSVインポート機能のみを提供している。グループ情報はdata/index.jsonのgroups配列に格納され、各グループは{ id, name, totalDurationSeconds, sessionIds }の構造を持つ。IndexMergerサービスは新規セッション追加時のマージロジックを担当するが、既存グループの編集機能は存在しない。

BlobWriterはexecuteWriteSequenceメソッドを提供し、indexUpdater関数でindex.jsonを更新できる。SAS token認証はuseAuthフックで管理され、Admin画面ではすでに利用されている。

Goals / Non-Goals

Goals:

  • Admin画面でグループ一覧を表示し、グループ名を編集可能にする
  • グループIDは変更せず、nameフィールドのみを更新
  • 変更をBlob Storageに保存し、即座に反映
  • 既存のBlobWriter、useAuth機能を活用
  • 直感的でシンプルなUI（モーダル不要）

Non-Goals:

  • グループ詳細画面での編集（今回はAdmin画面のみ）
  • グループIDの変更
  • 変更履歴の記録・監査ログ
  • 一括編集機能
  • グループの削除・統合機能

Decisions

1. 編集UIの配置: Admin画面にグループ管理セクションを追加

判断: 既存のAdmin画面に新規セクション「グループ管理」を追加する。

理由:

  • Admin画面はすでにBlobWriter、SAS token認証、index.json操作のコンテキストを持つ
  • グループ詳細画面は閲覧専用であり、編集機能を追加すると責務が複雑化
  • 管理者向け機能を一箇所に集約することで、UIの一貫性と保守性が向上

代替案:

  • グループ詳細画面に編集ボタンを配置 → Admin権限チェックが各画面で必要になり、実装が分散

2. 編集UIスタイル: インライン編集

判断: グループ一覧で行をダブルクリック、または編集アイコンクリックで入力フィールドに切り替え。

理由:

  • モーダル不要で軽量、操作ステップが少ない
  • 既存のCSVキュー表示と同様の水平レイアウトで統一感
  • キャンセル・保存ボタンで明確な操作フロー

代替案:

  • モーダルダイアログ → オーバーヘッドが大きく、単一フィールド編集には過剰

3. index.json更新ロジック: 新規IndexEditorサービスを作成

判断: IndexEditorクラスを作成し、updateGroupName(index, groupId, newName)メソッドを提供。

理由:

  • IndexMergerは「新規セッション追加」の責務を持ち、編集ロジックは異なる関心事
  • 単一責任原則に従い、別クラスで実装
  • テスタビリティが向上（IndexEditor単体でテスト可能）
  • 将来的にメンバー名編集など、他の編集機能を追加しやすい

代替案:

  • IndexMergerにメソッド追加 → クラスの責務が曖昧になり、凝集度が低下
  • Admin画面に直接ロジックを記述 → テスト困難、再利用不可

4. 状態管理: ローカルstate

判断: Admin画面内でuseStateを使用し、グループ一覧と編集状態を管理。

理由:

  • 編集状態は他画面で共有不要（Admin画面限定）
  • 保存完了後はDataFetcherで最新index.jsonを再取得すれば良い
  • シンプルで十分

代替案:

  • グローバルContext/Reducer → 過剰設計、状態の複雑化

5. バリデーション: クライアント側で基本チェック

判断: 空文字、空白のみ、256文字超過を検出してエラー表示。

理由:

  • サーバーレスアーキテクチャのため、サーバー側バリデーションなし
  • ユーザーフィードバックを即座に提供
  • 既存のCSVインポートと同様のアプローチ

Risks / Trade-offs

[Risk] 同時編集の競合 → Mitigation: 保存前に最新index.jsonを取得し、楽観的ロックの簡易版を実装（updatedAtタイムスタンプ比較）。競合時は警告表示。

[Risk] グループ名変更がセッションデータに反映されない → Mitigation: data/sessions/*.jsonはイミュータブルであり、変更不要。ダッシュボードはindex.jsonのnameを表示するため、自動的に反映される。

[Trade-off] グループ詳細画面からの編集不可 → 受容： 管理者はAdmin画面から編集する運用。将来必要になれば、IndexEditorを再利用して追加可能。

[Trade-off] 変更履歴なし → 受容： 初期スコープ外。必要になれば、セッションメタデータに履歴フィールドを追加。

Migration Plan

デプロイ手順:

  1. 新規ファイル追加（IndexEditor、GroupNameEditor コンポーネント）
  2. AdminPageを更新（グループ管理セクション追加）
  3. テスト実行（Vitest単体テスト、Playwright E2E）
  4. mainブランチへマージ → CI/CDで自動デプロイ

ロールバック戦略:

  • index.jsonの構造変更なし → データ互換性の問題なし
  • 機能追加のみのため、旧バージョンへの切り戻しが安全

既存データへの影響:

  • なし（既存index.jsonはそのまま動作）

Open Questions

（なし — 実装に必要な設計判断はすべて完了）