# 00-总览与范围

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 | 修改人/来源 |
| --- | --- | --- | --- | --- |
| 2026-07-20 | v0.1 | 重大需求变更 | 删除 KASIKA 顾客同步信息弹窗；同步任务统计由任务结果弹窗承接，顾客级结果统一在同步日志的批次顾客列表查看。 | AI（按需求修改） |

## 1. 文档定位

本文是 KASIKA 二期需求的总览 MRD，用于统一说明本期业务背景、使用者角色、业务场景、产品目标、范围边界、需求拆分和上线前 API 能力确认结论。

后续 `01-11` 文档均围绕本文拆解：

- `00` 说明为什么做、谁使用、在哪些场景使用、整体链路如何运转。
- `01-11` 分别说明配置、标签、权限、`customer_status` 标签配置边界、顾客页面、同步流程、日志、KASIKA入口页、C 端顾客访问权限接口和设计交付。

本文只写产品需求和业务流程，不展开具体技术实现。涉及 KASIKA API 能力、邮件变量、字段写入、变更检测、分页和批处理结果等条件，仍以研发实测或 KASIKA 官方确认为准。

## 2. 背景与问题

HOME VISTA 和 KASIKA 当前分别承担不同业务角色：

- KASIKA 负责顾客获取、资料请求、来场预约、自动回复邮件、场景邮件和客户经营。
- HOME VISTA 负责项目内容访问、资料展示、顾客访问 URL、访问密码和内容权限控制。

本期联动要解决的是：顾客在 KASIKA 侧产生后，如何顺畅进入 HOME VISTA，并且后续能根据 KASIKA 顾客属性变化自动调整 HOME VISTA 的访问内容。

当前存在以下问题：

1. KASIKA 自动回复邮件是即时发送，不能等待 VISTA 后续同步生成访问 URL 和密码。
2. 如果只依赖 VISTA 同步后回写 URL / 密码，再等待 KASIKA 定时类邮件触达，首次触达可能延迟到 1 天后；本期改为首次绑定后通过 KASIKA 自动回复邮件 API 触发指定自動返信ID。
3. KASIKA 顾客和 VISTA 顾客之间需要稳定绑定，否则后续字段同步、权限判定和追溯都无法闭环。
4. 顾客关注户型、来场预约、客户阶段、标签、自定义字段等信息主要存在 KASIKA 侧，VISTA 需要利用这些信息判断适合开放哪些内容。
5. 顾客主数据以 KASIKA 为来源，VISTA 侧新增、补充或修改的顾客资料不作为 KASIKA 顾客创建或覆盖来源。
6. 同步失败、匹配冲突、字段写入失败、权限判定失败等情况需要可追溯，管理员需要知道失败发生在哪个阶段、影响哪个顾客、下一步应如何处理。

## 3. 本期目标

本期目标不是完整复制 KASIKA 的顾客体系，而是建立必要的顾客联动和权限联动能力。

本期需要实现：

1. B 端管理员可以在 VISTA 项目中自助配置 KASIKA 联动。
2. KASIKA 顾客可以通过自动回复邮件中的 VISTA 项目入口，首次访问时完成邮箱校验、按项目设置决定是否设置密码，并创建或绑定 VISTA 顾客。
3. 顾客未点击 KASIKA入口页时，系统仍可通过同步兜底生成 VISTA URL / 初始密码，并通过 KASIKA 自动回复邮件 API 触达。
4. KASIKA customer_id 与 VISTA 顾客建立稳定绑定。
5. VISTA 可以读取 KASIKA 顾客字段，单独保存 KASIKA `customer_id`、邮箱和 `customer_status`，并根据 `customer_status` 字段配置同名 VISTA 标签。
6. VISTA 可以根据顾客当前 VISTA 标签命中的权限模板并集计算顾客可访问内容。
7. KASIKA 顾客属性变化后，VISTA 可以更新字段快照；首次绑定后的 `customer_status` 变化是否继续自动更新 VISTA 标签和访问权限，由 KASIKA 联动配置页的 `customer_status` 状态权限自动更新开关控制。
8. VISTA 只在首次绑定成功时，将 HOMEVISTA 访问 URL 写入 KASIKA 的 `VISTAURL` 字段；项目启用访问密码时，再将首次访问密码写入 `VISTAPWD` 字段。VISTA 顾客 ID、绑定状态、首次访问完成时间和其他 VISTA 顾客主数据均不回写 KASIKA；双方绑定信息只在 VISTA 内保存和追溯。
9. 同步、绑定、`customer_status` 标签配置、权限判定、删除和异常处理均有日志可追溯。
10. 顾客详情页需要展示 KASIKA 联动模块，用于查看当前顾客与 KASIKA 的关联字段和关联状态；KASIKA 绑定关系同时参与邮箱只读、入口校验、权限标签补充和日志追溯。本期不提供详情页手工解除绑定入口。

