# 04-统一顾客联动同步流程

## 1. 文档定位

本文是本期 KASIKA 开发的顾客联动核心规则事实源，定义 KASIKA 顾客进入 VISTA 后的业务规则、结果口径、页面反馈和异常追溯要求。

同步实现方案不在产品需求中展开。研发已确认当前同步模式为：一次性从 KASIKA 获取当前可取得的顾客数据集合，再由 VISTA 系统进行本地比对和更新。具体分页、批次拆分、并发、事务边界、处理顺序、重试和中断策略由研发按 KASIKA API 能力和系统稳定性设计；产品原型只定义页面样式、操作入口、展示结果和日志可追溯要求。

本文负责说明“规则如何成立”，不重复展开页面 UI 和日志字段：

| 关联文档 | 责任边界 |
| --- | --- |
| `01-KASIKA联动配置管理.md` | KASIKA API 参数、settingID、VISTA 项目入口 URL、访问密码设置开关、`customer_status` 状态权限自动更新开关 |
| `03-标签权限模板.md` | VISTA 标签与权限模板的配置和权限计算方式 |
| `05A/05B/05C/05D` | 顾客列表、详情、权限页、新增顾客页面展示与操作 |
| `07-同步日志与追溯.md` | 日志字段、错误字典、页面摘要和查询规则 |
| `08-KASIKA入口页与VISTA首次访问开户.md` | 顾客点击 KASIKA 自动回复邮件入口后的 C 端实时开户 / 绑定流程 |
| `09-C端顾客访问权限接口.md` | C 端实际读取可访问内容的接口规则 |

`08` 入口页和本文同步流程共同覆盖首次触达：

1. 顾客点击 KASIKA 自动回复邮件中的入口时，按 `08` 立即完成本人校验、VISTA 顾客创建 / 绑定、可选密码设置，并在首次绑定时强制执行一次 `customer_status` 同名标签初始化和初始权限判定。
2. 顾客未点击入口、或客户仍希望通过 KASIKA 后续邮件触达时，按本文批量同步流程完成自动绑定和访问字段回写；首次绑定完成后通过 KASIKA 自动回复邮件 API 和配置页保存的自動返信ID 触发顾客通知。

## 2. 核心规则总表

| 编号 | 规则 | 产品口径 |
| --- | --- | --- |
| R1 | API 前置 | 调用 KASIKA 顾客 API 前必须已保存完整 4 个 API KEY；4 个 API KEY 不完整时不拉取、不同步、不回写 |
| R2 | 无同步开关 | 本期不再提供顾客同步控制开关；同步是否执行由 API 参数完整性、KASIKA API 调用结果和系统任务状态决定 |
| R3 | 主数据方向 | 顾客主数据来源以 KASIKA -> VISTA 为主；VISTA 不向 KASIKA 创建顾客，不用 VISTA 姓名、邮箱、电话、公司名覆盖 KASIKA 顾客基础资料 |
| R4 | 绑定主键 | KASIKA `customer_id` / `cid` 是 KASIKA 顾客与 VISTA 顾客的绑定主键 |
| R5 | 邮箱匹配 | 邮箱只用于未绑定 KASIKA 顾客匹配既有 VISTA 顾客；必须唯一命中、未绑定、且未禁止再绑定才允许自动绑定 |
| R6 | 字段保存 | KASIKA `customer_id`、KASIKA 邮箱、`customer_status` 必须作为结构化关联字段保存；完整字段快照不能替代结构化保存 |
| R7 | 权限来源 | `customer_status` 是本期唯一 KASIKA 权限变化来源字段；首次绑定时必须按同名 VISTA 标签初始化并通过标签权限模板计算初始访问权限；后续是否按当前状态校准标签 / 权限，由配置页 `customer_status` 状态权限自动更新开关控制 |
| R8 | 首次回写 | 首次绑定成功后，只向 KASIKA 的 `VISTAURL` 写入 HOMEVISTA 访问链接；项目启用访问密码时，再向 `VISTAPWD` 写入首次访问密码。VISTA 顾客 ID、绑定状态和首次访问完成时间不回写 KASIKA |
| R9 | 绑定通知 | 首次绑定完成后，VISTA 调用 KASIKA 自动回复邮件 API，并传入客户预先配置的自動返信ID，触发 KASIKA 按回信模板给顾客发送邮件 |
| R10 | 权限变化边界 | 首次绑定完成后，开关开启时，后续同步按当前 `customer_status` 轻量校准 VISTA 标签、权限和日志，不重新生成 URL / 密码，不再次回写 KASIKA；开关关闭时，只更新结构化 `customer_status` 和日志，不主动更新标签和权限 |
| R11 | 绑定清理 | 本期顾客详情页不提供手工解除 KASIKA 绑定入口；仅在删除 VISTA 顾客时清理该顾客的有效 KASIKA 绑定关系，并保留历史绑定追溯 |
| R12 | 删除边界 | VISTA 删除顾客不删除 KASIKA 顾客，也不清空 KASIKA 侧已写入的 HOMEVISTA 访问 URL 和密码；删除后的原 VISTA 顾客不得随恢复操作自动恢复 KASIKA 有效绑定 |
| R13 | 实现边界 | 产品需求只定义一次性获取 KASIKA 顾客数据后在 VISTA 比对更新的业务口径；具体同步算法、执行顺序、分页、并发、事务和重试方案由研发设计 |

