# 07-同步日志与追溯

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 | 修改人/来源 |
| --- | --- | --- | --- | --- |
| 2026-07-20 | v0.2 | 重大需求变更 | 前台同步日志由“同步批次列表 → 批次顾客列表 → 顾客同步详情弹窗”收敛为两层列表；删除顾客同步详情弹窗，顾客行仅展示姓名、邮箱、双方 ID 与合并后的同步结果（含简短变化摘要）。 | AI（按需求修改） |
| 2026-07-16 | v0.1 | 重大需求变更 | 同步日志查询条件收敛为开始时间、结束时间；删除顾客名、顾客邮箱、KASIKA ID、VISTA ID 及其他非时间条件的查询与命中高亮要求。 | AI（按需求修改） |

## 1. 模块定位

本模块专门定义 KASIKA 二期顾客同步数据相关的同步、字段快照、`customer_status` 标签配置、权限判定、删除/错误绑定处置和失败状态的日志记录与追溯需求。

### 产品目标

- 确保所有同步数据的增删改可追溯。
- 让同步失败、权限变化、`customer_status` 标签配置变化、删除/错误绑定处置结果可定位、可解释；本期不提供前端重试入口，但日志需要明确失败阶段、下一步动作和后续自动检查口径。
- 让后台错误绑定处置后的历史 KASIKA 字段保留、禁止再绑定标记和后续被阻断的自动绑定尝试可追溯。
- 支持 B 端管理员从 KASIKA 联动管理页按开始时间和结束时间查询日志。
- 为顾客页面、`customer_status` 标签配置、权限模板和顾客同步任务提供统一日志能力。
- 覆盖 `08-KASIKA入口页与VISTA首次访问开户.md` 产生的 KASIKA入口页访问、KASIKA 顾客校验、邮箱校验、密码设置、首次开户和 KASIKA入口页绑定日志。

### 本模块不包含

- 不定义顾客列表和顾客详情的页面操作布局。
- 不定义三方字段映射规则；本期三方映射页注释保留。
- 不定义标签权限模板的授权计算规则。
- 不记录 KASIKA 联动配置表单的保存成功、保存失败、新增、修改、清空。

以上内容分别属于 `05A-顾客列表页.md`、`05B-顾客详情页.md`、`05C-顾客权限页.md`、`bak-04-第三方字段映射与权限判定.md` 和 `02-顾客标签管理.md`。

## 2. 日志记录范围

| 项目 | 内容 |
| --- | --- |
| 用例名称 | 记录 KASIKA 联动相关操作日志 |
| 触发来源 | 系统、销售人员、销售经理、B 端管理员 |
| 页面范围 | KASIKA 联动管理页 - 同步日志 |

### 需求细节

1. 所有同步数据的增删改都必须记录日志。
2. 日志类型包括：
   - 首次绑定时 `VISTAURL` 和适用时的 `VISTAPWD` 回写。
   - KASIKA -> VISTA 同步。
   - 后台错误绑定处置。
   - VISTA 顾客创建、更新、删除、错误绑定处置。
   - KASIKA 侧疑似删除或绑定异常标记。
   - 第三方字段快照保存和变化。
   - `customer_status` 标签配置判定。
   - 权限计算。
   - 历史字段重新判定。
   - 标签权限模板变更后的权限计算。
   - 定时同步批次。
   - KASIKA入口页访问。
   - 首次访问邮箱校验和密码设置。
   - 首次绑定自动回复邮件发送。
   - 失败状态与后续检查。
3. KASIKA 联动配置表单的保存成功、保存失败、新增、修改、清空不写入同步日志；配置页只通过页面 Toast 反馈保存结果。
4. 本期不单独设计同步日志保留期限、归档策略或日志清理规则。
5. 同步日志跟随项目数据生命周期保留；项目有效期内，删除类、错误绑定处置类、权限变化类日志不可被单独清除。
6. 项目到期清除数据时，日志数据随项目数据统一处理。
7. 日志需要区分人工操作和系统任务。
8. 日志不得记录 VISTA 访问密码明文、API KEY 明文、Secret Key 明文等敏感信息；涉及访问密码同步时，只记录是否同步成功、同步时间、目标顾客和失败原因。

### 验证标准

- 同步、`customer_status` 标签配置、权限判定、删除/错误绑定处置均有日志。
- KASIKA 联动配置表单的保存成功、保存失败、新增、修改、清空不写入同步日志。
- 人工操作和系统任务可以区分。
- 项目有效期内，删除类、错误绑定处置类和权限变化类日志不可被单独清除。
- 日志明细不展示 VISTA 访问密码明文、API KEY 明文和 Secret Key 明文。

## 3. 日志字段

| 项目 | 内容 |
| --- | --- |
| 用例名称 | 查看日志明细 |
| 操作者 | B 端管理员 |
| 页面范围 | KASIKA 联动管理页 - 同步日志 |

### 需求细节

1. 日志字段至少包括：
   - 项目。
   - 日志类型。
   - 触发方式。
   - 操作人或系统任务。
   - 操作时间。
   - VISTA 顾客 ID。
   - KASIKA customer_id。
   - 邮箱。
   - 绑定关系变化。
   - 操作结果。
   - 结果分类。
   - 处理阶段。
   - 错误编码。
   - 页面摘要。
   - 失败原因。
   - 下一步动作。
   - 后续处理状态。
   - 同步批次 ID。
   - 导入批次 ID。
   - KASIKA process_id。
   - KASIKA 处理状态。
   - 影响顾客数量。
   - 自动绑定后的 VISTA 顾客 ID 与 KASIKA customer_id。
   - 后台错误绑定处置或 VISTA 删除顾客时未清空 KASIKA 侧 HOMEVISTA 访问字段的处理结果。
   - VISTA 删除已绑定顾客时有效 KASIKA 绑定关系清理结果、绑定失效状态和历史绑定保留结果。
   - 后台错误绑定处置时绑定关系变化和权限重算结果。
   - 后台错误绑定处置时保留的历史 KASIKA `customer_id`、邮箱、`customer_status` 摘要。
   - 后台错误绑定处置后的禁止 KASIKA 再绑定标记。
   - 后续同步或 KASIKA入口页因禁止再绑定标记而跳过或阻断绑定的处理结果。
   - 首次绑定时 KASIKA 侧 HOMEVISTA 访问字段写入结果。
   - 首次绑定自动回复邮件发送结果、自動返信ID 和失败摘要。
   - 字段快照变化摘要。
   - `customer_status` 标签配置结果摘要。
   - `customer_status` 状态权限自动更新开关状态。
   - `customer_status` 状态变化前后的字段值。
   - 状态标签校准结果，包括当前状态同名标签补回、新标签添加、旧标签删除、无同名标签跳过和部分成功结果。
   - 权限变化摘要。
   - API 调用受限或并发受理限制原因。
   - KASIKA入口页访问来源。
   - 邮箱校验结果。
   - 密码设置结果，不记录密码明文。
   - 首次访问开户状态。
   - 批次实际拉取并参与处理的 KASIKA 顾客数。
   - 本次新增绑定数、更新完成数、失败／待处理数；三项的定义必须与同步完成弹窗一致。
   - 同项目同步任务锁冲突记录，包括冲突时已有任务的触发方式和触发时间；不记录敏感参数。
