# 新機能の監視要件を生成
/monitoring-readiness "ポイント有効期限機能"

# 要件定義書から監視要件を生成
/monitoring-readiness docs/requirements/point-expiration.md

# 既存機能の監視強化
/monitoring-readiness wallet --enhance

## 監視対象の特定

**機能:** ポイント有効期限機能

### 主要な処理フロー

1. **ポイント付与時の有効期限設定**
   - トリガー: GraphQL Mutation `walletCreate`
   - 頻度: 100回/日
   - 重要度: 🔴 Critical

2. **有効期限切れポイントの自動失効**
   - トリガー: Cronバッチ（毎日2:00）
   - 頻度: 1回/日
   - 重要度: 🔴 Critical

3. **有効期限通知送信**
   - トリガー: Cronバッチ（毎日10:00）
   - 頻度: 1回/日
   - 重要度: 🟡 High

4. **ポイント使用時の有効期限チェック**
   - トリガー: GraphQL Mutation `pointTransfer`, `utilityExchange`
   - 頻度: 500回/日
   - 重要度: 🔴 Critical

## メトリクス設計

### カテゴリ1: ビジネスメトリクス

#### 1. 失効ポイント総数（日次）

**メトリクス名:** `wallet.expiration.points_expired_total`
**型:** Counter
**ラベル:**
- `community_id`: コミュニティID
- `reason`: 失効理由（`expired`, `manual`）

