# 05A-顾客列表页

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 | 修改人/来源 |
| --- | --- | --- | --- | --- |
| 2026-07-20 | v0.1 | 重大需求变更 | 同步结果查看统一收敛至同步日志的批次顾客列表；删除 KASIKA 顾客同步信息弹窗作为结果承载入口。 | AI（按需求修改） |

## 1. 文档定位

本文定义顾客列表页的展示、筛选、导入/导出、新增入口、全量同步检查入口和同步任务弹窗。

顾客页面需求拆分为：

- `05A-顾客列表页.md`：列表展示、导入/导出、新增入口、全量同步检查入口。
- `05B-顾客详情页.md`：顾客基础信息、KASIKA 绑定摘要、最近同步状态、顾客本地编辑/删除。
- `05C-顾客权限页.md`：顾客标签、标签权限模板合成结果、个人权限追加、最终权限。
- `05D-新增顾客.md`：新增 VISTA 顾客时录入基础资料并选择初始标签。

本文不定义 KASIKA -> VISTA 核心同步规则。同步识别、匹配、绑定、创建、字段快照、访问字段回写、权限判定与日志分类按 `04-统一顾客联动同步流程.md` 和 `07-同步日志与追溯.md`。

## 2. 页面目标

- 沿用线上既有 HOME VISTA 顾客列表的信息结构和操作习惯。
- 顾客列表只保留轻量入口和 VISTA 标签显示，不展开 KASIKA 绑定、同步和失败详情。
- 联动可用时，顾客列表页提供唯一手动同步入口：“全量同步检查”按钮。
- 不提供单个同步、复选框同步和前端重试。
- VISTA 顾客文件导入完成后，只展示 VISTA 导入结果；不因导入结果向 KASIKA 创建或更新顾客。

## 3. KASIKA 信息显隐规则

1. 顾客列表页原则上不展示 KASIKA 绑定状态、KASIKA customer_id、同步状态、最近同步结果等 KASIKA 相关列表字段。
2. KASIKA 相关信息集中放在顾客详情页展示，避免对既有顾客列表造成过多干扰。
3. KASIKA 顾客同步所需 4 个 API KEY 不完整时，顾客列表页不显示“全量同步检查”按钮。
4. 4 个 API KEY 已完整配置时，仅 B 端管理员和销售经理可看到“全量同步检查”按钮；是否可点击还需受当前是否已有同步任务执行中和 KASIKA 调用限制控制。销售人员不展示该按钮。
5. 本期不再提供顾客信息同步开关；PID、settingID、绑定通知自動返信ID 或访问密码开关的缺失不作为隐藏“全量同步检查”按钮的条件，但会影响对应能力并在同步日志中记录清晰结果。
6. PID 为空仅影响访问上报，不决定顾客同步按钮禁用。

## 4. 页面内容

### 4.1 展示字段

- 沿用线上既有 HOME VISTA 顾客列表的信息结构和视觉布局。
- 既有列包括：选择框、ID、お名前、累計閲覧ページ数、累計アクセス回数、平均滞在時間、最終アクセス日時、共有有効期限、担当スタッフ、固定图标、更多操作菜单。
- 在既有表格基础上仅新增“标签”显示，用于展示当前顾客拥有的 VISTA 标签。
- “标签”列只负责展示，点击标签不触发筛选、不打开标签编辑；标签筛选在搜索区通过多选 tag 条件完成。
- 标签以 chip 形式展示，单行优先展示前 2 个标签；超过 2 个时折叠为 `+N`，完整标签编辑在顾客详情 `概要` 的 `タグ編集` 或 `権限` tab 中完成。
- 顾客列表不新增 KASIKA customer_id、KASIKA 绑定状态、同步状态、最近同步结果摘要等 KASIKA 专用列。
- 如需查看 KASIKA 绑定、同步、失败原因和建议动作，进入顾客详情页或同步日志查看。

### 4.2 搜索与筛选

