crm-backend-matt/.scratch/opportunity-module/issues/14-custom-views-and-builtin-view-family.md

# 14 自定义视图 + 内置视图族（推翻/扩展票 10 视图组织）

Type: grilling
Status: resolved
Blocked by: 10

## 缘起

产品以最新重构版 demo **`nginx/html/保伦CRM系统demo-重构版-S1_0803.html`** 的 `oppModule` 为准（用户明确「他是想做成这样」），推翻/扩展票 10 的四视图组织：销售机会下可**自定义视图**，并把内置视图从「一个我负责的」扩为**四个内置视图**族。

demo 出处：`oppModule`（HTML line 1228 `viewTitles` / line 1229 `viewItems` / line 1260–1305 视图菜单与自定义检索表单 / `saveCustomSearch`·`saveEditedSearch`·`saveAsNewSearch`·`runCustomSearch`·`editSearch`·`startRename`·`confirmRename`·`deleteSearch`·`pinView`·`persistCustomSearches`·`restoreCustomSearches`）。

## 与票 10 的差异（本票为 Amendment，票 10 其余口径不变）

| 维度 | 票 10 已定稿 | demo 0803 新意图（本票拍板） |
|---|---|---|
| 视图组织 | 三个独立工作区（个人/管理/公海）各是独立页面 + 最近访问 | **单一「销售机会」工作区下的视图下拉**（常用检索 / 自定义检索两 Tab）；商机管理 / 商机公海仍是并列 workspace（不变） |
| 内置个人视图 | 只有一个「我负责的（个人页）」 | **四个内置视图**：最近访问 / 我负责的 / **我参与的**（新增）/ 我关注的 |
| 「我参与的」 | 未定义 | 内置视图，见下【定义 1】 |
| 自定义视图 | 无 | 核心新增：保存检索为常用视图、编辑 / 重命名 / 删除、图钉设默认，见【定义 2】 |

> 票 10 的**四视图数据范围矩阵、列表字段、计算列口径、三皮肤、公海 `pool_reason`** 等一律不变。本票只改**「销售机会」这一工作区内的视图组织形态**（内置视图族 + 用户自定义视图），并把「最近访问」「我关注的」从票 10 的独立视图并入销售机会工作区的视图下拉。

## 决策（已定稿）

### 定义 1 —— 内置视图族（销售机会工作区，四个）

四个内置视图，均在「销售机会」workspace 的「常用检索」Tab 内，顺序 = 最近访问 / 我负责的 / 我参与的 / 我关注的：

| 视图 code | 名称 | 数据范围（WHERE 口径） |
|---|---|---|
| `recent` | 最近访问 | 当前用户打开过详情的商机，访问时间倒序、按商机 id 去重留最新，上限可配置（本期默认 50，票 10 P2-2 不变） |
| `mine` | 我负责的销售机会 | `owner_user_id = 当前用户`（票 10「销售机会（个人）」口径不变） |
| `participated` | 我参与的销售机会 | **我是该商机团队成员但不是负责人**：`EXISTS(团队成员表 WHERE opportunity_id=? AND user_id=当前用户) AND owner_user_id <> 当前用户`。团队成员表 = 票 02/04 建商机时落的团队成员（领取人=负责人 + 后续「添加团队成员」加入的成员）。**产品确认（本票确认点 1）：参与 = 团队成员且非负责人**，与「我负责的」互斥不重叠。 |
| `followed` | 我关注的销售机会 | 当前用户关注表命中（票 10「我的关注」口径不变） |

- **内置视图 = 系统固定四个，不可编辑 / 重命名 / 删除**；只可被「图钉」设为默认视图（见定义 3）。
- 「商机管理」「商机公海」仍是**独立 workspace**（不进销售机会视图下拉），口径同票 10（管理按 `@DataScope`、公海 `opp_status=1 且 owner 空`）。demo 里 `workspace` 三档（sales/manage/publicPool）印证。

### 定义 2 —— 自定义视图（= 保存的检索）

用户在「自定义检索」Tab 里配置检索条件并「保存为常用检索」，生成一个**自定义视图**，加入「常用检索」Tab 列表（排在四个内置视图之后）。一个自定义视图 =：

- **检索名称**（用户填，同一用户同一 scope 内唯一，demo `validateCustomRule` 查重）
- **检索条件**：一组「字段 + 操作符 + 值」（demo 本期 1 组条件；「+ 添加更多条件」「启用高级公式」demo 标注为后续迭代 —— **本期后端契约按「条件列表」建模**，前端本期只提交 1 组，留扩展位）
  - 字段（本票确认点 3）= **列表所有可筛选列**（不是 demo 简化的 4 个）；字段池归业务方（商机模块）定义，对齐 `crm-preference`「字段池」约定
  - 操作符：`等于 / 不等于 / 包含 / 不包含 / 为空 / 不为空`（demo `customMatches`）
