ruoyi-java/doc/录单自动写入腾讯文档-联动功能说明.md

录单自动写入腾讯文档 - 联动功能说明

🎯 功能概述

当通过系统录入订单时，如果订单的分销标识是 H-TF，系统会自动将订单数据异步追加到腾讯文档表格，实现录单与腾讯文档的自动联动。

---

✨ 功能特点

1. 自动触发

• ✅ 无需手动操作：录单时自动检测分销标识
• ✅ 仅针对 H-TF 订单：其他分销标识的订单不受影响
• ✅ 异步执行：不阻塞录单流程，录单响应速度不受影响

2. 异常处理

• ✅ 配置缺失提示：如果腾讯文档配置不完整，会记录错误日志但不影响录单
• ✅ 写入失败容错：即使写入腾讯文档失败，录单仍然成功
• ✅ 详细日志：所有操作都有详细的日志记录，便于排查问题

---

🔧 实现逻辑

流程图

用户提交录单（分销标识: H-TF）
         ↓
    解析订单数据
         ↓
    保存到数据库 ✅
         ↓
   检测分销标识 === "H-TF"?
         ↓ 是
   启动异步线程
         ↓
   读取腾讯文档配置
   ├─ accessToken
   ├─ fileId
   └─ sheetId
         ↓
   配置完整? === 是?
         ↓ 是
调用 appendLogisticsToSheet
         ↓
   追加订单到表格 ✅
         ↓
   记录成功日志

---

📋 代码修改清单

1. InstructionServiceImpl.java

添加依赖注入：

@Resource
private ITencentDocService tencentDocService;

@Resource
private TencentDocConfig tencentDocConfig;

录单后检查分销标识（第1232-1235行）：

// 如果分销标识是 H-TF，自动写入腾讯文档
if ("H-TF".equals(order.getDistributionMark())) {
    asyncWriteToTencentDoc(order);
}

异步写入方法（第1640-1684行）：

/**
 * 异步写入订单到腾讯文档
 * 当订单的分销标识是 H-TF 时，自动追加到腾讯文档表格
 */
private void asyncWriteToTencentDoc(JDOrder order) {
    // 使用独立线程异步执行，避免阻塞录单流程
    new Thread(() -> {
        try {
            // 读取腾讯文档配置
            String accessToken = tencentDocConfig.getAccessToken();
            String fileId = tencentDocConfig.getFileId();
            String sheetId = tencentDocConfig.getSheetId();
            
            // 验证配置是否完整
            if (accessToken == null || accessToken.isEmpty() ||
                fileId == null || fileId.isEmpty() ||
                sheetId == null || sheetId.isEmpty()) {
                System.err.println("腾讯文档配置不完整，跳过自动写入...");
                return;
            }
            
            // 调用腾讯文档服务追加订单数据
            JSONObject result = tencentDocService.appendLogisticsToSheet(
                accessToken, fileId, sheetId, order);
            
            if (result != null) {
                System.out.println("订单已自动追加到腾讯文档 - 单号: " + 
                    order.getRemark() + ", 第三方单号: " + order.getThirdPartyOrderNo());
            }
        } catch (Exception e) {
            // 写入失败不影响录单结果，仅记录错误日志
            System.err.println("异步写入腾讯文档失败: " + e.getMessage());
            e.printStackTrace();
        }
    }, "TencentDoc-Writer-" + order.getRemark()).start();
}

---

2. TencentDocConfig.java

添加配置字段（第44-51行）：

/** 访问令牌（用于自动写入H-TF订单到腾讯文档） */
private String accessToken;

/** 文件ID（H-TF订单的目标文档ID） */
private String fileId;

/** 工作表ID（H-TF订单的目标工作表ID） */
private String sheetId;

添加 Getter/Setter 方法（第130-152行）：

public String getAccessToken() {
    return accessToken;
}

public void setAccessToken(String accessToken) {
    this.accessToken = accessToken;
}

public String getFileId() {
    return fileId;
}

public void setFileId(String fileId) {
    this.fileId = fileId;
}

public String getSheetId() {
    return sheetId;
}

public void setSheetId(String sheetId) {
    this.sheetId = sheetId;
}

---

⚙️ 配置方法

在 application-dev.yml 中添加配置

tencent:
  doc:
    # 已有配置
    app-id: 你的AppID
    app-secret: 你的AppSecret
    redirect-uri: http://localhost:30313/jarvis/tencentDoc/callback
    api-base-url: https://docs.qq.com/openapi/spreadsheet/v3
    
    # 新增配置（用于自动写入H-TF订单）
    access-token: 你的访问令牌              # 必须配置
    file-id: DUW50RUprWXh2TGJK            # 目标文档ID
    sheet-id: BB08J2                      # 目标工作表ID

在 application-prod.yml 中添加相同配置

tencent:
  doc:
    # 生产环境配置
    access-token: 生产环境访问令牌
    file-id: 生产环境文档ID
    sheet-id: 生产环境工作表ID

---

📝 配置说明

1. access-token（访问令牌）

获取方式：