最终目标：

> 让 KASIKA 中的顾客可以顺畅进入 HOME VISTA 内容访问链路；让 HOME VISTA 根据 KASIKA 顾客属性自动完成合理的访问权限设定；并在首次绑定时将 HOMEVISTA 访问链接和适用时的首次访问密码回写 KASIKA，支撑 KASIKA 邮件触达。

## 4. 使用者角色

| 角色 | 使用场景 | 目标 |
| --- | --- | --- |
| B 端管理员 | 项目上线前配置 KASIKA 联动；上线后查看同步日志和异常 | 开通联动、维护 API KEY、复制 VISTA 项目入口 URL、确认同步状态和失败原因 |
| 销售经理 | 管理项目顾客、查看联动状态、确认顾客访问权限是否合理 | 通过顾客列表、标签、权限状态和日志判断客户经营是否正常 |
| 销售人员 | 新增或维护 VISTA 顾客，查看顾客是否与 KASIKA 绑定，调整顾客标签或权限 | 保持 VISTA 顾客资料可用，让顾客能看到适合的 VISTA 内容；不通过 VISTA 顾客资料反向覆盖 KASIKA |
| 顾客 | 从 KASIKA 自动回复邮件或后续邮件进入 VISTA | 完成首次访问设置，查看适合自己的项目内容 |
| 系统任务 | 定时同步 KASIKA 顾客、处理必要访问字段回写、计算权限、记录日志 | 自动完成顾客绑定、字段快照、`customer_status` 标签配置、权限判定、受控回写和异常追溯 |

## 5. 业务场景总览

### 5.1 场景 A：管理员开通 KASIKA 联动

谁：B 端管理员。

在什么场景：项目准备使用 KASIKA 与 HOME VISTA 联动时。

做什么：

1. 进入 KASIKA 联动配置页。
2. 配置 PID、4 个 API KEY、顾客批量导出 API settingID、顾客批量导入 API settingID。
3. 确认“是否需要 VISTA 访问密码”开关，默认开启。
4. 复制 VISTA 项目入口 URL，交给客户配置到 KASIKA 自动回复邮件模板。
5. 后续从同页进入同步日志，查看同步结果和异常。

要实现什么目标：

- 让 VISTA 项目具备调用 KASIKA API、同步顾客、读取字段、回写访问字段和支持 KASIKA入口页的基础能力。

设计边界：

- 不新增 KASIKA入口页独立开关；只要 4 个 API KEY 完整且可通过 Host 识别唯一 VISTA 项目，即支持 KASIKA入口页。
- VISTA 项目入口 URL 使用当前项目唯一子域名识别 VISTA 项目，复制出的 URL 不包含具体 `kasikacid`。
- KASIKA 顾客 ID 参数 `kasikacid` 由 KASIKA 邮件模板或发送机制在实际发信时追加 / 插入。

### 5.2 场景 B：KASIKA 新顾客通过 KASIKA入口页进入 VISTA

谁：顾客。

在什么场景：顾客在 KASIKA 侧提交资料请求、来场预约或事前登记后，收到 KASIKA 自动回复邮件。

做什么：

