1

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

@@ -0,0 +1,130 @@
+# 腾讯文档物流链接填充 - 严格模式
+
+## 🔒 核心安全机制
+
+### 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. 系统会自动：
+   - 读取表格数据
+   - 根据单号查询订单系统
+   - 逐个写入（每个都有锁保护）
+   - 记录所有操作日志
+
+## 🛡️ 安全保障
+
+### 防止数据覆盖
+- ✅ 分布式锁防止并发写入
+- ✅ 写入前验证单号匹配
+- ✅ 写入前检查物流列是否为空
+- ✅ 如果物流列已有值，拒绝写入并提示
+
+### 操作可追溯
+- ✅ 所有操作都记录到数据库
+- ✅ 记录操作人、操作时间
+- ✅ 记录成功/失败/跳过状态
+- ✅ 记录错误原因
+
+## 📊 数据库表结构
+
+```sql
+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. **物流列非空则跳过** - 如果物流列已有值，会拒绝写入并提示
+
+## 🔍 日志查询示例
+
+### 查询某个订单的操作历史
+```sql
+SELECT * FROM tencent_doc_operation_log 
+WHERE order_no = 'JY2025110329041' 
+ORDER BY create_time DESC;
+```
+
+### 查询失败的操作
+```sql
+SELECT * FROM tencent_doc_operation_log 
+WHERE operation_status = 'FAILED' 
+ORDER BY create_time DESC 
+LIMIT 100;
+```
+
+### 查询被跳过的操作（物流已存在）
+```sql
+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是否正常运行
+