crm-backend-matt/.scratch/opportunity-module/issues/10-four-views-query.md

# 10 四视图与列表/详情查询口径

Type: grilling
Status: resolved
Blocked by: 03, 04, 05

> **⚠ Amendment（票 14 推翻/扩展本票的视图组织）**：产品以 demo `nginx/html/保伦CRM系统demo-重构版-S1_0803.html` 为准，销售机会工作区改为「内置四视图（最近访问 / 我负责的 / **我参与的**（新）/ 我关注的）+ 用户自定义视图」的下拉，自定义视图落 `crm-preference` 平台能力（按 scope）。**本票的数据范围矩阵、列表字段、计算列、三皮肤、公海 `pool_reason` 口径均不变**，仅「销售机会」工作区的视图组织形态被票 14 改写。详见 `issues/14`。


定商机四视图查询口径 + 列表/详情字段与操作按视角差异。原型 A3-1-1 / A3-2-1 / A3-3-1 / A3-0-1 均已拉取核实，存档 `research-a3xx-four-views.md`。

---

## 一、四视图数据范围矩阵（口径已核实）

| 视图 | 原型 | 数据范围（WHERE 口径） | 视角下拉 |
|---|---|---|---|
| **销售机会（个人）** | A3-1-1 | `owner_user_id = 当前用户`（本人负责，不含访问记录） | 「我负责的销售机会 ▾ / 全部销售机会（个人）」 |
| **商机管理** | A3-2-1 | 按 `@DataScope` 可见范围（管理侧全部；复用 crm-auth 数据权限） | 「全部销售机会管理 ▾」「商机管理（领导）▾」 |
| **商机公海** | A3-3-1 | `opp_status=1 且 owner_user_id 空` 的逻辑视图（票 05，无池实体） + 匹配公海规则适用范围定可见 | — |
| **最近访问** | A3-0-1 | 当前用户**打开过详情页**的商机，按访问时间倒序、**按商机 id 去重留最新访问时间**，**上限可配置(本期默认 50 条)** | — |

- 视图不是状态切片：同一商机可同时出现在多视图（如自己负责 + 最近访问过）。公海 = status/owner 逻辑视图，与个人/管理互斥于 owner 维度。
- **`@DataScope` 复用 crm-auth**，本模块不自建数据权限。

---

## 二、列表字段（原型核实，个人/管理/最近访问共用基础字段）

原型明证「本页面与最近访问列表页字段结构高度相近，基础字段可复用」。共用列：
序号 / 选择框 / 商机名称 / 甲方 / 意向客户 / 行业 / 地区 / 预计金额 / **当前工作节点** / **节点停留时间** / **最近跟进** / **下一节点** / **方案卡状态** / 操作。

### 计算列口径（不冗余存，实时算/join）
| 列 | 口径 |
|---|---|
| 当前工作节点 | = `current_stage_id`(票03/06) 对应节点名 |
| 下一节点 | = 模板中当前节点的下一 `seq_no` 节点（自由切换下为"建议下一步"，展示用） |
| **节点停留时间** | = 当前日期 − **进入当前节点日期**（`opportunity_stage_history` 最新 to_time）；判长期未推进 |
| **最近跟进** | = 最新一条 `opportunity_follow.create_time`（票09）；无则 `--` |
| 方案卡状态 | = 取**主要意向客户**（票 13 `is_primary_intended`）那张方案卡的 `card_status`（草稿1/已提交2/已推送3，票07 P0-4）；无主客户卡 → “未创建”。**一客户一卡**故取值唯一，不需主卡概念 |
| 方案预算 | = 取**主要意向客户**那张方案卡的 `scheme_budget`（票 07）；无则空。同锚点（主客户卡） |
| 预计金额 | = 主表 `project_amount`（票03 Amendment 1，展示为「预计金额」） |
| 当前负责人 | = `owner_user_id` 反查；**个人页默认隐藏**（都是自己，可自定义列放出） |

### ✅ 口径冲突已解（产品拍板）
- **「预计成交时间」列**：原型列表页 A3-1-1/A3-2-1 曾有此列，但新增表单 A3-1-1-2-1 无此字段。**产品口径二次拍板：该列从商机列表删除**。它本是方案卡字段（票 07，方案卡运行时实有预计成交概率/预计投标时间等预测字段，research-a31113 line 381/401），仅存在于方案卡内部，**不上商机主表、不进商机四视图列表**。

