baijiahao_data_crawl/数据验证短信告警使用说明.md

# 数据验证与短信告警系统 - 使用说明

## 📋 功能概述

自动执行数据验证（JSON/CSV/数据库），当验证失败时通过阿里云短信服务发送告警通知。

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

---

## 🚀 快速开始

### 1. 安装依赖

```bash
# 安装阿里云短信SDK
pip install alibabacloud_dysmsapi20170525
pip install alibabacloud_credentials
pip install alibabacloud_tea_openapi
pip install 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,13800138000"
}
```

**获取方式：**
- AccessKey：https://ram.console.aliyun.com/manage/ak
- 短信签名和模板：https://dysms.console.aliyun.com/

### 3. 测试短信功能

```bash
# 测试短信发送
python data_validation_with_sms.py --test-sms
```

### 4. 手动执行验证

```bash
# 验证昨天的数据
python data_validation_with_sms.py

# 验证指定日期
python data_validation_with_sms.py --date 2025-12-29

# 验证特定表
python data_validation_with_sms.py --table ai_statistics_day
```

### 5. 配置定时任务

**Windows系统：**

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

然后使用管理员权限运行显示的PowerShell命令，或者手动配置：

1. 打开 `任务计划程序` (按 Win+R，输入 `taskschd.msc`)
2. 点击 "创建基本任务"
3. 填写任务信息：
   - **名称**: DataValidationWithSMS
   - **描述**: 每天9点执行数据验证并发送短信告警
4. 触发器：**每天**，时间：**上午 9:00**
5. 操作：**启动程序**
   - 程序：`C:\Python\python.exe` (您的Python路径)
   - 参数：`D:\workspace\xhh_baijiahao\data_validation_with_sms.py`
6. 完成

**Linux/macOS系统：**

编辑crontab：
```bash
crontab -e
```

添加定时任务（每天9点执行）：
```
0 9 * * * /usr/bin/python3 /path/to/data_validation_with_sms.py
```

---

## 📖 使用示例

### 示例1：验证JSON和CSV

```bash
python data_validation_with_sms.py --source json csv
```

### 示例2：验证CSV和数据库

```bash
python data_validation_with_sms.py --source csv database
```

### 示例3：完整验证（三个数据源）

```bash
python data_validation_with_sms.py --source json csv database
```

### 示例4：验证 ai_statistics_day 表

```bash
python data_validation_with_sms.py --table ai_statistics_day --source csv database
```

---

## 📧 短信告警说明

### 触发条件

以下情况会发送短信告警（错误代码：2222）：

1. **顺序不一致**：JSON和CSV中记录的顺序不匹配
2. **缺失记录**：某个数据源缺少记录
3. **多余记录**：某个数据源有多余的记录
4. **字段差异**：相同记录的字段值不一致

### 短信内容

短信格式（使用验证码模板）：
```
【北京乐航时代科技】您的验证码是2222
```

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

### 多号码配置

在 `sms_config.json` 中配置多个手机号：

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

---

## 📊 验证报告

每次验证后会自动生成详细报告，保存在项目根目录：

```
validation_report_20250104_090000.txt
```

报告内容包括：
- 顺序验证结果
- 交叉验证结果
- 数据差异统计
- 详细的错误列表

---

## ⚙️ 配置说明

### SMSAlertConfig 类

在 `data_validation_with_sms.py` 中可以修改配置：

```python
class SMSAlertConfig:
    # 阿里云访问凭据
    ACCESS_KEY_ID = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID', '默认值')
    ACCESS_KEY_SECRET = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET', '默认值')
    
    # 短信签名和模板
    SIGN_NAME = '北京乐航时代科技'
    TEMPLATE_CODE = 'SMS_486210104'
    
    # 接收号码
    PHONE_NUMBERS = '13621242430'
    
    # endpoint
    ENDPOINT = 'dysmsapi.aliyuncs.com'
```

### 环境变量方式（推荐）

为了安全起见，建议使用环境变量存储敏感信息：

**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. 短信发送失败

**检查项：**
- AccessKey ID 和 Secret 是否正确
- 短信签名是否已审核通过
- 短信模板是否已审核通过
- 账户余额是否充足
- 手机号格式是否正确（国内号码11位）

**查看错误日志：**
```bash
python data_validation_with_sms.py --test-sms
```

### 2. 数据库连接失败

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

### 3. 验证失败

查看生成的验证报告文件，了解详细错误信息。

### 4. 定时任务不执行

**Windows:**
- 检查任务计划程序中任务状态
- 查看任务历史记录
- 确认Python路径和脚本路径正确

**Linux/macOS:**
- 检查crontab配置：`crontab -l`
- 查看系统日志：`grep CRON /var/log/syslog`

---

## 📝 日志位置

- 验证报告：`validation_report_*.txt`
- 短信发送日志：控制台输出
- 系统日志：根据日志配置（如有）

---

## 🔐 安全建议

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

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

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

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

---

## 📞 联系支持

如有问题，请联系技术支持。

---

## 📅 更新日志

### v1.0.0 (2025-01-04)
- ✨ 初始版本
- ✅ 集成数据验证功能
- ✅ 阿里云短信告警
- ✅ 定时任务调度
- ✅ 多数据源支持