# KASIKA 账号与 VISTA 项目一对一关联限制（B 端补充需求）

## 基本信息

| 项目 | 内容 |
| --- | --- |
| 文档版本 | v0.1 |
| 需求类型 | B 端补充需求 |
| 当前状态 | 待开发 |
| 适用范围 | 已开通 KASIKA 联动功能的 VISTA 项目 |
| 关联模块 | KASIKA 联动配置、访问数据上报、顾客同步、入口绑定、访问字段回写、绑定通知 |

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 | 来源／备注 |
| --- | --- | --- | --- | --- |
| 2026-08-24 | v0.1 | 新建／重大需求变更 | 新增 KASIKA 账号与 VISTA 项目一对一关联限制；PID 和 4 项 API 授权信息分别按同名字段做项目唯一性校验，并补充原子保存、启停占用、运行时保护和恢复规则。 | B 端补充需求；不回改已开发完成的联动管理主体需求。 |

## 1. 背景与目标

现有 KASIKA 联动管理需求内容较多，且主体功能已经开发完成。本需求不重新调整原有页面、同步流程和字段定义，仅补充“一个 KASIKA 账号只能关联一个 VISTA 项目，且一个 VISTA 项目只能关联一个 KASIKA 账号”的限制。

本需求需要同时覆盖两条业务链路：

1. PID 用于 VISTA 向 KASIKA 上报顾客访问、浏览或转化相关数据。
2. 4 项 API 授权信息用于 VISTA 调用 KASIKA 顾客相关能力，包括顾客查询、同步、绑定、回写和通知。

只限制 PID 不能解决 API 数据被错误同步到其他 VISTA 项目的风险，因此两条链路都必须纳入限制。

## 2. 与既有需求的关系

1. 本文是独立补充需求，不把新增规则拆回 `01-KASIKA联动配置管理.md`、`04-统一顾客联动同步流程.md`、`07-同步日志与追溯.md` 和既有测试文档。
2. 既有需求中的页面结构、权限、字段必填、脱敏展示、同步触发和异常处理继续有效。
3. 如既有需求写明“不检查 PID、API KEY、Secret Key 的业务可用性”，仍然不要求 VISTA 验证这些参数能否在 KASIKA 正常使用；但保存和使用前必须增加本文定义的“是否已被其他 VISTA 项目占用”校验。两者不是同一种校验。
4. 当既有需求与本文的一对一关联规则冲突时，仅在“项目唯一性校验”范围内以本文为准。

## 3. 对象与口径

| 对象 | 本需求中的含义 | 唯一性口径 |
| --- | --- | --- |
| VISTA 项目 | 一个独立的 VISTA 项目 | 一个项目只允许保存并启用一套 KASIKA 联动配置 |
| PID | KASIKA 访问数据上报所使用的项目识别信息 | 同一 PID 只允许被一个已启用联动的 VISTA 项目使用 |
| 公司访问密钥 | KASIKA 公司级 API 授权信息之一 | 与其他项目的“公司访问密钥”比较，不得重复 |
| 公司 Secret Key | KASIKA 公司级 API 授权信息之一 | 与其他项目的“公司 Secret Key”比较，不得重复 |
| 用户访问密钥 | KASIKA 用户级 API 授权信息之一 | 与其他项目的“用户访问密钥”比较，不得重复 |
| 用户 Secret Key | KASIKA 用户级 API 授权信息之一 | 与其他项目的“用户 Secret Key”比较，不得重复 |

本地 KASIKA 帮助资料将公司级和用户级授权信息分别提供。考虑到同一公司下可能存在不同用户授权，仅把 4 项授权信息作为一个整体进行比较，可能漏掉部分复用情况。因此，本期采用简单、严格的规则：PID 和 4 项 API 授权信息分别校验是否已被其他项目使用。

## 4. 核心业务规则

### 4.1 一对一关联

1. 一个 VISTA 项目只允许存在一套当前生效的 KASIKA 联动配置。
2. 同一个 PID 不得同时用于两个或更多已启用 KASIKA 联动的 VISTA 项目。
3. 4 项 API 授权信息中的任意一项，只要与其他已启用项目的同名字段相同，即判定为配置冲突。
4. 只比较同名字段：PID 只与 PID 比较，公司访问密钥只与公司访问密钥比较，以此类推。PID 不与 API 授权信息比较，不同名称的授权信息之间也不交叉比较。
5. 当前项目保存自己的原值时，应排除当前项目自身，不得误判为重复。

