crm-backend-matt/crm-preference/CONTEXT.md

# 列偏好（crm-preference）

平台级的用户列表偏好能力，与 `crm-dict` 平行的通用模块：用户级、按 scope 分组、私有。含两种偏好：**①列偏好**（列显隐 + 拖拽排序，契约 `get / save`）；**②自定义视图**（用户保存的检索，票 14，契约 `list / save / delete / setDefault`）。本次只做到「够用的最小通用深度」，不做全平台通用化打磨。

## Language

**列偏好**:
一个用户在某个列表页上的列显隐与列顺序设置，存于 `user_column_preference(user_id, scope_key, visible_keys, column_order)`。用户级、私有，互不影响。
_Avoid_: 表格配置、字段配置、视图设置

**scope**:
偏好（列偏好 / 自定义视图共用）的作用范围键 `scope_key`，由业务方约定的稳定 code。**每菜单独立**、互不同步（推翻原型「共用一套」的说法）。线索域列偏好 4 个取值已钉死（ADR-0024，与 viewType 一一对应）：`lead.public_pool`（公海）/ `lead.my_lead`（我的线索）/ `lead.my_follow`（我的关注）/ `lead.manage`（线索管理）。商机自定义视图（票 14）本期 1 个：`opportunity.sales`（销售机会工作区）。
_Avoid_: 页面 ID、菜单 key、视图类型

**自定义视图**:
用户在某菜单保存的一条**检索**（票 14，demo 0803 `oppModule` 为准），存于 `user_saved_view(user_id, scope_key, view_id, name, filter_json, sort_field, sort_direction, is_default, seq_no)`。用户级私有、按 `scope_key` 分组，与列偏好同构。`filter_json` = 条件列表 `[{field, operator, value}, …]`（本期前端只提交 1 组，契约按列表预留复合/高级公式扩展位）；**字段合法性 crm-preference 不校验**（字段池归业务方，同「字段池」约定）。同 `(user_id, scope_key)` 至多一条 `is_default=1`（图钉设的默认视图）。系统**内置视图**（如商机的 最近访问/我负责的/我参与的/我关注的）**不入本表**——内置视图口径硬编码在业务方，本表只存用户自建的视图。**责任边界**：crm-preference 只负责**存/取** `filter_json`；把条件**翻译成查询**（filter_json → SQL/过滤）归业务方，因字段池/操作符语义在业务方（商机侧例 = `OpportunitySavedViewFilter`）。新菜单接入 = 直接复用本契约 + 自备一个翻译器，**crm-preference 无需改动**。
_Avoid_: 内置视图落库（内置固定在业务方，本表只存用户自建）、视图=页面路由、绑死某业务模块（按 scope 通用，加 scope 即复用）

**字段池**:
某 scope 下所有可显隐 / 可排序的候选列，**归业务方定义**，`crm-preference` 不持有字段清单，只存用户勾选与排序的结果（`visible_keys` / `column_order`）。
_Avoid_: 列定义、可选字段表、schema

**保存才落库**:
列偏好的持久化时机：用户在【列表设置】弹窗内点【保存】才把显隐 + 顺序一起写库；表头拖拽的临时顺序仅前端本地保留（关页面 / 刷新即丢），【取消】或未保存关页面则本轮变更全部作废（推翻原型「拖拽实时保存」的说法）。
_Avoid_: 实时保存、自动保存、拖拽即存