2. `customer_status` 标签配置和权限判定日志需要能追溯到使用的字段快照、字段值、命中的同名标签、是否发生同步校准，以及校准前后的顾客标签结果摘要。
3. 字段快照本体不保存在日志中；日志只记录字段快照保存、更新、无变化、失败等处理过程，以及变化字段、变化前后摘要、同步批次和处理结果。
4. 删除、自动绑定和后台错误绑定处置日志需要记录操作前后的绑定关系；VISTA 删除已绑定顾客时，需要记录有效 KASIKA 绑定关系清理结果、绑定失效状态、历史 KASIKA 字段保留结果，以及本期未清空 KASIKA 侧已保存访问链接和访问密码的处理结果。后台错误绑定处置日志还需要记录历史 KASIKA `customer_id`、邮箱、`customer_status` 的保留结果，以及禁止再绑定标记是否写入成功。
5. 批量任务日志需要支持查看单个顾客明细。
6. 顾客级前台同步结果统一为：同步更新成功、无变化未更新、同步更新失败。
7. 后台日志可按研发实现记录内部处理阶段、错误编码、原始失败原因和后续处理状态；产品需求不固定同步算法、处理顺序或阶段拆分。
8. 错误编码、页面摘要和下一步动作按“同步失败提示与错误信息汇总”统一生成；`04-统一顾客联动同步流程.md` 负责定义触发来源、业务规则和前台结果口径，不定义具体同步实现方案。
9. 日志采用两层展示结构（原型和交互实现）：
   - 第一层为“同步批次”层，一条记录对应一次同步批次（单条同步也同样用一条批次记录表示）。
   - 第二层为“当前批次顾客列表”独立页面，展示该批次内参与同步的顾客名单、同步结果和结果说明；该层不展示完整字段快照、内部处理阶段，且不提供顾客同步详情弹窗。
10. 列表层的对象字段展示：
    - 单顾客批次：展示该顾客名称（必填项）。
    - 多顾客批次：展示“共 N 名顧客”。
11. 同步批次列表中，无论单顾客或多顾客批次，点击“查看结果”均进入“当前批次顾客列表”独立页面。
12. 批次顾客列表固定展示三类信息：
    - 顾客：姓名、邮箱。
    - 关联 ID：KASIKA customer_id、VISTA 顾客 ID。
    - 同步结果：同步更新成功、无变化未更新或同步更新失败，加一条面向管理员的页面摘要；同步成功且存在变化时，摘要可补充最多 3 个变化字段名。无变化时明确展示“本次无字段变更”。
13. 批次顾客列表不提供“顾客详情”按钮、顾客同步详情页或顾客同步详情弹窗。错误编码、失败阶段、KASIKA process_id、KASIKA 处理状态、脱敏后的请求/响应摘要、完整 `customer_data` 快照、字段变更前后值和后续处理范围均作为后台容错/追溯字段，不在 B 端同步日志展示。
14. KASIKA `customer_data` 完整快照只作为服务端容错与受控排查数据保存，不提供 B 端列表、详情页、下载或接口读取入口；快照保存失败仍须记录失败阶段和原因，但不改变 B 端页面展示范围。
15. 顾客级同步结果不展示研发内部阶段或中间态；批次执行中仅记录“同步中”，不向前台返回伪进度、处理中数量或预计完成时间。任务完成后，顾客结果归入同步更新成功、无变化未更新或同步更新失败，批次层再按新增绑定、更新完成、失败／待处理汇总。
16. 批量同步不支持手动停止或取消。批量获取、VISTA 本地比对/绑定和 CSV 批量回写必须作为一个完成后才可结算的后台任务；任务锁冲突、系统异常失败和部分业务待处理分别记录原因及可追溯批次。

### 验证标准

- 日志可以定位到项目、顾客、KASIKA customer_id、邮箱和同步批次。
- 权限变化可以看到变化摘要。
- 删除和错误绑定处置可以看到操作前后的绑定关系；VISTA 删除已绑定顾客时可以看到有效绑定关系清理和绑定失效状态。
- 错误绑定处置可以看到历史 KASIKA 字段保留结果和禁止再绑定标记；后续被阻断的自动绑定尝试可以追溯到该标记。
- 批量任务和单顾客任务均可进入独立顾客列表页，查看顾客姓名、邮箱、双方 ID 和合并后的同步结果；页面不提供顾客同步详情弹窗。
- KASIKA 返回 process_id 或处理状态时，可以在日志中追溯。
- 前台顾客级同步结果只展示同步更新成功、无变化未更新、同步更新失败；后台日志可继续区分业务待处理、部分失败、系统异常失败和任务锁冲突等原因分类。
- 日志明细能保存统一错误编码、页面摘要、下一步动作和字段变更，供同步任务弹窗、批次顾客列表和顾客详情 KASIKA 联动模块复用；KASIKA `customer_data` 快照仅服务端容错保存，不向 B 端复用或展示。

## 4. 日志查询与筛选

| 项目 | 内容 |
| --- | --- |
| 用例名称 | 查询同步和权限日志 |
| 操作者 | B 端管理员 |
| 页面范围 | KASIKA 联动管理页 - 同步日志 |

### 需求细节

1. 同步日志仅支持以下查询条件：
   - 开始时间。
   - 结束时间。
2. 同步日志入口仅在 KASIKA 联动管理页展示给 B 端管理员。
3. B 端管理员进入同步日志后，仅可按开始时间和结束时间查询日志；页面不得提供顾客名、顾客邮箱、KASIKA ID、VISTA ID 或其他非时间查询条件。
4. 日志列表展示批次摘要；无论批量或单顾客批次，均进入独立顾客列表页展示顾客名单和合并后的同步结果；完整追溯字段在后台日志留存。
5. 本期不提供同步日志导出功能。
   - 日志列表仅按所选时间范围返回批次；进入详情后不因查询条件高亮或隐去顾客明细行。

