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

# 商机业务（crm-opportunity）

销售机会的全生命周期业务域：商机实体、两条正交轴（归属流转**状态** + 业务**阶段**）、四视图（商机公海 / 销售机会（我负责的）/ 我的关注 / 商机管理）、领取 / 分配 / 暂缓 / 抛公海 / 关闭 / 移交 / 转项目等流转。与线索同构，依赖方向单向 `crm-opportunity → crm-rule → (crm-auth / crm-dict / crm-file)`；商机规则（阶段模板 / 方案卡模板 / 方案推送 / 项目查重 / 商机公海与提醒 / 商机字典，原型 A7-3-2）归 `crm-rule`，本模块只消费。商机由**线索转入**或**销售直接创建**两条入口进入，进系统后完全平权（不按来源切片状态机/公海/视图）。

> 本文档只钉词汇与边界（票 01）；状态机迁移图、表结构、公海规则、四视图查询各留给后续票（04/03/05/10）。事实出处见 `.scratch/opportunity-module/research-close-pause-actions.md`（原型活数据 V1.0-20260815）。

## Language

**商机**:
一条正在推进、准备转成项目的销售机会记录，`crm-opportunity` 的核心聚合根。两条正交轴：归属流转 `oppStatus`（**状态**）+ 业务打法 `oppStage`（**阶段**）。归属由 `owner_user_id`（领取人）表达。全生命周期最终走向「已转项目」或被「关闭」。字段/类名统一 `opp` 前缀，模块名与表名全拼 `crm-opportunity` / `opportunity_*`。
_Avoid_: opportunity（英文单说）、线索（线索是上游实体）、项目（项目是转化后的下游实体）、客户

**状态（oppStatus）**:
商机的**归属流转轴**，`OpportunityStatus`（`opp_status` tinyint）。5 态：`1 待领取(在公海)` / `2 推进中`(默认活跃态) / `3 暂缓中` / `4 已关闭`(半终态，可重启) / `5 已转项目`(绝对终态，无出边)。与业务阶段是两条独立的线——状态管「归属处境」，不管「业务打法走到第几步」。迁移全图见票 04：领取/分配→2、抛公海 2→1、暂缓 2⇄3、关闭 2/3→4、重启 4→2、转项目 2→5、移交(换 owner 不改 status)。CAS 乐观锁 + 无 owner guard（可见即可点，票 01）。
_Avoid_: 阶段（阶段是另一条轴）、进度、stage、中止（不存在）

**阶段（oppStage）**:
商机的**业务阶段轴**，`OpportunityStage`。表达按公司标准打法走到第几步：客户圈定 → 关系摸排 → 资料采集 → 方案卡 → 已转项目（原型详情页进度条 A3-1-1-1-1）。阶段序列由 `crm-rule` 的**商机阶段模板**配置（原型 A7-3-2-1，票 06）。商机绑定模板时锁死具体版本（`stage_template_id`=版本行 id），发新版不自动迁移。除「已转项目」外其余阶段**可自由切换（连跳/回退）**，每次写 `opportunity_stage_history` 快照。「已转项目」为固定末节点（`is_fixed`，不可删、不可手动点），仅由**商机下任一方案卡转项目创建成功**触发，同时驱动轴1 已转项目终态（联动）。与状态正交。
_Avoid_: 状态（状态是另一条轴）、节点（口语可叫「节点」，字段用 stage）、status

**领取人**:
当前持有该商机的销售，存于 `owner_user_id`，= 归属 + 可见性两层含义（既是「谁负责」，也是默认「谁能看到」）。抛公海时清空。是「销售机会（我负责的）」视图的第一层业务过滤依据。直接创建商机时默认领取人 = 当前用户（原型 A3-1-1-2-1）。
_Avoid_: 负责人（负责人是公海池概念）、持有者、owner（英文单说）

**创建人**:
录入该商机的用户，全生命周期不变。直接创建 / 线索转入均落创建人。删除权限判定依据之一（对称线索：终态为删除禁区）。
_Avoid_: 录入人、owner（owner 是领取人）

**团队成员**:
领取人拉入协作的人员，存于独立关联（原型「添加团队成员&一键拉群」A3-1-1-2-8、团队成员 Tab A3-1-1-1-8）。每人配**项目角色**（商机负责人 / 方案工程师 / 招标专员 / 现场工程师 等）与**权限**（读写 / 只读 / 可写跟进 / 可推进节点 等）。团队成员是**行级授权白名单**——绕开 DataScope 部门天花板给出可见性，但能否写取决于其自身权限点。**抛公海只清空领取人，不动团队成员**（产品明确）。**转商机时自动插一条团队成员：领取人 = 商机负责人（票 02 拍板）**。
_Avoid_: 协作人、参与者、观察者（团队成员带角色与权限，不只是「能看」）