1. 顾客点击邮件中的 VISTA 项目入口。
2. VISTA 根据访问 Host 找到项目和 KASIKA API 配置。
3. VISTA 根据入口参数 `kasikacid` 取得 KASIKA 顾客信息。
4. 顾客在 C 端首次访问页面输入登记邮箱，并根据项目设置决定是否设置 VISTA 密码。
5. VISTA 创建或激活顾客，绑定 KASIKA customer_id。
6. VISTA 保存 KASIKA 字段快照，根据 `customer_status` 配置同名 VISTA 标签并执行初始权限判定。
7. 顾客进入 VISTA 内容页。

要实现什么目标：

- 顾客无需等待同步任务和定时类邮件，能在首次触达时尽快进入 VISTA。
- 首次进入时即可根据 KASIKA 顾客信息分配合适的初始内容权限。

设计边界：

- C 端只设计一个“首次访问设置页”，通过状态覆盖加载、本人校验、可选密码设置、完成和异常，不拆多个页面。
- 加载和通用错误状态不得展示具体顾客姓名、KASIKA customer_id 或权限判定结果。
- 本期固定使用邮箱校验，不提供其他本人校验方式配置。

### 5.3 场景 C：顾客未点击 KASIKA入口页时同步兜底

谁：系统任务、B 端管理员。

在什么场景：顾客没有点击 KASIKA 自动回复邮件中的 KASIKA入口页，或者客户仍希望在同步兜底绑定完成后由 KASIKA 邮件继续触达。

做什么：

1. 4 个 API KEY 完整时，系统定时同步，或销售经理点击顾客列表页“全量同步检查”；KASIKA 联动配置和完整同步日志仅 B 端管理员可操作或查看，销售人员不具备上述任一权限。
2. 系统从 KASIKA 拉取新顾客或变化顾客。
3. 对尚未绑定的 KASIKA 顾客，系统匹配现有 VISTA 顾客；无法匹配时创建 VISTA 顾客。
4. VISTA 生成访问 URL 和初始密码。
5. VISTA 将访问 URL 和初始密码写回 KASIKA 顾客字段。
6. 写入成功后，VISTA 调用 KASIKA 自动回复邮件 API，并传入客户预先配置的自動返信ID。
7. KASIKA 侧根据该自動返信ID 对应的自动回复模板发送邮件，邮件可带入 VISTA URL 和密码。

要实现什么目标：

- 即使顾客未点击 KASIKA入口页，也能通过 KASIKA 自动回复邮件获得 VISTA 访问方式。
- KASIKA入口页和同步兜底形成两条首次触达路径。

设计边界：

- 绑定通知通过 KASIKA 自動返信ID 触发自动回复邮件，不再依赖追加触发类 KASIKA 顾客标签。
- 如果顾客已通过 KASIKA入口页设置过密码，同步流程不得生成随机初始密码覆盖该密码；仅在该顾客首次绑定访问字段回写时，以顾客当前有效密码写入 KASIKA 访问密码字段。
- 本期不提供顾客信息同步控制开关；如 4 个 API KEY 不完整，则不执行同步兜底路径，也不提供手动“全量同步检查”兜底。

### 5.4 场景 D：KASIKA 顾客属性同步后校准 VISTA 权限

谁：系统任务、销售经理、销售人员。

在什么场景：KASIKA 顾客的 `customer_status` 被同步处理；可能是状态发生变化，也可能是 VISTA 侧曾人工调整标签后需要按当前状态校准。

做什么：

1. 4 个 API KEY 完整时，VISTA 在定时同步或全量同步检查中取得最新 KASIKA 顾客字段。
2. 系统保存 KASIKA 字段快照，并单独更新该顾客的 KASIKA `customer_id`、邮箱和 `customer_status`。
3. 系统根据单独保存的 `customer_status` 字段值和配置页的 `customer_status` 状态权限自动更新开关决定是否校准同名 VISTA 顾客标签。
4. 开关开启时，每次处理该顾客都按当前 `customer_status` 校准同名 VISTA 标签：同名标签存在则确保顾客持有该标签；同名标签不存在则不自动创建，仅记录跳过日志。
5. 开关开启且 `customer_status` 从旧状态变为新状态时，添加新状态对应的同名标签，并删除上一状态对应的旧标签；开关关闭时，仅保存字段和日志，不主动更新标签或权限。
6. 标签权限模板根据顾客当前标签重新计算访问权限。
7. 顾客继续使用原 VISTA 访问链接，但能看到的内容可能随权限变化而变化。

