baijiahao_data_crawl/数据验证短信告警README.md

# 📱 数据验证与短信告警系统

## 🎯 功能概述

自动化数据验证系统，每天定时检查数据一致性，发现问题时通过阿里云短信服务发送告警。

**核心功能：**
- ✅ 自动验证 JSON/CSV/数据库 三个数据源的一致性
- ✅ 验证失败自动发送短信告警（错误代码：2222）
- ✅ 支持定时任务（每天上午9点执行）
- ✅ 生成详细的验证报告
- ✅ 支持多手机号接收告警

---

## 📁 文件结构

```
xhh_baijiahao/
├── data_validation.py              # 数据验证核心模块
├── data_validation_with_sms.py     # 数据验证+短信告警集成脚本 ⭐
├── sms_config.json                 # 短信服务配置文件 ⭐
├── test_validation_sms.bat         # Windows快速测试脚本
├── 数据验证短信告警使用说明.md     # 详细使用文档
└── ai_sms/                         # 阿里云短信SDK示例
    └── alibabacloud_sample/
        └── sample.py
```

---

## 🚀 快速开始（5分钟）

### 1️⃣ 安装依赖

```bash
pip install alibabacloud_dysmsapi20170525 alibabacloud_credentials alibabacloud_tea_openapi alibabacloud_tea_util
```

### 2️⃣ 配置短信服务

编辑 `sms_config.json`：

```json
{
  "access_key_id": "您的AccessKey ID",
  "access_key_secret": "您的AccessKey Secret",
  "sign_name": "北京乐航时代科技",
  "template_code": "SMS_486210104",
  "phone_numbers": "13621242430"
}
```

**获取AccessKey：** https://ram.console.aliyun.com/manage/ak

### 3️⃣ 测试运行

**Windows用户（双击运行）：**
```
test_validation_sms.bat
```

**命令行运行：**
```bash
# 测试短信发送
python data_validation_with_sms.py --test-sms

# 执行数据验证
python data_validation_with_sms.py
```

### 4️⃣ 配置定时任务

```bash
# 查看配置命令
python data_validation_with_sms.py --setup-schedule
```

按照提示配置Windows任务计划程序，设置每天9点自动执行。

---

## 📖 使用场景

### 场景1：每日自动验证

**定时任务配置（每天9点）：**
- 程序：`C:\Python\python.exe`
- 参数：`D:\workspace\xhh_baijiahao\data_validation_with_sms.py`
- 触发器：每天上午9:00

**执行流程：**
1. 自动验证昨天的数据（JSON/CSV/数据库）
2. 如果发现问题 → 发送短信告警（错误代码2222）
3. 生成详细验证报告

### 场景2：手动验证指定日期

```bash
# 验证2025-12-29的数据
python data_validation_with_sms.py --date 2025-12-29

# 验证指定表
python data_validation_with_sms.py --table ai_statistics_day --date 2025-12-29

# 只验证特定数据源
python data_validation_with_sms.py --source csv database
```

### 场景3：仅验证不发短信

```bash
# 适用于调试或测试
python data_validation_with_sms.py --no-sms
```

---

## 🔔 短信告警说明

### 触发条件

发送短信告警（错误代码：**2222**）的情况：

| 问题类型 | 说明 | 示例 |
|---------|-----|-----|
| **顺序不一致** | JSON和CSV记录顺序不同 | 账号A在JSON第1位，CSV第3位 |
| **缺失记录** | 某个数据源少了记录 | JSON有10条，CSV只有9条 |
| **多余记录** | 某个数据源多了记录 | CSV有11条，数据库只有10条 |
| **字段差异** | 相同记录的字段值不同 | 阅读量：JSON=1000, CSV=999 |

### 短信内容

```
【北京乐航时代科技】您的验证码是2222
```

> 💡 **说明**：由于使用验证码模板，错误代码固定为 `2222`。具体错误详情请查看验证报告文件。

### 多号码配置

在 `sms_config.json` 中配置多个接收号码：

```json
{
  "phone_numbers": "13621242430,13800138000,13900139000"
}
```

---

## 📊 验证报告

每次验证自动生成详细报告：

```
validation_report_20250104_090523.txt
```

**报告内容：**
- ✅ 顺序验证结果
- ✅ 交叉验证结果  
- ✅ 数据差异统计
- ✅ 详细错误列表（记录级别）

