技術報告書作成ガイド：構造設計からデータ可視化、自動化まで

# ADR-001: メッセージキューの選定

## ステータス

承認済み（2026-03-10）

## コンテキスト

注文処理システムにおいて非同期メッセージ処理が必要です。
現在の日次注文量は50万件で、ピーク時には秒間1,000件の
処理が求められます。

## 決定

メッセージキューとしてApache Kafkaを選定します。

## 根拠

- 高スループット：秒間数十万件の処理が可能
- 永続性：ディスクベースの保存によりメッセージの損失を防止
- ストリーム処理：Kafka Streamsによるリアルタイム処理のサポート

## 検討した代替案

- RabbitMQ：スループットの制限（秒間約10,000件）
- Amazon SQS：ベンダーロックインの懸念

## 結果

Kafkaクラスターの構築と運用にインフラコストが追加で発生します。
チーム内にKafkaの運用経験が必要で、学習コストが発生します。

パフォーマンス低下の原因
├── インフラ層
│   ├── CPUボトルネック
│   ├── メモリ不足
│   ├── ディスクI/O過負荷
│   └── ネットワーク遅延
├── アプリケーション層
│   ├── 非効率的なアルゴリズム
│   ├── メモリリーク
│   ├── スレッド競合
│   └── コネクションプール枯渇
└── データ層
    ├── クエリの非効率
    ├── インデックスの欠如
    ├── テーブルロック競合
    └── データの偏り（Skew）

# プロジェクト進捗報告書

**プロジェクト**: 決済システムリファクタリング
**報告期間**: 2026-03-07 〜 2026-03-13
**作成者**: 田中太郎
**ステータス**: 予定通り進行中（On Track）

## Executive Summary

決済システムリファクタリングのフェーズ2が予定通り進行中です。
今週の主な成果として、レガシーAPIマイグレーション3件を完了しました。
来週はパフォーマンステストとステージングデプロイを実施する予定です。

## 主要な進捗

| マイルストーン       | 予定日 | ステータス | 進捗率 |
| -------------------- | ------ | ---------- | ------ |
| APIマイグレーション  | 03-14  | 進行中     | 75%    |
| パフォーマンステスト | 03-21  | 予定       | 0%     |
| ステージングデプロイ | 03-25  | 予定       | 0%     |
| 本番デプロイ         | 04-01  | 予定       | 0%     |

## 今週の完了項目

- 決済照会API v2マイグレーション完了
- 返金処理API v2マイグレーション完了
- 精算API v2マイグレーション完了

## リスクと課題

| リスク             | 影響度 | 発生可能性 | 対応策                     |
| ------------------ | ------ | ---------- | -------------------------- |
| 外部PG社のAPI変更  | 高     | 中         | PG社と事前調整完了         |
| テスト環境の不安定 | 中     | 高         | 専用テストクラスター構築中 |

## 来週の計画

1. 残りのAPIマイグレーション2件を完了
2. 統合テスト環境の構築
3. パフォーマンステストシナリオの作成

# 障害報告書

**障害ID**: INC-2026-0312-001
**深刻度**: P1（Critical）
**作成者**: 佐藤次郎
**作成日**: 2026-03-12

## 要約

2026年3月12日14:23〜15:47（JST）、決済サービスが約84分間
全面停止しました。全ユーザーのうち約32万人が影響を受け、
推定売上損失は約1,350万円です。

## タイムライン

| 時刻（JST） | イベント                                         |
| ----------- | ------------------------------------------------ |
| 14:23       | 決済成功率アラート発生（閾値95%以下）            |
| 14:25       | オンコールエンジニアが確認、調査開始             |
| 14:35       | DBコネクションプールの枯渇を確認                 |
| 14:45       | 新規デプロイされたバッチジョブが原因と推定       |
| 15:02       | バッチジョブ停止、コネクションプールの手動クリア |
| 15:30       | 決済成功率99%以上に回復                          |
| 15:47       | 正常状態を確認、障害終了宣言                     |

## 根本原因分析（Root Cause Analysis）