要实现什么目标：

- 让顾客访问内容跟随 KASIKA 顾客状态变化自动调整。
- 减少销售人员手动逐个调整权限的成本。

设计边界：

- 权限变化不默认改变顾客访问 URL。
- 首次绑定时必须执行一次 `customer_status` 同名标签初始化和初始权限判定；首次绑定后的状态标签校准和权限更新，由配置页开关控制。
- 本期不把 VISTA 权限结果或权限摘要回写到 KASIKA。
- 本期不由 VISTA 反向维护 KASIKA 顾客标签。
- VISTA 侧管理员可以继续按 VISTA 原有标签体系新增、编辑、删除标签或调整顾客标签；这些操作不回写 KASIKA。后续同步只在 VISTA 侧按当前 `customer_status` 做轻量校准。
- 4 个 API KEY 不完整或 KASIKA API 调用失败时，不从 KASIKA 拉取顾客字段快照，因此不会因 KASIKA 顾客状态变化触发 VISTA 标签和权限更新。

### 5.5 场景 E：HOMEVISTA 访问字段回写 KASIKA

谁：销售人员、系统任务。

在什么场景：KASIKA 顾客与 VISTA 顾客首次绑定成功，需要让 KASIKA 侧邮件／运营链路获得 HOMEVISTA 访问链接，以及项目启用访问密码时的首次访问密码。

做什么：

1. 4 个 API KEY 完整时，系统在首次绑定成功后向 KASIKA 的 `VISTAURL` 字段写入 HOMEVISTA 访问链接；项目启用访问密码时，再向 `VISTAPWD` 字段写入首次访问密码。
2. 首次绑定完成且访问字段准备完成后，通过 KASIKA 自动回复邮件 API 和配置页保存的自動返信ID 触发顾客通知邮件。
3. KASIKA入口页路径中，如项目要求访问密码且顾客自行设置密码，允许将顾客自设密码回写到 KASIKA 访问密码字段；如项目关闭访问密码设置，则不回写访问密码。
4. VISTA 顾客 ID、绑定状态和首次访问完成时间只在 VISTA 内保存，不回写 KASIKA。首次绑定完成后，VISTA 侧顾客资料或访问密码发生变化时，也不再次回写 KASIKA。
5. VISTA 删除已绑定顾客时，不删除、不清空 KASIKA 侧 HOMEVISTA 访问 URL 和访问密码；VISTA 侧必须清理该顾客的有效 KASIKA 绑定关系，并记录删除与绑定失效状态。
6. 本期顾客详情页不提供手动解除 KASIKA 绑定能力；如后续确需处理错误绑定，应另立后台处置或管理恢复需求。

要实现什么目标：

- 让 KASIKA 邮件和运营链路可以使用 HOMEVISTA 访问字段。
- 让 KASIKA 邮件可以取得访问方式，同时由 VISTA 保持双方顾客绑定关系、绑定失效状态和访问字段处理结果可追溯。

设计边界：

- 4 个 API KEY 不完整时，`04` 同步主流程中的 VISTA 本地操作不查询、不创建、不更新、不删除或清空 KASIKA 顾客数据；KASIKA入口页按 `08` 独立执行。
- VISTA 侧新增顾客、补充邮箱或手机号、修改姓名、电话、公司名等基础资料，均不向 KASIKA 创建或覆盖顾客。
- VISTA 删除顾客不清空 KASIKA 侧历史访问字段，但会清理 VISTA 侧有效 KASIKA 绑定关系，避免删除后新建绑定、再恢复旧顾客导致 1 对多绑定异常。
- 本期不提供 VISTA 端手工选择并绑定 KASIKA 顾客的入口。

### 5.6 场景 F：管理员处理异常和追溯日志

谁：B 端管理员、销售经理。