**示例报告片段：**
```
交叉验证结果
----------------------------------------------------------------------
json vs csv
  共同记录: 48 条
  仅在json: 0 条
  仅在csv: 2 条
  字段不匹配: 3 条

仅在csv中的记录（前5条）:
  - 测试账号1|1
  - 测试账号2|1

字段值不匹配的记录（前3条）:
  记录: 主力账号|1
    字段 read_count:
      json: 150000
      csv: 149999
```

---

## ⚙️ 高级配置

### 环境变量方式（更安全）

**Windows PowerShell：**
```powershell
$env:ALIBABA_CLOUD_ACCESS_KEY_ID="您的AccessKey ID"
$env:ALIBABA_CLOUD_ACCESS_KEY_SECRET="您的AccessKey Secret"
```

**Linux/macOS：**
```bash
export ALIBABA_CLOUD_ACCESS_KEY_ID="您的AccessKey ID"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="您的AccessKey Secret"
```

### 配置优先级

1. **环境变量** （最高优先级）
2. **sms_config.json** 配置文件
3. **代码中的默认值**

---

## 🔧 故障排查

### ❌ 短信发送失败

**常见原因：**
1. AccessKey ID/Secret 不正确
2. 短信签名未审核通过
3. 短信模板未审核通过
4. 账户余额不足
5. 手机号格式错误

**解决方法：**
```bash
# 测试短信发送
python data_validation_with_sms.py --test-sms
```

查看控制台输出的详细错误信息和诊断地址。

### ❌ 导入错误

```
ImportError: No module named 'alibabacloud_dysmsapi20170525'
```

**解决方法：**
```bash
pip install alibabacloud_dysmsapi20170525 alibabacloud_credentials alibabacloud_tea_openapi alibabacloud_tea_util
```

### ❌ 数据库连接失败

检查 `database_config.py` 配置是否正确。

### ❌ 定时任务不执行

**检查项：**
1. 任务计划程序中任务状态
2. Python路径和脚本路径是否正确
3. 查看任务历史记录

---

## 📝 命令行参数

```bash
python data_validation_with_sms.py [参数]
```

| 参数 | 说明 | 示例 |
|-----|-----|-----|
| `--date` | 指定验证日期 | `--date 2025-12-29` |
| `--source` | 指定数据源 | `--source json csv` |
| `--table` | 指定验证表 | `--table ai_statistics_day` |
| `--setup-schedule` | 配置定时任务 | `--setup-schedule` |
| `--test-sms` | 测试短信功能 | `--test-sms` |
| `--no-sms` | 禁用短信发送 | `--no-sms` |

---

## 🔐 安全建议

1. ✅ **使用环境变量存储敏感信息**
   - 不要将 AccessKey 提交到 Git
   - 将 `sms_config.json` 添加到 `.gitignore`

2. ✅ **定期轮换 AccessKey**
   - 建议每3-6个月更换一次

3. ✅ **使用 RAM 子账号**
   - 为短信服务创建专用子账号
   - 仅授予短信发送权限

4. ✅ **设置 IP 白名单**
   - 在阿里云 RAM 控制台限制访问 IP

---

## 📞 技术支持

### 阿里云短信服务

- 控制台：https://dysms.console.aliyun.com/
- 文档：https://help.aliyun.com/product/44282.html
- API参考：https://api.aliyun.com/product/Dysmsapi

### 常见问题

**Q：短信收不到？**
A：检查手机号是否正确，短信签名和模板是否已审核通过。

**Q：如何查看短信发送记录？**
A：登录阿里云短信服务控制台 → 业务统计 → 发送记录查询。

**Q：短信费用多少？**
A：验证码短信约0.045元/条，具体价格以阿里云官网为准。

**Q：可以自定义短信内容吗？**
A：需要在阿里云控制台申请新的短信模板，审核通过后修改 `template_code` 配置。

---

## 🎉 快速测试检查清单

- [ ] 安装Python依赖
- [ ] 配置 `sms_config.json`
- [ ] 运行 `test_validation_sms.bat`
- [ ] 收到测试短信
- [ ] 执行数据验证
- [ ] 生成验证报告
- [ ] 配置定时任务

---

## 📅 版本历史

### v1.0.0 (2025-01-04)
- ✨ 初始版本发布
- ✅ 数据验证功能
- ✅ 阿里云短信告警
- ✅ 定时任务支持
- ✅ 多数据源支持（JSON/CSV/数据库）
- ✅ 详细验证报告
- ✅ 配置文件支持

---

**开发团队：** 北京乐航时代科技  
**最后更新：** 2025-01-04