## 3. 前置条件与能力影响

### 3.1 API 参数完整性

1. 完整 4 个 API KEY 是 KASIKA 顾客查询、批量同步和首次绑定访问字段回写的基础前置条件。
2. 4 个 API KEY 任一缺失时：
   - 不创建同步任务。
   - 不调用 KASIKA 顾客 API。
   - 顾客列表页不显示“全量同步检查”按钮。
   - 不执行首次绑定访问字段回写。
   - 历史绑定、历史同步状态和日志保留。
3. settingID 用于 KASIKA 批量导出 / 导入 API 调用，不替代 4 个 API KEY 的认证作用。具体是否必须依赖 settingID，由研发按 KASIKA API 实测能力确认；产品侧要求缺失或不可用时必须记录清晰失败原因。

### 3.2 VISTA 访问密码设置

1. VISTA 访问密码设置开关由 `01-KASIKA联动配置管理.md` 定义。
2. 开关开启时：
   - `08` 入口页要求顾客设置 VISTA 访问密码。
   - 同步兜底创建 VISTA 顾客时，系统生成初始访问密码。
   - 首次绑定回写时允许写入访问密码。
3. 开关关闭时：
   - `08` 入口页仍需邮箱本人校验，但跳过密码设置。
   - 同步兜底创建 VISTA 顾客时不生成访问密码。
   - 首次绑定回写不得写入空密码或伪密码。

### 3.3 customer_status 状态权限自动更新设置

1. `customer_status` 状态权限自动更新开关由 `01-KASIKA联动配置管理.md` 定义，默认开启。
2. 首次绑定时：
   - 无论开关开启或关闭，系统都必须按本次 `customer_status` 执行一次同名 VISTA 标签初始化。
   - 如命中同名标签及其权限模板，按标签权限模板触发初始权限判定。
3. 首次绑定完成后，开关开启时：
   - 后续同步处理该顾客时，按当前 KASIKA `customer_status` 轻量校准同名 VISTA 标签。
   - 同名 VISTA 标签存在时，确保该顾客持有该标签；同名标签不存在时，不自动创建标签，仅记录跳过日志。
   - 如本次校准导致标签结果变化，按标签权限模板触发顾客权限重算。
4. 首次绑定完成后，开关关闭时：
   - 同步流程仍保存 KASIKA 结构化关联字段、完整字段快照和结构化 `customer_status`。
   - 不根据后续 `customer_status` 变化新增、删除或替换 VISTA 标签。
   - 不因后续 `customer_status` 变化主动触发顾客权限重算。
   - 不撤销顾客既有标签或既有权限。
5. 重新开启后，仅对后续同步处理的顾客生效；历史顾客是否补算，归属单独的手动同步 / 权限重算流程，不由开关自动追溯执行。

## 4. 数据主权与保存口径

### 4.1 VISTA 主字段

VISTA 主字段包括 VISTA 顾客 ID、姓名、邮箱、手机号、HOMEVISTA 访问 URL、访问密码、访问权限和 KASIKA customer_id 绑定关系。

### 4.2 KASIKA 结构化关联字段

以下字段必须结构化保存，供顾客详情展示、绑定一致性校验、权限变化和日志追溯使用：

| 字段 | 来源 | 用途 |
| --- | --- | --- |
| KASIKA `customer_id` / `cid` | KASIKA 顾客查询、批量同步、入口页 | 绑定主键 |
| KASIKA 邮箱 | KASIKA 顾客信息 | 邮箱一致性校验、冲突判断、展示 |
| `customer_status` | KASIKA 顾客信息 | 结构化保存；当状态权限自动更新开关开启时，配置同名 VISTA 标签并触发权限计算 |
| KASIKA 绑定状态 | VISTA 绑定处理结果 | 展示未绑定、已绑定、VISTA 顾客已删除导致绑定失效、绑定异常、疑似删除等状态 |
| KASIKA 信息更新时间 | 同步、入口页、VISTA 顾客删除操作 | 表示 KASIKA 关联信息的新旧程度 |
| 禁止再绑定标记 | 后台错误绑定处置 | 阻止后续同步或入口页自动绑定；本期顾客详情页不提供写入入口 |

### 4.3 KASIKA 字段快照