在什么场景：同步、绑定、`customer_status` 标签配置、权限判定、KASIKA入口页或回写发生失败、冲突、待处理或部分失败。

做什么：

1. 页面展示简要失败摘要和下一步动作。
2. 同步日志记录完整失败阶段、对象、触发来源、结果分类和错误编码。
3. 管理员根据日志修正源数据、走后台错误绑定处置、补齐配置或等待系统后续流程重新检查。

要实现什么目标：

- 让异常可定位、可解释、可追溯。
- 避免失败只停留在接口错误，无法被业务方理解。

设计边界：

- 本期不提供前端重试入口。
- 配置页保存成功、保存失败、新增、修改、清空不写入同步日志。
- 删除类失败只记录失败结果和失败原因，不回滚 VISTA 删除结果。

## 6. 端到端业务流程概览

### 6.1 整体链路图

```mermaid
flowchart LR
  A["B端管理员<br/>配置KASIKA联动"] --> B["KASIKA侧产生顾客<br/>资料请求 / 来场预约 / 事前登记"]
  B --> C{"顾客是否点击<br/>自动回复邮件入口"}

  C -->|点击| D["C端首次访问页<br/>邮箱校验 + 可选密码设置"]
  D --> E["VISTA创建或激活顾客<br/>绑定KASIKA customer_id"]
  E --> F["保存KASIKA字段快照"]
  F --> G["customer_status配置同名VISTA标签"]
  G --> H["标签权限模板<br/>计算访问权限"]
  H --> I["顾客进入VISTA内容"]

  C -->|未点击| J["定时同步 / 全量同步检查"]
  J --> K["发现未绑定KASIKA顾客"]
  K --> L["VISTA预创建顾客<br/>生成URL和初始密码"]
  L --> M["回写KASIKA字段<br/>调用自動返信ID"]
  M --> N["KASIKA自动回复邮件兜底触达"]
  N --> I

  B --> O["后续KASIKA顾客属性变化"]
  O --> F

  D -.失败.-> P["错误提示 / 日志"]
  J -.失败或冲突.-> P
  M -.部分失败.-> P
  H -.权限计算失败.-> P
```

### 6.2 首次触达双路径

| 路径 | 触发时机 | 主要动作 | 目标 |
| --- | --- | --- | --- |
| KASIKA入口页路径 | KASIKA 自动回复邮件即时发送后，顾客点击入口 | C 端邮箱校验、可选密码设置、创建或激活 VISTA 顾客、绑定 KASIKA customer_id、计算初始权限 | 让顾客尽快进入 VISTA |
| 同步兜底路径 | 顾客未点击 KASIKA入口页，后续由同步发现并首次绑定新顾客 | VISTA 生成 URL / 初始密码，首次绑定时回写 KASIKA，并通过 KASIKA 自動返信ID 触发自动回复邮件 | 保证未点击顾客仍可被触达 |

### 6.3 权限更新路径

```mermaid
flowchart LR
  A["KASIKA顾客属性变化"] --> B["VISTA同步取得字段"]
  B --> C["保存第三方字段快照"]
  C --> D["读取customer_status"]
  D --> E["配置同名VISTA标签"]
  E --> F["标签权限模板"]
  F --> G["计算最终访问权限"]
  G --> H["顾客访问内容变化"]
```

## 7. 同步规则概要

1. 本期统一使用一套“顾客联动同步流程”，不按产品功能拆成多个同步模块。
2. 批量同步用于从 KASIKA 拉取增量或全量顾客，并在 VISTA 侧完成匹配、创建、绑定、字段快照、`customer_status` 标签配置和权限判定。
3. 本期不做 VISTA 顾客主数据到 KASIKA 的同步；VISTA 创建顾客、补充邮箱或手机号、修改基础资料、删除顾客均不触发 KASIKA 顾客创建或覆盖。
4. `KASIKA -> VISTA` 表示顾客主数据同步方向；首次绑定访问字段回写只包括 `VISTAURL` 和适用时的 `VISTAPWD`，日志同时记录 VISTA 内部绑定状态和自動返信ID 调用结果，但不把这些内部信息写入 KASIKA，也不表示 VISTA 顾客主数据同步。
5. 本期前端只提供一个手动同步入口：顾客列表页的“全量同步检查”按钮；该按钮仅在 4 个 API KEY 完整时可用；不提供单个顾客手动同步、复选框批量同步或详情页手动同步。
6. 本期不提供 VISTA 端手工选择并绑定 KASIKA 顾客的入口。
7. 自动匹配失败、匹配冲突或历史顾客补绑定无法自动完成时，只进入待处理或绑定异常，由管理员修正源数据或走后台处置流程；本期不提供手工选择绑定、重新绑定或改绑入口。