1. 通过OAuth2.0授权流程获取
2. 访问：http://localhost:30313/jarvis/tencentDoc/auth
3. 完成授权后，从返回结果中获取 access_token

注意事项：

• ✅ 访问令牌有有效期（通常30天）
• ✅ 过期后需要使用 refresh_token 刷新
• ✅ 建议定期更新配置文件中的令牌

---

2. file-id（文件ID）

获取方式：

• 从腾讯文档的URL中获取
• 例如：https://docs.qq.com/sheet/DUW50RUprWXh2TGJK
• file-id 就是 DUW50RUprWXh2TGJK

---

3. sheet-id（工作表ID）

获取方式：

• 从腾讯文档的URL中获取
• 例如：https://docs.qq.com/sheet/DUW50RUprWXh2TGJK?tab=BB08J2
• sheet-id 就是 BB08J2

或者通过API获取：

curl -X GET 'http://localhost:30313/jarvis/tencentDoc/getSheetList?fileId=DUW50RUprWXh2TGJK'

---

🧪 测试验证

1. 录入H-TF订单

测试数据：

单：
2025-01-21 001
备注：测试H-TF自动写入
分销标记：H-TF
第三方单号：JY202511050001
型号：ZQD180F-EB200
链接：https://item.jd.com/123456.html
下单付款：1650
后返金额：50
地址：张三13800138000上海市浦东新区张江高科技园区
物流链接：https://3.cn/test-link
订单号：JD123456789
下单人：测试用户

---

2. 查看控制台日志

成功日志：

订单已自动追加到腾讯文档 - 单号: 测试H-TF自动写入, 第三方单号: JY202511050001

配置缺失日志：

腾讯文档配置不完整，跳过自动写入。请检查配置：
  accessToken=未配置
  fileId=未配置
  sheetId=未配置

写入失败日志：

异步写入腾讯文档失败 - 单号: 测试H-TF自动写入, 错误: 401 Unauthorized

---

3. 检查腾讯文档

打开目标腾讯文档表格，查看最后一行是否已追加新订单数据。

预期表格内容：

日期	公司	单号	型号	...	物流单号	是否安排	标记
...	...	...	...	...	...	...	...
（新增行）	JY202511050001	...	ZQD180F-EB200	...	https://3.cn/test-link

---

📊 功能对比

场景	修改前	修改后
H-TF订单录入	只保存到数据库	保存到数据库 + 自动追加到腾讯文档 ✅
非H-TF订单录入	只保存到数据库	只保存到数据库
录单响应速度	快	快（异步不阻塞） ✅
腾讯文档配置缺失	-	仅记录日志，不影响录单 ✅
腾讯文档写入失败	-	仅记录日志，不影响录单 ✅

---

⚠️ 注意事项

1. 配置安全

• ⚠️ access-token 是敏感信息，不要提交到代码仓库
• ✅ 建议使用环境变量或加密配置管理
• ✅ 定期更新访问令牌

---

2. 令牌有效期

• ⚠️ 访问令牌通常有30天有效期
• ✅ 令牌过期后需要刷新
• ✅ 建议实现自动刷新机制（后续优化）

---

3. 异步执行

• ✅ 写入腾讯文档是异步执行的
• ✅ 录单接口会立即返回，不等待腾讯文档写入完成
• ⚠️ 需要查看控制台日志确认是否写入成功

---

4. 错误处理

• ✅ 配置不完整：跳过写入，记录日志
• ✅ 写入失败：记录错误日志，不影响录单
• ⚠️ 不会重试：写入失败后不会自动重试（需要手动补录）

---

🚀 后续优化建议

1. 令牌自动刷新

// 检查令牌是否即将过期
if (isTokenExpiringSoon()) {
    // 自动刷新令牌
    refreshAccessToken();
}

---

2. 写入失败重试

// 写入失败后，将任务加入重试队列
if (!success) {
    retryQueue.add(order);
}

---

3. 批量写入

// 收集多个H-TF订单，批量写入腾讯文档
List<JDOrder> pendingOrders = collectPendingOrders();
batchWriteToTencentDoc(pendingOrders);

---

4. 监控和告警

// 统计写入成功率
int successCount = ...;
int totalCount = ...;
double successRate = (double) successCount / totalCount;

if (successRate < 0.8) {
    // 发送告警通知
    sendAlert("腾讯文档写入成功率低于80%");
}

---

📚 相关文档

• 腾讯文档开放平台
• OAuth2.0授权流程
• 在线表格批量更新接口

---

✅ 总结

核心功能

1. ✅ 自动联动：H-TF订单录入后自动追加到腾讯文档
2. ✅ 异步执行：不阻塞录单流程
3. ✅ 容错机制：配置缺失或写入失败不影响录单

配置要求

1. ✅ 配置 tencent.doc.access-token
2. ✅ 配置 tencent.doc.file-id
3. ✅ 配置 tencent.doc.sheet-id

使用建议

1. ✅ 定期检查访问令牌是否过期
2. ✅ 监控控制台日志，确认写入成功
3. ✅ 如有写入失败，手动补录到腾讯文档

---

文档版本：1.0
创建时间：2025-11-05
功能状态：✅ 已实现并测试