416 lines
11 KiB
Markdown
416 lines
11 KiB
Markdown
# 自动识别列位置 - 优化说明
|
||
|
||
## 🎯 优化目标
|
||
|
||
**修改前**：列位置可以由前端传递，也可以自动识别
|
||
**修改后**：所有列位置都由后端自动从表头识别，前端不再需要传递
|
||
|
||
---
|
||
|
||
## ✅ 优化原因
|
||
|
||
### 1. 降低前端复杂度
|
||
|
||
**修改前**，前端需要知道列的位置：
|
||
```json
|
||
{
|
||
"accessToken": "...",
|
||
"fileId": "...",
|
||
"sheetId": "...",
|
||
"headerRow": 2,
|
||
"orderNoColumn": 2, // ❌ 前端需要传递
|
||
"logisticsLinkColumn": 12 // ❌ 前端需要传递
|
||
}
|
||
```
|
||
|
||
**修改后**，前端只需要提供基本信息：
|
||
```json
|
||
{
|
||
"accessToken": "...",
|
||
"fileId": "...",
|
||
"sheetId": "...",
|
||
"headerRow": 2 // ✅ 只需要表头行号（可选，默认为1）
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 增强灵活性
|
||
|
||
**表格结构变化时**，不需要修改前端代码：
|
||
|
||
| 场景 | 修改前 | 修改后 |
|
||
|------|--------|--------|
|
||
| 列的顺序改变 | ❌ 需要更新前端参数 | ✅ 自动识别，无需改动 |
|
||
| 添加新列 | ❌ 需要重新计算索引 | ✅ 自动识别，无需改动 |
|
||
| 列名称不变 | ✅ 无需改动 | ✅ 无需改动 |
|
||
|
||
---
|
||
|
||
### 3. 减少出错概率
|
||
|
||
**常见错误**：
|
||
- ❌ 前端传递的列索引不正确（数错了列）
|
||
- ❌ 前端传递的索引是从1开始，但后端期望从0开始
|
||
- ❌ 表格结构变化后，前端忘记更新参数
|
||
|
||
**修改后**：
|
||
- ✅ 后端自动识别，避免手动数列
|
||
- ✅ 统一使用从0开始的索引，前端无需关心
|
||
- ✅ 表格结构变化后，只要列名不变，自动适配
|
||
|
||
---
|
||
|
||
## 🔧 代码修改
|
||
|
||
### 修改 1：删除前端参数接收
|
||
|
||
**修改前**：
|
||
```java
|
||
// 可选参数：指定列位置
|
||
Integer orderNoColumn = params.get("orderNoColumn") != null ?
|
||
Integer.valueOf(params.get("orderNoColumn").toString()) : null;
|
||
Integer logisticsLinkColumn = params.get("logisticsLinkColumn") != null ?
|
||
Integer.valueOf(params.get("logisticsLinkColumn").toString()) : null;
|
||
Integer headerRow = params.get("headerRow") != null ?
|
||
Integer.valueOf(params.get("headerRow").toString()) : 1;
|
||
```
|
||
|
||
**修改后**：
|
||
```java
|
||
// 可选参数：表头行号
|
||
Integer headerRow = params.get("headerRow") != null ?
|
||
Integer.valueOf(params.get("headerRow").toString()) : 1;
|
||
```
|
||
|
||
---
|
||
|
||
### 修改 2：始终自动识别列位置
|
||
|
||
**修改前**（条件识别）：
|
||
```java
|
||
// 自动识别列位置（如果未指定）
|
||
if (orderNoColumn == null || logisticsLinkColumn == null) {
|
||
// 查找所有相关列
|
||
...
|
||
}
|
||
```
|
||
|
||
**修改后**（始终识别）：
|
||
```java
|
||
// 自动识别列位置（从表头中识别）
|
||
Integer orderNoColumn = null; // "单号"列
|
||
Integer logisticsLinkColumn = null; // "物流单号"列
|
||
Integer arrangedColumn = null; // "是否安排"列
|
||
Integer markColumn = null; // "标记"列
|
||
|
||
// 查找所有相关列
|
||
for (int i = 0; i < headerRowData.size(); i++) {
|
||
String cellValue = headerRowData.getString(i);
|
||
if (cellValue != null) {
|
||
String cellValueTrim = cellValue.trim();
|
||
|
||
// 识别"单号"列
|
||
if (orderNoColumn == null && cellValueTrim.contains("单号")) {
|
||
orderNoColumn = i;
|
||
log.info("✓ 识别到 '单号' 列：第 {} 列（索引{}）", i + 1, i);
|
||
}
|
||
|
||
// 识别"物流单号"或"物流链接"列
|
||
if (logisticsLinkColumn == null && (cellValueTrim.contains("物流单号") || cellValueTrim.contains("物流链接"))) {
|
||
logisticsLinkColumn = i;
|
||
log.info("✓ 识别到 '物流单号' 列：第 {} 列（索引{}）", i + 1, i);
|
||
}
|
||
|
||
// 识别"是否安排"列（可选）
|
||
if (arrangedColumn == null && cellValueTrim.contains("是否安排")) {
|
||
arrangedColumn = i;
|
||
log.info("✓ 识别到 '是否安排' 列：第 {} 列（索引{}）", i + 1, i);
|
||
}
|
||
|
||
// 识别"标记"列（可选）
|
||
if (markColumn == null && cellValueTrim.contains("标记")) {
|
||
markColumn = i;
|
||
log.info("✓ 识别到 '标记' 列：第 {} 列（索引{}）", i + 1, i);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 修改 3：增强错误提示
|
||
|
||
**修改后的错误提示更加友好**：
|
||
|
||
```java
|
||
// 检查必需的列是否都已识别
|
||
if (orderNoColumn == null) {
|
||
return AjaxResult.error("无法找到'单号'列，请检查表头是否包含'单号'字段");
|
||
}
|
||
if (logisticsLinkColumn == null) {
|
||
return AjaxResult.error("无法找到'物流单号'或'物流链接'列，请检查表头");
|
||
}
|
||
|
||
// 提示可选列的识别情况
|
||
if (arrangedColumn == null) {
|
||
log.warn("未找到'是否安排'列，将跳过该字段的更新");
|
||
}
|
||
if (markColumn == null) {
|
||
log.warn("未找到'标记'列，将跳过该字段的更新");
|
||
}
|
||
|
||
log.info("列位置识别完成 - 单号: {}, 物流单号: {}, 是否安排: {}, 标记: {}",
|
||
orderNoColumn, logisticsLinkColumn, arrangedColumn, markColumn);
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 列识别规则
|
||
|
||
### 必需列
|
||
|
||
| 列名关键字 | 识别条件 | 必需 | 说明 |
|
||
|-----------|---------|------|------|
|
||
| "单号" | `cellValue.contains("单号")` | ✅ 是 | 用于匹配订单 |
|
||
| "物流单号" 或 "物流链接" | `cellValue.contains("物流单号")` <br> 或 `cellValue.contains("物流链接")` | ✅ 是 | 写入物流链接 |
|
||
|
||
### 可选列
|
||
|
||
| 列名关键字 | 识别条件 | 必需 | 说明 |
|
||
|-----------|---------|------|------|
|
||
| "是否安排" | `cellValue.contains("是否安排")` | ❌ 否 | 写入 "2" |
|
||
| "标记" | `cellValue.contains("标记")` | ❌ 否 | 写入日期（`yyMMdd`） |
|
||
|
||
**识别规则**：
|
||
- ✅ 只要列名**包含**关键字即可（不需要完全匹配）
|
||
- ✅ 自动去除前后空格
|
||
- ✅ 区分大小写
|
||
- ✅ 从左到右查找，找到第一个匹配的列
|
||
|
||
---
|
||
|
||
## 🔍 日志输出示例
|
||
|
||
### 成功识别
|
||
|
||
```
|
||
✓ 识别到 '单号' 列：第 3 列（索引2）
|
||
✓ 识别到 '物流单号' 列：第 13 列（索引12）
|
||
✓ 识别到 '是否安排' 列：第 12 列（索引11）
|
||
✓ 识别到 '标记' 列：第 15 列（索引14）
|
||
列位置识别完成 - 单号: 2, 物流单号: 12, 是否安排: 11, 标记: 14
|
||
```
|
||
|
||
### 部分列缺失（可选列）
|
||
|
||
```
|
||
✓ 识别到 '单号' 列：第 3 列（索引2）
|
||
✓ 识别到 '物流单号' 列：第 13 列（索引12）
|
||
WARN 未找到'是否安排'列，将跳过该字段的更新
|
||
WARN 未找到'标记'列，将跳过该字段的更新
|
||
列位置识别完成 - 单号: 2, 物流单号: 12, 是否安排: null, 标记: null
|
||
```
|
||
|
||
### 必需列缺失（错误）
|
||
|
||
```
|
||
ERROR 无法找到'单号'列，请检查表头是否包含'单号'字段
|
||
```
|
||
|
||
或
|
||
|
||
```
|
||
ERROR 无法找到'物流单号'或'物流链接'列，请检查表头
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 测试场景
|
||
|
||
### 场景 1：标准表格
|
||
|
||
**表头**：
|
||
| 日期 | 公司 | 单号 | 型号 | ... | 物流单号 | 是否安排 | 标记 |
|
||
|
||
**结果**：
|
||
- ✅ 所有列都识别成功
|
||
- ✅ 同时更新4个字段
|
||
|
||
---
|
||
|
||
### 场景 2：列名有变化
|
||
|
||
**表头**：
|
||
| 日期 | 公司 | 订单单号 | 型号 | ... | 物流链接 | 安排状态 | 备注标记 |
|
||
|
||
**结果**：
|
||
- ✅ "订单单号" → 识别为"单号"列（包含"单号"）
|
||
- ✅ "物流链接" → 识别为"物流单号"列（包含"物流链接"）
|
||
- ❌ "安排状态" → 无法识别（不包含"是否安排"）
|
||
- ✅ "备注标记" → 识别为"标记"列（包含"标记"）
|
||
|
||
---
|
||
|
||
### 场景 3：列顺序改变
|
||
|
||
**原表头**：
|
||
| 单号 | 公司 | 日期 | ... | 物流单号 | 是否安排 | 标记 |
|
||
|
||
**新表头**（顺序改变）：
|
||
| 日期 | 单号 | 公司 | ... | 是否安排 | 标记 | 物流单号 |
|
||
|
||
**结果**：
|
||
- ✅ 仍然能正确识别所有列
|
||
- ✅ 前端代码无需任何修改
|
||
|
||
---
|
||
|
||
### 场景 4：最小必需列
|
||
|
||
**表头**：
|
||
| 日期 | 公司 | 单号 | 型号 | ... | 物流单号 |
|
||
|
||
**结果**：
|
||
- ✅ 必需列识别成功
|
||
- ⚠️ "是否安排"列不存在，跳过更新
|
||
- ⚠️ "标记"列不存在，跳过更新
|
||
- ✅ 只更新物流单号
|
||
|
||
---
|
||
|
||
## 📋 前端调用示例
|
||
|
||
### 修改前（需要传递列位置）
|
||
|
||
```javascript
|
||
// ❌ 需要手动指定列位置
|
||
const data = {
|
||
accessToken: "...",
|
||
fileId: "DUW50RUprWXh2TGJK",
|
||
sheetId: "BB08J2",
|
||
headerRow: 2,
|
||
orderNoColumn: 2, // 需要前端知道列位置
|
||
logisticsLinkColumn: 12 // 需要前端知道列位置
|
||
};
|
||
|
||
axios.post('/jarvis/tencentDoc/fillLogisticsByOrderNo', data);
|
||
```
|
||
|
||
---
|
||
|
||
### 修改后（自动识别）
|
||
|
||
```javascript
|
||
// ✅ 只需要基本信息
|
||
const data = {
|
||
accessToken: "...",
|
||
fileId: "DUW50RUprWXh2TGJK",
|
||
sheetId: "BB08J2",
|
||
headerRow: 2 // 可选，默认为1
|
||
};
|
||
|
||
axios.post('/jarvis/tencentDoc/fillLogisticsByOrderNo', data);
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 API 参数说明
|
||
|
||
### 请求参数
|
||
|
||
| 参数名 | 类型 | 必需 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| `accessToken` | String | ✅ 是 | - | 腾讯文档访问令牌 |
|
||
| `fileId` | String | ✅ 是 | - | 文件ID |
|
||
| `sheetId` | String | ✅ 是 | - | 工作表ID |
|
||
| `headerRow` | Integer | ❌ 否 | 1 | 表头所在行号（从1开始） |
|
||
| `forceStart` | Boolean | ❌ 否 | false | 是否强制从指定行开始 |
|
||
| `forceStartRow` | Integer | ❌ 否 | null | 强制起始行号 |
|
||
|
||
**已移除的参数**：
|
||
- ~~`orderNoColumn`~~ - 不再需要，自动识别
|
||
- ~~`logisticsLinkColumn`~~ - 不再需要，自动识别
|
||
|
||
---
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"msg": "填充物流链接完成",
|
||
"code": 200,
|
||
"data": {
|
||
"startRow": 3,
|
||
"endRow": 52,
|
||
"filledCount": 45,
|
||
"skippedCount": 3,
|
||
"errorCount": 0,
|
||
"orderNoColumn": 2, // 自动识别的列位置
|
||
"logisticsLinkColumn": 12, // 自动识别的列位置
|
||
"message": "处理完成：成功填充 45 条，跳过 3 条，错误 0 条"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
### 1. 列名要求
|
||
|
||
**必需列**必须包含特定关键字：
|
||
- ✅ "单号"、"订单单号"、"第三方单号" → 都能识别
|
||
- ❌ "编号"、"ID" → 无法识别
|
||
|
||
**建议**：保持列名包含明确的关键字，如"单号"、"物流单号"、"是否安排"、"标记"。
|
||
|
||
---
|
||
|
||
### 2. 列名唯一性
|
||
|
||
如果表格中有多个包含相同关键字的列，只会识别第一个：
|
||
|
||
**示例**：
|
||
| 采购单号 | 销售单号 | 物流单号 |
|
||
|
||
**识别结果**：
|
||
- "单号"列 → 第1列（采购单号）
|
||
- "物流单号"列 → 第3列
|
||
|
||
**建议**：如果有多个"单号"列，确保目标列是第一个出现的。
|
||
|
||
---
|
||
|
||
### 3. 向后兼容
|
||
|
||
虽然前端不再需要传递 `orderNoColumn` 和 `logisticsLinkColumn`，但如果传递了这些参数，后端会忽略它们，不会报错。
|
||
|
||
---
|
||
|
||
## ✅ 总结
|
||
|
||
### 优化效果
|
||
|
||
| 方面 | 优化前 | 优化后 |
|
||
|------|--------|--------|
|
||
| **前端参数** | 5个参数 | 3个参数 ✅ |
|
||
| **前端复杂度** | 需要知道列位置 | 只需要基本信息 ✅ |
|
||
| **灵活性** | 表格结构变化需要修改前端 | 自动适配 ✅ |
|
||
| **出错概率** | 容易传错列索引 | 自动识别，减少错误 ✅ |
|
||
| **可维护性** | 前后端都需要维护列信息 | 只有后端识别逻辑 ✅ |
|
||
|
||
### 关键改进
|
||
|
||
1. ✅ **前端简化**：不再需要传递列位置
|
||
2. ✅ **自动适配**：表格结构变化时自动识别
|
||
3. ✅ **错误提示**：更友好的错误信息
|
||
4. ✅ **日志完善**：详细的识别过程日志
|
||
|
||
---
|
||
|
||
**文档版本**：1.0
|
||
**修改日期**：2025-11-05
|
||
**状态**：✅ 已完成
|
||
|