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 或联系技术支持
|