# 02-顾客标签管理

## 1. 模块定位

本模块只定义 VISTA 顾客标签列表页（左侧导航：标签管理页）的交互和规则。

### 本模块负责

- 标签定义的新增、编辑与删除。
- 标签在页面列表中的展示、筛选与基础操作入口。
- 在标签列表中集中展示标签及其对应权限模板的编辑入口。
- 按当前标签管理页原型触发的标签编辑、权限编辑、删除标签等动作。

### 本模块不包含

- `customer_status` 同名标签配置边界和本期不开发三方映射页的说明（见 `bak-04-第三方字段映射与权限判定.md`）。
- 标签权限模板的新增、编辑、权限公式与实时生效规则（见 `03-标签权限模板.md`）。
- 同步流程触发、字段主权、日志与失败处理（见 `04-统一顾客联动同步流程.md`、`07-同步日志与追溯.md`）。

## 2. 页面范围

| 项目 | 内容 |
| --- | --- |
| 用例名称 | 管理 VISTA 顾客标签 |
| 操作者 | B 端管理员 |
| 页面范围 | 左侧导航 - 标签管理页 |

## 3. 需求细节

1. 标签管理页顶部提供 `＋ 标签添加` 按钮，点击后打开新增弹窗。
2. 新增弹窗只包含 `标签名` 输入框。
3. 标签名必填。
4. 标签名最大长度 30 字符。
5. 允许使用输入时自动去首尾空白；提交时按标准化后的标签名进行判断。
6. 标签名称在当前项目内去重（按标准化后（trim + 大小写不敏感）比较）。重复提交提示：`同名标签不可重复添加`。
7. 标签列表需展示以下列：标签名、使用中顾客、权限模板、最终更新、操作。
8. 标签列表行内操作区只保留一行按钮，按钮顺序固定为：`标签编辑`、`权限编辑`、`删除`。
9. `标签编辑` 打开标签名编辑弹窗；保存时沿用标签名必填、30 字符上限、同名不可重复规则。编辑后需同步更新顾客已持有的标签显示名称和该标签对应模板的标签名称。
10. `权限编辑` 跳转到 `标签权限模板设定` 页面，并带入当前标签；若当前标签尚未配置权限模板，则进入该标签的模板创建 / 编辑状态。
11. 标签管理页不再提供标签停用 / 恢复入口，也不展示标签状态切换按钮。
12. 标签管理页不再提供权限模板停用 / 恢复入口，也不展示权限模板启用状态切换按钮。
13. 标签管理页不再提供 `清空用户` / `清除用户` 按钮；如需移除顾客标签关系，应进入顾客编辑或权限相关页面按单个顾客调整。
14. 标签管理页不再提供 `删除权限模板` 按钮；权限模板与标签保持一对一绑定，通过 `权限编辑` 修改模板内容。删除标签本体时，其对应权限模板随标签一并删除。
15. `删除`：删除标签本体。删除前必须弹窗确认；确认后需同步清理该标签的所有顾客关系，并删除该标签对应的权限模板。
16. `删除` 行为必须有二次确认弹窗；若标签有绑定顾客需在文案中展示即将影响的顾客数量。
17. 删除标签时需同步清理该标签在现有顾客的所有标签关系；删除后列表中不再显示该标签。
18. 如被删除标签名称曾与 KASIKA `customer_status` 字段值同名，删除动作仍按 VISTA 标签删除规则执行，不回写 KASIKA，也不修改 KASIKA `customer_status`。后续同步处理到该状态时，因同名 VISTA 标签不存在，系统不自动创建标签，仅记录跳过日志。
19. 系统内标签不允许被外部流程自动创建。

## 4. 验收标准

- 点击新增可打开标签弹窗，标签名为空、重复或超长时禁止保存。
- 标签名在当前项目内不允许重复。
- 新增成功后列表立即可见新标签。
- 标签列表显示标签名、使用中顾客、模板名称、最终更新、可点操作。
- 标签行内最终按钮只有一行，且只包含 `标签编辑`、`权限编辑`、`删除` 三个按钮。
- 标签编辑后，列表、顾客标签显示和对应模板绑定名称同步更新。
- 标签管理页不展示标签停用 / 恢复、权限模板停用 / 恢复、清空用户、删除权限模板按钮。
- 点击 `权限编辑` 能跳转到标签对应的权限模板设置页面。
- 点击 `删除` 必须二次确认；确认后删除标签并同步清理该标签的所有用户标签关系。
- 删除与 KASIKA `customer_status` 同名的 VISTA 标签后，后续同步不会自动重建该标签，只记录无同名标签跳过日志。

## 5. 用户用例

### 用例 1：新增标签
- 前置：管理员进入「标签管理」页。
- 操作：点击 `＋ 标签添加`，输入标签名，确认保存。
- 预期：标签名有效且未重名时创建成功；异常情况下展示错误并阻断保存。

### 用例 2：重复标签拦截
- 前置：已存在同名标签（忽略首尾空白和大小写）。
- 操作：在新增弹窗输入相同标签名。
- 预期：保存失败，提示标签名不可重复。

### 用例 3：标签编辑
- 前置：列表中存在任一标签。
- 操作：点击该标签行内 `标签编辑`，在弹窗中修改标签名并保存。
- 预期：标签名通过必填、长度、重名校验后保存成功；顾客已持有标签和该标签绑定的模板名称同步更新。

### 用例 4：进入权限编辑页
- 前置：列表存在任一标签。
- 操作：点击该标签行内 `权限编辑`。
- 预期：跳转到标签权限模板页，并默认选中当前标签；可继续编辑该标签唯一的权限模板。

### 用例 5：删除标签
- 前置：标签已分配给部分或全部顾客。
- 操作：点击行内 `删除`，在二次确认弹窗中确认。
- 预期：标签从列表中移除，该标签在系统内关联的所有顾客标签关系同时清空，并删除其对应权限模板；若删除失败需提示失败原因并保留当前状态。

### 用例 6：标签管理页按钮收口
- 前置：管理员进入「标签管理」页。
- 操作：查看任一标签行的操作区。
- 预期：操作区只有一行按钮，且仅展示 `标签编辑`、`权限编辑`、`删除`；不展示标签停用 / 恢复、权限模板停用 / 恢复、清空用户、删除权限模板按钮。