1. KASIKA 返回的营销字段、状态、标签、自定义字段、负责人等信息保存为完整字段快照。
2. 字段快照用于追溯、差异判断和排查，不直接覆盖 VISTA 主字段。
3. 完整字段快照不能替代 KASIKA `customer_id`、邮箱、`customer_status` 的结构化保存。
4. 完整 KASIKA `customer_data` 快照只进入同步日志详情，不进入顾客详情概要。

### 4.4 展示与敏感信息边界

1. 顾客详情 `概要` tab 需要按 `05B-顾客详情页.md` 展示独立 KASIKA 联动模块，用于查看 KASIKA `customer_id`、KASIKA 邮箱、`customer_status`、绑定状态和最近同步时间 / 结果；本期不提供手工解除绑定入口。
2. KASIKA 关联字段不得混入顾客基础信息模块内部；顾客基础信息区不得展示 KASIKA 同步状态、失败原因或 KASIKA 内部字段。
3. 已绑定 KASIKA 的顾客，顾客详情基础信息区的邮箱字段只读，不允许通过页面编辑覆盖。
4. VISTA 访问密码明文即使因业务需要在 VISTA 侧保存，也不得进入同步日志明细或 KASIKA 快照展示。
5. API KEY、Secret Key、settingID、访问密码明文不得出现在页面错误、Toast、同步日志摘要或接口错误摘要中。

## 5. 触发来源矩阵

| 触发来源 | 触发流程 | 说明 |
| --- | --- | --- |
| 顾客列表页“全量同步检查”按钮 | 批量顾客同步流程 | B 端管理员和销售经理可手动触发一次 KASIKA 顾客全量同步检查，不依赖当前列表勾选项；仅在 4 个 API KEY 完整时可用。销售人员不得通过前端或接口查看或触发。 |
| 系统每小时定时检查 | 批量顾客同步流程 | API 参数完整后，以本项目**已保存的 KASIKA 联动配置最后修改时间**为调度锚点，在 `最后修改时间 + N × 1 小时` 的固定时点触发；每次从 KASIKA 获取当前可取得的顾客数据集合，并由 VISTA 进行本地比对更新 |
| 首次绑定访问字段回写补偿 | 单顾客补偿流程 | 首次绑定已成功但 `VISTAURL` 或适用时的 `VISTAPWD` 写入失败时，仅补偿失败字段 |
| 顾客点击 KASIKA入口页 | KASIKA入口页流程 | 不属于本文批量同步主流程；按 `08-KASIKA入口页与VISTA首次访问开户.md` 执行 |
| 首次绑定后发送自动回复邮件 | 绑定通知流程 | 首次绑定完成且访问字段准备完成后，调用 KASIKA 自动回复邮件 API 触发指定自動返信ID |
| VISTA 删除顾客 | 本地删除记录流程 | 不调用 KASIKA 删除或清空字段接口；如删除对象已绑定 KASIKA，清理 VISTA 侧有效绑定关系，并记录历史绑定、绑定失效和删除结果 |

## 6. KASIKA -> VISTA 批量同步决策树

### 6.1 流程图

```mermaid
flowchart TB
  A["批量触发<br/>手动全量同步检查 / 每小时定时检查"] --> B{"4 个 API KEY 是否完整"}
  B -->|否| B1["不执行同步<br/>不显示手动入口<br/>保留历史状态"]
  B -->|是| C["一次性获取 KASIKA 顾客数据集合"]
  C --> E["VISTA 本地比对并生成更新结果"]

  E --> F{"KASIKA customer_id 是否已绑定 VISTA 顾客"}
  F -->|已绑定| G["更新 KASIKA 结构化字段和字段快照"]
  G --> H{"customer_status 状态权限自动更新是否开启"}
  H -->|开启| I["按 customer_status 配置同名 VISTA 标签"]
  I --> J["按标签权限模板重算权限"]
  H -->|关闭| H1["仅保存 customer_status<br/>不更新标签和权限"]
  J --> Z["记录成功 / 无变化 / 失败"]
  H1 --> Z

  F -->|未绑定| K{"是否存在同邮箱、未绑定、未禁止再绑定的 VISTA 顾客"}
  K -->|唯一命中| L["绑定既有 VISTA 顾客"]
  K -->|无命中| M["新建 VISTA 顾客并生成访问字段"]
  K -->|多重命中 / 已绑定 / 禁止再绑定| N["业务待处理<br/>不自动绑定"]

  L --> O["保存结构化字段和字段快照"]
  M --> O
  O --> P["首次绑定时强制执行<br/>customer_status 同名标签初始化和初始权限判定"]
  P --> Q["首次绑定回写 VISTAURL<br/>按设置回写 VISTAPWD"]
  Q --> R["调用自動返信ID<br/>发送自动回复邮件"]
  R --> S["完成或记录部分失败"]

  E --> T["不扫描 VISTA 未绑定顾客<br/>不向 KASIKA 创建顾客"]
```

