279 lines
8.1 KiB
Markdown
279 lines
8.1 KiB
Markdown
# 企业微信表格数据自动抓取与统计系统
|
||
|
||
## 📋 系统概述
|
||
|
||
本系统实现了从企业微信自动抓取指定表格数据，进行数据解析、去重、统计分析的完整流程。
|
||
|
||
## 🔄 完整流程图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 企业微信表格数据处理流程 │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
|
||
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` 中配置：
|
||
|
||
```yaml
|
||
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）
|
||
1. 登录企业微信管理后台：https://work.weixin.qq.com/
|
||
2. 进入「我的企业」→「企业信息」
|
||
3. 复制「企业 ID」
|
||
|
||
#### 2.2 获取 app-secret（应用密钥）
|
||
1. 登录企业微信管理后台
|
||
2. 进入「应用管理」→ 选择或创建一个应用
|
||
3. 在应用详情页面找到「Secret」
|
||
4. 复制应用的 Secret
|
||
|
||
**注意**: 需要给应用授予「企业微信文档」的权限
|
||
|
||
#### 2.3 获取 doc-id（文档 ID）
|
||
1. 在企业微信中打开目标表格文档
|
||
2. 查看浏览器地址栏的 URL
|
||
3. URL 格式：`https://doc.weixin.qq.com/sheet/xxxxx`
|
||
4. `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` 中配置数据库连接：
|
||
|
||
```yaml
|
||
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：
|
||
```bash
|
||
curl -X POST http://localhost:8080/wecom/table/sync
|
||
```
|
||
|
||
### 方式三：查看服务状态
|
||
```bash
|
||
curl -X GET http://localhost:8080/wecom/table/status
|
||
```
|
||
|
||
## 📊 数据处理逻辑
|
||
|
||
### 去重策略
|
||
1. **当天数据去重**：
|
||
- 使用「客户名称 + 添加人账号」作为唯一键
|
||
- 计算数据的 MD5 哈希值
|
||
- 如果键和哈希值都相同，则跳过
|
||
|
||
2. **历史数据处理**：
|
||
- 非当天的数据直接处理，不进行去重检查
|
||
- 适用于补录历史数据的场景
|
||
|
||
### 缓存管理
|
||
- 内存缓存：存储当天已处理的数据
|
||
- 数据库持久化：记录所有处理历史
|
||
- 自动清理：每次处理后清理非当天的缓存
|
||
|
||
## 📝 日志说明
|
||
|
||
系统会记录详细的日志信息：
|
||
- 数据抓取日志：记录抓取的数据量
|
||
- 去重日志：记录新数据、跳过数据、无效数据的数量
|
||
- 错误日志：记录所有异常信息
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
1. **权限要求**：
|
||
- 企业微信应用需要有「企业微信文档」的 API 权限
|
||
- 应用需要能访问目标文档
|
||
|
||
2. **API 限制**：
|
||
- 企业微信 API 有调用频率限制
|
||
- access_token 有效期为 7200 秒（2 小时）
|
||
|
||
3. **数据量限制**：
|
||
- 单次查询的数据量不宜过大
|
||
- 建议 range 设置在 1000 行以内
|
||
|
||
4. **表格格式要求**：
|
||
- 第一行必须是表头
|
||
- 列的顺序必须与 CustomerData 实体的字段映射一致
|
||
|
||
## 🔍 故障排查
|
||
|
||
### 问题 1：获取 access_token 失败
|
||
- 检查 corp-id 和 app-secret 是否正确
|
||
- 检查应用是否有相应权限
|
||
- 检查网络连接是否正常
|
||
|
||
### 问题 2：获取表格数据失败
|
||
- 检查 doc-id 和 sheet-id 是否正确
|
||
- 检查应用是否有文档访问权限
|
||
- 检查 range 范围是否合法
|
||
|
||
### 问题 3：数据解析失败
|
||
- 检查表格列的顺序是否与代码映射一致
|
||
- 检查日期格式是否为 yyyy-MM-dd
|
||
- 查看详细的错误日志
|
||
|
||
## 📚 相关文档
|
||
|
||
- [企业微信 API 文档](https://developer.work.weixin.qq.com/document/)
|
||
- [企业微信文档 API](https://developer.work.weixin.qq.com/document/path/97459)
|
||
- [EasyExcel 文档](https://easyexcel.opensource.alibaba.com/)
|
||
|
||
## 🎉 总结
|
||
|
||
本系统提供了一个完整的企业微信表格数据自动化处理方案，包括：
|
||
- ✅ 自动抓取企业微信表格数据
|
||
- ✅ 智能去重（基于日期和数据哈希）
|
||
- ✅ 数据统计分析
|
||
- ✅ 定时任务自动执行
|
||
- ✅ REST API 手动触发
|
||
- ✅ 完整的日志记录
|
||
|
||
只需配置好企业微信的相关参数，系统即可自动运行！
|