管理客资列表

一、功能介绍

客资列表直接查询 `crm.lead` 客资记录，展示创建、清洗、分配、领取、跟进、人工拨打、来源、意向和归属等状态。系统内部保留 Lead 技术标识，面向用户统一称为“客资”。页面本身只负责查阅、筛选、排序、导出和跳转详情，不在列表内执行批量分配或领取。

列表默认不限制日期，使用创建时间倒序和每页 20 条。只有同时选择开始、结束时间时，后端才应用时间条件；清空日期会查询当前数据范围内全部时间。

二、功能亮点

1. 关键词同时匹配客户姓名、手机号、微信号、微信昵称、地址、备注和三方客资 ID。
2. 时间类型支持创建、更新、分配和领取时间。
3. 支持多选意向品类，并按客户意向、来源、经销商、客户状态、分配、领取、跟进和人工拨打状态组合筛选。
4. 字段设置可选择可见列、调整列宽，并设置一个排序字段及正序/倒序。
5. 列表和导出复用同一套人员/组织范围与筛选 Specification。
6. 点击查看携带当前页客资 ID 集合进入流量分配详情，便于在该页结果间前后切换。
7. 导出按当前可见列、筛选和排序生成 Excel。

三、使用场景

适合主管核对客资分配与领取进度、销售查找待跟进对象、运营抽查渠道和意向质量。页面显示的“员工未跟进”存在特殊计算口径，导出也没有规模上限，因此不应未经复核直接用于员工绩效、全量经营报表或大规模数据提取。

四、使用权限

1. 进入页面需要「客资列表」菜单可见且 `CUSTOMER_SALES` 专区可用。
2. 前端只在拥有 `/customer/lead-list` 下 `export` 按钮键时显示导出按钮。
3. 列表和导出控制器没有服务端查看或导出细分功能权限守卫；按钮隐藏不能阻止直接调用导出接口。
4. 非管理员通过 `OrgScopeUtils` 限制可见人员和组织：可看到负责人位于可见人员范围的客资，也可在负责人为空时按关联客户负责人或 ownerOrgId 补充判断。
5. 对已经关联客户的客资，还会排除关联客户负责人超出可见人员范围的记录；未关联客户可按客资本身归属判断。
6. LeadEntity 声明 authCorpId 租户过滤器；正式验收仍要用两个企业账号验证运行时过滤启用。
7. 列表“查看”按钮没有独立权限判断，进入详情后的操作权限必须由详情页和服务端另行控制。

五、前置条件

1. 确认登录企业、角色和组织范围正确，并用一条已知客资核对可见性。
2. 确认本次需要查询客资而不是已经转化后的客户档案；后者使用《查看和筛选客户》。
3. 确认 lead 与 lead_contract 对象的 Picklist 可读取；选项加载失败时下拉框可能为空或表格显示原始编码。
4. 确认来源树存在启用的二级节点；页面的“二级渠道”下拉实际提交来源 ID。
5. 导出前取得字段、对象范围、用途、接收人、保留期限和销毁方式审批。
6. 绩效核对前明确清洗、领取和跟进状态的计算口径，尤其不要把“员工未跟进”直接理解为零条跟进记录。
7. 大范围查询先用页面分页抽样；服务端 pageSize 和导出总量均没有最大值保护。

六、操作步骤

1. 进入「客户管理 → 客资列表」，确认初始条件为空、当前排序为“创建时间 / 倒序”。
2. 输入客户姓名、手机号、微信号、微信昵称、地址、备注或三方客资 ID 的连续片段，按 Enter 或点击「搜索」。
3. 需要限定周期时先选择时间类型，再选择完整开始和结束时间。只传一端不会应用时间过滤；页面日期组件正常选择时会同时提交两端。
4. 按意向品类多选过滤。多个值按“命中任意一个”处理，不是必须同时包含全部品类。
5. 选择“二级渠道”时注意页面提交的是来源树二级节点 ID，而表格“二级渠道”列展示 lead.secondChannel 字段；两者不是同一个存储字段，筛选值和显示文本可能不能直接对账。
6. 按经销商名称输入片段；后端忽略大小写并做包含匹配。
7. 继续选择客户状态、分配状态、领取状态、跟进状态或人工拨打状态。领取状态综合 assignAction、assignStatus 和 claimTime 判定。
8. 点击「搜索」，记录筛选条件、总数、排序和查询时间。重置会清空全部筛选并恢复创建时间类型，但不会重置字段方案和排序。
9. 点击齿轮打开「客资列表字段设置」，选择可见列、列宽及单列排序。保存后页码回到 1 并重新查询。
10. 字段设置保存在当前浏览器 localStorage；不会按账号同步到其他设备。即使尝试取消全部列，组件也会恢复默认列。
11. 点击某条记录的「查看」。详情地址会携带当前行 ID 以及当前页 dataSource 中全部 ID；上一条/下一条只覆盖当前页，不代表全部筛选结果。
12. 导出前核对当前可见列和排序。导出不带 pageNo/pageSize，会读取所有命中记录；先收窄条件，避免一次处理过多个人信息。
13. 下载后核对 Excel 行数、列头、第一条与最后一条、时间和状态翻译。若筛选无记录，后端返回 0 字节，页面仍可能保存文件并提示成功，必须检查文件是否可打开。