### 6.2 获取 KASIKA 顾客数据与比对边界

1. 批量流程以一次性从 KASIKA 获取当前可取得的顾客数据集合为前提，再由 VISTA 系统进行本地比对和更新。
2. 产品需求不定义 KASIKA 数据获取的分页方式、并发方式、接口组合、临时落库、事务边界、处理顺序或重试机制。
3. 批量处理范围以 KASIKA 实际返回并参与本次比对的数据为准，不以 VISTA 当前列表筛选或勾选结果为准。
4. 产品侧只要求最终能够形成每个参与比对顾客的同步结果、字段变化摘要和必要的失败追溯信息。

### 6.3 已绑定 KASIKA 顾客

1. VISTA 本地比对时，通过 KASIKA `customer_id` 判断该 KASIKA 顾客是否已绑定 VISTA 顾客。
2. 如果已有绑定关系：
   - 保存或更新 KASIKA 结构化关联字段。
   - 保存或更新 KASIKA 字段快照。
   - 读取 `customer_status` 字段。
   - 判断 `customer_status` 状态权限自动更新开关。
   - 开关开启时，根据 `customer_status` 字段值校准同名 VISTA 标签；无同名标签时不修改标签、不自动创建标签。
   - 开关开启且校准后标签结果变化时，进入权限判定流程。
   - 开关关闭时，仅保存结构化 `customer_status` 和字段快照，不因后续状态变化更新 VISTA 标签，不触发权限判定。
3. 已绑定顾客的 KASIKA 字段快照更新、`customer_status` 标签配置或权限变化，不触发 KASIKA 顾客资料回写。
4. 已绑定顾客后续变化不触发首次绑定访问字段回写。

### 6.4 未绑定 KASIKA 顾客：匹配已有 VISTA 顾客

1. 如果 KASIKA 顾客没有绑定 VISTA 顾客，系统先检查是否存在邮箱相同、未绑定 KASIKA、且未标记禁止 KASIKA 再绑定的 VISTA 顾客。
2. 如果存在唯一匹配的 VISTA 顾客：
   - 建立 VISTA 顾客与 KASIKA `customer_id` 的绑定关系。
   - 保存 KASIKA 结构化关联字段和字段快照。
   - 无论 `customer_status` 状态权限自动更新开关是否开启，均根据本次 `customer_status` 执行一次同名 VISTA 标签初始化，并触发初始权限判定；无同名标签时不新增标签、不阻塞绑定。
   - 将 VISTA 侧已有的 HOMEVISTA 访问链接写入 KASIKA 的 `VISTAURL`；项目启用访问密码时，将当前有效首次访问密码写入 `VISTAPWD`。
   - 访问字段回写完成后，记录首次绑定结果。
3. 如果邮箱命中多个 VISTA 顾客、候选 VISTA 顾客已绑定其他 KASIKA 顾客，或候选 VISTA 顾客已标记禁止 KASIKA 再绑定，则进入业务待处理，不自动绑定。

### 6.5 未绑定 KASIKA 顾客：新建 VISTA 顾客

1. 如果没有检测到邮箱匹配的未绑定 VISTA 顾客，系统在 VISTA 侧新建顾客。
2. 新建字段至少包括：
   - 姓名。
   - 邮箱。
   - 手机号。
   - KASIKA `customer_id`。
3. VISTA 创建顾客时同步生成 HOMEVISTA 访问 URL；如访问密码设置开关开启，同步生成初始访问密码；访问 URL 有效期为永久。
4. 保存 KASIKA 结构化关联字段和字段快照。
5. 无论 `customer_status` 状态权限自动更新开关是否开启，系统都根据本次 `customer_status` 执行一次同名 VISTA 标签初始化，并触发初始权限判定；无同名标签时不新增标签、不阻塞绑定。
6. VISTA 顾客创建和绑定成功后，将 HOMEVISTA 访问链接写入 KASIKA 的 `VISTAURL`；访问密码设置开关开启时，将首次访问密码写入 `VISTAPWD`，关闭时不回写 `VISTAPWD`。
7. 访问字段回写完成后，记录首次绑定结果。

### 6.6 不处理未绑定 VISTA 顾客

1. 批量流程不扫描 VISTA 侧未绑定 KASIKA 的顾客。
2. VISTA 侧未绑定顾客即使存在邮箱或手机号，也不向 KASIKA 查询、创建或更新顾客。
3. VISTA 顾客文件导入、新增顾客、补充邮箱或手机号，不会触发 KASIKA 顾客创建或覆盖。
4. 后续只有当 KASIKA 同步拉取到对应顾客，并按邮箱命中唯一未绑定且未禁止再绑定的 VISTA 顾客时，才建立绑定关系。

### 6.8 自动与手动同步并发控制