**商机来源**:
渠道归因字段 `oppSource`（字典码，必填，原型 A3-1-1-2-1）。表达商机从哪个渠道来（展会 / 转介绍 / 官网 等）。**与「来源线索」是两回事**——来源是渠道分类，每条商机都有；来源线索是血缘。**从线索转来的商机，`oppSource` 默认置为「线索转入」**（产品明确）；直接创建的由用户选。
_Avoid_: 来源线索、渠道（口语，字段名 oppSource）、来路

**来源线索**:
线索转入的血缘键 `source_lead_id`（可空 FK）。**两条入口都可写此字段**：线索侧 port 自动带（票 02），商机侧新增入口当用户选商机来源=「线索转入」时手选一条【关联线索】（票 12，候选范围 = 线索状态已领取/跟进中，与线索侧转商机准入对称）。直接创建且商机来源非「线索转入」的为 NULL（「直接创建」= `source_lead_id IS NULL`，不单列术语）。是幂等键——`UNIQUE(source_lead_id)`（票 02）保证**一条线索只能关联一条商机**，两条入口共享同一 DB 约束。**不参与商机身份**：线索转来的与直接创建的商机在模型里完全平权。
_Avoid_: 商机来源（那是 oppSource 渠道）、线索 id、parent

**关联客户**:
商机关联的客户 / 联系人（原型「添加关联客户」A3-1-1-2-4、客户信息 Tab A3-1-1-1-2）。本域只存 `customer_id` **引用 + 快照字段**；客户实体本身归 A4 客户模块。至少关联一个客户，同一商机唯一主要客户（原型 A3-1-1-2-1）。**转商机时自动插一条关联客户，关系标记「主要意向客户」，`customer_id` = 线索侧下拉选中的客户 id（引用）+ 客户名快照（票 02 拍板）**。⚠ 依赖线索侧「意向客户下拉」+ A4 客户下拉能力落地，见票 11。
_Avoid_: 客户（客户是 A4 域的实体）、甲方（甲方是快照里的一个字段）、customer

**暂缓**:
商机流转动作（原型 A3-1-1-2-6）：短期推不动、但仍有价值时挂起。选**暂缓原因**（字典）+ **预计重启日期**（必填，不早于今天）+ 补充说明 → 状态「暂缓中」。**保留领取人+团队、不进公海、冻结回收计时**（暂缓期间不被超时回收；取消暂缓后按剩余天数续算，票 05）。保留暂缓前阶段/节点。到期不自动恢复——系统提醒领取人，人工选 取消暂缓（恢复推进）/ 继续暂缓 / 关闭。按钮可见性由权限点配置，可见即可点，与是否领取人无关。
_Avoid_: 中止（不存在）、挂起、冻结、关闭（关闭是明确无价值）

**取消暂缓**:
暂缓的逆动作（产品补充）：暂缓中 → 恢复推进，回到暂缓前阶段/节点。原型 A3 无独立页（推测详情页按钮）。按钮可见即可点，与领取人无关。
_Avoid_: 恢复（口语）、重启（重启是关闭的逆动作）、激活

**抛公海**:
商机流转动作（原型 A3-1-1-2-7）：不想继续做，退回商机公海让他人领取。**只清空领取人**，回公海，**不动其他团队成员**（产品明确）。**无池实体**——公海 = `opp_status=1 且 owner 为空` 的逻辑视图，`owner_dept_id` 保留决定谁能看到（票 05 原型 A7-3-2-5 定稿，推翻初稿的 `pool_id` 回池模型）。人工抛公海入口受公海规则 `allow_manual_pool` 开关控制；此外连续 `recycle_days` 天无**有效跟进**会被**超时回收**自动回公海（票 05 `executeRecycle`，锚点 `last_valid_follow_time`）。
_Avoid_: 释放（线索用「释放」）、退回、放弃

**关闭**:
商机流转动作（原型 A3-1-1-2-9）：明确无法继续推进时终止。选**关闭原因**（字典：项目取消 / 客户放弃 / 竞争失败 / 重复商机 / 无效商机 / 其他）+ 补充说明（选「其他」必填）+ 勾选确认框 → 状态「已关闭」。保留关闭前状态/阶段（**只读锁定**），历史数据不删。已关闭不可重复关闭。与暂缓互斥：短期有价值→暂缓，明确无价值→关闭。
_Avoid_: 中止（不存在）、作废（线索用「作废」）、删除、输单（口语）

**重启商机**:
关闭的逆动作（原型称「重新开启」，产品称「重启商机」）：已关闭 → 恢复。原型要求填重开原因。原型原文写「须管理权限用户」，但**产品后来统一为「重启按钮由权限点控制、可见即可点、与领取人无关」，以产品口径为准**。
_Avoid_: 恢复、取消暂缓（取消暂缓是暂缓的逆动作）、激活

**移交**:
负责人变更动作，**入口在团队成员页（原型 A3-1-1-1-8）**，非详情页顶部操作区。**移交只换领取人 `owner_user_id`**（产品明确），不动其他。**无独立「转让」动作**——「转让只有负责人能转」不是额外 guard，而是移交入口本身在负责人管理的团队成员页里（原型：「当前用户只能维护其权限范围内的团队成员及权限设置」），团队管理权实际落在领取人手上。
_Avoid_: 转让（无此独立动作）、转移、指派（分配才是指派）

