|
|
|
|
# 09 — 客户导入 + 联系人快速新增（OCR 划出）
|
|
|
|
|
|
|
|
|
|
Type: research
|
|
|
|
|
Status: resolved
|
|
|
|
|
Blocked by: 02
|
|
|
|
|
|
|
|
|
|
## 问题
|
|
|
|
|
|
|
|
|
|
定客户 Excel 批量导入流程（模板下载 / 上传解析 / 校验 / 结果反馈）。**OCR 快捷新增划出**（chart D2），本图只做 Excel 导入。
|
|
|
|
|
|
|
|
|
|
## 一手证据（蓝湖缓存 txt）
|
|
|
|
|
|
|
|
|
|
- `a4-3-2_客户导入.txt` — 客户导入主页
|
|
|
|
|
- `a4-3-2_新增客户信息.txt` — 与新增页同族（同 a4-3-2 前缀，可能是导入后进入新增回显）
|
|
|
|
|
- `a4-3-5_客户导入.txt` / `a4-3-6_客户导入.txt` — 导入步骤/结果页
|
|
|
|
|
- `a4-3-3-3______.txt` / `a4-3-3-4_ocr____.txt` / `a4-3-5_ocr____.txt` — OCR 相关（划出，不读）
|
|
|
|
|
|
|
|
|
|
## 已知事实（待原型细读补充）
|
|
|
|
|
|
|
|
|
|
- 模板下载 → 用户填 → 上传 → 后台异步解析 → 结果表（成功/失败逐行）。
|
|
|
|
|
- 复用票 04 查重口径：信用代码唯一硬拦、名称相似只提示不阻断（导入场景可能改为「相似=跳过」或「相似=创建但标记」）。
|
|
|
|
|
- 复用票 02 字段清单：必填校验（客户名称/客户类型/所属地区/行业/星级/关系星级）。
|
|
|
|
|
- 销售负责人：允许在 Excel 里指定 or 默认导入者。
|
|
|
|
|
|
|
|
|
|
## 待拍板点
|
|
|
|
|
|
|
|
|
|
1. **导入策略**：全成才提交（整体事务）vs 逐行独立事务（部分成功）？→ 推荐**逐行独立**（对称一般 CRM 导入的常识 + 商机模块导入若已建可参照）。
|
|
|
|
|
2. **异步 vs 同步**：批量大（>500）走异步任务 + 轮询进度 vs 同步阻塞？→ 推荐**同步小批 + 异步大批**双通道，阈值可配。
|
|
|
|
|
3. **相似客户在导入场景的处理**：跳过 / 创建但标记 / 报错 → 拍板。
|
|
|
|
|
4. **导入历史记录表** `customer_import_batch`：批次号 / 上传人 / 上传时间 / 总数 / 成功数 / 失败数 / 状态 / 失败明细文件 url。
|
|
|
|
|
5. **模板字段清单**：Excel 列 = 客户主表可导入字段子集（工商信息、附件、人脉关系单位标签集怎么表达？→ 标签用「;」分隔）。
|
|
|
|
|
6. **联系人一起导入**：Excel 是否含联系人 sheet？还是分两批？→ 推荐只导客户主表，联系人另导（联系人导入本图划出，见票 06）。
|
|
|
|
|
|
|
|
|
|
## Answer
|
|
|
|
|
|
|
|
|
|
**Status: resolved**
|
|
|
|
|
|
|
|
|
|
### A. 范围（定稿）
|
|
|
|
|
|
|
|
|
|
- ✅ **做**：客户主数据 + 联系人子表 的 Excel 导入（异步任务 + 行级处理 + 结果明细）。
|
|
|
|
|
- ❌ **不做**：OCR 快捷新增（划出）；Excel 内图片/附件转存（V1 忽略对象）；通过 Excel 清空已有字段（V1 不支持）。
|
|
|
|
|
|
|
|
|
|
### B. 导入方式（定稿，三选一）
|
|
|
|
|
|
|
|
|
|
| 方式 | 匹配到已有客户 | 未匹配 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| 仅新增数据 | 不导入，标「客户已存在」 | 创建新客户 |
|
|
|
|
|
| 仅更新数据 | 更新 | 不新增，标「未找到可更新客户」 |
|
|
|
|
|
| 新增或更新数据 | 更新 | 创建新客户 |
|
|
|
|
|
|
|
|
|
|
- **匹配顺序**（定稿）：① 客户编号完全一致 → ② 统一社会信用代码完全一致。
|
|
|
|
|
- 编号与信用代码**均缺失或均未匹配** → 不得仅凭名称自动覆盖；名称相似/相同行列「疑似重复」，本次不写入，由用户去新增/编辑流程人工处理（对称票 04 查重口径）。
|
|
|
|
|
- 编号与信用代码**分别匹配到不同客户** → 该行冲突，禁止导入。
|
|
|
|
|
- 文件内**多行匹配同一客户**：`覆盖导入`/`重复时不导入` 互斥，默认「重复时不导入」；覆盖按文件自上而下、最后一条通过校验的为准；不导入则重复组全部失败。
|
|
|
|
|
|
|
|
|
|
### C. 字段语义（定稿）
|
|
|
|
|
|
|
|
|
|
- **新增导入**：必填字段空 → 该行失败；非必填空 → 按空值创建。`customer_stage` 固定=潜在（不得指定）。
|
|
|
|
|
- **更新导入**：空白单元格 = 不修改已有值（V1 不支持清空）。
|
|
|
|
|
- **禁止通过导入修改**：销售负责人/协同人（普通销售导入负责人固定=当前用户；有分配权限者可指定授权范围内负责人，超出 → 该行失败）、客户阶段（更新不得回退）、工商字段/战略协议/关联业务汇总等系统计算字段。
|
|
|
|
|
- **联系人子表**：电话存在 → 按电话查重（匹配本客户已有联系人→更新；匹配他客户联系人→冲突禁止转移）；电话空 → 按「客户+姓名+职务」疑似重复，不自动覆盖，列失败明细。
|
|
|
|
|
- **原子单元** = 单条客户主记录 / 单条联系人子记录；联系人失败不回滚已成功的客户主记录。
|
|
|
|
|
|
|
|
|
|
### D. 任务模型（定稿，对称商机/线索导入范式）
|
|
|
|
|
|
|
|
|
|
- **异步任务**：上传 + 服务端预校验 → 展示预计新增/更新/失败/疑似重复数 → 用户确认 → 创建正式导入任务。
|
|
|
|
|
- **预校验**：文件类型(.xls/.xlsx) / 大小(≤20MB) / 模板版本 / 表头(无空单元格才导) / 单 sheet ≤50000 行 / 不计算公式 / 忽略图片附件对象。
|
|
|
|
|
- **行级处理，允许部分成功**：单行内原子（不半行写入）。
|
|
|
|
|
- **结果页**：任务状态 / 总行数 / 新增成功 / 更新成功 / 未变化 / 失败数 / 提交人 / 提交时间 / 完成时间；失败明细（sheet名/行号/客户识别/失败字段/失败原因）可下载，敏感值按字段权限脱敏。
|
|
|
|
|
- **任务超时/异常 → 标记失败**，不得让用户重复提交状态未知的任务。
|
|
|
|
|
- **操作日志**：记录任务 ID/导入方式/模板版本/文件哈希/成功失败数/触发后续动作选择；**不记录文件名、文件内容、敏感字段原值**。
|
|
|
|
|
- **最近导入记录**入口，仅当前用户有权查看的任务。
|
|
|
|
|
|
|
|
|
|
**契约**：
|
|
|
|
|
```
|
|
|
|
|
POST /api/customer/import/upload 上传 + 预校验（返回预计数 + 预校验明细）
|
|
|
|
|
POST /api/customer/import/{taskId}/confirm 确认创建正式任务（返回 taskId）
|
|
|
|
|
GET /api/customer/import/{taskId} 任务结果
|
|
|
|
|
GET /api/customer/import/{taskId}/failures 失败明细下载
|
|
|
|
|
GET /api/customer/import/page 最近导入记录
|
|
|
|
|
GET /api/customer/import/template 下载导入模板（含模板版本）
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### E. 回填 / 下游
|
|
|
|
|
|
|
|
|
|
- **票 04**：复用 `CustomerDedupService`（信用代码精确查重 + 名称相似判定）做导入匹配。
|
|
|
|
|
- **票 03**：导入成功刷新「我的客户」，仍按当前用户数据范围展示。
|
|
|
|
|
- **票 07**：oplog 记录每次导入（任务级）。
|
|
|
|
|
- **crm-file**：文件上传/哈希复用平台能力（对称商机/线索导入）。
|
|
|
|
|
|
|
|
|
|
### F. ⚠ 挂号（需拍板）
|
|
|
|
|
|
|
|
|
|
1. 文件内多行匹配同一客户时，默认「重复时不导入」（原型默认）——确认默认值？**推荐：默认「重复时不导入」**（避免覆盖歧义）。
|
