# 客户管理 · 列表页产品需求说明（PRD）

> 本页为客户主数据台账列表。标注「原型演示」的跳转、导入、导出仅 Toast 提示。

---

## 1. 模块定位

| 项 | 说明 |
|---|---|
| 模块名称 | 客户管理 — 列表页 |
| 目标用户 | 销售、业务负责人、运营、**法务、财务、风控** |
| 核心任务 | 按多维度筛选客户台账，查看风险标签与状态，**在列表页维护客户风险标签**，新增客户或进入详情/编辑 |
| 页面结构 | 面包屑 + **操作角色切换** + 筛选区 + 工具栏 + 表格 + 分页 |

**重要约束：** 风险标签**不在**客户新增页、客户编辑表单中维护，仅在列表页作为操作入口。

---

## 2. 客户编号规则（集团多子公司）

- 总长度 7，仅含大写字母 A–Z 与数字 0–9
- 结构：第 1 位 = 签约/归属子公司代码；第 2–7 位 = 6 位数字流水号（000001–999999）
- 流水号在「同一子公司代码」下递增
- 校验正则：`/^[A-Z][0-9]{6}$/`
- 示例：A000001（华东）、B000001（华南）、C000001（华北）等

---

## 3. 数据来源

| 数据 | 来源 | 用途 |
|---|---|---|
| 客户台账 | `data/customers.json`（20 条样例） | 列表、筛选选项 |
| 客户标签（展示） | 客户 `labels` 字段 | 列表「风险标签」列、筛选区「标签」多选 |
| 风险标签明细 | `riskTagsByCustomer` 运行时状态 + 种子迁移 | 标签管理抽屉、审批、日志 |
| 标签目录 | `utils/riskTagConstants.ts` → `TAG_CATALOG` | 打标表单选项、级别、分组 |
| 操作日志 | `data/risk-tag-operation-logs.json` + 运行时追加 | 抽屉「操作日志」Tab |
| 部门-负责人 | 由台账聚合 + `DEPT_MANAGER_MAP` | 筛选联动 |

列表 `labels` 与「生效中」风险标签自动同步，保证筛选器与列表展示一致。

---

## 4. 筛选区

默认展示前 4 项（一行），点击「更多筛选」显示全部。

| 字段 | 控件 | 匹配规则 |
|---|---|---|
| 客户编号 | 可搜索单选 | 精确匹配 `code` |
| 客户名称 | 可搜索单选 | 精确匹配 `name` |
| 标签 | 多选 | 客户 `labels` 包含任一选中标签（OR） |
| 区域 | 可搜索单选 | 精确匹配 `region` |
| 客户状态 | 多选 | `status` 在选中集合内 |
| 业务部门 | 多选 | `department` 在选中集合内 |
| 业务负责人 | 多选 | 随部门联动选项；`manager` 在选中集合内 |
| 创建时间 | 日期范围 | `createTime` 落在区间内（含边界日） |

### 4.1 操作逻辑

| 操作 | 行为 |
|---|---|
| **查询** | 将当前筛选项写入已应用条件，页码重置为 1，清空行选中 |
| **重置** | 清空待应用与已应用条件，页码重置为 1，清空行选中 |
| 修改筛选项未点查询 | 不影响当前列表 |

---

## 5. 列表工具栏

| 按钮 | 行为 |
|---|---|
| 新增客户 | 进入新增客户页（分组表单） |
| 批量导入 | Toast：批量导入（原型演示） |
| **批量打标** | 勾选 ≥1 行且当前角色有打标权限时显示；打开批量打标弹窗 |
| 批量导出 | Toast：导出当前列表条数 |

### 5.1 操作角色切换（原型演示）

列表顶部提供「当前操作角色」下拉，用于模拟不同部门用户：

