crm-backend-matt/.scratch/customer-module/issues/09-answer.md

Answer

Status: resolved

A. 范围（定稿）

• ✅ 做：客户主数据 + 联系人子表 的 Excel 导入（异步任务 + 行级处理 + 结果明细）。
• ❌ 不做：OCR 快捷新增（划出）；Excel 内图片/附件转存（V1 忽略对象）；通过 Excel 清空已有字段（V1 不支持）。

B. 导入方式（定稿，三选一）

方式	匹配到已有客户	未匹配
仅新增数据	不导入，标「客户已存在」	创建新客户
仅更新数据	更新	不新增，标「未找到可更新客户」
新增或更新数据	更新	创建新客户

• 匹配顺序（定稿）：① 客户编号完全一致 → ② 统一社会信用代码完全一致。
• 编号与信用代码均缺失或均未匹配 → 不得仅凭名称自动覆盖；名称相似/相同行列「疑似重复」，本次不写入，由用户去新增/编辑流程人工处理（对称票 04 查重口径）。
• 编号与信用代码分别匹配到不同客户 → 该行冲突，禁止导入。
• 文件内多行匹配同一客户：覆盖导入/重复时不导入 互斥，默认「重复时不导入」；覆盖按文件自上而下、最后一条通过校验的为准；不导入则重复组全部失败。

C. 字段语义（定稿）

• 新增导入：必填字段空 → 该行失败；非必填空 → 按空值创建。customer_stage 固定=潜在（不得指定）。
• 更新导入：空白单元格 = 不修改已有值（V1 不支持清空）。
• 禁止通过导入修改：销售负责人/协同人（普通销售导入负责人固定=当前用户；有分配权限者可指定授权范围内负责人，超出 → 该行失败）、客户阶段（更新不得回退）、工商字段/战略协议/关联业务汇总等系统计算字段。
• 联系人子表（D26 翻案后校准 20260902）：电话存在 → 匹配本客户已有联系人→更新；匹配他客户联系人→软提示疑似重复、不禁止导入（列疑似重复明细，跟随查重设置「联系电话」开关；开关关则不提示），不做跨客户电话唯一硬拦；电话空 → 按「客户+姓名+职务」疑似重复，不自动覆盖，列疑似重复明细。同一导入文件内同客户电话相同两行 → 该行失败（表单级）。
• 原子单元 = 单条客户主记录 / 单条联系人子记录；联系人失败不回滚已成功的客户主记录。

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. 挂号 — 已随 grill 全部销号

1. 文件内多行匹配同一客户默认值 已拍板（grill Q14）：默认「重复时不导入」（重复组全部失败）。