# 从Status字段提取手机号码功能说明

## 功能概述

在批量同步物流链接到腾讯文档时，系统会自动从订单的 `status` 字段中提取手机号码，并写入到腾讯文档的"下单电话"列。

> **注意：** 手机号码存储在 `status` 字段，不是 `remark` 字段。

## 实现原理

### 1. 列识别

系统在读取表头时，会自动识别以下列名：
- `下单电话`
- `电话`
- `手机`

任何包含以上关键词的列都会被识别为"下单电话"列。

### 2. 手机号码提取

从订单的 `status`（状态）字段中提取手机号码：

**提取规则：**
- 自动移除status字段中的空格、横线、括号等分隔符
- 使用正则表达式匹配11位手机号码（1开头的11位数字）
- 支持格式示例：
  ```
  138 0013 8000
  138-0013-8000
  (138)00138000
  13800138000
  ```

**正则表达式：** `1[3-9]\d{9}`

**匹配规则：**
- 第1位必须是 `1`
- 第2位必须是 `3-9`
- 后面9位是任意数字 `0-9`

### 3. 写入逻辑

在批量同步时，如果同时满足以下条件，会写入手机号码：
1. ✅ 表头中识别到了"下单电话"列
2. ✅ 从订单备注中成功提取到手机号码
3. ✅ 订单有物流链接需要同步

写入时使用 `batchUpdate` API，一次性更新多个字段：
1. 物流单号（超链接类型）
2. **下单电话（普通文本）** ← 新增
3. 是否安排（值为"2"）
4. 标记（当前日期，格式：251106）

## 代码实现

### 关键方法

#### `extractPhoneFromRemark(String remark)`

```java
/**
 * 从备注中提取手机号码
 * 支持11位手机号码，可能包含空格、横线等分隔符
 * 
 * @param remark 备注信息
 * @return 提取到的手机号码，如果没有则返回null
 */
private String extractPhoneFromRemark(String remark) {
    if (remark == null || remark.trim().isEmpty()) {
        return null;
    }

    // 移除所有空格、横线、括号等分隔符
    String cleanedRemark = remark.replaceAll("[\\s\\-\\(\\)\\[\\]（）\\【\\】]", "");

    // 匹配11位手机号码（1开头的11位数字）
    java.util.regex.Pattern pattern = java.util.regex.Pattern.compile("1[3-9]\\d{9}");
    java.util.regex.Matcher matcher = pattern.matcher(cleanedRemark);

    if (matcher.find()) {
        String phone = matcher.group();
        log.debug("从备注中提取到手机号码: {}", phone);
        return phone;
    }

    return null;
}
```

### 使用位置

**`TencentDocController.fillLogisticsByOrderNo`** - 批量同步方法

1. **列识别阶段**（第1003-1008行）：
```java
// 识别"下单电话"列（可选）
if (phoneColumn == null && (cellValueTrim.contains("下单电话") 
    || cellValueTrim.contains("电话") 
    || cellValueTrim.contains("手机"))) {
    phoneColumn = i;
    log.info("✓ 识别到 '下单电话' 列：第 {} 列（索引{}）", i + 1, i);
}
```

2. **数据处理阶段**（第1188-1195行）：
```java
// 从status字段中提取手机号码
String phone = null;
if (phoneColumn != null) {
    phone = extractPhoneFromRemark(order.getStatus());
    if (phone != null) {
        log.info("✓ 从status字段提取手机号码 - 单号: {}, 手机号: {}", orderNo, phone);
    }
}
```

3. **构建更新请求**（第1201-1205行）：
```java
// 如果找到手机号码，也添加到更新中
if (phone != null && phoneColumn != null) {
    update.put("phone", phone);
    update.put("phoneColumn", phoneColumn);
}
```

4. **写入腾讯文档**（第1294-1300行）：
```java
// 2. 更新"下单电话"列（如果存在且提取到了手机号码）
String phone = update.getString("phone");
Integer phoneCol = update.getInteger("phoneColumn");
if (phone != null && phoneCol != null) {
    requests.add(buildUpdateCellRequest(sheetId, row - 1, phoneCol, phone, false));
    log.info("✓ 准备写入手机号码 - 单号: {}, 手机号: {}, 行: {}, 列: {}", 
        expectedOrderNo, phone, row, phoneCol);
}
```