## 8. 权限规则概要

1. VISTA 标签是本期权限判定的核心对象。
2. 本期权限联动只使用 KASIKA `customer_status` 字段配置同名 VISTA 标签。
3. 每个 VISTA 标签可以配置一个标签权限模板。
4. 顾客拥有多个已配置权限模板的标签时，最终权限按标签权限模板并集计算。
5. 单个顾客仍可手动追加个人访问内容；本期不支持在顾客权限页单独删除标签权限模板已经赋予的内容。
6. 权限变化不改变顾客访问 URL，只改变该 URL 背后的可访问内容。
7. C 端顾客访问权限接口必须按“标签权限模板并集 + 个人权限追加”实时返回可访问内容；不得只读取顾客单独权限或忽略标签模板并集。
8. 户型图与样板间、内容与导航菜单之间的既有关联规则继续生效，不受权限来源是标签模板还是个人追加影响。
9. `customer_status` 无同名标签、字段为空或配置失败时，不新增状态标签；最终访问内容仍按当前标签权限模板并集和个人权限追加实时计算，结果可以为空。
10. 本期不把 VISTA 权限结果或权限摘要回写 KASIKA。

## 9. 页面与模块范围

| 页面/模块 | 本期范围 |
| --- | --- |
| KASIKA 联动配置 | PID、4 个 API KEY、顾客批量导出 API settingID、顾客批量导入 API settingID、绑定通知自動返信ID、VISTA 访问密码设置开关、VISTA 项目入口 URL 只读复制字段、帮助说明、同步日志入口 |
| 第三方字段映射 / 权限映射 | 本期注释保留，不开发；入口隐藏或注释，不向 B 端管理员展示 |
| 标签管理 | 新增、编辑、删除、停用 VISTA 顾客标签 |
| 标签权限模板 | 为 VISTA 顾客标签配置可访问内容权限 |
| 顾客列表 | 沿用现有列表，仅新增标签显示；不展示 KASIKA 专用列；4 个 API KEY 完整时显示“全量同步检查”按钮 |
| 新增顾客 | 录入 VISTA 顾客基础资料，并在顾客情报模块下方选择初始标签；新增保存不向 KASIKA 创建或更新顾客 |
| VISTA 顾客文件导入与结果弹窗 / 结果面板 | 展示 VISTA 导入新增、更新、标签写入和失败结果；导入完成后不因 VISTA 顾客导入向 KASIKA 创建或更新顾客 |
| 同步任务结果弹窗 / 同步日志 | 任务结果弹窗展示批次处理统计；同步日志的批次顾客列表展示姓名、邮箱、KASIKA ID、VISTA ID 和合并后的同步结果，不提供顾客同步详情弹窗 |
| 顾客详情 / 编辑 | 沿用既有顾客基础信息编辑；概要 tab 展示 KASIKA 联动模块、当前标签和访问统计；KASIKA 绑定顾客邮箱只读 |
| 顾客权限设置 | 在顾客详情 `権限` / `編集` tab 中编辑 VISTA 标签、标签权限模板联动结果和个人权限追加；不支持单独删除标签模板已赋予权限；不在权限 tab 编辑 KASIKA 绑定关系 |
| KASIKA 联动管理 - 同步日志 | 仅 B 端管理员可进入，查看顾客同步、字段快照、权限计算、删除导致的绑定失效、有效绑定关系清理和失败明细 |
| kasika入口页 | KASIKA入口页打开后的单页多状态页面，覆盖加载、本人校验、可选密码设置、完成和通用错误 |