- **排序条件**：排序字段 + 方向（`asc/desc`）（demo `filteredRows` 里 `预计成交金额 / 计划成交时间` 是简化，后端排序字段同属字段池）

生命周期动作（demo 已实现，全部按用户私有）：
- **保存为常用检索** `saveCustomSearch`（新建）/ **另存为新检索** `saveAsNewSearch`
- **编辑检索** `editSearch` → **保存修改** `saveEditedSearch`（覆盖原视图）
- **重命名** `startRename`/`confirmRename`
- **删除** `deleteSearch`（删当前视图时回落到 `mine`；删默认视图时默认回 `mine`）

### 定义 3 —— 默认视图（图钉）

- 每个视图（内置四个 + 自定义任一）行尾有「图钉」，点击 = **设为该用户在此 scope 的默认视图** `pinView`（demo `defaultView`，持久化）。
- 进入销售机会页时打开默认视图；默认视图未设 → `mine`。
- 默认视图 = **用户级、单值**（一个 scope 只有一个默认）。

### 决策 4 —— 落 `crm-preference` 平台能力，不绑死商机（本票确认点 2）

产品确认：**目前只在销售机会启用，但要有灵活性，后续其他菜单也会有**。故自定义视图**做成 `crm-preference` 的平台级能力**（与既有「列偏好」并列的第二种偏好），**按 `scope_key` 分组、用户级私有**，与 ADR-0024「每菜单独立」完全对称：

- 新增偏好实体（建议 `user_saved_view`）：`(user_id, scope_key, view_id, name, filter_json, sort_field, sort_direction, is_default, seq_no, create_time, update_time)`。
  - `filter_json` = 条件列表（`[{field, operator, value}, ...]`）序列化；**`crm-preference` 不校验字段合法性**（字段池归业务方，对齐既有「字段池」约定）。
  - `scope_key` 复用列偏好同一套 scope 命名；销售机会本期 scope = **`opportunity.sales`**（单一，因自定义视图只属销售机会个人工作区，见确认点 2）。管理 / 公海本期不开自定义视图。
  - `is_default` 承载定义 3 的默认视图（同 `(user_id, scope_key)` 至多一条 `is_default=1`）。
- **契约**：`crm-preference` 现有 `get/save` 两法（列偏好）之外，为自定义视图加一组 `list / save / delete / setDefault`（用户级、按 scope）。具体方法签名留实现阶段定，本票只钉「落 crm-preference、按 scope、用户私有」的归属决策。
- **确认点 2 明确**：本期只 `opportunity.sales` 一个 scope 启用；实体 / 契约按「任意 scope 通用」设计，不含商机专有字段，后续菜单加 scope 即可复用。

## 传出决策 / 回填其他票

- **回填票 10**：销售机会工作区的视图组织从「单一我负责的」改为「内置四视图（最近访问 / 我负责的 / **我参与的**（新）/ 我关注的）+ 自定义视图」；「最近访问」「我的关注」并入销售机会视图下拉（数据范围口径不变）。票 10 的列 / 计算列 / 三皮肤 / 公海不变。
- **回填 `crm-opportunity/CONTEXT.md`**：【四视图】术语改写为【视图（内置 + 自定义）】；新增【我参与的】术语（团队成员且非负责人）。
- **回填 `crm-preference/CONTEXT.md`**：新增【自定义视图】能力段（平台级、按 scope、用户私有、图钉默认视图）；scope 清单增补 `opportunity.sales`。
- **新增待办（Not yet specified / 后续实现票）**：自定义视图 `crm-preference` 契约方法签名 + `user_saved_view` 表 DDL（实现阶段）；商机列表**可筛选列字段池清单**（确认点 3，字段池归商机模块，实现阶段列全）。
- **明确 spin-out（本票不做）**：多组条件（`AND/OR` 复合）、高级公式 —— demo 标注后续迭代；本期契约按「条件列表」预留，前端只 1 组。

## Comments

- 确认点回执（用户 2026-08-20）：①「我参与的」= 团队成员且非负责人 —— **认可**；②自定义视图作用域 —— 目前只销售机会，但要灵活性、后续其他菜单也会有 → 落 `crm-preference` 平台能力按 scope；③检索字段 —— 用列表所有可筛选列；④先更新 spec（本票），不动代码。