### 4.2 启用与停用

1. 本需求中的“启用／停用”，以一期运营后台的 KASIKA 联动控制总开关状态为准；B 端配置页不新增停用入口。
2. 只有总开关已启用的项目占用 PID 和 4 项 API 授权信息。
3. 总开关在服务端停用成功后，立即释放上述信息，其他项目可以使用。
4. 停用项目重新启用时，必须一次性重新校验 PID 和全部 4 项 API 授权信息；全部通过后才可切换为启用状态。如任一项已被其他项目占用，则启用失败，原停用状态和原配置保持不变。
5. 停用不删除原配置。再次启用前，管理员仍需处理可能出现的占用冲突。

### 4.3 并发提交

当两个项目在相近时间提交相同 PID 或相同的同名 API 授权信息时，系统必须保证最终只有一个项目成功保存或启用，另一个项目收到冲突提示。两个请求必须分别返回真实结果，不得出现两个项目均提示成功，或页面提示成功但实际未生效的情况。失败方再次提交时，必须重新校验完整的 PID 和 4 项 API 授权信息。

## 5. 保存与启用校验

### 5.1 校验时机

以下操作提交时必须在服务端校验，不能只依赖页面提示：

1. 首次保存 KASIKA 联动配置。
2. 编辑 PID 或任一 API 授权信息后保存。
3. 重新启用 KASIKA 联动。

### 5.2 处理结果

| 校验结果 | 系统处理 |
| --- | --- |
| 无冲突 | 按既有规则继续保存或启用 |
| PID 冲突 | 拒绝本次保存或启用，不覆盖当前已生效配置 |
| 任一 API 授权信息冲突 | 拒绝本次保存或启用，不覆盖当前已生效配置 |
| 同时存在多项冲突 | 拒绝本次保存或启用；页面无需列出所有冲突项目和配置值 |

保存或启用按一次完整操作生效，不允许先写入部分字段再回退：

1. 校验失败时，本次输入不得成为生效配置；当前项目原生效配置、启停状态和页面保存前的展示状态全部保持不变。
2. 校验成功时，本次提交的配置整体成为新的生效配置。
3. 无论成功或失败，均不得意外改变既有同步进度、绑定关系或已保存顾客数据。

### 5.3 页面提示

建议提示文案：

| 场景 | 提示文案 |
| --- | --- |
| PID 冲突 | 该 PID 已被其他 VISTA 项目使用，请确认后重新填写。 |
| API 授权信息冲突 | 该 KASIKA API 配置已被其他 VISTA 项目使用，请确认后重新填写。 |
| 重新启用时发生冲突 | 当前 KASIKA 配置已被其他 VISTA 项目使用，请修改配置后再启用。 |

页面和接口响应不得展示冲突项目名称、项目标识、完整 PID、API 授权信息或其可识别片段，避免通过报错反查其他项目配置。

## 6. 运行时保护

仅在保存时校验不足以覆盖上线前已经存在的重复配置。系统在执行 KASIKA 相关处理前，还必须确认当前项目没有违反本文的一对一规则。

运行时必须以“当前所有总开关已启用项目的生效配置”为判断范围，在每次 KASIKA 相关处理开始前，将当前项目与其他已启用项目的同名字段进行服务端等值校验。不得只依赖保存时留下的校验结果或页面状态。若本次唯一性校验自身不可用或无法得到可信结果，为避免数据进入错误项目，本次处理应停止，并记录“配置校验失败”；恢复后由既有重试入口再次处理。

### 6.1 需要保护的处理

1. PID 相关的访问、浏览和转化数据上报。
2. 手动同步和定时同步。
3. KASIKA 入口顾客查询、开户和绑定。
4. VISTAURL、VISTAPWD 等访问字段回写。
5. 失败补偿或重新处理。
6. 首次绑定后的 KASIKA 自动回复通知。

### 6.2 冲突处理

1. 发现 PID 或任一 API 授权信息冲突时，当前项目的整套 KASIKA 联动均视为不可执行，不继续上报，也不调用 KASIKA 顾客相关能力。
2. 不自动解除任何项目的关联，不自动选择“正确项目”，也不自动把顾客数据迁移到其他项目。
3. 已保存的项目配置、顾客、绑定关系和历史同步结果保持不变，等待管理员处理冲突。
4. 系统应记录“配置冲突导致未执行”，但日志不得包含冲突项目和敏感配置内容。