**转项目**:
商机的下游终态动作：商机推到最后转成项目，商机进入「已转项目」终态、锁死不可回退（对称线索的「已转商机」）。**转项目端口**名字先占位——项目实体、项目查重规则（原型 A7-3-2-4）归 A5 项目模块，本域只承认终态、定占位契约。
_Avoid_: 成交、转化、结项、CreateProject（具体接口名留给 A5）

**已转项目**:
商机**终态**：已转成项目。锁死——不可暂缓 / 抛公海 / 关闭 / 编辑。对称线索的「已转商机」终态。
_Avoid_: 已成交、已完成、结束

**项目金额**:
商机主表字段 `project_amount`（decimal(14,2)，选填）。销售挖掘得来的**项目整体总包金额**。一个商机一个值，默认人民币元不建币种字段。早期未必知可后编缓补。票 03 Amendment 1。
_Avoid_: 方案预算（方案卡字段，不同层次）、预计金额（旧名，已弃）、成交金额（项目阶段才有）、合同金额

**方案预算**:
方案卡子表字段 `scheme_budget`（票 07）。销售对该商机下某个**方案卡**填的金额，**一个商机可多个方案卡 → 多个预算**。商机列表的「方案预算」列关联查主要方案卡的预算，主表不冗余。
_Avoid_: 项目金额（商机主表字段，不同层次）、预计金额（旧名，已弃）

**商机阶段模板**:
商机业务阶段轴（轴2）的**版本化配置**，住 `crm-rule` 的 `opportunity_stage_template`（票 06 原型 A7-3-2-1）。范式 = `template_code`+`version_no`+草稿/发布中/已停用 + 适用范围(所有商机/指定部门/指定业务类型) + 是否默认，与票 05 公海规则、票 07 方案卡模板**同族**（公共约定 V-CONFIG）。子表：`_dept`/`_biztype`(适用对象)、`opportunity_stage_node`(有序阶段节点，引用「商机阶段」字典)。商机绑定后**锁死版本、发新版不迁移**（在途商机续用原版本，新建用最新发布版本）。
_Avoid_: 阶段字典（模板引用字典，不同层次）、阶段（阶段是运行时轴，模板是配置）

**阶段模板节点**:
`opportunity_stage_node`：一个阶段模板版本下的有序节点（`seq_no` + `stage_dict_code` 引用「商机阶段」字典 + `custom_node_name` + `work_goal` 工作目标 + `is_fixed`）。「已转项目」= `is_fixed=1` 固定末节点。模板节点覆盖显示名不反写字典。
_Avoid_: 阶段字典项（被引用方）、current_stage（运行时指针）

**商机公海规则**:
商机公海/回收/领取/提醒的**版本化规则配置**，住 `crm-rule` 的 `opportunity_pool_rule`（票 05 原型 A7-3-2-5 定稿）。范式 = 草稿/发布中/已停用 + `rule_code` + `version_no`（与票 06 阶段模板、票 07 方案卡模板同族），**不是** `lead_pool` 那种「一部门一池」实体（推翻初稿）。适用范围 = 所有部门通用 / 对应部门专用 + 默认规则兜底（无省/市/区地理维度）。**匹配以最低层级规则为准**（部门专用 > 通用默认，多部门专用取最具体）；**一个部门同时只能被一条发布中规则覆盖**（发布时校验部门不重叠），故命中唯一（票 05 产品拍板）。五配置项：`allow_manual_pool`（允许手动抛公海）/ `auto_recycle_enabled`+`recycle_days` / `allow_free_claim`（允许自由领取）/ `recycle_remind_enabled`+`remind_days`。
_Avoid_: 商机公海池（无池实体）、商机池、线索池

**回收天数**:
商机公海规则字段 `recycle_days`（`auto_recycle_enabled` 时必填）：连续 `recycle_days` 天无**有效跟进**（跟进/附件/字段编辑，非浏览；锚点 `last_valid_follow_time`）则超时回收→待领取，清 owner（票 05 `executeRecycle`）。回收前 `remind_days` 天提醒当前负责人（`remind_days` < `recycle_days` 硬校验）。**无失效天数 M**（商机无失效态，票 04/05）。
_Avoid_: 失效天数（商机无）、超时天数、N

## 待细化（后续票）
- 「移交」按钮原型位置、「取消暂缓/重启」独立页存否 —— 见 `issues/01` 的 To-verify，以产品口径为准。
- 商机主表 + 子表（团队成员 / 方案卡 / 现场勘察 / 跟进 / 附件 / 操作日志）字段（票 03/07/08/09）。
- 商机公海规则已定（票 05，版本化配置 `opportunity_pool_rule`，原型 A7-3-2-5）；四视图查询与「我的关注」表（票 10）。
- `crm-rule` 从「线索规则」升级为「通用业务规则域」的 CONTEXT.md 改写（本决策副作用）。