### 用例：按时间范围查询同步日志

- 前置：B 端管理员已进入 KASIKA 联动管理页的“同步日志”页面。
- 操作：填写开始时间和结束时间后点击“查询”。
- 预期：
  - 系统仅返回执行时间落在该时间范围内的同步日志批次。
  - 页面只展示开始时间和结束时间两个查询输入项；不展示顾客名、顾客邮箱、KASIKA ID、VISTA ID、项目、日志类型、操作结果、操作人或系统任务等查询项。
  - 点击“重置”后清空开始时间和结束时间，并恢复查看全部日志。

### 验证标准

- 仅可以按开始时间和结束时间筛选日志。
- 从 KASIKA 联动管理页进入日志时，B 端管理员只能通过时间范围查询对应日志批次。
- 页面不展示顾客名、顾客邮箱、KASIKA ID、VISTA ID 或其他非时间查询条件，也不按顾客查询命中结果高亮明细行。
- 顾客详情和批量任务结果不提供完整同步日志入口。
- 页面不提供同步日志导出入口。

## 5. 失败处理与批次追溯

| 项目 | 内容 |
| --- | --- |
| 用例名称 | 查看失败原因和后续处理 |
| 操作者 | B 端管理员 |
| 页面范围 | KASIKA 联动管理页 - 同步日志、同步任务弹窗、批次顾客列表、顾客详情 KASIKA 联动模块摘要 |

### 需求细节

1. 本期不提供前端手动重试入口，失败日志只展示失败原因、失败阶段、下一步动作和后续系统自动检查口径。
2. 需要标记失败阶段的类型包括：
   - 首次绑定时 `VISTAURL` 或适用时的 `VISTAPWD` 回写失败。
   - KASIKA -> VISTA 拉取或写入 VISTA 失败。
   - KASIKA 身份信息取得或确认失败。
   - 字段快照保存失败。
   - 权限计算失败。
   - 标签权限模板变更后的权限计算失败。
3. 删除类失败只记录失败结果和失败原因，不提供重试入口。
4. 后续系统自动流程再次处理同一对象时，需要生成新的日志，并能从顾客和批次维度追溯到此前失败记录。
5. 批量同步允许部分成功、部分失败。
6. 成功项立即生效并记录成功日志；失败项记录失败原因、失败顾客明细和后续处理状态。
7. 批量同步不因部分顾客失败而回滚同批次已成功顾客。
8. 本期不支持从页面单独重试失败项；后续系统自动流程重新处理时，不应重复创建或重复绑定已成功阶段。
9. 批量任务完成后需要记录并可追溯：
   - 实际拉取并参与处理的 KASIKA 顾客总数。
   - 新增绑定数。
   - 更新完成数。
   - 失败／待处理数。
   - 成功、无变化、失败、跳过和 KASIKA 已受理但未完成等后台结果分类。
   - KASIKA process_id、CSV 回写结果和必要的失败原因。
   - 如手动触发被任务锁拒绝，记录冲突原因和当时占用的任务标识；不创建新的同步批次。
10. 批量任务完成后，日志需要能查看每个顾客的处理结果。
11. 批量任务被 KASIKA 受理但尚未完成时，任务层状态可显示为“等待 KASIKA 处理”；顾客级最终结果需待本次比对结果明确后再归入三种前台结果。
12. 业务待处理项在前台顾客级结果中归入“同步更新失败”；后台日志仍需保留匹配冲突、绑定冲突等原因，便于管理员修正源数据、走后台错误绑定处置后等待后续系统自动流程重新检查。`customer_status` 无同名标签不作为接口异常，后台记录为跳过或无变化原因。
13. 无变化项不作为失败，只记录检查时间、触发方式和无变化结果。
14. 部分失败项需要标记成功阶段和失败阶段；后续系统自动流程重新处理时应基于已成功阶段继续，不重复执行已成功创建或绑定。
15. 后续系统自动检查仅在下一次符合触发条件的同步流程中执行，包括每小时定时同步、B 端管理员或销售经理点击顾客列表页“全量同步检查”、首次绑定访问字段回写失败补偿。4 个 API KEY 不完整时，不执行每小时定时重检，也不执行访问字段回写，但保留失败日志和后续处理状态；管理员或销售经理可在 4 个 API KEY 完整时通过“全量同步检查”触发重新检查。

### 验证标准

- 失败项可查看失败原因。
- 顾客页面和日志页面不提供前端重试入口。
- 后续系统自动流程再次处理同一对象时会产生新日志，并可从顾客和批次维度追溯此前失败记录。
- 批量任务可以查看汇总和单个顾客结果。
- 批量任务部分失败时，已成功项不被回滚，后续重新处理不得重复创建或重复绑定已成功阶段。
- 前台“同步更新失败”下的业务待处理、接口失败、等待 KASIKA 处理等原因，可在后台日志中继续区分，不误计为同一种接口异常。

## 6. KASIKA 批量任务状态与调用限制追溯

| 项目 | 内容 |
| --- | --- |
| 用例名称 | 追溯 KASIKA 批量任务处理状态 |
| 操作者 | B 端管理员 |
| 页面范围 | KASIKA 联动管理页 - 同步日志、批量任务日志 |

### 需求细节

1. HOMEVISTA 访问链接 / 访问密码批量写入 KASIKA、KASIKA 顾客批量拉取和其他批量联动任务，都需要生成批量任务日志；本期不因 VISTA 删除顾客向 KASIKA 提交批量删除或字段清空任务。
2. 如果 KASIKA 返回 `process_id`，日志必须保存该 ID。
3. 如果 KASIKA 返回处理状态，日志需要展示状态含义，包括：
   - 已受理。
   - 处理中。
   - 处理完成。
   - 处理失败。
4. 如果 KASIKA 返回调用次数达到上限，日志记录为“调用受限”，并展示 KASIKA 返回的错误信息、处理状态或原因摘要。
5. 如果 KASIKA 返回存在未处理的 KASIKA 批量新增、更新或删除请求，日志记录为“已有任务处理中”，并阻止重复提交同类任务。
6. 如果 KASIKA 返回认证失败、权限不足或 IP 限制，日志记录为同步任务的认证或权限失败，并提示管理员检查 API KEY 或 KASIKA 侧权限。
7. 批量任务完成后，日志需要展示 KASIKA 返回的汇总信息。
8. 如果 KASIKA 返回 `error_rows_csv_download_url` 等错误客户列表 URL，VISTA 只需要在同步日志中保存 KASIKA 返回的错误提示、错误行 URL、`process_id`、批次状态和处理时间。
9. 本期不要求 VISTA 下载、解析或长期归档 KASIKA 错误 CSV 文件。
10. 由于 KASIKA API 可能存在调用次数和并发受理限制，系统需要在日志中保留被拒绝提交的时间、原因和操作人，便于管理员按 KASIKA 返回信息判断后续处理。
11. 本期不要求 VISTA 自行计算或展示具体剩余等待时间；如果 KASIKA 明确返回可再次提交时间或剩余等待时间，VISTA 可以原样展示，否则不估算。