## 7. 冲突恢复

1. 管理员可修改当前项目配置，或停用实际不再使用该配置的原项目。
2. 修改保存或重新启用时，系统按第 5 章重新校验。
3. 冲突解除后，不自动补做冲突期间被阻断的历史操作：
   - 顾客同步由管理员再次手动触发，或等待下一次定时同步。
   - 顾客入口处理由顾客重新访问后触发。
   - 其他补偿任务按既有重试入口重新发起。
4. 本期不提供冲突项目查询页、自动修复、自动解绑或跨项目迁移工具。

## 8. 权限与安全

1. 本需求不改变既有 B 端权限，仍由有 KASIKA 联动配置权限的管理员操作。
2. 唯一性校验结果只说明“当前输入已被其他项目使用”，不得让管理员查看其他项目的身份或配置。
3. 4 项 API 授权信息继续按既有规则脱敏展示、加密传输和安全存储。
4. 技术实现需要支持对敏感信息做等值判断，但不得为此在页面、接口返回或业务日志中暴露明文；具体实现方式由研发确定。
5. 页面、接口响应和业务日志不得包含 5 项受检配置值的任何子串、哈希值、指纹或其他可用于关联、枚举和反查的信息；错误码也不得映射出冲突项目身份。

## 9. 验收标准

| 编号 | 验收场景 | 预期结果 |
| --- | --- | --- |
| AC-01 | 项目 B 保存项目 A 已使用的 PID | 保存失败；项目 B 不生效；提示不泄露项目 A 或完整配置 |
| AC-02 | 项目 B 分别复用项目 A 的公司访问密钥、公司 Secret Key、用户访问密钥、用户 Secret Key | 每一项单独复用时均保存失败 |
| AC-03 | 两个不同名称字段恰好值相同 | 不因跨字段相同而判定冲突 |
| AC-04 | 项目 A 未修改任何值，重复保存自己的配置 | 可正常保存，不把自身判为冲突 |
| AC-05 | 两个项目同时保存相同 PID 或同名 API 授权信息 | 两个请求完成后，仅一个请求返回成功，且任一时刻只有一个已启用项目实际占用该值；失败项目重新提交时再次校验全部 5 项信息 |
| AC-06 | 项目 A 的运营后台总开关停用成功后，项目 B 使用其原配置 | 停用成功即释放占用，项目 B 可通过校验；项目 A 再次启用时重新校验全部 5 项并被拦截 |
| AC-07 | 上线前已存在重复配置，系统发起上报、同步、入口绑定、回写、补偿或通知 | 相关处理均不执行，不调用 KASIKA；既有数据不被修改 |
| AC-08 | 管理员解除冲突后再次同步，或顾客重新访问入口 | 按既有流程恢复；不自动补做冲突期间的历史操作 |
| AC-09 | 发生冲突后查看页面提示、接口响应和业务日志 | 不出现冲突项目、API 授权信息明文或可识别片段 |
| AC-10 | PID 和 4 项 API 授权信息均未被其他已启用项目使用 | 按既有规则正常保存、启用和执行联动 |
| AC-11 | 运行时唯一性校验不可用或无法得到可信结果 | 本次联动停止，不上报、不调用 KASIKA；记录配置校验失败，恢复后按既有重试入口处理 |

## 10. 影响范围

本补充需求会在以下既有能力中增加校验或阻断点，但不修改原有页面结构和主要流程：

1. KASIKA 联动配置保存与重新启用。
2. PID 访问数据上报。
3. 顾客手动同步与定时同步。
4. KASIKA 入口查询、开户与绑定。
5. 访问字段回写、失败补偿和绑定通知。
6. 配置冲突的安全日志记录。

本期不新增页面、导航、冲突管理中心或新的配置字段。现有配置页复用原有字段错误和提交结果提示，因此不要求同步修改页面原型。

## 11. 非本期范围

1. 不校验 PID 或 API 授权信息在 KASIKA 是否真实有效。
2. 不建立 KASIKA 账号主数据或新增稳定账号 ID。
3. 不定义 KASIKA 密钥轮换、失效或重置流程。
4. 不限制 settingID、自動返信ID 等其他配置项的跨项目复用。
5. 不处理 VISTA 项目删除时的配置迁移或 KASIKA 侧清理。
6. 不自动判断哪个项目应保留配置，也不自动处理历史冲突数据。