- 保留顾客姓名搜索。
- 增加顾客邮箱搜索输入框。
- 增加 VISTA 分享 ID 搜索输入框。VISTA 分享 ID 指分享 URL 中用于识别顾客访问链接的 VISTA 侧 ID，不是 KASIKA customer_id。
- 保留担当スタッフ筛选，控件使用下拉框，不使用自由输入框。
- 支持按 VISTA 标签筛选顾客；标签条件使用紧凑的折叠式多选控件，不在搜索区平铺全部标签。
- 标签筛选默认只显示入口按钮和已选摘要，例如 `タグ`、`タグ 2件` 或已选标签摘要；点击后打开弹出面板，在面板中以 checkbox/tag 形式复选多个标签。
- 标签复选为空时不限制标签；选择多个标签时，返回命中任一所选标签的顾客。
- 搜索区需要提供明确的 `検索` 提交按钮。输入框、下拉框和标签复选可以先在页面本地形成待提交条件，点击 `検索` 后再按条件请求/刷新列表。
- 顾客列表顶部操作布局分为两组：
  - 检索组：顾客姓名、顾客邮箱、VISTA 分享 ID、担当スタッフ、标签筛选和 `検索` 按钮放在同一个检索表单区域。
  - 列表操作组：`インポート`、`エクスポート`、`新規追加`、`全量同步检查` 放在独立操作区，不与筛选输入混排。
- `検索` 是检索组的提交动作；`インポート`、`エクスポート` 为次要列表操作；`新規追加` 为主要列表操作；`全量同步检查` 是 KASIKA 同步操作，应在视觉上与普通导入/导出/新增动作区分。
- 不新增 KASIKA customer_id 搜索条件。
- 不新增 KASIKA 绑定状态、同步状态、最近同步结果等筛选条件。

### 4.3 列表操作

- 保留线上既有的搜索、インポート、エクスポート、新規追加、行固定、更多操作菜单等操作。
- 点击 `新規追加` 进入独立的新建顾客页面，具体基础资料和标签选择规则见 `05D-新增顾客.md`。
- 列表最右侧三个点按钮点击后打开行内菜单弹窗，不直接打开编辑抽屉。
- 三点菜单至少包含：`顧客情報の編集`、`顧客情報のコピー`、`アクセスリンクのコピー`。
- `顧客情報の編集` 进入顾客信息编辑入口或顾客详情编辑路径；`顧客情報のコピー` 将该顾客基础信息复制到剪贴板；`アクセスリンクのコピー` 将该顾客 VISTA 访问链接复制到剪贴板。
- 本页不需要右侧编辑抽屉；三点菜单不提供删除入口。
- 4 个 API KEY 不完整时，不显示“全量同步检查”按钮。
- 4 个 API KEY 完整时，仅 B 端管理员和销售经理可显示“全量同步检查”按钮；若无同步任务并发限制，则可点击触发全量同步检查。销售人员不显示该按钮，也不得通过接口触发同步。
- 不显示单条同步、复选框同步、前端重试入口。
- 已绑定顾客不在列表提供 KASIKA 绑定关系操作、改绑或同步操作；如需删除 VISTA 顾客，按顾客详情页既有删除规则处理。
- 不新增“同步失败导出”和“处理中心”。

## 5. 全量同步检查

### 5.1 入口规则

1. “全量同步检查”是顾客列表页唯一手动同步入口。
2. “全量同步检查”不依赖列表复选框，点击后按 KASIKA 拉取结果执行全量检查。
3. 角色权限固定如下：B 端管理员和销售经理可见、可发起本项目“全量同步检查”；销售人员不显示该按钮，也不得通过直接请求接口创建手动同步任务。服务端必须校验角色，不得只依赖前端显隐。
4. 该按钮必须在 4 个 API KEY 完整时才可显示和执行；4 个 API KEY 任一缺失时不显示。
5. 本期不再提供顾客信息同步开关；定时同步和手动全量同步检查是否执行，由 API 参数完整性、KASIKA API 调用结果、任务并发状态和上述角色权限决定。
6. 点击“全量同步检查”时，服务端先以项目为粒度检查同步任务锁；若系统正在执行自动定时同步或另一人工同步，则弹出提示“正在同步kasika数据，请稍后再尝试”，不创建新的同步任务。
7. 自动定时同步触发时，若系统正在执行手动全量同步检查，则跳过本次定时同步并等待下一次定时触发。