## 10. 需求拆分纲要

| 文档 | 承接内容 |
| --- | --- |
| `01-KASIKA联动配置管理.md` | KASIKA 配置页、PID/API KEY、settingID、绑定通知自動返信ID、VISTA 访问密码设置开关、VISTA 项目入口 URL、关闭规则 |
| `02-顾客标签管理.md` | VISTA 顾客标签的新增、编辑、停用、删除和顾客标签维护 |
| `03-标签权限模板.md` | 标签权限模板、模板并集计算、模板影响范围 |
| `04-统一顾客联动同步流程.md` | 横跨 `05` 顾客页面的 KASIKA 同步事实源；定义 KASIKA 到 VISTA 的顾客同步、绑定、匹配、VISTA 创建、VISTA 侧新增保存信息清单、字段快照、受控回写、同步兜底、失败处理 |
| `05A-顾客列表页.md` | 顾客列表、导入结果、全量同步检查入口、同步任务弹窗 |
| `05B-顾客详情页.md` | 顾客详情概要、本地编辑/删除、KASIKA 绑定顾客邮箱只读、标签和权限摘要 |
| `05C-顾客权限页.md` | 顾客标签编辑、权限模板合成、个人权限追加、最终权限 |
| `05D-新增顾客.md` | 新增 VISTA 顾客、初始标签选择、新增保存边界 |
| `07-同步日志与追溯.md` | 同步日志、错误编码、失败摘要、下一步动作、追溯字段 |
| `08-KASIKA入口页与VISTA首次访问开户.md` | KASIKA 自动回复邮件中的 KASIKA入口页、C 端首次访问、邮箱校验、可选密码设置、KASIKA入口页流程 |
| `09-C端顾客访问权限接口.md` | C 端顾客访问 HOME VISTA 内容时的权限接口、标签模板并集、个人权限追加和兜底规则 |
| `bak-04-第三方字段映射与权限判定.md` | 备份文档；本期不开发三方映射页，仅保留 `customer_status` 同名标签配置和页面入口注释边界说明 |

## 11. 数据对象概要

| 数据对象 | 说明 |
| --- | --- |
| KASIKA 联动配置 | PID、API KEY、导出 / 导入 settingID、绑定通知自動返信ID、VISTA 访问密码设置开关、配置保存状态 |
| VISTA 项目入口 URL | 由 VISTA 项目生成，展示在 KASIKA 联动配置页；使用项目唯一子域名识别项目，不包含具体 `kasikacid`，由 KASIKA 邮件侧补入 `kasikacid` |
| KASIKA customer_id 绑定 | VISTA 顾客 ID 与 KASIKA customer_id 的绑定关系、绑定状态和异常状态 |
| KASIKA 关联信息 | VISTA 侧为每个相关顾客保存的 KASIKA `customer_id`、邮箱、`customer_status`、绑定状态、更新时间；用于顾客详情 KASIKA 联动模块展示、入口校验、权限标签补充和日志追溯 |
| VISTA 顾客 | HOME VISTA 内部顾客数据、访问 URL、访问密码、访问权限 |
| VISTA 顾客标签 | VISTA 通用标签，可由人工维护或 `customer_status` 同名标签配置生成 |
| 标签权限模板 | 标签对应的可访问内容权限，覆盖现有 VISTA 顾客权限设置页支持的可访问内容对象 |
| KASIKA 字段快照 | 从 KASIKA 同步到 VISTA 的顾客字段值、字段来源、同步时间和批次 |
| KASIKA 同步摘要 | 最近同步结果、处理阶段、失败原因、下一步动作、后续处理状态和来源批次；用于同步日志追溯，不在顾客详情页展示 |
| `customer_status` 标签配置 | 根据 KASIKA `customer_status` 字段值匹配 VISTA 同名标签 |
| 禁止 KASIKA 再绑定 | 后台处置错误绑定时可写入的 VISTA 顾客标记；后续同步、全量同步检查和 KASIKA入口页不得将该顾客绑定到其他 KASIKA 顾客账号；本期顾客详情页不提供写入入口 |
| KASIKA 回写结果 | 首次绑定时 `VISTAURL` 和适用时的 `VISTAPWD` 写入 KASIKA 的处理结果；日志记录成功／失败，不展示访问密码明文；VISTA 顾客 ID、绑定状态和首次访问完成时间不回写 |
| 权限判定结果 | 根据 VISTA 标签和标签权限模板计算出的顾客最终访问权限 |
| 同步任务 | 系统自动触发或由“全量同步检查”触发的同步批次 |
| 同步日志 | 记录顾客同步、字段快照、权限计算、删除导致的绑定失效、有效绑定关系清理和失败原因 |

