ruoyi-java/doc/腾讯文档物流链接填充-严格模式说明.md

腾讯文档物流链接填充 - 严格模式

🔒 核心安全机制

1. 分布式锁

• 使用Redis分布式锁，防止并发写入
• 锁的粒度：文档ID:工作表ID:订单单号
• 锁超时时间：30秒
• 确保同一订单同一时刻只能有一个请求处理

2. 操作日志记录

• 所有操作都会记录到数据库表 tencent_doc_operation_log
• 记录内容包括：
  • 文档ID、工作表ID
  • 操作类型（WRITE_SINGLE / BATCH_SYNC）
  • 订单单号、目标行号
  • 物流链接
  • 操作状态（SUCCESS / FAILED / SKIPPED）
  • 错误信息
  • 操作人、操作时间

3. 写入前验证

在写入之前，会进行以下验证：

1. 再次读取目标行 - 防止行数据在查找和写入之间发生变化
2. 验证单号匹配 - 确保单号仍然在预期的行
3. 验证物流列为空 - 如果已有物流链接，则拒绝写入，防止覆盖

4. 录单不再自动触发

• 旧行为：录单时如果分销标识是 H-TF，自动写入腾讯文档
• 新行为：录单时不再自动写入，必须通过订单列表手动触发
• 原因：防止并发写入和数据覆盖，需要人工确认

📋 操作流程

单个订单填充物流链接

1. 在订单列表找到目标订单
2. 点击"推送物流"按钮（或类似按钮）
3. 系统会：
   • 获取分布式锁
   • 读取表头识别列位置
   • 查找订单单号所在行
   • 验证单号和物流列
   • 写入物流链接
   • 记录操作日志
   • 释放锁

批量同步物流链接

1. 点击"批量同步"按钮
2. 系统会自动：
   • 读取表格数据
   • 根据单号查询订单系统
   • 逐个写入（每个都有锁保护）
   • 记录所有操作日志

🛡️ 安全保障

防止数据覆盖

• ✅ 分布式锁防止并发写入
• ✅ 写入前验证单号匹配
• ✅ 写入前检查物流列是否为空
• ✅ 如果物流列已有值，拒绝写入并提示

操作可追溯

• ✅ 所有操作都记录到数据库
• ✅ 记录操作人、操作时间
• ✅ 记录成功/失败/跳过状态
• ✅ 记录错误原因

📊 数据库表结构

CREATE TABLE `tencent_doc_operation_log` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `file_id` varchar(100) DEFAULT NULL COMMENT '文档ID',
  `sheet_id` varchar(100) DEFAULT NULL COMMENT '工作表ID',
  `operation_type` varchar(50) DEFAULT NULL COMMENT '操作类型',
  `order_no` varchar(100) DEFAULT NULL COMMENT '订单单号',
  `target_row` int(11) DEFAULT NULL COMMENT '目标行号',
  `logistics_link` varchar(500) DEFAULT NULL COMMENT '写入的物流链接',
  `operation_status` varchar(20) DEFAULT NULL COMMENT '操作状态',
  `error_message` text COMMENT '错误信息',
  `operator` varchar(100) DEFAULT NULL COMMENT '操作人',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `remark` varchar(500) DEFAULT NULL COMMENT '备注',
  PRIMARY KEY (`id`),
  KEY `idx_order_no` (`order_no`),
  KEY `idx_create_time` (`create_time`),
  KEY `idx_file_sheet` (`file_id`, `sheet_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='腾讯文档操作日志表';

⚠️ 注意事项

1. 必须先执行SQL - 请先执行 doc/腾讯文档操作日志表.sql 创建日志表
2. Redis必须可用 - 分布式锁依赖Redis
3. 手动触发 - 录单后需要手动点击按钮推送到腾讯文档
4. 物流列非空则跳过 - 如果物流列已有值，会拒绝写入并提示

🔍 日志查询示例

查询某个订单的操作历史

SELECT * FROM tencent_doc_operation_log 
WHERE order_no = 'JY2025110329041' 
ORDER BY create_time DESC;

查询失败的操作

SELECT * FROM tencent_doc_operation_log 
WHERE operation_status = 'FAILED' 
ORDER BY create_time DESC 
LIMIT 100;

查询被跳过的操作（物流已存在）

SELECT * FROM tencent_doc_operation_log 
WHERE operation_status = 'SKIPPED' 
AND error_message LIKE '%物流链接列已有值%'
ORDER BY create_time DESC;

📞 技术支持

如遇到问题，请检查：

1. 操作日志表 tencent_doc_operation_log
2. 应用日志中的 TencentDocController 相关日志
3. Redis是否正常运行