131 lines
4.2 KiB
Markdown
131 lines
4.2 KiB
Markdown
# 腾讯文档物流链接填充 - 严格模式
|
||
|
||
## 🔒 核心安全机制
|
||
|
||
### 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是否正常运行
|
||
|