## 日志输出

### 成功提取手机号码

```
✓ 从status字段提取手机号码 - 单号: JY2025110601, 手机号: 13800138000
✓ 准备写入手机号码 - 单号: JY2025110601, 手机号: 13800138000, 行: 3, 列: 6
✓ 写入成功 - 行: 3, 单号: JY2025110601, 物流链接: https://3.cn/xxx, 手机号: 13800138000
```

### 未找到手机号码

```
找到订单物流链接 - 单号: JY2025110602, 物流链接: https://3.cn/xxx, 手机号: 无, 行号: 4, 已推送: 否
✓ 写入成功 - 行: 4, 单号: JY2025110602, 物流链接: https://3.cn/xxx
```

### 未识别到"下单电话"列

```
未找到'下单电话'列，将跳过该字段的更新
列位置识别完成 - 单号: 2, 物流单号: 12, 是否安排: null, 标记: 14, 下单电话: null
```

## 使用示例

### 订单Status字段示例

| Status内容 | 提取结果 | 说明 |
|---------|---------|------|
| `联系电话：138 0013 8000` | `13800138000` | ✅ 成功提取 |
| `手机号138-0013-8000` | `13800138000` | ✅ 成功提取 |
| `电话：(138)00138000` | `13800138000` | ✅ 成功提取 |
| `13800138000 张三` | `13800138000` | ✅ 成功提取 |
| `17703916233` | `17703916233` | ✅ 成功提取 |
| `无电话` | `null` | ❌ 未提取到 |
| `12345678901` | `null` | ❌ 不符合规则（不是1开头） |
| `1280013800` | `null` | ❌ 不符合规则（第2位不是3-9） |

### 腾讯文档表头示例

支持的表头名称（包含即可识别）：
- ✅ `下单电话`
- ✅ `电话`
- ✅ `手机`
- ✅ `手机号`
- ✅ `联系电话`
- ✅ `客户电话`

## 兼容性

### 向后兼容

- ✅ 如果表头中**没有**"下单电话"列，功能自动跳过，不影响其他字段的同步
- ✅ 如果订单status字段中**没有**手机号码，功能自动跳过，不影响其他字段的同步
- ✅ 不影响现有的物流链接、是否安排、标记字段的同步

### 可选性

此功能是**完全可选**的：
1. 不需要在表头中添加"下单电话"列
2. 订单status字段可以不包含手机号码
3. 功能会自动识别和适配

## 测试建议

### 测试场景

1. **正常场景**
   - 表头包含"下单电话"列
   - 订单status字段包含手机号码
   - 预期：手机号码正确写入

2. **无电话列场景**
   - 表头不包含"下单电话"列
   - 预期：其他字段正常同步，手机号码跳过

3. **无手机号场景**
   - 表头包含"下单电话"列
   - 订单status字段不包含手机号码
   - 预期：其他字段正常同步，手机号码列为空

4. **多种格式场景**
   - 测试不同格式的手机号码（带空格、横线、括号等）
   - 预期：都能正确提取

### 测试步骤

1. 在腾讯文档表头添加"下单电话"列（或"电话"、"手机"）
2. 确保订单的status字段包含手机号码（例如：17703916233）
3. 点击"批量同步物流"按钮
4. 查看后端日志，确认提取和写入成功
5. 查看腾讯文档，确认手机号码正确显示在"下单电话"列

## 未来优化建议

1. **支持更多手机号格式**
   - 国际号码（+86）
   - 固定电话（区号+号码）

2. **支持多个手机号**
   - 从备注中提取多个手机号码
   - 用逗号或分号分隔

3. **手机号验证**
   - 验证号码段有效性（如：135、138等）
   - 提示无效号码

4. **手机号脱敏**
   - 日志中对手机号进行脱敏显示
   - 如：138****8000

## 相关文件

- **Controller**: `TencentDocController.java`
- **方法**: `fillLogisticsByOrderNo()`, `extractPhoneFromRemark()`
- **API**: 腾讯文档 `batchUpdate` API

---

**最后更新时间**: 2025-11-06  
**版本**: v1.0