quarterly-database-cleanup

季度数据库清理

一项结构化的季度审计，可在数据偏移演变为危机之前及时发现问题。每个季度初运行一次（如果数据库规模较大或增长迅速，也可每月运行）。

前提条件

• HubSpot 私有应用访问令牌（.env 中的 HUBSPOT_ACCESS_TOKEN）
• Python 3.10+ 和 uv
• 上一季度的报告（用于趋势对比）——首次运行时可选

审计清单

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：回滚

这是只读审计，无需回滚。报告中的行动项将通过各自的技能单独执行。

定期安排

• 设置周期性日历提醒，在每个季度的第一个星期一执行。
• 为报告中的每项行动指定负责人。
• 开始新一轮审计前，先检查上一季度的行动项是否已完成。