查看和筛选客户

一、功能介绍

客户列表以 `crm.account` 客户档案为主体，结合最新客资、跟进、定金、合同、标签、来源、负责人和组织链生成 87 个展示字段。页面提供分页、多条件筛选、列设置、详情、Excel 导出和删除入口；它不是未转化客资列表，也不是企微外部联系人原始通讯录。

页面默认只查询最近一个月：起点为浏览器当前日期减一个月的当天 00:00，终点为当天 23:59:59。时间判断优先使用客户注册时间，注册时间为空时才回退创建时间。若要核对更早客户，必须主动修改或清空注册时间。

二、功能亮点

1. 分页按注册时间、创建时间和客户 ID 倒序，默认每页 50 条。
2. 实际生效的关键词匹配手机号、客户名称、旧地址字段和组织编码。
3. 支持注册时间、组织层级、上级/所属组织、导购、客户状态与阶段、留资方式、性别、系统标签、企微添加状态与时间、跟进状态、到店状态、省市和首次合同/首次跟进时间组合筛选。
4. 列表聚合客户基础、来源归属、销售过程、关键时间、金额、协作、行为、企微及流失字段。
5. 列设置决定当前浏览器显示和导出的字段顺序。
6. 详情入口跳转到 `/customer/detail?id={客户ID}`。
7. 导出复用已生效筛选并去掉分页参数。

三、使用场景

适合销售、客服和运营在自己的组织数据范围内查找已形成客户档案的对象，核对负责人、客户阶段、企微承接和经营节点，或在获得明确审批后导出限定字段。客户身份、获客渠道和页面上的“数据范围”单选目前不参与请求，因此不能用这些控件完成审计级分群。

四、使用权限

1. 进入页面需要「客户列表」菜单可见且客户销售专区可用。
2. 前端用 `/customer/list` 下的 `import`、`export`、`del` 按钮键控制导入、导出和删除入口显示。
3. 列表与导出共同使用 `OrgScopeUtils.getVisibleUserIds()`：非管理员只查询 ownerId 位于可见人员集合的客户；集合为空时返回空数据，管理员不加该人员条件。
4. 导出与删除端点已接入服务端 export/del 细分权限守卫，流失、转移端点各有独立守卫；前端按钮隐藏不能代替服务端授权。
5. 导出端点在 `CUSTOMER_SALES` 专区之外还校验 `/customer/list` 菜单的 `export` 细分权限。
6. 删除端点校验 `del` 细分权限，实现为软删除（仅标记 is_deleted）；恢复端点同样要求 `del` 权限。
7. 列表仍明文展示手机号等敏感字段；导出默认 3-4-4 掩码、明文开关仅管理员生效、超过 20000 行截断并提示，但没有字段级明文查看审批记录；只向确有业务必要的最小人员范围开放。
8. 客户实体声明企业租户过滤器；正式验收仍须用两个企业账号验证运行时过滤确实启用，不能只以实体注解替代跨企业测试。

五、前置条件

1. 确认当前登录企业、站点和角色正确，并记录当前角色的数据范围。
2. 明确本次查找的是客户档案而非待清洗、待分配客资；未转化记录应到《管理客资列表》查询。
3. 首次进入先注意默认最近一个月范围；需要全历史时清空时间，需要固定周期时设置精确起止。
4. 确认 Picklist、组织树、来源树、员工、地域和标签数据可以加载；选项失败会影响筛选但不一定阻止列表加载。
5. 导出前取得用途、字段、人员范围、保存位置和保留期限审批，只勾选业务必需列；手机号、会员电话、地址和经营信息没有自动脱敏。
6. 删除前完成身份复核、关联客资/合同/跟进/会员引用检查和审计留痕；删除为软删除（仅标记 is_deleted），后端提供恢复能力，但页面没有回收站。
7. 删除操作只允许从系统页面的确认框发起，不打开或转发 `/customer/delete/{id}` 链接；该端点现为 POST 软删除，后端另有恢复端点。
8. 不要依赖“客户身份”“获客渠道”或“数据范围”控件缩小结果，这三项当前不会传给列表接口。

六、操作步骤

1. 进入「客户管理 → 客户列表」，先记录默认注册时间为最近一个月。
2. 若查询手机号、客户名称、旧地址字段或组织编码，在关键词框输入完整或连续片段后按 Enter 或点击「搜索」。占位文字虽写“备注”，后端关键词实际不匹配备注；按备注查找应改用其他已验证入口。
3. 点击「展开」，按需要设置组织级别、上级组织、所属组织或所属导购。上级和所属组织会展开到有效后代；同时设置时取两者范围交集。
4. 选择客户状态后再打开客户阶段；状态变化会清空阶段，避免保留不相容选项。
5. 留资方式支持多选父子来源，后端按每个客户最新一条客资的 sourceId 判断；系统标签同样按最新客资的 orgTag 判断。
6. 设置“是否添加企微”或添加企微时间时，前者按客户档案的企微状态判断，后者按档案中的企微通过时间判断。
7. 需要按首次业务动作筛选时，在组合控件选择首次合同或首次跟进，再选日期。只选类型而不选日期不会产生过滤条件。
8. 不要把“获客渠道”“客户身份”和“数据范围”单选当成有效条件；当前构建请求时没有读取这三个值。
9. 点击「搜索」并记录筛选条件、页面总数和生成时间。点击「重置」会恢复最近一个月，而不是清空所有条件后查询全历史。
10. 点击表格右上角齿轮打开「列表显示字段设置」，只保留本次工作必需列并保存。设置在当前浏览器 localStorage，不会同步到其他设备。
11. 点击「查看」进入客户详情，核对姓名、手机号、负责人、最新客资和关键经营字段后返回列表；避免在共享屏幕展示完整敏感字段。
12. 导出前再次检查筛选结果和可见列，移除手机号、会员电话、地址、微信号、金额等非必要字段。点击「导出数据」后核对文件名、行数、列头和抽样数据；若首行出现【导出提示】，说明命中 20000 行上限被截断。
13. 导出按 20000 行上限分批查询；大范围条件可能命中截断，应先缩小条件分批导出并错峰执行。
14. 确需删除时先进入详情完成关联检查，只在当前页面点击「删除」并二次确认。删除为 POST 软删除，不复制、转发或预打开删除地址。
15. 成功后重新查询客户 ID、手机号和关联入口并保存审计证据；删除为软删除，后端提供恢复能力，但页面没有回收站入口。