1. 自动定时同步与手动全量同步检查互斥：同一项目同一时刻只允许执行一个同步任务。
2. 自动定时同步以该项目**已保存的 KASIKA 联动配置最后修改时间**为锚点，按 `最后修改时间 + N × 1 小时`（`N` 为正整数）生成后续触发时点；不按所有项目统一整点触发，以分散多项目同时批量同步的性能压力。
3. 仅成功保存 KASIKA 联动配置时才更新该调度锚点；用户在表单中编辑但未保存、保存被校验拦截或保存失败，均不得改变既有自动同步时序。配置保存成功后，从新的最后修改时间重新计算下一次自动同步时间。
4. 自动定时任务触发时也必须使用与手动任务相同的项目级原子任务锁。抢锁成功才创建同步任务；若已有自动或手动同步占用，则跳过本次定时触发，等待该项目下一个固定触发时点，不产生前端提示，也不补跑本次跳过的任务。
5. 手动全量同步检查触发时（管理员或销售经理点击“全量同步检查”），服务端必须以项目为粒度原子检查并占用同步任务锁；若自动定时同步或其他人工同步已占用，不创建新的同步任务。
6. 发生上述冲突时，前端弹窗提示“正在同步kasika数据，请稍后再尝试”，关闭提示后仍停留在顾客列表；不得仅依赖前端按钮禁用判断并发。
7. 同步任务一旦开始，不支持人工停止、取消或再次发起；用户关闭浏览器、关闭弹窗或离开页面均不得影响后台任务继续执行。
8. 批量获取、VISTA 本地比对与批量 CSV 回写属于一个不可中断的后台任务。产品不展示伪进度、处理中数量或预计完成时间；任务的最终结果以后台任务完成后生成的结果汇总和日志为准。
## 7. 绑定时触发邮件通知方案

首次绑定完成后，VISTA 使用 KASIKA 的自动回复邮件功能通知顾客。

### 7.1 配置前提

1. 客户需要先在 KASIKA 侧预先设置自动回复邮件模板。
2. 自动回复邮件模板中可配置 HOMEVISTA 顾客邀请链接和访问密码等变量。
3. VISTA 在 KASIKA 联动配置页保存用于触发该模板的 KASIKA `自動返信ID`。
4. 4 个 API KEY 不完整或自動返信ID 未配置时，不触发绑定通知邮件，但不影响顾客创建、绑定、访问字段回写、`customer_status` 初始标签或初始权限判定。

### 7.2 触发时机

1. 首次绑定完成，并且 HOMEVISTA 访问 URL 已生成后，VISTA 调用 KASIKA 自动回复邮件 API。
2. 项目开启访问密码设置时，访问密码已生成或顾客已设置密码后，才触发自动回复邮件，以保证邮件模板可带入密码。
3. 项目关闭访问密码设置时，邮件模板不得依赖访问密码字段；VISTA 不写入空密码或伪密码。
4. 已绑定顾客再次访问 KASIKA入口页时，不重复触发自动回复邮件。
5. 首次绑定后 VISTA 侧顾客资料、访问密码或绑定状态发生后续变化时，不再次触发自动回复邮件。

### 7.3 发送内容与变量

1. 邮件正文以 KASIKA 侧自動返信ID 对应的模板为准，VISTA 不在本期提供 KASIKA 邮件模板编辑器。
2. 邮件模板可带入 HOMEVISTA 顾客邀请链接。
3. 项目开启访问密码设置时，邮件模板可带入 HOMEVISTA 访问密码。
4. VISTA 只负责在首次绑定后调用指定自動返信ID；邮件正文、标题、发送人、发送对象等邮件表现由 KASIKA 自动回复模板配置决定。

### 7.4 失败处理

1. 自动回复邮件发送失败不回滚 VISTA 顾客创建、绑定保存、访问字段回写、`customer_status` 初始标签或初始权限判定。
2. 发送失败必须记录同步日志，包含 KASIKA customer_id、VISTA 顾客 ID、自動返信ID、触发来源、失败摘要和后续处理状态。
3. 后续补偿只允许继续执行自动回复邮件发送，不得重复创建顾客、重复绑定、重复回写已成功的访问字段或重复配置状态标签。

## 8. `customer_status` 到权限的处理

### 8.1 标签配置