### 5.2 同步任务弹窗

1. 点击“全量同步检查”并确认、且服务端成功取得本项目同步任务锁后，显示同步任务弹窗；后台任务继续执行，不受用户关闭弹窗、离开页面或刷新页面影响。
2. 同步任务弹窗不展示“1/2/3/4”分阶段流程说明、百分比进度条、预计完成时间、处理中数量或进度统计。KASIKA 先批量返回顾客数据，VISTA 再完成批量绑定与 CSV 批量回写，执行过程没有可信的逐条完成口径。
3. 执行中仅展示 VISTA 经典“转大象”加载动画、标题“正在同步 KASIKA 数据”和说明“正在获取顾客信息、完成 VISTA 比对与批量回写，请勿重复发起同步。”；不展示取消、关闭、停止或再次同步按钮。
4. 同步完成后，转大象动画消失，弹窗展示实际结果摘要和唯一“确认”按钮。摘要先展示“本次已处理 N 名 KASIKA 顾客”，再以三个结果数字展示：
   - 新增绑定：本次创建 VISTA 顾客或将未绑定 VISTA 顾客首次绑定至 KASIKA 的数量；
   - 更新完成：既有绑定顾客完成结构化字段、状态标签/权限校准或 KASIKA CSV 回写的数量；
   - 失败／待处理：因数据冲突、业务待处理或系统失败而未完成本次预期处理的数量。
5. 三个数字只使用后台任务完成后可落日志的实际结果，不在执行中预估或滚动展示；“本次已处理 N 名”与三个结果的统计口径必须可在同步日志追溯。
6. 用户点击确认后关闭弹窗并刷新顾客列表状态；不额外使用 Toast 替代同步结果结论。

## 6. VISTA 顾客文件导入结果

### 6.1 页面内容

- 展示 VISTA 顾客文件导入结果：
  - 新增数量；
  - 更新数量；
  - 失败数量；
  - 标签写入结果；
  - 失败明细。
- 导入完成后，不因本次 VISTA 导入结果向 KASIKA 创建或更新顾客；若后续 KASIKA 同步拉取到相同顾客，系统再按 KASIKA -> VISTA 规则进行匹配和绑定。
- 导入结果界面不展示 KASIKA 同步明细，不提供“KASIKA 同步”按钮。
- KASIKA -> VISTA 批量同步的进度、结果和失败原因由同步任务弹窗、批次顾客列表或同步日志承接，不新增顾客列表常驻同步状态列。

### 6.2 交互约束

1. VISTA 导入结果弹窗/结果面板只负责 VISTA 导入闭环，不承载 KASIKA 核心同步规则。
2. 导入完成不触发向 KASIKA 创建或更新顾客的同步任务。
3. 如果管理员或销售经理需要检查 KASIKA 侧是否已有对应顾客，可在 4 个 API KEY 完整时，通过顾客列表页“全量同步检查”触发 KASIKA -> VISTA 检查。
4. 本期不新增长期导入历史结果入口。

## 7. 验收标准