## 12. 非目标

本期不做：

1. 不做内部安全管理、外部安全登录、设备限制。
2. 不重新设计、重新开发或重新验收一期已完成的浏览记录 / 顾客访问行为上报能力。
3. 不完整复制 KASIKA 顾客字段体系。
4. 不在联动配置页让运营人员手动维护 KASIKA 自定义字段名。
5. 不在 B 端逐项目配置或编辑 `application_id`。
6. 不假设 KASIKA 主动调用 HOME VISTA 接口。
7. 不实现无 API 支撑的实时 KASIKA 变更推送。
8. 不提供 VISTA 端手工选择并绑定 KASIKA 顾客的入口。
9. 不提供单个顾客手动同步、复选框批量同步或详情页手动同步。
10. 不实现长期免密码访问链接。
11. 不在入口页面直接展示系统生成的明文初始密码。
12. 不把 VISTA 权限结果或权限摘要回写 KASIKA。
13. 不由 VISTA 反向维护 KASIKA 顾客标签。
14. 不做只适配 KASIKA、未来第三方不可复用的权限方案。
15. 不从 VISTA 向 KASIKA 创建顾客或覆盖 KASIKA 顾客基础资料。
16. 不因 VISTA 顾客删除而删除或清空 KASIKA 侧 HOMEVISTA 访问 URL 和访问密码。
17. 本期不开发第三方字段映射 / 权限映射页面，入口只注释保留。
18. 不把 VISTA 顾客 ID、绑定状态或首次访问完成时间回写 KASIKA。

## 13. 上线前 API 能力确认结论

本期 KASIKA 联动依赖的 API 能力、邮件变量能力、批处理限制、数据取得范围和配置前置条件均已确认。当前无剩余待确认 API 能力风险。

1. KASIKA 自动回复邮件可以在实际发信时插入 KASIKA customer_id，并形成 `kasikacid={KASIKA顾客ID}`，用于 `08` 的 KASIKA入口页识别。
2. KASIKA 自动回复邮件为即时发送；本期通过 KASIKA入口页解决即时触达，未点击入口的顾客再由同步兜底和后续邮件触达覆盖。
3. `customer_custom_fields` 的字段定义、写入校验和邮件变量使用能力已确认；客户侧需按约定预先完成 KASIKA 自定义字段和邮件模板配置。
4. KASIKA 自动回复邮件 API 与自動返信ID 可用于首次绑定后的顾客通知；VISTA 只负责调用指定自動返信ID，邮件正文和变量配置由 KASIKA 侧模板决定。
5. KASIKA 顾客数据取得范围、批处理并发限制、处理状态返回和主数据 / 字段定义列表 API 的有无均已确认；同步实现按 `04` 和 `07` 的既定口径处理。

## 14. 修订记录

| 日期 | 修订内容 |
| --- | --- |
| 2026-07-13 | 明确 KASIKA 角色权限：销售经理负责手动全量同步检查；B 端管理员负责联动配置和完整同步日志；销售人员禁止上述操作。 |
| 2026-08-04 | 明确首次绑定只向 KASIKA 的 `VISTAURL` 和适用时的 `VISTAPWD` 两个承接字段回写；VISTA 顾客 ID、绑定状态和首次访问完成时间仅在 VISTA 内保存，不回写 KASIKA。 |