| 角色 | 部门 | 打标权限 |
|---|---|---|
| 王风控 | 风控部 | 全部标签 |
| 李法务 | 法务部 | 法务类标签 |
| 张财务 | 财务部 | 财务类标签 |
| 赵运维 | 运维部 | 运维类标签 |
| 陈销售 | 销售一部 | 仅查看，无打标入口 |

切换角色后，风险标签管理抽屉内的**标签类型**、**可选标签**、**审批/移除按钮**随之联动更新。

---

## 6. 列表字段说明

| 列 | 说明 |
|---|---|
| 客户编号 | 左固定列 |
| 客户名称 | 超长省略 |
| **风险标签** | 展示「生效中」标签；按风险级别着色（低/中/高/极高）；首标签 + `+N` 悬浮全部；有待审批时显示「审」标识；可点击打开管理抽屉 |
| 客户区域 | 大区名称 |
| 客户状态 | 绿点「正常」/ 红点「黑名单」 |
| 业务部门 / 业务负责人 | 文本 |
| 客户类型 / 所属行业 | 文本 |
| 统一社会信用代码 / 法人 / 注册资本 / 经营状态 | 文本 |
| 详细地址 / 创建时间 | 文本；创建时间不换行 |
| 操作 | 详情、编辑、**管理标签**（有权限时）、删除（原型 Toast） |

支持行多选（checkbox，仅当前页）；横向滚动；操作列右固定。

---

## 7. 客户标签枚举与分级目录

标签按业务分类维护，打标时下拉按 **optgroup 分组** 展示。风险级别由目录**自动带出且不可手改**。

### 7.1 信用与回款

| 标签名称 | 标签类型 | 风险级别 | 典型触发 |
|---|---|---|---|
| 逾期预警 | 财务 | 中 | 当前逾期或近 6 个月内曾逾期 |
| 严重拖欠 | 财务 | 高 | 逾期 > 30 天未结清或历史坏账 |
| 频繁改账期 | 财务 | 低 | 一年内申请延长账期 ≥ 3 次 |

### 7.2 合规与法律

| 标签名称 | 标签类型 | 风险级别 | 典型触发 |
|---|---|---|---|
| 资质存疑 | 法务 | 中 | 证照过期、抬头与付款主体不一致等 |
| 涉诉/仲裁 | 法务 | 高 | 与我司或第三方重大未结诉讼 |
| 制裁/高风险地区 | 法务 | 高 | 名单筛查命中（依公司合规清单） |

### 7.3 经营与履约

| 标签名称 | 标签类型 | 风险级别 | 典型触发 |
|---|---|---|---|
| 频繁争议 | 法务 | 中 | 合同或扣款争议次数超阈值 |
| 车辆/资产高风险 | 运维 | 高 | 违章、事故、疑似骗保等 |
| 信息不实 | 风控 | 中 | 联系人/主体核查不实、空壳公司等 |

### 7.4 操作与流程

| 标签名称 | 标签类型 | 风险级别 | 典型触发 |
|---|---|---|---|
| 开票异常 | 财务 | 低 | 频繁退票、抬头异常变更 |
| 多头签约 | 风控 | 低 | 同一实控人多主体分别签约 |

### 7.5 列表展示样式

- 低：灰色边框
- 中：橙色浅底
- 高：红色浅底
- 极高：深红浅底
- 单元格最大宽度受限，避免撑乱表格

---

## 8. 风险标签维护（列表页专属）

### 8.1 入口

| 入口 | 说明 |
|---|---|
| 行操作「管理标签」 | 打开右侧抽屉，管理单个客户 |
| 点击标签列 | 有权限时同「管理标签」 |
| 工具栏「批量打标」 | 对当前勾选客户批量提交同一标签 |

**不在**新增页、编辑页维护标签。

### 8.2 管理抽屉结构

| Tab | 内容 |
|---|---|
| 当前标签 | 已打标签列表：名称、类型、级别、状态、原因摘要；支持查看详情、移除、审批 |
| 新增标签 | 打标表单（见 8.3） |
| 操作日志 | 该客户全部标签相关审计记录 |