1. 系统读取 KASIKA 返回的 `customer_status` 字段值，并保存为结构化关联字段。
2. 首次绑定时，无论 `customer_status` 状态权限自动更新开关是否开启，都必须尝试执行一次同名 VISTA 标签初始化。
3. 首次绑定时，如字段值为空、缺失或无法解析，则不配置 VISTA 标签，不阻塞绑定或开户，但需记录“首次状态为空 / 无法解析”日志。
4. 首次绑定时，如 VISTA 项目中存在与 `customer_status` 字段值文字相同的标签，则为该 VISTA 顾客配置该标签。
5. 首次绑定时，如不存在同名标签，系统不自动创建标签，不新增该状态标签，不阻塞绑定或开户，但需记录“首次状态无同名标签”日志。
6. 首次绑定完成后，如 `customer_status` 状态权限自动更新开关关闭，则后续处理到此为止：不配置 VISTA 标签，不删除上一状态标签，不触发权限判定；同步日志记录为“状态已保存，标签 / 权限自动更新关闭”。
7. 首次绑定完成后，如开关开启但字段值为空、缺失或无法解析，则不配置 VISTA 标签，不阻塞后续同步。
8. 首次绑定完成后，如开关开启，且 VISTA 项目中存在与 `customer_status` 字段值文字相同的标签，则确保该 VISTA 顾客持有该标签；如果该标签曾被 VISTA 侧人工从顾客身上移除，本次同步会重新补回。
9. 首次绑定完成后，如开关开启，且本次 `customer_status` 与上一轮已保存的 `customer_status` 不一致，系统需要按最新状态更新顾客标签：添加新状态对应的同名标签，并删除上一状态对应的旧标签。
10. 首次绑定完成后，如开关开启但不存在同名标签，系统不自动创建标签，不新增该状态标签；如本次确认为状态变化，仍需删除上一状态对应的旧标签。
11. VISTA 侧管理员新增、编辑、删除标签或在顾客权限页调整顾客标签，均不回写 KASIKA，也不改变 KASIKA `customer_status`。后续同步只在 VISTA 侧按当前 `customer_status` 做轻量校准。

### 8.2 权限计算

1. 首次绑定时，系统必须基于本次 `customer_status` 标签初始化结果触发初始权限判定，不受 `customer_status` 状态权限自动更新开关影响。
2. 首次绑定完成后，仅当 `customer_status` 状态权限自动更新开关开启且标签校准导致顾客标签结果变化后，系统才触发权限判定。
3. 权限判定时，C 端顾客访问权限接口按 `09-C端顾客访问权限接口.md` 的统一规则实时返回可访问内容：标签权限模板并集 + 个人权限追加。
4. 如果 `customer_status` 同名标签命中权限模板，系统按顾客当前标签命中的权限模板并集计算访问权限。
5. 如果未命中标签或命中标签未配置权限模板，系统不额外赋予默认内容；最终访问内容仍按当前标签权限模板并集和个人权限追加计算，结果可以为空。
6. 首次绑定完成后，开关关闭时，系统不因后续 `customer_status` 变化主动重算权限；顾客最终可访问内容仍由其当前已有标签和个人权限追加决定。
7. 标签配置或权限计算失败不应回滚已完成的顾客绑定或访问字段回写结果，但需记录日志。

### 8.3 权限变化边界

1. KASIKA 顾客 `customer_status` 变化后，VISTA 始终更新字段快照和结构化 `customer_status`。
2. 首次绑定时，VISTA 必须根据 `customer_status` 执行一次同名标签初始化和初始权限判定。
3. 首次绑定完成后，仅当 `customer_status` 状态权限自动更新开关开启时，VISTA 才根据当前状态校准同名 VISTA 标签和访问权限。
4. 开关开启时，每次同步处理该顾客都按当前 `customer_status` 校准同名标签；同名标签存在则确保顾客持有该标签，同名标签不存在则不自动创建并记录跳过。
5. 开关开启且 `customer_status` 变化时，标签更新采用加新删旧：添加新状态同名标签，删除上一状态同名标签。
6. 开关关闭时，不因后续状态变化添加新状态标签，不删除上一状态标签，不主动重算权限，也不撤销既有标签或既有权限。
7. 权限变化不默认改变顾客访问 URL。
8. 权限变化不向 KASIKA 回写权限结果或权限摘要。

## 9. 访问字段回写边界

### 9.1 首次绑定回写字段

首次绑定成功后，系统可向 KASIKA 回写：

- `VISTAURL`：HOMEVISTA 访问链接，必须回写。
- `VISTAPWD`：首次访问密码，仅限项目开启访问密码设置时回写。

VISTA 顾客 ID、绑定状态和首次访问完成时间只在 VISTA 内保存和追溯，不回写 KASIKA。

### 9.2 不做 VISTA 主数据反向同步

1. VISTA 创建顾客时，只按 VISTA 既有顾客创建流程生成 HOMEVISTA 访问字段，不向 KASIKA 创建顾客。
2. VISTA 未绑定顾客补充邮箱或手机号时，不向 KASIKA 查询、创建或更新顾客。
3. VISTA 已绑定顾客修改姓名、邮箱、手机号、公司名等基础资料时，不覆盖 KASIKA 顾客基础资料，也不自动改绑 KASIKA 顾客。
4. VISTA 顾客文件导入完成后，不向 KASIKA 创建或更新顾客。

### 9.3 VISTA 修改访问密码