放大查看

移动端客户列表支持按客户阶段、未跟天数、渠道、标签和意向筛选，并从客户卡片进入跟进等操作。

关闭

放大查看

从客户管理进入客户列表，先核对面包屑、筛选区与当前站点上下文。

关闭

放大查看

输入关键词执行搜索后核对结果列表与总数，当前演示环境返回空结果属正常。

关闭

七、字段与规则说明

1. 默认注册时间：最近一个月；注册时间非空时按 registerTime，只有为空才按 createdTime。
2. 关键词：实际匹配 mobile、name、旧 address 和组织编码，不匹配备注。
3. 客户状态与阶段：来自 account Picklist；阶段选项依赖当前状态。
4. 组织与导购：展示和筛选优先使用客户 ownerId，部分关联字段在 ownerId 为空时回退最新客资负责人。
5. 留资方式：按最新客资来源过滤；选择父来源时服务展开所有有效子来源。
6. 系统标签：按最新客资 orgTag 的逗号分隔值匹配，不汇总全部历史客资标签。
7. 客户身份、获客渠道、数据范围：当前只有控件状态，未写入列表或导出参数，筛选不生效。
8. 手机号等敏感字段：列表仍明文展示，导出默认 3-4-4 掩码、明文开关仅管理员生效、超过 20000 行截断并提示；没有自动的明文审批流程。
9. 列设置：只保存可见列键；表格中的操作列始终保留，不进入导出字段。
10. 导出：移除 pageNo/pageSize 后查询全部命中客户，列由当前可见字段键决定。
11. 删除：删除为软删除（仅标记 is_deleted），后端提供恢复能力；页面没有回收站，用户无法自助恢复，删除前必须完成关联检查、数据范围核对与审计留痕。

八、风险与限制

Excel 导入客户选择文件后只显示“待后端导入接口接入后自动解析”提示，尚未接入导入接口。客户身份、获客渠道、数据范围三个筛选不生效；备注不在关键词范围。列设置只存在浏览器本地。导出默认对手机号 3-4-4 掩码，勾选“明文导出”也仅管理员生效；导出超过 20000 行会截断并在文件首行提示。删除为软删除（仅标记 is_deleted），后端提供恢复能力，但页面没有回收站，用户无法自助恢复已删除客户。

九、常见问题

1. 为什么刚进入只看到近期客户？页面默认注册时间为最近一个月；清空或修改时间后重新搜索。
2. 为什么按备注搜不到？占位文案包含备注，但后端关键词只匹配手机号、名称、旧地址和组织编码。
3. 为什么选择客户身份、获客渠道或数据范围后数量不变？这三个控件当前没有进入查询参数。
4. 为什么更改客户状态后阶段被清空？阶段依赖状态，页面主动重置旧阶段。
5. 为什么重置后仍不是全历史？重置会恢复最近一个月默认时间。
6. 为什么导入按钮只显示提示？Excel 导入客户当前尚未实现。
7. 为什么没有导出或删除按钮？当前角色缺少前端按钮键；服务端也会按 export/del 细分权限拒绝直调。
8. 导出的手机号会自动脱敏吗？导出默认 3-4-4 掩码，勾选“明文导出”也仅管理员生效；列表仍明文展示，应只选必要列并加密保管。
9. 为什么导出有行数上限？导出按 20000 行上限分批查询，超出部分截断并在导出文件首行提示。
10. 为什么列设置没有同步到另一台电脑？设置保存在当前浏览器 localStorage。
11. 可以直接打开删除链接吗？禁止；删除必须从页面确认流程发起，不要复制或转发删除地址。
12. 删除后能恢复吗？删除为软删除（仅标记 is_deleted），后端提供恢复能力；但页面没有回收站，用户无法自助恢复，需由技术人员调用恢复端点。
13. 为什么和同事看到的数量不同？比较企业、角色、可见人员、默认时间和全部已生效筛选，不要把未接入请求的三个控件算入口径。

十、相关指南

未转化客资请阅读《管理客资列表》；需要用 MQL/SQL 辅助分层时阅读《配置 MQL 与 SQL 销售资格判定》；客户类型与资料字段配置分别参考《配置客户类型》《配置客户资料表单》。涉及批量导出或删除时，同时核对企业的数据分级、审批、留存和审计制度。