1. 顾客列表沿用线上既有 HOME VISTA 列表信息结构和操作布局。
2. 顾客列表仅在既有表格基础上新增“标签”显示，不新增 KASIKA customer_id、绑定状态、同步状态、最近同步结果摘要等 KASIKA 专用列。
3. 标签列以 chip 展示当前顾客标签，超过 2 个时展示前 2 个和 `+N`；列表标签 chip 不承担点击筛选或列表内编辑。
4. 顾客列表搜索条件包含顾客姓名、顾客邮箱、VISTA 分享 ID、担当スタッフ、VISTA 标签。
5. 担当スタッフ使用下拉框；标签筛选使用折叠式多选控件，不平铺占用搜索区空间，也不使用单选下拉。
6. 点击 `検索` 后提交当前搜索条件并刷新列表；不依赖输入过程中的即时响应作为唯一检索方式。
7. `検索`、`インポート`、`エクスポート`、`新規追加`、`全量同步检查` 的布局分组清晰：检索按钮归属检索表单，导入/导出/新增/同步归属列表操作区。
8. 顾客列表不新增 KASIKA customer_id、KASIKA 绑定状态或同步状态筛选。
9. 保留インポート、エクスポート、新規追加等既有操作。
10. 三点按钮打开行内菜单弹窗，包含顾客信息编辑、顾客信息复制、访问链接复制；不直接打开右侧编辑抽屉，不提供删除入口。
11. 4 个 API KEY 不完整时，不显示“全量同步检查”按钮。
12. 本期不展示或使用顾客信息同步开关；同步按钮状态仅受管理员/销售经理角色权限、4 个 API KEY、服务端任务锁和 KASIKA 调用限制影响。销售人员不展示该按钮，也不得调用对应接口。
13. 管理员或销售经理在 4 个 API KEY 完整且服务端无并发任务拦截时可点击“全量同步检查”；点击后创建一次全量同步检查任务，具体处理范围和数据规则按 `04-统一顾客联动同步流程.md`。
14. 列表无单条同步、复选框同步、重试动作。
15. 联动异常或历史绑定信息进入顾客详情页展示，列表不展开 KASIKA 同步摘要。
16. 手动全量同步检查执行中只展示转大象动画和不可量化的同步说明，不展示百分比、逐条处理进度统计或固定 1/2/3/4 阶段说明。
17. 同步开始后不提供停止、取消、关闭或重复发起入口；关闭页面不影响后台任务继续执行。
18. 正常完成后，弹窗显示实际处理总数，以及新增绑定、更新完成、失败／待处理三个结果数字；点击确认后关闭弹窗并刷新列表，不通过 Toast 作为主要结果反馈。
19. 导入完成后可看到 VISTA 导入新增、更新、失败和标签写入结果。
20. 导入完成后不向 KASIKA 创建或更新顾客；KASIKA API 配置状态不改变导入本身结果。
21. 导入界面没有 KASIKA 手动同步按钮，也不展示 KASIKA 同步明细。

## 8. 用户用例

### 用例 1：联动未配置时隐藏同步入口
- 前置：项目未配置 4 个 KASIKA API KEY，且不存在历史 KASIKA 绑定关系。
- 操作：管理员、销售经理或销售人员进入顾客列表页。
- 预期：
  - 顾客列表不展示“全量同步检查”按钮。
  - 顾客列表不展示 KASIKA customer_id、绑定状态、同步状态、最近同步结果等 KASIKA 专用列。
  - 既有顾客列表、导入、导出、新增、搜索等 VISTA 功能保持不变。

### 用例 2：联动已配置且可用时查看列表
- 前置：项目 4 个 API KEY 完整。
- 操作：用户进入顾客列表页。
- 预期：
  - 顾客列表沿用线上既有列结构，仅新增“标签”显示。
  - 标签列仅展示 VISTA 标签 chip，超过 2 个时折叠为 `+N`；标签不可在列表页点击筛选或编辑。
  - 顾客列表不展示 KASIKA customer_id、绑定状态、同步状态、最近同步结果摘要等 KASIKA 专用列。
  - 如需查看绑定或失败详情，用户进入顾客详情或同步日志。

### 用例 2-1：按搜索条件提交检索顾客
- 前置：顾客列表中存在多个顾客，且顾客拥有不同邮箱、VISTA 分享 ID、担当スタッフ和 VISTA 标签。
- 操作：用户输入顾客姓名、顾客邮箱或 VISTA 分享 ID，选择担当スタッフ，并在标签筛选中复选一个或多个 VISTA 标签后点击 `検索`。
- 预期：
  - 系统按提交时的条件刷新顾客列表。
  - 顾客姓名、邮箱、VISTA 分享 ID 为文本输入条件。
  - 担当スタッフ为下拉选择条件。
  - 标签筛选默认以紧凑入口展示，点击后打开多选面板；多选时返回命中任一所选标签的顾客。
  - 搜索条件不包含 KASIKA customer_id、KASIKA 绑定状态或 KASIKA 同步状态。

