# 企微会话存档 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`