# Kk0ga Employee Time Attendance Graph API Resilience Privacy

> Graph API Resilience & Privacy Skill

- Skill: `tomevault-io/kk0ga-employee-time-attendance-graph-api-resilience-privacy` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/kk0ga-employee-time-attendance-graph-api-resilience-privacy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/kk0ga-employee-time-attendance-graph-api-resilience-privacy/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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](../../../docs/frontend-data-contract.md)

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/kk0ga) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->