# 快速开始指南

## 📋 前置条件

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