放大查看

进入客户管理的客资列表后，可按关键词、时间、意向、渠道和流转状态组合筛选。

关闭

放大查看

在关键词框输入筛选词后，可配合时间类型与状态条件缩小客资范围。

关闭

放大查看

执行搜索后列表返回命中的演示客资并显示总数，可用于核对筛选口径。

关闭

七、字段与规则说明

1. 默认分页：20 条；页面可选 10、20、50、100，但直接接口的 pageSize 只校验至少为 1，没有最大值。
2. 默认排序：createdTime 倒序，并以 ID 倒序作为同值次排序。未知排序字段会回退创建时间。
3. 时间过滤：只有开始与结束同时存在且都能解析时才生效。
4. 意向品类：逗号分隔多值按 OR 匹配字段中的独立值。
5. 领取状态：CLAIM 动作或在动作空白时存在 claimTime 视为已领取；ASSIGN/TRANSFER 或已分配且无领取时间视为待领取；RELEASE 显示短横线。
6. 清洗状态：lastFollowTime 为空显示未清洗；否则优先显示最新跟进内容，没有内容时显示已清洗。
7. 员工未跟进：根节点下发客资在跟进记录数恰好为 1 时显示“员工未跟进”，不是按 0 条记录判断。
8. 字段方案：保存可见列、宽度和单列排序到本机浏览器；操作列始终追加。
9. 详情 ID 集合：只取当前分页 dataSource，不包含其他页。
10. 导出：读取全部命中实体并批量组装跟进、来源、导购和 Picklist 翻译，没有分页或显式行数上限。

八、风险与限制

服务端没有客资列表查看和导出细分权限，导出仅依赖专区与数据范围；大范围导出可能产生高内存、慢响应并暴露手机号、微信号、地址、意向和备注。“二级渠道”筛选与同名展示列使用不同字段；“员工未跟进”以一条跟进记录为特殊条件；无结果导出会产生 0 字节响应。字段方案和排序仅保存在本机浏览器。

九、常见问题

1. 为什么没有导出按钮？当前角色缺少前端 `export` 按钮键；同时要注意服务端没有对应细分权限守卫。
2. 为什么不选时间会看到全部历史？页面默认 dateRange 为空，后端只有起止时间同时存在才过滤。
3. 为什么多个意向品类结果比预期多？多选条件按任一值命中，不是同时包含。
4. 为什么二级渠道筛选值和表格文字不一致？筛选使用 sourceId，展示列使用 secondChannel。
5. 为什么显示员工未跟进却存在记录？当前口径把根节点下发且跟进计数恰好为 1 的客资显示为员工未跟进。
6. 为什么详情前后切换不到下一页？跳转只携带当前页 ID。
7. 为什么另一台电脑的列和排序不同？字段方案仅保存在浏览器 localStorage。
8. 为什么空结果仍下载文件？后端无记录时返回 0 字节，前端只检查 Blob 类型；请检查文件大小和可打开性。
9. 为什么大范围导出很慢？服务会一次读取和组装全部命中记录，没有最大行数。
10. 为什么同事看到的数量不同？比较企业、角色、可见人员和组织、全部筛选、排序以及关联客户负责人范围。

十、相关指南

转化后的客户档案请阅读《查看和筛选客户》；需要执行具体分配时阅读《分配客资》，需要清洗或跟进核对时阅读《处理客资清洗》。