### 验证标准

- KASIKA 返回 process_id 时，日志能保存并展示。
- KASIKA 批量任务可区分已受理、处理中、完成、失败。
- 调用次数上限、已有任务处理中、认证失败、权限不足等原因可被查询。
- 页面只按照 KASIKA 返回的错误信息、处理状态或原因摘要提示用户；不自行估算具体剩余等待时间。
- KASIKA 返回错误客户列表 URL 时，日志保存错误提示和 URL，但不要求下载、解析或长期归档错误 CSV 文件。
- 被 KASIKA 拒绝受理的批量任务也有日志。

## 7. 同步失败提示与错误信息汇总

本节定义统一的同步失败提示和报错信息字典。`05A-顾客列表页.md` 中的同步任务弹窗和批次顾客列表负责轻量摘要展示；`05B-顾客详情页.md` 只展示 KASIKA 联动模块摘要，`05C-顾客权限页.md` 不展示 KASIKA 同步失败详情；`04-统一顾客联动同步流程.md` 负责触发来源、业务规则和前台结果口径；本节负责统一错误分类、页面摘要、下一步动作、后续处理口径和日志脱敏规则。具体内部处理阶段由研发按同步实现记录。

### 提示展示层级

1. 顾客列表页不新增 KASIKA 同步状态列或最近同步摘要；同步任务结果页和批次顾客列表可展示“前台同步结果 + 页面摘要”，例如“同步更新失败：邮箱重复，请查看同步日志”。
2. 顾客详情页只在 `概要` tab 的 KASIKA 联动模块展示绑定状态、最近同步时间 / 结果等摘要，不展示处理阶段、错误编码、后续处理状态或下一步动作；相关详细信息进入同步日志。
3. 批量任务结果页按同步更新成功、无变化未更新、同步更新失败展示顾客结果数量；任务执行中仅记录同步中，完成后展示实际结果；可进入批次顾客名单。
4. 同步日志按“同步批次列表 -> 批次顾客列表页”展示；批次顾客列表仅展示顾客识别信息和合并后的同步结果，本次同步取得的完整 `customer_data` 快照只作服务端容错保存，不提供 B 端查看。
5. 页面展示不得暴露 API KEY、Secret Key、HOMEVISTA 访问密码明文、完整请求头、完整请求体或完整响应体。
6. KASIKA 返回的原始错误信息如包含敏感信息，页面和日志只保存脱敏后的原因摘要。
7. 同步日志可以保存脱敏后的 KASIKA 请求/响应摘要，用于管理员和研发定位失败阶段；不得保存完整 KASIKA 请求/响应原文。

### 错误信息字段

| 字段 | 说明 |
| --- | --- |
| 错误编码 | 系统内部统一识别用编码，供页面、日志和统计复用 |
| 前台结果 | 同步更新成功、无变化未更新、同步更新失败 |
| 后台原因分类 | 等待处理、处理中、成功、失败、部分失败、业务待处理、无变化、跳过、等待 KASIKA 处理等，由研发按日志实现细化 |
| 处理阶段 | 查询/拉取、匹配、创建、绑定保存、访问字段写入、字段快照保存、`customer_status` 标签配置、访问字段回写、权限判定、自动回复邮件发送、KASIKA入口页访问、KASIKA入口页顾客校验、邮箱校验、密码设置、首次访问开户 |
| 页面摘要 | 顾客列表和批量结果页展示的短文案 |
| 用户可见说明 | 详情页或日志详情可展示的解释 |
| 下一步动作 | 用户可以执行的处理动作 |
| 后续处理状态 | 系统后续可重新检查、需先处理密钥、需先处理权限、需人工处理、无需处理 |
| 后续处理范围 | 后续重新检查整个顾客、仅继续失败阶段、仅继续字段写入、仅继续权限计算等 |
| 日志记录要求 | 需要保留的日志字段和敏感信息处理要求 |

### 统一错误字典

