254 lines
6.8 KiB
Markdown
254 lines
6.8 KiB
Markdown
|
# 快速开始指南
|
|||
|
|
|
|||
|
|
## 📋 前置条件
|
|||
|
|
|
|||
|
|
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 创建数据库
|
|||
|
|
```sql
|
|||
|
|
CREATE DATABASE IF NOT EXISTS ruoyi DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 2.2 执行表结构脚本
|
|||
|
|
```bash
|
|||
|
|
mysql -u root -p ruoyi < RuoYi-Vue/excel-handle/sql/schema.sql
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
或者在 MySQL 客户端中执行：
|
|||
|
|
```sql
|
|||
|
|
USE ruoyi;
|
|||
|
|
SOURCE /path/to/RuoYi-Vue/excel-handle/sql/schema.sql;
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 第三步：配置应用参数
|
|||
|
|
|
|||
|
|
编辑配置文件 `RuoYi-Vue/excel-handle/src/main/resources/application.yml`：
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
# 企业微信配置
|
|||
|
|
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 编译项目
|
|||
|
|
```bash
|
|||
|
|
cd RuoYi-Vue
|
|||
|
|
mvn clean package -DskipTests
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 5.2 运行项目
|
|||
|
|
```bash
|
|||
|
|
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 命令：
|
|||
|
|
```bash
|
|||
|
|
curl -X POST http://localhost:8080/wecom/table/sync
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 6.3 查看服务状态
|
|||
|
|
```bash
|
|||
|
|
curl -X GET http://localhost:8080/wecom/table/status
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 6.4 查询数据库
|
|||
|
|
```sql
|
|||
|
|
-- 查看客户数据
|
|||
|
|
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` 注解
|
|||
|
|
|
|||
|
|
### 数据清理
|
|||
|
|
系统会自动清理非当天的缓存数据，但数据库中的历史记录会保留。
|
|||
|
|
|
|||
|
|
如需清理历史数据：
|
|||
|
|
```sql
|
|||
|
|
-- 清理 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. 优化性能（批量处理、异步处理等）
|
|||
|
|
|
|||
|
|
## 📚 相关文档
|
|||
|
|
|
|||
|
|
- [完整文档](README.md)
|
|||
|
|
- [企业微信 API 文档](https://developer.work.weixin.qq.com/document/)
|
|||
|
|
- [RuoYi 框架文档](http://doc.ruoyi.vip)
|
|||
|
|
|
|||
|
|
## 💡 技术支持
|
|||
|
|
|
|||
|
|
如遇到问题，请：
|
|||
|
|
1. 查看日志文件获取详细错误信息
|
|||
|
|
2. 参考常见问题部分
|
|||
|
|
3. 查阅企业微信 API 文档
|
|||
|
|
4. 提交 Issue 或联系技术支持
|