1. VISTA 修改顾客访问密码时，只更新 VISTA 侧当前访问密码，不向 KASIKA 回写新密码明文。
2. 已绑定顾客首次绑定时写入 KASIKA 的 HOMEVISTA 访问密码字段不随 VISTA 后续密码修改自动更新。
3. 如后续需要支持密码变更回写，需作为独立需求重新确认触发条件、覆盖规则和日志规则。

## 10. 错误绑定处置、删除与禁止再绑定

### 10.1 错误绑定处置边界

1. 顾客详情页的 KASIKA 联动模块只展示 KASIKA 关联信息和绑定状态，本期不提供手工解除绑定入口。
2. 本期不提供重新绑定、改绑、手工选择 KASIKA 顾客或手工解除 KASIKA 绑定入口。
3. 如后续确需处理复杂错误绑定，应走后台数据治理、同步日志处置或另立管理恢复需求。
4. 后台处置错误绑定时，VISTA 不应删除该顾客最后一次保存的 KASIKA `customer_id`、KASIKA 邮箱和 `customer_status`，应保留用于同步日志追溯和问题排查。
5. 如后台处置写入“禁止 KASIKA 再绑定”标记，具有该标记的 VISTA 顾客不得作为 KASIKA -> VISTA 同步中的邮箱匹配候选，不得被 KASIKA入口页按同邮箱自动绑定，也不得绑定到其他 KASIKA 顾客账号。
6. 本期不提供恢复绑定、改绑或清除禁止再绑定标记的页面能力。

### 10.2 VISTA 删除顾客

1. VISTA 删除顾客时，不向 KASIKA 删除顾客。
2. VISTA 删除顾客时，也不删除或清空 KASIKA 对应顾客自定义字段中的 HOMEVISTA 访问 URL 和访问密码。
3. 如果该顾客已绑定 KASIKA `customer_id`，系统必须清理该 VISTA 顾客的有效 KASIKA 绑定关系，使该已删除顾客不再作为有效绑定对象参与同步、入口页校验或邮箱匹配。
4. 删除时需要保留历史绑定记录、最后一次保存的 KASIKA `customer_id`、KASIKA 邮箱、`customer_status`、删除操作人、删除时间和绑定失效状态，用于同步日志追溯。
5. 后续如 KASIKA 再次拉取到同一 KASIKA 顾客，系统可按未绑定 KASIKA 顾客重新执行匹配和新建流程，但不得把绑定自动恢复到已删除的原 VISTA 顾客。
6. 如已删除的 VISTA 顾客后续被恢复，恢复操作不得自动恢复原 KASIKA 有效绑定；如与新建顾客形成 1 对多风险，应按绑定异常或业务待处理记录，具体恢复需后台数据治理判断。

## 11. 异常矩阵

| 异常 | 处理规则 | 是否回滚已完成结果 |
| --- | --- | --- |
| KASIKA 拉取失败 | 本次批量同步中止或部分中止；已完成顾客不回滚；未处理数据记录为失败或等待 KASIKA 处理 | 否 |
| 匹配冲突 | 多邮箱命中、候选已绑定、候选禁止再绑定时进入业务待处理，不自动绑定 | 否 |
| VISTA 创建失败 | 不保存绑定关系，不回写 KASIKA；记录失败原因 | 否 |
| 绑定保存失败 | 不重复创建 VISTA 顾客；日志记录已创建的 VISTA 顾客 ID 和 KASIKA `customer_id`，便于后续处理 | 否 |
| URL 回写失败 | 保留 VISTA 顾客和绑定关系；后续只补写失败字段 | 否 |
| 密码回写失败 | 项目开启访问密码时，保留绑定关系；后续只补写密码字段 | 否 |
| 自动回复邮件发送失败 | 保留 VISTA 顾客、绑定关系、访问字段回写结果和权限结果；后续仅补偿邮件发送 | 否 |
| 字段快照保存失败 | 不执行基于该快照的 `customer_status` 标签配置和权限判定；记录失败原因 | 否 |
| `customer_status` 无同名标签 | 不视为接口异常，不作为业务待处理；记录为无变化或跳过 | 否 |
| 权限判定失败 | 不影响已完成的顾客绑定和访问字段回写；记录失败原因 | 否 |
| VISTA 删除已绑定顾客 | 清理 VISTA 侧有效 KASIKA 绑定关系；不删除或清空 KASIKA URL、访问密码和绑定字段；记录原绑定关系、历史字段保留结果、删除结果和绑定失效状态 | 否 |

## 12. 日志与结果分类

日志规则、错误字典和页面摘要统一按 `07-同步日志与追溯.md`。本文仅定义必须覆盖的触发来源、前台展示结果和日志追溯要求，不定义内部处理阶段拆分。

### 12.1 触发来源

