d327826c78
1. 更新所有服务Dockerfile，切换到eclipse-temurin:17-jre-alpine镜像并调整服务端口 2. 配置前端项目基础路径与nginx代理 3. 新增数据库初始化编码设置与测试依赖 4. 添加部分服务的Servlet编码配置与JWT/LLM密钥配置 5. 完善话术实体类校验注解与Mapper接口 6. 新增密码生成工具类与部分测试文件配置
172 lines
4.9 KiB
Markdown
172 lines
4.9 KiB
Markdown
# 企微会话存档 SDK 对接指南
|
||
|
||
## 一、SDK 下载
|
||
|
||
### 官方下载地址
|
||
- 企微开发者中心：https://developer.work.weixin.qq.com/document/path/91774
|
||
- 下载页面：「获取会话内容」→ SDK 下载
|
||
|
||
### 下载版本选择
|
||
| 环境 | 推荐版本 | 说明 |
|
||
|------|---------|------|
|
||
| Windows x64 | SDK v3.0 (OpenSSL 3.0) | 2025-02-13 更新 |
|
||
| Linux x64 | SDK v3.0 (OpenSSL 3.0) | 2025-02-13 更新 |
|
||
|
||
### Windows SDK 文件清单
|
||
解压后 `financeWinSdk/java_sdk/WeWorkFinanceSdk/` 目录下包含：
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `WeWorkFinanceSdk.dll` | 主 SDK 动态库 |
|
||
| `libcrypto-3-x64.dll` | OpenSSL 3.0 依赖 |
|
||
| `libssl-3-x64.dll` | OpenSSL 3.0 依赖 |
|
||
| `libcurl-x64.dll` | libcurl HTTP 依赖 |
|
||
| `Finance.java` | 官方 JNI 封装（本项目使用 JNA，无需此文件） |
|
||
|
||
## 二、SDK 放置
|
||
|
||
### Windows 环境
|
||
|
||
将上述 4 个 DLL 文件放到项目目录：
|
||
|
||
```
|
||
backend/archive-service/
|
||
└── sdk/ <-- 新建此目录
|
||
├── WeWorkFinanceSdk.dll
|
||
├── libcrypto-3-x64.dll
|
||
├── libssl-3-x64.dll
|
||
└── libcurl-x64.dll
|
||
```
|
||
|
||
### Linux 环境
|
||
|
||
```bash
|
||
# 将 libWeWorkFinanceSdk_Java.so 重命名并放到系统库路径
|
||
sudo cp libWeWorkFinanceSdk_Java.so /usr/lib/libWeWorkFinanceSdk.so
|
||
sudo ldconfig
|
||
|
||
# 或者放到项目目录并通过环境变量指定
|
||
mkdir -p backend/archive-service/sdk
|
||
cp libWeWorkFinanceSdk_Java.so backend/archive-service/sdk/libWeWorkFinanceSdk.so
|
||
```
|
||
|
||
## 三、配置参数
|
||
|
||
### 环境变量方式（推荐）
|
||
|
||
```bash
|
||
# 企微会话存档 Secret
|
||
export WECOM_ARCHIVE_SECRET="your-archive-secret"
|
||
|
||
# RSA 私钥（PKCS#1 格式，Base64 编码）
|
||
export WECOM_ARCHIVE_RSA_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----"
|
||
|
||
# 回调验证 Token（企微后台配置的 Token）
|
||
export WECOM_ARCHIVE_CALLBACK_TOKEN="your-callback-token"
|
||
|
||
# SDK 路径（指向存放 DLL/SO 的目录）
|
||
export WECOM_ARCHIVE_SDK_PATH="D:\www\agent_9art\backend\archive-service\sdk"
|
||
|
||
# Mock 模式（开发测试用，无真实 SDK 时设为 true）
|
||
export WECOM_ARCHIVE_MOCK=false
|
||
```
|
||
|
||
### application.yml 配置项
|
||
|
||
```yaml
|
||
wecom:
|
||
archive:
|
||
corp-id: wwd483c2fba24ae30a # 企业微信 CorpID
|
||
secret: ${WECOM_ARCHIVE_SECRET:} # 会话存档 Secret
|
||
rsa-private-key: ${WECOM_ARCHIVE_RSA_KEY:} # RSA 私钥
|
||
callback-token: ${WECOM_ARCHIVE_CALLBACK_TOKEN:} # 回调 Token
|
||
sdk-path: ${WECOM_ARCHIVE_SDK_PATH:} # SDK 目录路径
|
||
mock-mode: ${WECOM_ARCHIVE_MOCK:false} # Mock 模式开关
|
||
```
|
||
|
||
## 四、参数获取方式
|
||
|
||
### 1. CorpID
|
||
企微管理后台 → 「我的企业」→ 「企业ID」
|
||
|
||
### 2. 会话存档 Secret
|
||
企微管理后台 → 「管理工具」→ 「会话内容存档」→ 查看 Secret
|
||
|
||
### 3. RSA 密钥对
|
||
```bash
|
||
# 生成 RSA 私钥（PKCS#1 格式）
|
||
openssl genrsa -out private_key.pem 2048
|
||
|
||
# 提取公钥
|
||
openssl rsa -in private_key.pem -pubout -out public_key.pem
|
||
|
||
# 将公钥配置到企微后台
|
||
# 将私钥内容配置到 WECOM_ARCHIVE_RSA_KEY 环境变量
|
||
```
|
||
|
||
### 4. 回调 Token
|
||
企微后台配置接收消息时设置，用于验证回调请求签名。
|
||
|
||
## 五、Mock 模式（开发/测试）
|
||
|
||
当没有真实企微 SDK 或不想连接企微服务器时，启用 Mock 模式：
|
||
|
||
```bash
|
||
export WECOM_ARCHIVE_MOCK=true
|
||
```
|
||
|
||
Mock 模式下：
|
||
- 跳过 SDK 初始化，不会报错
|
||
- `pullMessages()` 返回 10 条模拟会话消息
|
||
- 完整的 `saveAndNotify()` 链路正常工作（入库 + MQ + Redis）
|
||
- 数据看板可以展示存档统计
|
||
|
||
**测试接口：**
|
||
```bash
|
||
# 手动触发拉取（Mock 模式下返回模拟数据）
|
||
curl -X POST "http://localhost:8082/api/v1/archive/pull" \
|
||
-d "seq=0&limit=10"
|
||
```
|
||
|
||
## 六、验证对接成功
|
||
|
||
### 1. 启动服务时日志
|
||
```
|
||
# 真实 SDK 模式
|
||
企微存档SDK初始化成功
|
||
|
||
# Mock 模式
|
||
企微存档Mock模式已启用，跳过SDK初始化
|
||
```
|
||
|
||
### 2. 手动拉取测试
|
||
```bash
|
||
curl -X POST "http://localhost:8082/api/v1/archive/pull" \
|
||
-d "seq=0&limit=5"
|
||
```
|
||
|
||
### 3. 回调测试（需配置可信域名）
|
||
企微后台配置回调 URL 为：
|
||
```
|
||
https://your-domain/api/v1/archive/callback
|
||
```
|
||
|
||
## 七、常见问题
|
||
|
||
### Q1: 启动报错 `UnsatisfiedLinkError: Unable to load library 'WeWorkFinanceSdk'`
|
||
- 检查 `WECOM_ARCHIVE_SDK_PATH` 是否指向正确的 DLL 目录
|
||
- 确认 DLL 文件名正确（Windows 为 `WeWorkFinanceSdk.dll`）
|
||
- 确认依赖库（libcrypto/libssl/libcurl）也在同一目录
|
||
|
||
### Q2: SDK 初始化返回非 0
|
||
- 检查 `corp-id` 和 `secret` 是否正确
|
||
- 确认企业已开通「会话内容存档」功能
|
||
|
||
### Q3: 回调签名验证失败
|
||
- 检查 `callback-token` 是否与企微后台配置一致
|
||
- 确认回调 URL 没有被中间件修改参数
|
||
|
||
### Q4: 数据库查询不到存档消息
|
||
- 检查 `archive_messages` 表是否有 `deleted` 字段（逻辑删除）
|
||
- MyBatis-Plus 全局配置 `logic-delete-field: deleted`
|