a4a8b468cd
|
||
|---|---|---|
| .. | ||
| sql | ||
| src/main | ||
| CUSTOMER_DATA_TRACKING_GUIDE.md | ||
| README.md | ||
| pom.xml | ||
README.md
企业微信表格数据自动抓取与统计系统
📋 系统概述
本系统实现了从企业微信自动抓取指定表格数据，进行数据解析、去重、统计分析的完整流程。
🔄 完整流程图
┌─────────────────────────────────────────────────────────────────┐
│ 企业微信表格数据处理流程 │
└─────────────────────────────────────────────────────────────────┘
1. 【获取访问令牌】
├─ 使用 corpId + appSecret
├─ 调用企业微信 API 获取 access_token
└─ 缓存 token（有效期 7200 秒）
2. 【抓取表格数据】
├─ 使用 access_token + docId + sheetId + range
├─ 调用企业微信文档 API
└─ 获取表格原始数据（JSON 格式）
3. 【数据转换】
├─ 解析 JSON 数据结构
├─ 映射到 CustomerData 实体
└─ 处理日期、文本等字段
4. 【数据去重】
├─ 计算数据哈希值（MD5）
├─ 基于日期的智能去重
│ ├─ 当天数据：检查缓存，跳过已处理
│ └─ 非当天数据：直接处理
└─ 记录处理状态到数据库
5. 【数据统计】
├─ 按标签组统计数量
├─ 按日期统计趋势
└─ 生成统计报表
6. 【数据存储】
├─ 保存客户数据到数据库
├─ 保存统计结果
└─ 清理过期缓存
7. 【定时任务】
└─ 每小时自动执行一次（可配置）
🎯 核心功能模块
1. 企业微信 API 集成
- 文件:
WecomApiUtils.java - 功能:
- 获取并缓存 access_token
- 调用企业微信文档 API 获取表格数据
- 自动处理 token 过期和刷新
2. 数据抓取服务
- 文件:
WecomTableService.java - 功能:
- 从企业微信抓取表格数据
- 数据格式转换（JSON → CustomerData）
- 智能去重处理
- 批量保存数据
3. 数据去重服务
- 文件:
ProcessedDataService.java - 功能:
- 基于日期的去重策略
- 数据哈希计算
- 缓存管理（内存 + 数据库）
- 自动清理过期数据
4. 数据统计服务
- 文件:
CustomerDataService.java - 功能:
- Excel 文件解析
- 标签统计分析
- 统计结果持久化
5. 定时任务
- 文件:
WecomTableSyncTask.java - 功能:
- 定时自动抓取（默认每小时）
- 异常处理和日志记录
6. REST API 接口
- 文件:
WecomTableController.java - 接口:
POST /wecom/table/sync- 手动触发同步GET /wecom/table/status- 查询服务状态
📦 数据实体
CustomerData（客户数据）
包含 31 个字段：
- 基本信息：客户名称、描述、手机、邮箱、企业、地址、职务、电话
- 添加信息：添加人、添加人账号、添加人部门、添加时间
- 来源信息：来源
- 标签信息：18 个标签组（投放、公司孵化、商务、成交日期等）
🔧 必需的外部参数
1. 企业微信配置参数（必填）
在 application.yml 中配置：
wecom:
# 企业 ID（必填）
corp-id: "your_corp_id"
# 应用密钥（必填）
app-secret: "your_app_secret"
# 文档 ID（必填）
doc-id: "your_doc_id"
# 工作表 ID（必填）
sheet-id: "your_sheet_id"
# 查询范围（必填，A1 表示法）
range: "A1:AE1000"
# 抓取间隔（可选，默认 60 分钟）
fetch-interval: 60
2. 参数获取方法
2.1 获取 corp-id（企业 ID）
- 登录企业微信管理后台：https://work.weixin.qq.com/
- 进入「我的企业」→「企业信息」
- 复制「企业 ID」
2.2 获取 app-secret（应用密钥）
- 登录企业微信管理后台
- 进入「应用管理」→ 选择或创建一个应用
- 在应用详情页面找到「Secret」
- 复制应用的 Secret
注意: 需要给应用授予「企业微信文档」的权限
2.3 获取 doc-id（文档 ID）
- 在企业微信中打开目标表格文档
- 查看浏览器地址栏的 URL
- URL 格式：
https://doc.weixin.qq.com/sheet/xxxxx xxxxx部分就是 doc-id
2.4 获取 sheet-id（工作表 ID）
方法一：通过 API 查询
- 调用企业微信文档 API 获取文档的所有工作表列表
- 从返回结果中找到目标工作表的 ID
方法二：通过开发者工具
- 打开企业微信文档
- 按 F12 打开开发者工具
- 切换工作表时查看网络请求
- 找到包含 sheet_id 的请求参数
2.5 设置 range（查询范围）
- 使用 A1 表示法，例如：
A1:Z100- 查询 A 到 Z 列，前 100 行A1:AE1000- 查询 A 到 AE 列，前 1000 行A:Z- 查询 A 到 Z 列的所有行
3. 数据库配置（必填）
需要在主项目的 application.yml 中配置数据库连接：
spring:
datasource:
url: jdbc:mysql://localhost:3306/your_database?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT%2B8
username: your_username
password: your_password
4. 数据库表结构（需要创建）
需要创建以下表：
customer_data- 存储客户数据processed_data_record- 存储已处理数据记录（用于去重）customer_tag_statistics- 存储标签统计数据
🚀 使用方式
方式一：自动定时任务
系统启动后，定时任务会自动执行（默认每小时整点）
方式二：手动触发
调用 REST API：
curl -X POST http://localhost:8080/wecom/table/sync
方式三：查看服务状态
curl -X GET http://localhost:8080/wecom/table/status
📊 数据处理逻辑
去重策略
-
当天数据去重：
- 使用「客户名称 + 添加人账号」作为唯一键
- 计算数据的 MD5 哈希值
- 如果键和哈希值都相同，则跳过
-
历史数据处理：
- 非当天的数据直接处理，不进行去重检查
- 适用于补录历史数据的场景
缓存管理
- 内存缓存：存储当天已处理的数据
- 数据库持久化：记录所有处理历史
- 自动清理：每次处理后清理非当天的缓存
📝 日志说明
系统会记录详细的日志信息：
- 数据抓取日志：记录抓取的数据量
- 去重日志：记录新数据、跳过数据、无效数据的数量
- 错误日志：记录所有异常信息
⚠️ 注意事项
-
权限要求：
- 企业微信应用需要有「企业微信文档」的 API 权限
- 应用需要能访问目标文档
-
API 限制：
- 企业微信 API 有调用频率限制
- access_token 有效期为 7200 秒（2 小时）
-
数据量限制：
- 单次查询的数据量不宜过大
- 建议 range 设置在 1000 行以内
-
表格格式要求：
- 第一行必须是表头
- 列的顺序必须与 CustomerData 实体的字段映射一致
🔍 故障排查
问题 1：获取 access_token 失败
- 检查 corp-id 和 app-secret 是否正确
- 检查应用是否有相应权限
- 检查网络连接是否正常
问题 2：获取表格数据失败
- 检查 doc-id 和 sheet-id 是否正确
- 检查应用是否有文档访问权限
- 检查 range 范围是否合法
问题 3：数据解析失败
- 检查表格列的顺序是否与代码映射一致
- 检查日期格式是否为 yyyy-MM-dd
- 查看详细的错误日志
📚 相关文档
🎉 总结
本系统提供了一个完整的企业微信表格数据自动化处理方案，包括：
- ✅ 自动抓取企业微信表格数据
- ✅ 智能去重（基于日期和数据哈希）
- ✅ 数据统计分析
- ✅ 定时任务自动执行
- ✅ REST API 手动触发
- ✅ 完整的日志记录
只需配置好企业微信的相关参数，系统即可自动运行！