### 用例 2-2：通过三点菜单执行行操作
- 前置：用户位于顾客列表页。
- 操作：用户点击某一行最右侧三个点按钮。
- 预期：
  - 页面在该行附近展示菜单弹窗。
  - 菜单包含 `顧客情報の編集`、`顧客情報のコピー`、`アクセスリンクのコピー`。
  - 点击 `顧客情報のコピー` 后复制该顾客基础信息。
  - 点击 `アクセスリンクのコピー` 后复制该顾客 VISTA 访问链接。
  - 三点按钮不直接打开右侧编辑抽屉，菜单中不提供删除操作。

### 用例 3：顾客列表页触发全量同步检查
- 前置：项目 4 个 API KEY 完整，且当前没有其他同步任务执行中。
- 操作：管理员或销售经理在顾客列表页点击“全量同步检查”，并在确认弹窗中确认。
- 预期：
  - 系统创建一次全量同步检查任务，处理范围以 KASIKA 拉取结果为准，不依赖当前列表筛选或勾选。
  - 页面展示仅含转大象动画和同步说明的同步任务弹窗，不展示进度百分比、处理中数量或停止按钮。
  - 同步完成后，转大象动画消失，展示实际处理总数、新增绑定数、更新完成数、失败／待处理数和确认按钮。
  - 用户确认后关闭弹窗并刷新顾客列表。

### 用例 4：已有同步任务执行中时拦截全量同步检查
- 前置：项目 4 个 API KEY 完整，但系统已有自动定时同步或手动全量同步检查正在执行。
- 操作：用户进入顾客列表页。
- 预期：
  - 顾客列表可显示“全量同步检查”按钮，但点击时提示“正在同步kasika数据，请稍后再尝试”，不创建新的同步任务。
  - 顾客列表仍可正常搜索、导入、导出、新增、进入详情。
  - 定时同步遇到手动任务执行中时跳过本次触发，不弹出前端提示。

### 用例 5：VISTA 顾客文件导入结果
- 前置：用户在 VISTA 执行顾客文件导入。
- 操作：导入完成后查看导入结果弹窗或结果面板。
- 预期：
  - 页面展示 VISTA 导入新增数量、更新数量、失败数量、标签写入结果和失败明细。
  - 导入完成不触发向 KASIKA 创建或更新顾客。
  - 导入结果界面不展示 KASIKA 同步明细，不提供“KASIKA 同步”按钮。
- 如管理员或销售经理需要检查 KASIKA 侧是否已有对应顾客，只能在同步条件满足时从顾客列表页触发“全量同步检查”。

### 用例 6：手动同步遇到自动同步执行中
- 前置：系统正在执行自动定时同步。
- 操作：管理员或销售经理在顾客列表页点击“全量同步检查”。
- 预期：页面弹出提示“正在同步kasika数据，请稍后再尝试”，不创建新的同步任务。

### 用例 7：自动同步遇到手动同步执行中
- 前置：管理员或销售经理已在顾客列表页启动手动全量同步检查，任务正在执行。

- 操作：系统到达自动定时同步触发时间。
- 预期：本次定时同步不执行，等待下一次触发；不弹出前端提示。

## 9. 修订记录

| 日期 | 修订内容 |
| --- | --- |
| 2026-07-13 | 因 KASIKA 采用“批量获取 → VISTA 比对/绑定 → CSV 批量回写”的不可流式任务，取消手动停止、取消和伪进度；执行中仅展示 VISTA 转大象动画及防重复发起说明，完成后展示实际处理总数及新增绑定、更新完成、失败／待处理三个结果，并仅保留确认按钮。同步入口调整为管理员和销售经理可见、可发起，销售人员不可见；同项目采用服务端任务锁，冲突提示统一为“正在同步kasika数据，请稍后再尝试”。 |