| 错误编码 | 结果分类 | 处理阶段 | 页面摘要 | 用户可见说明 | 下一步动作 | 后续处理状态 | 日志记录要求 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `KASIKA_QUERY_FAILED` | 失败 | 查询/拉取 | KASIKA 查询失败 | 系统未能读取 KASIKA 顾客或任务状态。 | 等待后续系统自动检查；如持续失败，检查 KASIKA 连接和账号权限。 | 系统后续可重新检查 | 记录接口类型、失败摘要、KASIKA customer_id 或邮箱；不记录完整请求/响应。 |
| `KASIKA_AUTH_FAILED` | 失败 | 查询/拉取 | KASIKA 认证失败 | KASIKA 返回认证失败，当前 API KEY 不可用。 | 管理员检查 API KEY，配置恢复后等待后续系统自动检查。 | 需先处理密钥 | 记录认证失败摘要；API KEY、Secret Key 必须脱敏。 |
| `KASIKA_PERMISSION_DENIED` | 失败 | 查询/拉取 | KASIKA 权限不足 | KASIKA 账号没有执行当前接口的权限。 | 管理员检查 KASIKA 账号权限或更换 API KEY，配置恢复后等待后续系统自动检查。 | 需先处理权限 | 记录权限不足摘要、接口类型、操作人。 |
| `KASIKA_RATE_LIMITED` | 等待 KASIKA 处理 | 查询/拉取 | KASIKA 调用受限 | KASIKA 返回调用次数限制或临时不可提交。 | 按 KASIKA 返回信息等待后续自动检查；如返回可再次提交时间则原样展示。 | 系统后续可重新检查 | 记录限制原因、返回的可再次提交时间或处理状态；不自行估算等待时间。 |
| `KASIKA_TASK_IN_PROGRESS` | 等待 KASIKA 处理 | 查询/拉取 | KASIKA 已有任务处理中 | KASIKA 当前已有同类批量任务处理中，不能重复提交。 | 等待当前任务完成后由后续流程再次提交。 | 系统后续可重新检查 | 记录 process_id、任务状态、触发人和批次。 |
| `MATCH_DUPLICATE_EMAIL` | 业务待处理 | 匹配 | 邮箱匹配到多个顾客 | 邮箱不是唯一匹配，系统不能自动绑定。 | 修正 VISTA 或 KASIKA 侧邮箱、清理重复顾客后等待后续系统自动检查；本期不支持手工选择绑定。 | 需人工处理 | 记录候选数量、邮箱；不自动绑定。 |
| `MATCH_DUPLICATE_PHONE` | 业务待处理 | 匹配 | 手机号匹配到多个顾客 | 手机号不是唯一匹配，系统不能自动绑定。 | 修正 VISTA 或 KASIKA 侧手机号、清理重复顾客后等待后续系统自动检查；本期不支持手工选择绑定。 | 需人工处理 | 记录候选数量、手机号；不自动绑定。 |
| `MATCH_CANDIDATE_ALREADY_BOUND` | 业务待处理 | 匹配 | 候选顾客已绑定 | 候选顾客已经存在有效绑定关系，不能重复绑定。 | 检查已有绑定；如为错误绑定，管理员走后台错误绑定处置后等待后续系统自动检查。 | 需人工处理 | 记录候选顾客 ID、已绑定对象。 |
| `BOUND_TARGET_NOT_FOUND` | 业务待处理 | 匹配 | 绑定目标疑似不存在 | 已绑定的对侧顾客无法确认存在，系统不自动清理有效绑定关系。 | 管理员检查后决定是否走后台处置或保留追溯。 | 需人工处理 | 记录原绑定关系、识别方式、异常标记时间和触发批次。 |
| `VISTA_CREATE_FAILED` | 失败 | 创建 | VISTA 顾客创建失败 | KASIKA 顾客未能创建为 VISTA 顾客。 | 修正失败原因后等待后续系统自动检查。 | 系统后续可重新检查 | 记录 KASIKA customer_id、邮箱、姓名和失败摘要。 |
| `BINDING_SAVE_FAILED` | 失败 | 绑定保存 | 绑定保存失败 | 顾客可能已创建成功，但双方绑定关系保存失败。 | 后续流程仅继续绑定保存；不得重复创建已成功创建的顾客。 | 仅继续失败阶段 | 记录已成功阶段、双方顾客 ID、失败摘要。 |
| `IDENTITY_WRITE_FAILED` | 失败 | 访问字段写入 | 访问字段写入失败 | 绑定已保存，但 `VISTAURL` 或适用时的 `VISTAPWD` 写入 KASIKA 失败。 | 后续流程仅继续失败字段写入。 | 仅继续字段写入 | 记录写入字段名和失败摘要；访问密码不得明文记录。 |
| `IDENTITY_WRITE_PARTIAL_FAILED` | 部分失败 | 访问字段写入 | 访问字段部分写入失败 | `VISTAURL`、适用时的 `VISTAPWD` 中有部分字段写入 KASIKA 失败。 | 后续流程仅继续失败字段写入。 | 仅继续字段写入 | 记录失败字段名；访问密码仅记录字段名和结果，不记录值。 |
| `SNAPSHOT_SAVE_FAILED` | 失败 | 字段快照保存 | 字段快照保存失败 | 绑定关系已保存，但 KASIKA 字段快照未保存成功。 | 后续流程仅继续字段快照保存和 `customer_status` 标签配置。 | 仅继续失败阶段 | 记录 KASIKA customer_id、同步批次、失败摘要。 |
| `IDENTITY_CALLBACK_FAILED` | 失败 | 访问字段回写 | 访问字段回写 KASIKA 失败 | VISTA 顾客和字段快照已处理，但 `VISTAURL` 或适用时的 `VISTAPWD` 回写 KASIKA 失败。 | 后续流程仅继续失败字段回写；不回滚 VISTA 顾客和字段快照。 | 仅继续字段写入 | 记录回写字段名和失败摘要；访问密码不得明文记录。 |
| `AUTO_REPLY_ID_MISSING` | 跳过 | 自动回复邮件发送 | 自動返信ID 未配置 | 首次绑定已完成，但项目未配置绑定通知自動返信ID，系统不触发自动回复邮件。 | 管理员配置自動返信ID 后，由后续补偿流程处理是否补发。 | 需人工处理 | 记录项目、VISTA 顾客 ID、KASIKA customer_id 和触发批次。 |
| `AUTO_REPLY_SEND_FAILED` | 部分失败 | 自动回复邮件发送 | 自动回复邮件发送失败 | 顾客绑定和访问字段已处理，但 KASIKA 自动回复邮件未能发送。 | 后续流程仅继续自动回复邮件发送；不得重复创建、重复绑定或重复回写已成功字段。 | 仅继续失败阶段 | 记录 KASIKA customer_id、VISTA 顾客 ID、自動返信ID、失败摘要和触发批次；不记录完整请求/响应或访问密码明文。 |
| `ENTRY_PROJECT_INVALID` | 失败 | KASIKA入口页访问 | 入口链接无效 | 当前访问 Host 无法识别 VISTA 项目，或项目入口无效。 | 顾客重新打开正确邮件链接；如持续失败，联系销售。 | 无需处理 | 记录访问 Host、解析结果、访问时间和安全摘要。 |
| `ENTRY_KASIKA_UNAVAILABLE` | 失败 | KASIKA入口页顾客校验 | 无法确认顾客信息 | 系统暂时无法通过 KASIKA 确认顾客信息。 | 稍后重试；如持续失败，管理员检查 KASIKA API KEY。 | 系统后续可重新检查 | 记录 KASIKA customer_id、项目、接口失败摘要；API KEY 必须脱敏。 |
| `ENTRY_CUSTOMER_NOT_FOUND` | 失败 | KASIKA入口页顾客校验 | 顾客信息不存在 | KASIKA 中无法取得该顾客信息，系统未创建 VISTA 顾客。 | 确认邮件链接或联系销售。 | 无需处理 | 记录 KASIKA customer_id 和项目，不记录完整请求/响应。 |
| `ENTRY_COOKIE_WRITE_FAILED` | 部分失败 | KASIKA入口页访问 | 访问统计识别 Cookie 写入失败 | 顾客身份已通过 KASIKA 校验，但系统未能写入或确认 KASIKA 识别 Cookie。 | 不阻塞顾客开户、登录或访问；后续访问统计可能无法归属到该顾客。 | 无需处理 | 记录项目、KASIKA customer_id、访问 Host 和失败摘要；不记录 Cookie 完整值。 |
| `ENTRY_EMAIL_VERIFY_FAILED` | 失败 | 邮箱校验 | 邮箱校验失败 | 输入邮箱与 KASIKA 顾客邮箱不一致。 | 顾客确认登记邮箱后重试。 | 无需处理 | 记录校验失败结果和脱敏邮箱摘要；不记录完整邮箱输入明文。 |
| `ENTRY_BOUND_EMAIL_MISMATCH` | 业务待处理 | 首次访问开户 | 绑定邮箱不一致 | 该 KASIKA 顾客已绑定 VISTA 顾客，但 KASIKA 邮箱与绑定 VISTA 顾客邮箱不一致。 | 不允许顾客继续开户或自动改绑；管理员通过同步日志确认后走解除或后台处置。 | 需人工处理 | 记录 KASIKA customer_id、绑定 VISTA 顾客 ID、脱敏邮箱摘要和触发时间。 |
| `ENTRY_BINDING_CONFLICT` | 业务待处理 | 首次访问开户 | 绑定冲突 | 入口页按邮箱找到的 VISTA 顾客已绑定其他 KASIKA customer_id，或同邮箱存在多个候选，系统不能自动绑定。 | 管理员修正重复顾客或错误绑定后，等待后续入口访问或同步流程重新判定。 | 需人工处理 | 记录候选数量、候选绑定状态、KASIKA customer_id 和脱敏邮箱摘要。 |
| `ENTRY_REBIND_FORBIDDEN` | 业务待处理 | 首次访问开户 | 已禁止自动再绑定 | 该 VISTA 顾客曾因删除导致 KASIKA 有效绑定失效，或被后台处置标记禁止再绑定，入口页不自动恢复绑定。 | 如需恢复，走后台数据治理或另立恢复需求；本期前台不提供恢复入口。 | 需人工处理 | 记录 VISTA 顾客 ID、KASIKA customer_id、删除恢复状态或禁止再绑定标记和触发时间。 |
| `ENTRY_PASSWORD_SET_FAILED` | 失败 | 密码设置 | 密码设置失败 | 顾客访问密码未能保存。 | 顾客按页面提示重试；如持续失败，提交研发排查。 | 系统后续可重新检查 | 记录 VISTA 顾客 ID、KASIKA customer_id 和失败摘要；不得记录密码明文。 |
| `ENTRY_ACCOUNT_CREATE_FAILED` | 失败 | 首次访问开户 | 首次开户失败 | 系统未能完成 VISTA 顾客创建或绑定。 | 稍后重试；如持续失败，管理员查看日志。 | 系统后续可重新检查 | 记录已成功阶段、项目、KASIKA customer_id 和失败摘要。 |
| `ENTRY_ALREADY_BOUND` | 无变化 | KASIKA入口页访问 | 顾客已绑定 | 该 KASIKA 顾客已绑定 VISTA 顾客，本次访问不重复创建。 | 无需处理。 | 无需处理 | 记录既有绑定关系和访问时间。 |
| `CUSTOMER_STATUS_AUTO_UPDATE_OFF` | 跳过 | `customer_status` 标签配置 | 状态权限自动更新关闭 | 已保存新的 `customer_status`，但项目关闭了自动更新开关，系统不更新 VISTA 标签和权限。 | 如需按最新状态更新权限，管理员开启开关后等待后续同步或另行执行确认后的补算流程。 | 无需处理 | 记录开关状态、字段变化前后值、同步批次；不修改标签。 |
| `CUSTOMER_STATUS_TAG_NO_MATCH` | 跳过 | `customer_status` 标签配置 | 无同名标签 | 已保存字段快照，但 `customer_status` 字段值没有对应的同名 VISTA 标签。 | 管理员按需创建同名标签或保持不处理。 | 无需处理 | 记录字段值摘要和同步批次。 |
| `CUSTOMER_STATUS_TAG_ADD_FAILED` | 失败 | `customer_status` 标签配置 | 状态标签添加失败 | 系统未能把新 `customer_status` 对应的同名 VISTA 标签配置给顾客。 | 后续流程仅继续状态标签配置；不得回滚已完成的顾客绑定或访问字段回写。 | 仅继续失败阶段 | 记录新状态字段值、目标标签、顾客 ID、失败摘要和同步批次。 |
| `CUSTOMER_STATUS_OLD_TAG_REMOVE_FAILED` | 部分失败 | `customer_status` 标签配置 | 旧状态标签移除失败 | 新状态标签可能已添加成功，但上一状态对应的旧标签未能移除。 | 后续流程仅继续旧状态标签移除和权限重算；需避免重复添加新标签。 | 仅继续失败阶段 | 记录新旧状态字段值、新标签添加结果、旧标签删除结果、顾客 ID 和失败摘要。 |
| `CUSTOMER_STATUS_TAG_UPDATE_PARTIAL` | 部分失败 | `customer_status` 标签配置 | 状态标签部分更新 | 状态标签校准过程中只有部分操作成功。 | 后续流程只处理未完成的标签更新步骤，再按最新标签结果计算权限。 | 仅继续失败阶段 | 记录每个标签操作的成功/失败结果、字段变化前后值和同步批次。 |
| `PERMISSION_CALC_FAILED` | 失败 | 权限判定 | 权限计算失败 | 标签已处理，但权限计算失败。 | 后续流程仅继续权限计算。 | 仅继续权限计算 | 记录标签、模板、顾客 ID 和失败摘要。 |
| `NO_CHANGE` | 无变化 | 查询/拉取 | 本次无变化 | 本次检查未发现需要同步或权限重算的变化。 | 无需处理。 | 无需处理 | 记录检查时间、触发方式。 |
| `UNKNOWN_ERROR` | 失败 | 其他 | 同步失败 | 发生未归类错误，系统未能完成本次处理。 | 管理员查看日志详情；如持续失败，提交研发排查。 | 系统后续可重新检查 | 记录安全摘要、关联批次和可定位对象；敏感信息必须脱敏。 |

