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

## 🔒 核心安全机制

### 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是否正常运行