新規デプロイされた精算バッチジョブにトランザクションタイムアウトの
設定が漏れていたため、長時間実行されるクエリがDBコネクションを
保持したまま返却しませんでした。コネクションプール（最大100）が
30分以内に枯渇し、新規決済リクエストが処理できなくなりました。

## 改善措置

| 措置項目                                         | 担当者   | 期限  | 優先度 |
| ------------------------------------------------ | -------- | ----- | ------ |
| バッチジョブのトランザクションタイムアウト設定   | 佐藤次郎 | 03-14 | P0     |
| コネクションプール監視アラートの追加             | 鈴木花子 | 03-17 | P1     |
| デプロイ前チェックリストにタイムアウト検証を追加 | 高橋一郎 | 03-21 | P1     |
| コネクションプールサイズの拡大検討               | 佐藤次郎 | 03-28 | P2     |

## 教訓

1. バッチジョブにもAPIと同レベルのタイムアウトポリシーを適用すべきです
2. リソースプールの使用量に対する監視とアラートが不可欠です
3. デプロイチェックリストにタイムアウト/リソース設定の検証を含めるべきです

# キャッシングソリューション比較分析

## Executive Summary

ユーザーセッションキャッシングソリューションとしてRedisを推奨します。
Memcachedと比較してデータ構造のサポートが豊富であり、
Persistence機能により障害時のデータ復旧が可能です。

## 比較分析

| 基準                      | Redis                           | Memcached          | 重み |
| ------------------------- | ------------------------------- | ------------------ | ---- |
| 処理性能（TPS）           | 10万以上                        | 12万以上           | 20%  |
| データ構造サポート        | 豊富（String, Hash, List, Set） | 単純（Key-Value）  | 25%  |
| Persistence               | サポート（RDB, AOF）            | 非サポート         | 20%  |
| クラスタリング            | ネイティブサポート              | クライアントサイド | 15%  |
| 運用利便性                | 高い                            | 普通               | 10%  |
| コミュニティ/エコシステム | 非常に活発                      | 活発               | 10%  |
| **総合スコア**            | **87/100**                      | **71/100**         | -    |

import pandas as pd
import matplotlib.pyplot as plt
from datetime import datetime, timedelta

# 週次報告書データの自動収集
def generate_weekly_report(start_date, end_date):
    """週次パフォーマンス報告書の自動生成"""

    # データのロード
    metrics = pd.read_csv("metrics.csv", parse_dates=["timestamp"])
    mask = (metrics["timestamp"] >= start_date) & (metrics["timestamp"] <= end_date)
    weekly_data = metrics[mask]

    # 主要指標の計算
    summary = {
        "avg_response_time_ms": weekly_data["response_time"].mean(),
        "p99_response_time_ms": weekly_data["response_time"].quantile(0.99),
        "error_rate_pct": (weekly_data["status"] >= 500).mean() * 100,
        "total_requests": len(weekly_data),
        "uptime_pct": (1 - weekly_data["downtime_minutes"].sum() / (7 * 24 * 60)) * 100,
    }

    return summary

# チャート生成
def create_trend_chart(data, metric_name, title):
    """時系列トレンドチャートの生成"""
    fig, ax = plt.subplots(figsize=(10, 5))
    ax.plot(data["timestamp"], data[metric_name], linewidth=2)
    ax.set_title(title, fontsize=14, fontweight="bold")
    ax.set_xlabel("日付")
    ax.set_ylabel(metric_name)
    ax.grid(True, alpha=0.3)
    plt.tight_layout()
    return fig

# .github/workflows/weekly-report.yml
name: Weekly Performance Report

on:
  schedule:
    - cron: '0 9 * * 1' # 毎週月曜日の午前9時

jobs:
  generate-report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Generate report
        run: python scripts/generate_weekly_report.py

      - name: Create PR with report
        run: |
          git checkout -b report/weekly-$(date +%Y-%m-%d)
          git add reports/
          git commit -m "Add weekly report for $(date +%Y-%m-%d)"
          gh pr create --title "Weekly Report $(date +%Y-%m-%d)" --body "Auto-generated weekly performance report"