### 字典使用规则

1. 同一个失败在不同页面必须使用同一错误编码和同一页面摘要。
2. 顾客列表不得展示过长技术信息，只展示页面摘要和下一步动作。
3. 批次顾客列表的“同步结果”仅展示该顾客账号本次同步的同步结果说明和必要的变化字段名摘要；处理阶段、错误编码和后续处理状态等字段仅进入后台日志追溯，不作为前台可见字段。
4. 日志详情可以展示脱敏后的 KASIKA 返回摘要、系统内部失败摘要和关联批次。
5. “业务待处理”不进入接口失败处理队列；需要用户处理后等待后续系统自动流程重新检查或重新判定。
6. “等待 KASIKA 处理”不视为系统异常失败；如 KASIKA 返回 process_id 或处理状态，必须保存到日志。
7. “无变化”不视为失败，不提供失败处理入口。
8. 同步失败提示的新增、合并或改名，需要同步检查 `05A-顾客列表页.md`、`05B-顾客详情页.md`、`05C-顾客权限页.md`、`04-统一顾客联动同步流程.md` 和本文件的一致性。
9. 日志可以保留脱敏后的请求/响应摘要，包括接口用途、状态码或业务错误码、错误摘要、`process_id`、批次状态、错误行 URL 等必要追溯信息；不得保存完整请求头、完整请求体或完整响应体。
10. HOMEVISTA 访问密码、API KEY、Secret Key 不得出现在页面摘要、用户可见说明或日志明细中。
11. 如研发排查需要完整报文，应通过服务端受控调试或临时排查机制处理，不进入产品同步日志。