### 8.3 打标表单字段

| 字段 | 必填 | 规则 |
|---|---|---|
| 标签名称 | 是 | 按 7.1–7.4 分组下拉；仅当前角色有权限的标签可选；已存在同名有效标签不可重复选 |
| 标签类型 | 是 | **根据当前操作角色自动带出**（财务→财务、法务→法务、运维→运维、风控→风控），**置灰不可编辑** |
| 风险级别 | 是 | **选择标签名称后按目录自动带出**，**置灰不可编辑** |
| 生效时间 | 是 | 日期，默认当天 |
| 有效期至 | 是 | 日期，须 ≥ 生效时间；默认一年后 |
| 原因说明 | 是 | 至少 10 字，供法务/财务/风控审批留痕 |
| 附件 | 否 | 支持 .pdf / .jpg / .png / .xlsx，可多个 |

### 8.4 批量打标

- 展示已选客户 chips（超过 6 个显示 +N）
- 表单字段与单客户打标一致
- 已存在同名有效标签的客户自动跳过
- 提交后写入批量操作日志

### 8.5 标签生命周期

| 状态 | 说明 |
|---|---|
| 生效中 | 参与列表展示，同步至 `labels` |
| 待审批 | 高风险标签提交后进入；列表暂不展示为生效 |
| 待确认 | 预留 |
| 已驳回 | 审批未通过，不同步至 `labels` |
| 已移除 | 操作人主动移除，需填写原因 |
| 已过期 | 预留 |

**高风险规则：** 风险级别为「高」或「极高」的标签提交后状态为「待审批」，须法务或风控审批通过后变为「生效中」。

### 8.6 移除标签

- 仅「生效中」且当前角色有移除权限的标签可移除
- 须填写移除原因（至少 5 字）
- 写入操作日志，并从列表 `labels` 同步清除

---

## 9. 权限与审批

### 9.1 打标权限

| 角色 | 可选标签范围 | 标签类型（自动） |
|---|---|---|
| 财务 | 财务类（信用与回款、操作与流程中的财务标签） | 财务 |
| 法务 | 法务类（合规与法律、经营与履约中的法务标签） | 法务 |
| 运维 | 运维类（车辆/资产高风险） | 运维 |
| 风控 / 管理员 | 全部 | 风控 |
| 销售 | 无 | — |

### 9.2 审批权限

- 法务、风控、管理员可审批「待审批」标签
- 支持通过 / 驳回；驳回须填写原因

### 9.3 移除权限

与打标权限一致：各角色仅能移除本类型标签；风控 / 管理员可移除全部类型。

---

## 10. 操作日志

所有标签 **新增、移除、提交审批、审批通过、审批驳回、批量打标** 均写入日志。

| 字段 | 说明 |
|---|---|
| 操作类型 | 新增 / 移除 / 提交审批 / 审批通过 / 审批驳回 / 批量打标 |
| 客户 | 客户名称 + ID |
| 标签名称 | 涉及标签 |
| 详情 | 原因、审批结论等 |
| 操作人 | 姓名 + 角色 |
| 操作时间 | `YYYY-MM-DD HH:mm:ss` |

抽屉「操作日志」Tab 按客户过滤；原型预置样例日志见 `data/risk-tag-operation-logs.json`。

---

## 11. 原型实现索引

| 能力 | 代码位置 |
|---|---|
| 列表编排 | `index.tsx` |
| 风险标签列 | `components/RiskLabelTags.tsx` |
| 管理抽屉 | `components/RiskTagDrawer.tsx` |
| 批量打标 | `components/BatchRiskTagModal.tsx` |
| 打标表单 | `components/RiskTagForm.tsx` |
| 标签目录 | `utils/riskTagConstants.ts` |
| 权限 | `utils/permissions.ts` |
| 业务逻辑 | `utils/riskTagStore.ts` |
| 类型定义 | `types/riskTag.ts` |
