Kk0ga Employee Time Attendance Graph API Resilience Privacy

Graph API Resilience & Privacy Skill

目的

Microsoft Graph を使ったデータ取得/更新を、

• 壊れにくく（429/一時障害に強い）
• 漏らさず（トークン/個人情報をログに出さない）
• 分かりやすく（日本語の失敗UX） 実装できる状態にする。

設計ルール（このリポジトリ方針）

• Graph呼び出しは src/lib/graph に集約し、UIで fetch() を散らさない
• 取得は必要最小限（select/fields絞り込み、ページング前提）
• 監視/一覧更新は差分取得（Modified以降）を優先し、フルスキャンを避ける

エラー分類とユーザー表示（推奨）

1. 401（未認証）

   • UI: 「セッションが切れました。再ログインしてください。」
   • 対応: MSALで再ログイン導線

2. 403（権限不足）

   • UI: 「権限がありません。管理者に連絡してください。」
   • 対応: scope/ロール/SharePoint権限の見直し

3. 429（レート制限） / 503（混雑・一時障害）

   • UI: 「混雑しています。しばらくしてから再試行してください。」
   • 対応: 自動リトライ（上限あり）+ 手動リトライ導線

リトライ方針（必須）

• 429/503 は 指数バックオフ + リトライ上限
• Retry-After ヘッダがあれば最優先で尊重
• “永遠に待つ” を避ける（最大試行回数 / 最大待機時間を定義）

ページング・差分取得

• 一覧取得はページング前提（nextLinkの追従）
• “毎回全件” を避ける：lastModifiedDateTime 等の差分キーで取得範囲を絞る

ログ/計測（秘匿）

• 絶対に出さない: アクセストークン、IDトークン、refresh token、Authorizationヘッダ
• 個人情報は最小化: メールアドレス・氏名は原則ログに載せない
• 代わりに出す: リクエスト種別、HTTPステータス、リトライ回数、待機時間、相関ID（あれば）

成果物（このスキルで必ず出す）

• Graphクライアントの共通関数方針（例：graphFetch()）
• 429/503 のリトライ仕様（上限、待機、Retry-After）
• 画面向けエラーメッセージ（日本語）のテンプレ

依頼例

• 「Graphで一覧取得してるけど、429が出る。Retry-After対応のリトライを入れたい」
• 「401/403/429 の時の画面表示と再試行導線を整えたい」
• 「SharePoint Lists の取得を差分更新にしたい（5分間隔で十分）」

References

• docs/frontend-data-contract.md

Converted and distributed by TomeVault — claim your Tome and manage your conversions.