luoweijian
/
crm-backend-matt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
139 Commits
1 Branch
0 Tags
403 MiB
 
 
 
 
 
 
Tree: b48fbb8beb
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'b48fbb8beb'
${ noResults }
crm-backend-matt/.scratch/customer-module/issues/09-import.md

6.4 KiB
Raw Blame History

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. 文件内多行匹配同一客户时，默认「重复时不导入」（原型默认）——确认默认值？推荐：默认「重复时不导入」（避免覆盖歧义）。