crm-backend-matt/.scratch/customer-module/issues/03-ownership-views.md

# 03 — 归属流转 + 三 workspace + 内置视图 + 自定义视图查询口径

Type: research
Status: resolved
> **⚠ 20260902 复核注记**：本文件关于「已归档客户/已被合并客户」独立 tab/子页的旧口径**已被推翻**——D19 拍板去掉「已被合并」态、**已归档=删除语义、不做独立 tab**，只加 `archive_status` 筛选条件（默认排除已归档）。**三值归档态/独立子页方案作废，以 `03-answer.md` 为准。**
Blocked by: 02

## 问题

定客户模块三个 workspace（客户总览 / 我的客户 / 客户公海）的**数据范围**、**内置视图**、**共用列**、**行内操作**、**自定义视图接入**（复用商机 saved-view 手册）。同时定归属的迁移动作（领取/分配/抛公海/交割换主/归档）在读侧怎么反映。

## 一手证据（蓝湖缓存 txt）

- `a4-1-1_客户公海列表.txt` / `a4-1-1_客户公海列表_列表视图_.txt` / `a4-1-2_客户公海列表_分屏视图_.txt` — 客户公海（普通销售视角=批量领取 + 领导视角=批量分配）
- `a4-2-1_客户总览列表_列表视图_.txt` / `a4-2-1_客户总览列表_分屏视图_.txt` / `a4-2-1_客户总览列表_卡片视图_.txt` — 客户总览（三视图：表格/列表详情/看板；含分配/抛公海/归档）
- `a4-3-1_我的客户列表_分屏视图_.txt` / `a4-3-1_我的客户列表_列表视图_.txt` / `a4-3-1_我的客户列表_卡片视图_.txt` — 我的客户

## 已知事实

- **三 workspace 数据范围**（对称商机四视图）：
  - **我的客户** = 当前用户 owner 或作为协同人的有效客户（去重）。
  - **客户总览** = 按 `@DataScope` 覆盖组织范围内的**未删除、未进入公海**客户；含内置子筛「我负责的 / 我协同的 / 我关注的 / 最近访问」；**不混入公海**（公海是独立入口）；含**已归档客户 / 已被合并客户**两个专门 tab（原型 A4-2-1 有）。
  - **客户公海** = `archive_status=有效 且 owner_user_id IS NULL` 的逻辑视图；无独立池表；`owner_dept_id`+匹配规则的可见性（对称商机公海口径，待与超期规则票 10 呼应）。
- **行内操作差异**：
  - 我的客户：详情 / 关注 / 跟进 / 编辑；分配/抛公海按 RBAC 出。
  - 客户总览：详情 / 关注 / **分配** / **抛公海** / 更多（含 **归档**）；顶部批量：批量分配 / 批量抛公海 / 批量归档 / 工商信息更新。
  - 客户公海：普通销售=详情+关注+**领取**+批量领取；领导=详情+关注+**分配**+批量分配（不做审批）。
- **三视图模式（仅客户总览有全三种；公海/我的客户只有列表+分屏）**：表格 / 列表详情(左表+右详情) / 看板（客户阶段分列？待原型核实）。切换视图记住用户偏好（复用 crm-preference）。
- **自定义视图 = crm-preference 平台能力**（商机图票 14 已建平台；本模块新接一个 scope，参商机 `OpportunitySavedViewFilter` 手册）——见票 11。

## 待拍板点