**収集方法:**
\`\`\`typescript
// バッチ処理内
metrics.increment('wallet.expiration.points_expired_total', {
  tags: {
    community_id: wallet.communityId,
    reason: 'expired'
  },
  value: expiredPoints
});
\`\`\`

**アラート:**
- 失効ポイント > 100,000pt/日 → 警告（異常値の可能性）
- 失効ポイント = 0 → 警告（バッチ未実行の可能性）

---

#### 2. 失効ユーザー数（日次）

**メトリクス名:** `wallet.expiration.users_affected_total`
**型:** Counter
**ラベル:**
- `community_id`: コミュニティID

**収集方法:**
\`\`\`typescript
metrics.increment('wallet.expiration.users_affected_total', {
  tags: { community_id: wallet.communityId },
  value: affectedUserCount
});
\`\`\`

**アラート:**
- 失効ユーザー > 1,000人/日 → 警告

---

#### 3. 通知送信成功率

**メトリクス名:** `wallet.expiration.notification_success_rate`
**型:** Gauge
**値:** 0.0 ～ 1.0

**収集方法:**
\`\`\`typescript
const successRate = successCount / totalCount;
metrics.gauge('wallet.expiration.notification_success_rate', successRate);
\`\`\`

**アラート:**
- 成功率 < 0.95 → 警告（LINE API問題の可能性）
- 成功率 < 0.8 → 緊急

---

### カテゴリ2: 技術メトリクス

#### 4. バッチ処理実行時間

**メトリクス名:** `wallet.expiration.batch_duration_seconds`
**型:** Histogram
**ラベル:**
- `batch_type`: `expire_points`, `send_notifications`

**収集方法:**
\`\`\`typescript
const startTime = Date.now();
await expirePoints();
const duration = (Date.now() - startTime) / 1000;

metrics.histogram('wallet.expiration.batch_duration_seconds', {
  tags: { batch_type: 'expire_points' },
  value: duration
});
\`\`\`

**アラート:**
- 実行時間 > 60秒 → 警告（パフォーマンス劣化）
- 実行時間 > 300秒 → 緊急（タイムアウトの可能性）

---

#### 5. 有効期限チェックのレスポンスタイム

**メトリクス名:** `wallet.expiration.check_duration_ms`
**型:** Histogram

**収集方法:**
\`\`\`typescript
const start = Date.now();
await this.checkExpiration(wallet);
const duration = Date.now() - start;

metrics.histogram('wallet.expiration.check_duration_ms', duration);
\`\`\`

**アラート:**
- P95 > 100ms → 警告
- P99 > 200ms → 注意

---

#### 6. データベースクエリ時間

**メトリクス名:** `wallet.expiration.db_query_duration_ms`
**型:** Histogram
**ラベル:**
- `query_type`: `find_expired`, `update_balance`

**収集方法:**
\`\`\`typescript
// Prismaミドルウェアで自動収集
prisma.$use(async (params, next) => {
  const start = Date.now();
  const result = await next(params);
  const duration = Date.now() - start;

  metrics.histogram('wallet.expiration.db_query_duration_ms', {
    tags: { query_type: params.action },
    value: duration
  });

  return result;
});
\`\`\`

**アラート:**
- P95 > 50ms → 警告（インデックス不足の可能性）

---

### カテゴリ3: エラーメトリクス

#### 7. エラー発生率

**メトリクス名:** `wallet.expiration.error_rate`
**型:** Counter
**ラベル:**
- `error_type`: `WALLET_EXPIRED`, `BATCH_FAILED`, `NOTIFICATION_FAILED`

**収集方法:**
\`\`\`typescript
try {
  await expirePoints();
} catch (error) {
  metrics.increment('wallet.expiration.error_rate', {
    tags: { error_type: error.code || 'UNKNOWN' }
  });
  throw error;
}
\`\`\`

**アラート:**
- エラー率 > 5% → 警告
- エラー率 > 10% → 緊急

## アラート設定

### アラートレベル

#### 🟢 Info（情報通知）
- **通知先:** Slack #dev-info
- **対応:** 任意（営業時間内に確認）

#### 🟡 Warning（警告）
- **通知先:** Slack #dev-alerts
- **対応:** 24時間以内に確認
- **エスカレーション:** 48時間放置で PagerDuty

#### 🔴 Critical（緊急）
- **通知先:** PagerDuty（オンコール担当）
- **対応:** 即座（15分以内）
- **エスカレーション:** 30分対応なしで上位エスカレーション

---

### アラートルール

#### Alert 1: バッチ処理失敗

\`\`\`yaml
alert: WalletExpirationBatchFailed
expr: increase(wallet_expiration_error_rate{error_type="BATCH_FAILED"}[5m]) > 0
for: 0m
severity: critical
annotations:
  summary: ポイント失効バッチ処理が失敗しました
  description: "バッチ処理が {{ $value }} 回失敗しました"
actions:
  - PagerDuty: オンコール担当に通知
  - Slack: #dev-alerts に通知
  - Runbook: https://wiki.example.com/runbook/wallet-expiration-batch-failed
\`\`\`

---

#### Alert 2: 通知送信成功率低下

\`\`\`yaml
alert: ExpirationNotificationLowSuccessRate
expr: wallet_expiration_notification_success_rate < 0.95
for: 10m
severity: warning
annotations:
  summary: 有効期限通知の成功率が低下しています
  description: "成功率: {{ $value | humanizePercentage }}"
actions:
  - Slack: #dev-alerts
  - Runbook: https://wiki.example.com/runbook/notification-failure
\`\`\`

---

#### Alert 3: バッチ処理時間超過

\`\`\`yaml
alert: ExpirationBatchSlow
expr: histogram_quantile(0.95, wallet_expiration_batch_duration_seconds) > 60
for: 5m
severity: warning
annotations:
  summary: バッチ処理が遅延しています
  description: "P95実行時間: {{ $value }}秒"
actions:
  - Slack: #dev-alerts
\`\`\`

---

#### Alert 4: 異常な失効ポイント数

\`\`\`yaml
alert: AbnormalPointsExpiration
expr: increase(wallet_expiration_points_expired_total[24h]) > 100000
for: 0m
severity: warning
annotations:
  summary: 異常な量のポイントが失効しました
  description: "失効ポイント: {{ $value }}pt"
actions:
  - Slack: #dev-alerts
  - Email: product-owner@example.com
\`\`\`

## ダッシュボード設計

### Dashboard 1: ポイント有効期限 概要

**ツール:** Grafana / Datadog

#### パネル構成

##### Row 1: ビジネスメトリクス

**Panel 1.1: 失効ポイント総数（時系列）**
- グラフ: 折れ線グラフ
- クエリ: `sum(rate(wallet_expiration_points_expired_total[24h]))`
- Y軸: ポイント数
- X軸: 時間

**Panel 1.2: 失効ユーザー数（時系列）**
- グラフ: 折れ線グラフ
- クエリ: `sum(rate(wallet_expiration_users_affected_total[24h]))`

**Panel 1.3: 通知送信成功率（ゲージ）**
- グラフ: ゲージ
- クエリ: `wallet_expiration_notification_success_rate`
- 閾値:
  - 緑: >= 0.95
  - 黄: 0.8 ～ 0.95
  - 赤: < 0.8

---

##### Row 2: パフォーマンスメトリクス

**Panel 2.1: バッチ処理実行時間（ヒートマップ）**
- グラフ: ヒートマップ
- クエリ: `histogram_quantile(0.95, wallet_expiration_batch_duration_seconds)`

**Panel 2.2: データベースクエリ時間（P50/P95/P99）**
- グラフ: 折れ線グラフ（複数線）
- クエリ:
  - P50: `histogram_quantile(0.5, wallet_expiration_db_query_duration_ms)`
  - P95: `histogram_quantile(0.95, wallet_expiration_db_query_duration_ms)`
  - P99: `histogram_quantile(0.99, wallet_expiration_db_query_duration_ms)`

---

##### Row 3: エラーメトリクス

**Panel 3.1: エラー率（時系列）**
- グラフ: 折れ線グラフ
- クエリ: `sum(rate(wallet_expiration_error_rate[5m])) by (error_type)`
- 凡例: error_type別

**Panel 3.2: 最近のエラーログ（テーブル）**
- グラフ: テーブル
- データソース: Elasticsearch / CloudWatch Logs
- フィールド: timestamp, error_type, error_message, user_id

---

### Dashboard 2: リアルタイム監視

**用途:** オンコール担当者向け

#### パネル構成

**Panel 1: 現在のアラート状況**
- Active Alerts一覧
- 色分け: Critical=赤、Warning=黄

**Panel 2: 今日の失効ポイント**
- 単一値
- クエリ: `sum(increase(wallet_expiration_points_expired_total[24h]))`

**Panel 3: 直近1時間のエラー**
- ログストリーム

## ログ戦略

### ログレベル

- **DEBUG:** 詳細なデバッグ情報（開発環境のみ）
- **INFO:** 通常の処理フロー
- **WARN:** 警告（処理は継続）
- **ERROR:** エラー（処理失敗）

---

### ログ出力

#### ログ1: バッチ処理開始

\`\`\`typescript
logger.info('Wallet expiration batch started', {
  batch_type: 'expire_points',
  timestamp: new Date().toISOString(),
  expected_count: expectedCount
});
\`\`\`

---

#### ログ2: ポイント失効実行

\`\`\`typescript
logger.info('Points expired', {
  user_id: userId,
  wallet_id: walletId,
  expired_points: expiredPoints,
  expires_at: expiresAt,
  remaining_balance: remainingBalance
});
\`\`\`

---

#### ログ3: バッチ処理完了

\`\`\`typescript
logger.info('Wallet expiration batch completed', {
  batch_type: 'expire_points',
  duration_seconds: duration,
  processed_count: processedCount,
  error_count: errorCount
});
\`\`\`

---

#### ログ4: エラー

\`\`\`typescript
logger.error('Wallet expiration batch failed', {
  error: error.message,
  error_code: error.code,
  stack_trace: error.stack,
  wallet_id: walletId
});
\`\`\`

---

### ログ集約

**ツール:** Elasticsearch / CloudWatch Logs

**インデックス:**
- `civicship-api-prod-YYYY.MM.DD`

**検索クエリ例:**
\`\`\`
# 今日の失効ポイント総数
message:"Points expired" AND @timestamp:[now-24h TO now]
| stats sum(expired_points) as total_expired

# エラー発生率
message:"batch failed" AND level:ERROR
| timechart span=5m count()
\`\`\`

## 監視準備チェックリスト

### メトリクス

- [ ] ビジネスメトリクスの定義完了
  - [ ] 失効ポイント総数
  - [ ] 失効ユーザー数
  - [ ] 通知送信成功率

- [ ] 技術メトリクスの定義完了
  - [ ] バッチ処理実行時間
  - [ ] データベースクエリ時間
  - [ ] API レスポンスタイム

- [ ] エラーメトリクスの定義完了
  - [ ] エラー発生率
  - [ ] エラー種別分類

---

### アラート

- [ ] アラートルールの定義完了
  - [ ] バッチ処理失敗
  - [ ] 通知送信失敗
  - [ ] パフォーマンス劣化
  - [ ] 異常値検出

- [ ] 通知先の設定完了
  - [ ] Slack #dev-alerts
  - [ ] PagerDuty（オンコール）

- [ ] Runbookの作成完了
  - [ ] バッチ処理失敗時の対処
  - [ ] ロールバック手順

---

### ダッシュボード

- [ ] Grafana / Datadogダッシュボードの作成
  - [ ] ビジネスメトリクス可視化
  - [ ] パフォーマンスメトリクス可視化
  - [ ] エラー可視化

- [ ] ダッシュボードのアクセス権限設定
  - [ ] 開発チーム: 閲覧・編集
  - [ ] プロダクトオーナー: 閲覧のみ

---

### ログ

- [ ] 構造化ログの実装
  - [ ] JSON形式
  - [ ] 必要なフィールド含む

- [ ] ログ集約の設定
  - [ ] Elasticsearch / CloudWatch Logs
  - [ ] 検索クエリの作成

- [ ] ログ保持期間の設定
  - [ ] 本番: 90日
  - [ ] ステージング: 30日

---

### テスト

- [ ] メトリクス収集のテスト
  - [ ] ステージング環境で確認
  - [ ] メトリクスが正しく送信されるか

- [ ] アラート発火のテスト
  - [ ] 手動でアラート条件を満たす
  - [ ] 通知が正しく届くか

- [ ] ダッシュボード表示のテスト
  - [ ] データが正しく表示されるか

# 監視準備レポート

**機能:** ポイント有効期限機能
**作成日:** 2026-01-15

---

## 監視要件サマリー

### メトリクス

- **ビジネスメトリクス:** 3個
- **技術メトリクス:** 3個
- **エラーメトリクス:** 1個
- **合計:** 7個

### アラート

- **Critical:** 2個
- **Warning:** 2個
- **合計:** 4個

### ダッシュボード

- **概要ダッシュボード:** 1個（9パネル）
- **リアルタイムダッシュボード:** 1個（3パネル）

---

## 実装工数

| タスク | 工数 |
|--------|------|
| メトリクス実装 | 4h |
| アラート設定 | 2h |
| ダッシュボード作成 | 3h |
| ログ実装 | 2h |
| テスト | 2h |
| **合計** | **13h** |

---

## 承認

- [ ] テックリード
- [ ] DevOpsリード
- [ ] プロダクトオーナー

/monitoring-readiness "ポイント有効期限機能"

/monitoring-readiness wallet --enhance