wecom-dashboards/excel-handle/QUICKSTART.md

快速开始指南

📋 前置条件

1. Java 8 或更高版本
2. MySQL 5.7 或更高版本
3. Maven 3.x
4. 企业微信账号及相关权限

🚀 快速部署步骤

第一步：获取企业微信配置参数

1.1 获取企业 ID (corp-id)

1. 登录企业微信管理后台：https://work.weixin.qq.com/
2. 进入「我的企业」→「企业信息」
3. 复制「企业 ID」

1.2 获取应用密钥 (app-secret)

1. 在企业微信管理后台，进入「应用管理」
2. 选择或创建一个自建应用
3. 在应用详情页面找到「Secret」
4. 点击「查看」并复制 Secret

重要：需要给应用授予以下权限：

• 企业微信文档 API 权限
• 文档读取权限

1.3 获取文档 ID (doc-id)

1. 在企业微信中打开目标表格文档
2. 查看浏览器地址栏的 URL
3. URL 格式：https://doc.weixin.qq.com/sheet/xxxxx
4. xxxxx 部分就是 doc-id

1.4 获取工作表 ID (sheet-id)

方法一：通过浏览器开发者工具

1. 打开企业微信文档
2. 按 F12 打开开发者工具
3. 切换到「Network」标签
4. 在文档中切换工作表
5. 查看网络请求，找到包含 sheet_id 的请求参数

方法二：使用默认值

• 如果是文档的第一个工作表，可以尝试使用 sheet_id = "1"

第二步：配置数据库

2.1 创建数据库

CREATE DATABASE IF NOT EXISTS ruoyi DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

2.2 执行表结构脚本

mysql -u root -p ruoyi < RuoYi-Vue/excel-handle/sql/schema.sql

或者在 MySQL 客户端中执行：

USE ruoyi;
SOURCE /path/to/RuoYi-Vue/excel-handle/sql/schema.sql;

第三步：配置应用参数

编辑配置文件 RuoYi-Vue/excel-handle/src/main/resources/application.yml：

# 企业微信配置
wecom:
  # 企业 ID（必填）
  corp-id: "ww1234567890abcdef"  # 替换为你的企业 ID

  # 应用密钥（必填）
  app-secret: "your_secret_here"  # 替换为你的应用 Secret

  # 文档 ID（必填）
  doc-id: "your_doc_id_here"  # 替换为你的文档 ID

  # 工作表 ID（必填）
  sheet-id: "1"  # 替换为你的工作表 ID

  # 查询范围（必填，A1 表示法）
  range: "A1:AE1000"  # 根据实际表格列数和行数调整

  # 抓取间隔（可选，默认 60 分钟）
  fetch-interval: 60

# 数据库配置
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/ruoyi?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT%2B8
    username: root  # 替换为你的数据库用户名
    password: password  # 替换为你的数据库密码

第四步：确认表格格式

确保企业微信表格的列顺序与以下格式一致：

列号	字段名	说明
A	客户名称	必填
B	描述	可选
C	添加人	可选
D	添加人账号	必填
E	添加人所属部门	可选
F	添加时间	格式：yyyy-MM-dd
G	来源	可选
H	手机	可选
I	企业	可选
J	邮箱	可选
K	地址	可选
L	职务	可选
M	电话	可选
N-AE	标签组1-18	可选

注意：第一行必须是表头，数据从第二行开始。

第五步：编译和运行

5.1 编译项目

cd RuoYi-Vue
mvn clean package -DskipTests

5.2 运行项目

cd ruoyi-admin/target
java -jar ruoyi-admin.jar

或者在 IDE 中直接运行 RuoYiApplication.java

第六步：验证功能

6.1 查看日志

启动后查看日志，确认定时任务是否正常执行：

开始执行企业微信表格数据同步任务
获取企业微信access_token成功
获取企业微信表格数据成功，行数: 100
数据处理统计: 总计 99 条，新数据 99 条，当天已处理跳过 0 条，无效数据 0 条
企业微信表格数据同步任务执行完成

6.2 手动触发同步

使用 API 工具（如 Postman）或 curl 命令：

curl -X POST http://localhost:8080/wecom/table/sync

6.3 查看服务状态

curl -X GET http://localhost:8080/wecom/table/status

6.4 查询数据库

-- 查看客户数据
SELECT * FROM customer_data ORDER BY create_time DESC LIMIT 10;

-- 查看处理记录
SELECT * FROM processed_data_record ORDER BY create_time DESC LIMIT 10;

-- 查看统计数据
SELECT * FROM customer_tag_statistics ORDER BY stat_date DESC, tag_count DESC;

🔧 常见问题

Q1: 获取 access_token 失败

错误信息: 获取企业微信access_token失败: 40013 - invalid corpid

解决方法:

• 检查 corp-id 是否正确
• 检查 app-secret 是否正确
• 确认应用未被停用

Q2: 获取表格数据失败

错误信息: 获取企业微信表格数据失败: 40003 - invalid openid

解决方法:

• 检查 doc-id 是否正确
• 检查 sheet-id 是否正确
• 确认应用有文档访问权限
• 确认文档未被删除或移动

Q3: 数据解析失败

错误信息: 转换表格数据失败

解决方法:

• 检查表格列的顺序是否与代码映射一致
• 检查日期格式是否为 yyyy-MM-dd
• 检查表格是否有空行或格式异常

Q4: 定时任务不执行

解决方法:

• 检查 Spring Boot 是否启用了定时任务：@EnableScheduling
• 查看日志是否有异常信息
• 检查定时任务配置是否正确

Q5: 数据重复

解决方法:

• 检查去重逻辑是否正常工作
• 查看 processed_data_record 表是否有记录
• 检查数据的 customer_name 和 add_person_account 是否为空

📊 监控和维护

日志位置

• 应用日志：logs/ruoyi-admin.log
• 错误日志：logs/ruoyi-admin-error.log

定时任务时间

• 默认：每小时整点执行一次
• 修改：编辑 WecomTableSyncTask.java 中的 @Scheduled 注解

数据清理

系统会自动清理非当天的缓存数据，但数据库中的历史记录会保留。

如需清理历史数据：

-- 清理 30 天前的处理记录
DELETE FROM processed_data_record WHERE create_time < DATE_SUB(NOW(), INTERVAL 30 DAY);

-- 清理 90 天前的统计数据
DELETE FROM customer_tag_statistics WHERE create_time < DATE_SUB(NOW(), INTERVAL 90 DAY);

🎯 下一步

1. 根据业务需求调整表格字段映射
2. 自定义标签统计规则（实现 TagValidator 接口）
3. 添加数据导出功能
4. 配置告警通知（邮件、企业微信消息等）
5. 优化性能（批量处理、异步处理等）

📚 相关文档

• 完整文档
• 企业微信 API 文档
• RuoYi 框架文档

💡 技术支持

如遇到问题，请：

1. 查看日志文件获取详细错误信息
2. 参考常见问题部分
3. 查阅企业微信 API 文档
4. 提交 Issue 或联系技术支持