wecom-dashboards/excel-handle/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` 中配置：

```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 手动触发
- ✅ 完整的日志记录

只需配置好企业微信的相关参数，系统即可自动运行！