1. **公海准入规则**（原型 A4-1-1 §3 明说）：客户有「进行中商机/项目」不可移入公海——本票拍板：抛公海写路径的前置校验点（读 crm-opportunity 存在性；A5 未建先跳过项目那半）。
2. **看板视图（卡片视图）分列维度**：客户阶段？客户星级？→ 需 grill 或读原型细节。
3. **共用列 vs 差异列**：列表统一列 = 客户名/客户类型/行业/客户阶段/星级×2/战略等级/VIP等级/进入公海时间(公海)or销售负责人+部门+关联业务+最近跟进(总览/我的)。字段设置=复用 crm-preference 列偏好。
4. **归属迁移动作枚举**：领取(公海→个人)、分配(公海→个人 / 个人→个人)、抛公海(个人→公海)、交割(交割票 08 专管，本票只留 seam)、归档(→archive_status=2)。每边写操作日志（票 07）。
5. **并发**：所有归属变更 CAS 乐观锁 + 版本号；批量操作跳过已被他人处理的（Toast 报成功/跳过数）。
6. **领导视角 DataScope 映射**：客户总览 = ALL(领导) / DEPT_AND_CHILD(总监) / DEPT(普通销售不可见总览菜单)——对称 crm-auth DataScopeEnum。

## Answer

**Status: resolved**

### A. 三个 workspace 数据范围（定稿）

| workspace | 数据范围 | 附加状态页 |
|---|---|---|
| **我的客户** | 当前用户为**销售负责人或协同人** 且 `archive_status=有效(1)` 且 **非公海**（owner 非空） | 子页「已归档客户」= owner 当前用户 且 archive_status=2；「已被合并客户」= owner 当前用户 且 archive_status=3 |
| **客户总览** | `@DataScope` 覆盖组织范围的 **未删除、未进入公海** 客户（含有效/已归档/已被合并三态，但**默认只列有效**，归档/合并走独立 tab） | 顶部 tab「已归档客户」「已被合并客户」 |
| **客户公海** | `archive_status=有效(1)` **且 `owner_user_id IS NULL`** 逻辑视图 | 无 |

- **公海不是独立实体**，无池表；对称商机公海 = 逻辑视图（chart D3）。
- **管理职务不扩大「我的客户」数据范围**（原型 2.1 §6 明文）；管理视角走「客户总览」。
- **协同人视角**：协同人可见客户（进「我的客户」），但**不得归档/合并**（仅负责人可，原型 2.2 §4）。

### B. 内置视图 / 常用检索（硬编码，不入库）

**我的客户** 内置：`我负责的客户`(owner=我) / `我协同的客户`(团队成员表含我) / `待跟进的客户`(有下次跟进时间且 ≤ now) / `我关注的客户`(关注表) / `最近访问`(view_log 倒序)。

**客户公海** 内置：`最近访问` / `我关注的客户`（原型 A4-1-1 检索列表只见这两项 + 自定义）。

**客户总览** 内置：`最近访问` / `我关注的客户` / `我负责的客户` / `我协同的客户`（原型 A4-2-1 有「我负责的/我协同的」身份筛选）。

> 自定义视图 = crm-preference 平台能力，票 11 接入（三个 scope_key）。内置视图**不落库**，口径硬编码（对称商机票 14 拍板）。

### C. 三视图模式（定稿）

| workspace | 视图模式 |
|---|---|
| 我的客户 | 表格 / 列表详情(左表+右详情) / **看板** |
| 客户总览 | 表格 / 列表详情 / **看板** |
| 客户公海 | 表格 / 分屏(左表+右详情) |

- **看板视图分组页签 = 三个**：`客户阶段` / `客户星级` / `关系星级`（原型 A4-3-1 §1.3 明文「看板视图包含客户阶段、客户星级、关系星级三个分组页签」；A4-2-1 卡片视图顶部即「潜在客户(3)/重潜客户(3)/已成交客户(3)」）。
- **视图切换记住用户偏好**（复用 crm-preference 列偏好能力；对称商机票 14）；首次默认表格视图。
- 勾选跨分页保留；全选仅当前页/当前批次；批量操作按已勾选 ID 集合执行。

### D. 共用列（定稿，三 workspace 同款列基础 + 差异列）

**共用列**：客户名称(固定列不可隐藏) / 客户编号 / 客户类型 / 所属地区 / 行业 / 客户阶段 / 客户星级 / 关系星级 / 战略协议等级(快照) / 已成交VIP客户等级(快照) / 关联业务(商机/项目计数) / 最近跟进时间。