### 验证标准

- 同步任务弹窗、批次顾客列表、顾客详情 KASIKA 联动模块和后台日志详情使用同一套错误编码和页面摘要。
- 前台顾客级结果统一为同步更新成功、无变化未更新、同步更新失败；后台日志可清晰区分业务待处理、系统异常失败、等待 KASIKA 处理和无变化等原因分类。
- 失败项能定位到后续处理范围，不重复执行已成功阶段。
- 敏感信息不会出现在页面摘要、用户可见说明或日志明细中。

## 8. 权限与审计规则

| 项目 | 内容 |
| --- | --- |
| 用例名称 | 控制日志查看与审计 |
| 操作者 | B 端管理员 |
| 页面范围 | KASIKA 联动管理页 - 同步日志 |

### 需求细节

1. B 端管理员可以从 KASIKA 联动管理页查看本项目全部 KASIKA 顾客同步数据相关日志。
2. 销售人员和销售经理不可查看完整同步日志，也不展示同步日志页面入口。
3. 同步任务弹窗、批次顾客列表、顾客详情 KASIKA 联动模块和同步信息弹窗只展示必要摘要或当前操作反馈，不承载完整日志查询。
4. 删除类日志、错误绑定处置类日志、权限变化日志不可由普通用户删除或修改。
5. 完整同步日志的列表、详情、筛选和查询接口必须校验 B 端管理员权限；销售经理和销售人员即使构造直接请求也不得读取。
6. 日志记录本身不允许被业务操作覆盖。

### 验证标准

- 只有 B 端管理员可以从 KASIKA 联动管理页进入完整同步日志。
- 销售人员和销售经理不可查看完整同步日志，不展示同步日志页面入口。
- 完整同步日志的列表、详情、筛选和查询接口仅 B 端管理员可调用；销售经理和销售人员不得通过接口读取。
- 删除类、错误绑定处置类、权限变化类日志不可被业务用户删除。
- 日志详情不可被编辑覆盖。
- 日志可追溯字段快照变化过程，但不作为字段快照的主存储位置。

## 9. 本模块业务规则

1. 所有顾客同步数据相关的自动任务和人工操作都必须记录日志。
2. 所有同步数据的增删改都必须记录日志。
3. 删除类、自动绑定和后台错误绑定处置操作必须记录操作前后的绑定关系；首次绑定导致 KASIKA 侧 HOMEVISTA 访问字段写入或更新时，需要记录写入结果。
4. KASIKA 侧找不到已绑定 customer_id 对应顾客时，系统只标记疑似删除或绑定异常，不自动清理 VISTA 侧有效绑定关系；日志必须记录识别方式、原 KASIKA customer_id、异常标记时间和触发批次。
5. 权限变化必须记录变化前后摘要。
6. `customer_status` 标签配置判定必须记录单独保存的 `customer_status` 当前值、上一轮保存值、最近取得时间、来源批次、自动更新开关状态、命中的同名标签，以及状态标签校准结果；完整 KASIKA 字段快照仅作为追溯资料。
7. 同步失败不得静默失败。
8. 后续系统自动流程再次处理失败项时，必须保留原失败日志，并追加新的处理日志。
9. 历史字段重新判定、补标签、标签权限模板变更后的权限计算都必须记录日志。
10. 日志需要能定位到项目、VISTA 顾客、KASIKA customer_id、邮箱、触发方式、操作人或系统任务。
11. KASIKA 返回的 process_id、处理状态、调用限制和并发限制需要进入日志。
12. 批量任务未被 KASIKA 受理时，也必须记录失败原因。
13. 本期不发送同步失败站内通知或内部告警邮件，也不定义通知接收人配置；顾客绑定通知邮件按 `04` 的 KASIKA 自动回复邮件方案处理。
14. 本期只提供顾客列表页“全量同步检查”作为前端手动同步入口；顾客详情页不展示 KASIKA 同步失败详情；相关失败原因和后续处理状态进入同步日志，完整日志只能由 B 端管理员从 KASIKA 联动管理页查看。
15. 定时同步、后台批量任务失败时，只记录日志、批次状态、失败明细和后续处理状态，管理员通过 KASIKA 联动管理页的同步日志查询。
16. 日志中必须区分业务待处理、跳过/无变化和系统异常失败：邮箱或手机号匹配冲突、候选顾客已绑定属于业务待处理；`customer_status` 无同名标签属于跳过或无变化；查询失败、接口不可用、认证失败、权限不足、调用受限、保存失败、写入失败属于系统异常或接口失败状态。
17. VISTA 顾客创建成功但后续绑定保存、字段写入、字段快照保存或访问字段回写失败时，日志必须记录已成功阶段，避免重试时重复创建或重复绑定；本期不存在向 KASIKA 创建顾客的成功阶段。
18. 后台错误绑定处置和 VISTA 删除顾客不清空 KASIKA 侧 HOMEVISTA 访问字段，日志需要记录该处理结果；同时记录绑定关系变化、有效绑定关系清理结果、历史 KASIKA 字段保留结果、禁止再绑定标记和访问权限重算结果。VISTA 顾客删除后的原顾客如被恢复，不自动恢复原 KASIKA 有效绑定；后台处置后的顾客后续被同步或入口页命中时，不自动重新绑定，只记录跳过或业务待处理结果。
19. 同步失败提示、页面摘要、下一步动作和后续处理口径必须优先使用本文件“同步失败提示与错误信息汇总”的统一错误字典。
20. KASIKA 联动配置表单的保存成功、保存失败、新增、修改、清空不写入同步日志。

## 10. 本模块验收标准