- 手动全量同步检查。
- 每小时定时检查。
- 首次绑定访问字段回写补偿。
- 首次绑定自动回复邮件发送或发送补偿。
- KASIKA入口页流程。
- VISTA 删除顾客本地操作。
- 后台错误绑定处置。

### 12.2 前台展示结果

- 同步更新成功。
- 无变化未更新。
- 同步更新失败。

匹配冲突、绑定冲突、权限不足、KASIKA 调用受限、字段写入失败、权限计算失败、部分阶段失败等异常，在前台顾客同步结果中统一归入“同步更新失败”；后台日志可继续记录错误编码、失败原因和处理范围。

### 12.3 后台日志追溯维度

后台日志需要能追溯失败原因、影响对象、触发来源、字段变化和后续处理口径。具体是否拆分为 KASIKA 获取、匹配、VISTA 创建、绑定保存、URL / 密码回写、字段快照保存、`customer_status` 标签配置、权限判定等内部阶段，由研发按实际同步实现设计；产品页面不直接展示这些阶段。

## 13. 验收标准

1. 4 个 API KEY 不完整时，不显示“全量同步检查”按钮，不执行同步或回写。
2. 系统不提供顾客同步控制开关。
3. KASIKA `customer_id`、KASIKA 邮箱、`customer_status` 均被结构化保存，且完整字段快照不能替代这些字段。
4. 已绑定顾客同步时，始终更新快照、结构化 `customer_status` 和日志；仅当 `customer_status` 状态权限自动更新开关开启时，才按当前状态校准 VISTA 标签和权限；不回写 KASIKA。
5. 未绑定 KASIKA 顾客只有在邮箱唯一命中未绑定且未禁止再绑定的 VISTA 顾客时才自动绑定；否则进入业务待处理。
6. 未匹配到 VISTA 顾客时，系统可新建 VISTA 顾客，生成访问字段，完成绑定，并只向 KASIKA 回写 `VISTAURL` 和适用时的 `VISTAPWD`。
7. 首次绑定时，必须根据 `customer_status` 执行一次同名 VISTA 标签初始化和初始权限判定，不受 `customer_status` 状态权限自动更新开关影响。
8. 首次绑定完成后，`customer_status` 状态权限自动更新开关开启时，每次同步处理该顾客都按当前状态校准同名 VISTA 标签；状态变化时按加新删旧更新标签，不存在同名标签时不自动创建标签、不阻塞绑定。
9. 首次绑定完成后，`customer_status` 状态权限自动更新开关关闭时，仅保存状态，不添加新状态标签、不删除上一状态标签、不主动重算权限、不撤销既有标签或既有权限。
10. 权限结果按标签权限模板并集 + 个人权限追加计算。
11. 顾客详情页的 KASIKA 联动模块不提供手工解除绑定、重新绑定或改绑入口；复杂错误绑定如需处理，走后台处置或另立管理恢复需求。
12. VISTA 删除已绑定顾客时，必须清理 VISTA 侧有效 KASIKA 绑定关系；不删除 KASIKA 顾客，不清空 KASIKA 侧 HOMEVISTA 访问 URL 和访问密码；恢复已删除 VISTA 顾客时不得自动恢复原 KASIKA 有效绑定。
13. 首次绑定后可通过 KASIKA 自动回复邮件 API 和配置页保存的自動返信ID 触发邮件，邮件可带入顾客邀请链接和访问密码。
14. 自动回复邮件发送失败不回滚已完成绑定和权限结果，后续仅补偿邮件发送。
15. 所有同步更新失败、无变化未更新、任务锁冲突和任务异常结果，均可在同步日志中追溯到触发来源、对象、原因和后续处理口径；内部处理阶段是否展示或拆分由研发按日志实现设计。

## 14. 修订记录

| 日期 | 修订内容 |
| --- | --- |
| 2026-07-13 | 因 KASIKA 采用“批量获取 → VISTA 比对/绑定 → CSV 批量回写”的不可流式任务，取消手动停止、取消和伪进度；任务一经开始不受关闭页面或弹窗影响。同步入口调整为 B 端管理员和销售经理可见、可发起，销售人员不可见。以项目为粒度增加服务端任务锁，冲突时统一提示“正在同步kasika数据，请稍后再尝试”；任务完成后按实际处理结果写入日志。 |
| 2026-07-13 | 新增自动同步调度规则：以已保存 KASIKA 联动配置最后修改时间为锚点，按该时间起每小时固定间隔触发，以分散多项目同步压力；仅成功保存配置后重置本项目调度时序。自动任务也须抢占项目级任务锁，抢锁失败即跳过本次固定触发，不补跑。 |
| 2026-08-04 | 收紧首次绑定回写边界：只向 KASIKA 的 `VISTAURL` 和适用时的 `VISTAPWD` 回写；VISTA 顾客 ID、绑定状态和首次访问完成时间仅保存在 VISTA。 |