**差异列**：
- 我的客户 / 客户总览：+ 销售负责人 / 销售部门。
- 客户公海：+ **进入公海时间**(`enter_pool_time`，见票 03 回填) / 无销售负责人列（owner 空）。

**字段设置** = crm-preference 列偏好（列显隐/排序，用户级）；客户名称为固定列不参与设置。

### E. 归属迁移动作枚举（定稿）

| 动作 | 语义 | 前置校验 | 触发方 |
|---|---|---|---|
| 领取 | 公海→个人（owner 空→当前用户） | 客户仍在公海 + 无进行中商机/项目 | 普通销售 |
| 分配 | 公海→个人 / 个人→个人（换 owner） | 目标人员启用 + 有权分配范围 + 非原负责人 | 领导/管理 |
| 抛公海 | 个人→公海（清 owner+协同人） | **无进行中商机/项目**（原型 A4-1-1 §3 明文）+ 有抛公海权限 | 领导/管理 |
| 归档 | 有效→已归档（archive_status 1→2） | 仅销售负责人可；**无进行中商机/项目**（原型 A4-3-1 归档弹窗明说） | 销售/领导 |
| 恢复 | 已归档→有效（2→1） | 仅销售负责人可 | 销售/领导 |
| 交割 | 换 owner（跨模块同步商机/项目负责人） | 票 08 专管 | 销售本人 |

- 每边**写操作日志**（票 07 oplog）；CAS 乐观锁 + 版本号。
- **批量操作部分失败不回滚**（按客户逐条独立事务，跳过已不可操作项，Toast 报成功/跳过数）——**例外：批量归档整批预检**，任一失败整批不执行（原型 A4-3-1 §3.6 明文）。
- **「进行中商机/项目」阻止抛公海/归档**：商机侧读 crm-opportunity（状态=推进中 即 opp_status=2）；**项目侧留 seam**（A5 未建，先跳过项目那半，等 A5 建好补校验）。

### F. 新增字段（回填票 02）

| Java 字段 | 列名 | 类型 | 说明 |
|---|---|---|---|
| enterPoolTime | enter_pool_time | datetime | 进入公海时间（公海列表列；抛公海时写入，领取/分配时清空） |

> `enterPoolTime` 无孤立单大写字母陷阱，无需 `@Column(name=...)`。

### G. 领导视角 DataScope 映射（对称 crm-auth）

- 客户总览可见性 = `@DataScope(module="customer")` 套 `DataScopeEnum(SELF/DEPT/DEPT_AND_CHILD/ALL)`，按用户角色配置决定（ADR-0018 按模块可配）。
- 普通销售**无客户总览菜单权限**时不可见；总监=DEPT_AND_CHILD 或 ALL（按后台配置）。
- 公海：普通销售看「可领取」= 其部门集合可见范围内 owner 空的客户；领导看「可分配」= 其管理范围。

### H. 待产品确认（⚠）

| # | 问题 | 影响 |
|---|---|---|
| P0-1 | 客户总览「已归档客户/已被合并客户」是**独立 tab** 还是**筛选状态**？原型 A4-2-1 顶部有「已归档客户/已被合并客户」两个 tab 且 A4-3-1 也把它们当独立子页——**推荐独立子页**（archive_status 过滤），归档/合并态不进主列表 | 列表查询参数 |
| P1-1 | 公海列表是否需要「进入公海时间」排序？原型列为固定列 → 推荐保留 | 排序字段池（票 11） |

### I. 回填 / 下游影响

- **票 02**：新增 `enter_pool_time` 字段（本票 F）。
- **票 08**（交割）：owner 换主 = 本票「分配」动作的扩展版（跨模块同步），交割事务复用 owner 变更 oplog 语义。
- **票 11**（saved-view）：三 workspace 各自 scope_key，字段池白名单 = 本票 D 共用列 + 差异列。
- **票 07**（oplog）：归属迁移（领取/分配/抛公海/归档/恢复/交割）都写 oplog。
- **票 01**（CONTEXT）：术语「客户公海」「销售负责人」「协同人」「归档」「已合并」。