---

## 三、各视图差异（操作/专属列）

| 视图 | 专属列 | 操作按钮 | 新增入口 |
|---|---|---|---|
| 个人 A3-1-1 | 当前负责人默认隐藏 | 详情 / 写跟进 | **有**「+新增商机」（仅个人跟进场景，默认归当前用户） |
| 管理 A3-2-1 | 当前负责人显示 | 详情 / **分配 / 催办 / 关闭** + **批量催办 / 批量分配 / 管理关注 / 领导释放** | 无（管理不主动新建） |
| 公海 A3-3-1 | **入池前工作节点 / 进入公海原因 / 当前负责人** | 详情 / **关注 / 领取** + **批量领取 / 批量关注** | 无 |
| 最近访问 A3-0-1 | 按访问时间排序 | 详情 / 写跟进 / 关注 / 领取（按角色+商机态动态） | 无 |

### 回填其他票的新事实
- **公海「进入公海原因」= 分类字段**（回填票 04/05）：`销售主动释放 / 特殊原因暂停 / 领导释放 / 超期回收`。→ 抛公海(票04 E1)/回收(票05)需记 `pool_reason`，公海列表按此筛选。
- **公海「入池前工作节点」**：抛公海时快照进池前的 `current_stage_id`（清 owner 但保留阶段快照供公海展示）。
- **管理「催办/督办」**（A3-2-1-1-1 督办功能）：管理对负责人的推进督促——spin-out 独立功能，本票只记列表入口存在。
- **「领导释放」= 管理侧强制抛公海**（对齐票04 抛公海边，操作人=管理者而非 owner，pool_reason=领导释放）。

---

## 四、商机详情三皮肤（个人 A3-1-1-1 / 管理 A3-2-1-1 / 公海 A3-3-1-1）

- **同一详情聚合，按视角展示不同操作区，非三套数据**：Tab 结构一致（概览/客户信息/方案卡/现场勘察/相关附件/跟进记录/工作计划/团队成员/操作日志，票06-09）；差异在**头部操作按钮 + 进入权限**：
  - 个人：写跟进/编辑/暂缓/抛公海/关闭/新增方案卡… (票06 概览页已核实)
  - 管理：+ 分配/催办/关闭/督办（A3-2-1-1）
  - 公海：领取/关注（A3-3-1-1），无跟进/推进入口（未领取不可推进，票04/06）
- 操作可见性 = 视角 + `opp_status` + 权限点，无 owner guard（可见即可点，票01）。

---

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

- **回填票 04**：抛公海边记 `pool_reason`（销售主动释放/特殊原因暂停/领导释放/超期回收）；「领导释放」= 管理侧抛公海（操作人≠owner）。
- **回填票 03**：新增 `pool_reason` + 「入池前工作节点」快照的承载（或复用 `opportunity_stage_history`）；**✅「预计成交时间」列从商机列表删除、不上主表（产品二次拍板）**。
- **回填票 05**：公海列表 = 逻辑视图口径印证（`status=1 且 owner 空`）；`pool_reason`「超期回收」= `executeRecycle` 触发。
- **CONTEXT.md**：新增【四视图】口径术语（数据范围矩阵 + 计算列口径 + 三皮肤）；【进入公海原因】术语。
- **spin-out**：督办/催办功能（A3-2-1-1-1）独立。

## 待产品/原型核实（不阻塞建模）

- ✅ **预计成交时间（已拍板）**：从商机列表删除、不上主表；仅方案卡内部字段（票 07）。
- ✅ **最近访问去重 + 上限（产品拍板 P2-2）**：按商机 id 去重（留最新访问时间）；**上限做成配置值**，本期默认 **50 条**（原型未画，本期只商机用，做成可配置便于后续复用/调整）。原型仅画死：打开过详情/访问时间倒序/未访问不展示（line 2672-2683），去重·上限本由产品定。
- ✅ 方案卡状态列/方案预算列多卡取值口径（已拍板 P0-4）：取**主要意向客户**那张方案卡（票 13；一客户一卡），不引入主卡。
- ⚠ 视角下拉「领导 ▾」的层级数据范围与 `@DataScope` 的精确映射。
- ⚠ 默认排序（原型「建议按最近跟进/节点停留时间」等，具体待产品）。