quarterly-database-cleanup

四半期ごとのデータベースクリーンアップ

データのずれが危機的な状況になる前に検出する、体系的な四半期監査です。各四半期の初めに実施してください（データベースが大規模または急速に拡大している場合は、毎月実施してください）。

前提条件

• HubSpot のプライベートアプリのアクセストークン（.env 内の HUBSPOT_ACCESS_TOKEN）
• uv を含む Python 3.10 以降
• 前四半期のレポート（傾向の比較用）— 初回実行時は省略可能

監査チェックリスト

1. リストの健全性

• アクティブなリスト、静的リスト、未使用のリスト（メンバー数がゼロ）の総数を確認します
• どのワークフローやメールからも参照されていないリストを特定します
• 重複または重なりのあるリストにフラグを立てます

2. バウンスの監視

• バウンスが 1 回、2 回、3 回以上のコンタクト数を確認します
• 前四半期とハードバウンス率を比較します
• バウンス監視ワークフローによってフラグが付けられたコンタクトを確認します

3. データ品質

• メールアドレス、会社、業種、国、ライフサイクルステージの欠損
• 前四半期と割合を比較します
• プロパティの入力率が 5% を超えて低下した場合にフラグを立てます

4. スコアリングの調整

• リードスコアの分布を確認します（ヒストグラム）
• MQL のコンバージョン率を確認します — スコアの高いリードは実際にコンバージョンしていますか？
• コンバージョン率が 10% 未満または 50% を超える場合は、スコアリングモデルを調整します

5. エンゲージメント指標

• アクティブなコンタクト（過去 90 日間にエンゲージメントがあったコンタクト）が総数に占める割合
• ゾンビコンタクト（6 か月以上エンゲージメントがないコンタクト）が総数に占める割合
• メールの開封率とクリック率の推移

6. プロパティのクリーンアップ

• 値が入力されたレコードがゼロのカスタムプロパティ
• リスト、ワークフロー、フォームのいずれでも使われていないプロパティ
• アーカイブすべきテスト用／一時プロパティ

手順

ステージ 1：実施前 — 基準値を収集する

1. reports/ に前四半期のレポートがあれば、場所を確認します。
2. /hubspot-audit を実行して、すべての項目の最新の数値を取得します。

ステージ 2：実施 — 詳細に確認する

上記の各チェック項目について、次の作業を行います。

1. HubSpot API を介して最新の指標を取得します（監査スクリプトのパターンを再利用します）。
2. 前四半期の数値と比較します。
3. 5 パーセントポイントを超えて悪化した指標にフラグを立てます。
4. 対応が必要な具体的なコンタクト、リスト、プロパティを記録します。

ステージ 3：実施後 — レポートを作成する

次の構成でレポートを reports/quarterly-cleanup-{YYYY-Q#}.md に保存します。

# Quarterly Database Health Report — YYYY Q#

## Summary

| Metric | Last Quarter | This Quarter | Change |
|--------|-------------|-------------|--------|
| Total contacts | XX,XXX | XX,XXX | +X% |
| Data completeness | XX% | XX% | +X% |
| Bounce rate | X.X% | X.X% | -X% |
| Zombie contacts | XX% | XX% | -X% |
| Unused lists | XX | XX | -XX |

## Action Items

1. [item with owner and deadline]
2. ...

## Detailed Findings

[One section per checklist item with metrics and recommendations]

ステージ 4：ロールバック

これは読み取り専用の監査のため、ロールバックは不要です。レポートの対応項目は、それぞれのスキルを通じて別途実行します。

スケジュール

• 各四半期の最初の月曜日に、定期的なカレンダーリマインダーを設定します。
• レポートの各対応項目に担当者を割り当てます。
• 新しい監査を始める前に、前四半期の対応項目が完了しているか確認します。