| 验收点 | 标准 |
| --- | --- |
| 同步日志 | 所有同步成功和失败都可查 |
| 配置表单保存 | KASIKA 联动配置表单的保存成功、保存失败、新增、修改、清空不写入同步日志 |
| 字段日志 | 字段快照保存、变化、`customer_status` 标签配置结果、自动更新开关状态和状态标签校准结果可查 |
| 权限日志 | 权限计算、权限变化、模板变更后的实时计算结果可查 |
| 删除/错误绑定处置日志 | 删除和错误绑定处置操作前后状态可追溯 |
| 自动绑定日志 | 同步流程自动建立或重新建立绑定关系时，绑定前后关系、触发批次、匹配依据、操作结果和 KASIKA 侧 HOMEVISTA 访问字段写入结果可追溯 |
| 后台错误绑定处置日志 | 后台处置操作人、操作时间、处置前后关系、原因、结果、未清空 KASIKA 侧 HOMEVISTA 访问字段的处理结果和权限重算结果可追溯 |
| 历史任务日志 | 历史字段重新判定、补标签结果可查；模板保存不生成额外历史任务 |
| 批次日志 | 定时同步和批量同步有汇总和明细 |
| KASIKA 批量状态 | process_id、处理中、完成、失败、调用受限、已有任务处理中等状态可查 |
| 前台结果 | 顾客级结果统一展示同步更新成功、无变化未更新、同步更新失败 |
| 后台原因分类 | 日志可区分等待处理、处理中、成功、失败、部分失败、业务待处理、无变化、跳过和等待 KASIKA 处理等原因 |
| 阶段追溯 | VISTA 创建、绑定、字段写入、字段快照保存、访问字段回写、自动回复邮件发送等阶段失败可分别追溯 |
| 错误字典 | 同步任务弹窗、批次顾客列表、详情页 KASIKA 联动模块和后台日志详情复用统一错误编码、页面摘要、下一步动作和后续处理口径 |
| 失败处理 | 同步、字段快照、权限计算等失败项记录失败阶段和后续处理状态；删除类失败只记录失败和原因，不提供重试 |
| 失败通知 | 本期不发送站内通知或邮件通知；失败结果通过页面状态和管理员日志处理 |
| 日志入口 | 仅 KASIKA 联动管理页提供完整同步日志入口，且仅 B 端管理员可见 |
| 日志导出 | 本期不提供同步日志导出功能 |

## 11. 本模块待确认事项

1. 【已确认】同步失败、`customer_status` 无同名标签等情况，本期只记录日志和页面状态，不发送站内通知或邮件通知，也不定义通知接收人范围。
2. 【已确认】本期不单独设计同步日志保留期限、归档策略或日志清理规则；同步日志跟随项目数据生命周期保留，项目到期清除数据时统一处理。
3. 【已确认】本期不提供同步日志导出功能。
4. 【已确认】批量同步允许部分顾客成功、部分顾客失败；前台顾客级结果归入同步更新成功、无变化未更新、同步更新失败，后台日志记录失败原因、失败顾客明细和后续处理状态，不回滚同批次已成功顾客。
5. 【已确认】KASIKA 批量任务调用限制和并发受理限制，本期不要求 VISTA 自行计算或展示具体剩余等待时间；页面只按照 KASIKA 返回的错误信息、处理状态或原因摘要提示用户。如果 KASIKA 明确返回可再次提交时间或剩余等待时间，VISTA 可以原样展示，否则不估算。
6. 【已确认】完整同步日志仅 B 端管理员可查看，入口放在 KASIKA 联动管理页；销售人员和销售经理不可查看完整同步日志，也不展示同步日志页面入口。
7. 【已确认】删除类失败只记录失败结果和失败原因，不提供重试入口，也不在日志页直接重试。
8. 【已确认】KASIKA 批量处理进度确认 API 可能返回 `error_rows_csv_download_url` 等错误客户列表 URL。本期不要求 VISTA 下载、解析或长期归档 KASIKA 错误 CSV 文件；只需要在同步日志中保存 KASIKA 返回的错误提示、错误行 URL、`process_id`、批次状态和处理时间，供管理员从日志中查看。
9. 【已确认】同步日志可以保存脱敏后的 KASIKA 请求/响应摘要，用于失败追溯和研发排查；不得保存完整请求头、完整请求体、完整响应体，也不得记录 API KEY、Secret Key、HOMEVISTA 访问密码明文等敏感信息。如研发排查需要完整报文，应通过服务端受控调试或临时排查机制处理，不进入产品同步日志。
10. 【已确认】HOMEVISTA 访问密码不允许明文出现在日志明细中；涉及访问密码同步时，日志只记录是否同步成功、同步时间、目标顾客、处理阶段和失败原因，不记录密码值本身。
11. 【已确认】前台顾客级结果只展示同步更新成功、无变化未更新、同步更新失败；日志中仍需要区分“业务待处理”和“系统异常失败”。邮箱或手机号匹配冲突、`customer_status` 无同名标签、无变化等状态不作为接口异常；查询失败、接口不可用、认证失败、权限不足、调用受限、保存失败、写入失败等状态作为失败或异常记录，并提供失败原因和后续处理状态。
12. 【2026-07-20 修订】同步失败提示和报错信息汇总放在本文件“同步失败提示与错误信息汇总”中统一维护；同步任务弹窗、批次顾客列表、顾客详情 KASIKA 联动模块和后台日志详情复用同一套错误编码、页面摘要、下一步动作和后续处理口径。前台不提供 KASIKA 顾客同步信息弹窗。VISTA 顾客文件导入结果弹窗只展示 VISTA 导入和标签写入结果，不作为 KASIKA 同步错误字典的展示载体。

## 12. 修订记录

| 日期 | 修订内容 |
| --- | --- |
| 2026-07-13 | 明确完整同步日志仅 B 端管理员可查看和查询；销售经理与销售人员不展示入口，也不得通过接口读取日志。 |
| 2026-07-13 | 配合不可流式批量同步改造：取消“手动停止／未完成”作为正常前台任务结果和相关日志字段；批次完成后统一记录实际处理总数、新增绑定、更新完成、失败／待处理、KASIKA process_id 与 CSV 回写结果。新增同项目任务锁冲突记录，不创建冲突批次；前台执行中不展示伪进度或处理中数量。 |
| 2026-07-13 | 顾客同步详情弹窗取消“同步基本信息 / KASIKA 快照”Tab 与所有 B 端快照查看入口；弹窗只保留同步结论、顾客识别信息和字段变更。完整 KASIKA `customer_data` 快照改为仅服务端容错与受控排查保存，不提供 B 端读取、展示或下载。 |
| 2026-08-04 | 明确 KASIKA 回写日志只覆盖 `VISTAURL` 和适用时的 `VISTAPWD`；VISTA 顾客 ID、绑定状态和首次访问完成时间只作为 VISTA 内部信息记录，不属于 KASIKA 回写字段。 |