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）。子表 = opportunity_customer（票 13）：customer_id 引用 A4 客户 + 名快照、customer_role 角色（→crm-dict）、is_primary_intended 是否主要意向客户。规则（产品拍板）：一商机可多个关联客户，有且仅一个主要意向客户；UNIQUE(opportunity_id, customer_id)。线索转商机时填的意向客户 = 落为主要意向客户；商机侧可加普通关联客户、可改主要意向客户（切换标记）。主表冗余 primary_customer_id/名快照（免 join）。主要意向客户是列表派生列（方案预算/方案卡状态）的取值锚点（票 07/10）。⚠ customer_id 引用 + 下拉选客户能力依赖 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）。销售对该商机下某个方案卡填的金额。一客户一卡（UNIQUE(opportunity_id, customer_id)），一商机多客户 → 多卡多预算。商机列表「方案预算」列 = 查主要意向客户（票 13）那张方案卡的预算，主表不冗余。不做主卡（is_primary）——取值锚点是主要意向客户（客户级），非卡级。 Avoid: 项目金额（商机主表字段，不同层次）、预计金额（旧名，已弃）

方案卡: 商机推进过程中沉淀「客户需求/预算/招标形式/介入阶段/方案状态」的业务单据，转项目的基础档案。住 crm-opportunity 的 opportunity_scheme_card（票 07，原型 A3-1-1-1-3）。一商机可多张、一客户一卡（UNIQUE(opportunity_id, customer_id)），每张必关联商机下一个关联客户（无孤立方案卡）；字段集由绑定的方案卡模板版本驱动（动态字段）；单卡状态 草稿1/已提交2/已推送3（「未创建」=0卡展示态，P0-4）。列表「方案卡状态/方案预算」列取主要意向客户那张卡（票 13，非主卡）。商机下任一方案卡转项目创建成功 = 「已转项目」联动触发源（票 06）。 Avoid: 推送方案/方案推送规则（A7-3-2-3，out of scope）、查重规则（A7-3-2-4，out of scope）

现场勘察: 记录商机某次到客户现场勘察的结果单据（现场条件/客户需求/安装环境/工程师建议 + 附件）。住 crm-opportunity 的 opportunity_site_survey（票 08，原型 A3-1-1-1-4）。一商机可多条（多次勘察保留历史不覆盖）；无状态机（区别于方案卡）；不绑阶段节点（自由记录）；主要工程师从 crm-auth 组织架构选（engineer_user_id，非自由文本）；附件**复用 crm-file**商机附件子表（biz_type=SITE_SURVEY+biz_id，票 09），不独立建表。 Avoid: 工程师=操作人（工程师是被选执行人，可跨部门；操作人是当前登录销售）

跟进记录: 商机的客户沟通记录，opportunity_follow（票 09，原型 A3-1-1-1-6）。无草稿态（确认即提交，异于线索反馈记录）；字段：跟进内容/时间/方式/关联客户/联系人/结果标签/下次跟进时间/附件。保存跟进→刷新 last_valid_follow_time（票 05 回收锚点刷新点之一）；与阶段推进不联动。 Avoid: 线索反馈记录（有草稿态，机制不同）

商机附件: 统一附件子表 opportunity_attachment（票 09，原型 A3-1-1-1-5，文件本体走 crm-file）。一张表 + biz_type+biz_id 定位，服务商机通用/跟进/勘察/方案卡各场景（biz_type 枚举 OPP/FOLLOW_UP/SITE_SURVEY/SCHEME_CARD…），避免每个子表各建一套附件表。资料类型走 crm-dict「商机资料类型」分组（原型明要求做字典）；附件归属商机（无孤立附件）。 Avoid: 方案卡附件/勘察附件各自建表（已统一为一表）

工作计划: 商机下的待办/后续动作子表 opportunity_work_plan（票 09，原型 A3-1-1-1-7）。字段：计划内容/截止时间/执行状态(未完成/已完成/逐期实时算)/创建人。本域只定商机侧子表结构与归属，不定 Tab 怎么读中央工作计划模块 A1X（spin-out）。 Avoid: 中央工作计划模块（A1X，跨域，本票不定读写）

操作日志: 商机的字段级变更审计 opportunity_oplog（票 09，原型 A3-1-1-1-9）：实体对象/字段名称/旧值/新值/操作说明/来源(系统自动 vs 人工)/时间/操作人。普通用户只读。与线索 lead_history 口径不同：线索是动作类型枚举(CLAIM/ASSIGN…)+JSON，商机是字段级旧新值审计。状态/阶段迁移另有专用快照表（opportunity_status_history/opportunity_stage_history），与本通用审计并存不重。 Avoid: 线索 history 模型（动作枚举，口径不同）、状态/阶段快照表（专用表，非通用审计）

四视图: 商机列表四视图（票 10，原型 A3-1-1/A3-2-1/A3-3-1/A3-0-1）：销售机会（个人） owner=当前用户 / 商机管理 按 @DataScope / 商机公海 opp_status=1 且 owner 空 逻辑视图 / 最近访问 打开过详情的商机按时间倒序、按商机 id 去重留最新，上限可配置(本期默认 50 条)。计算列不冗余存：节点停留时间=今−进入当前节点日(stage_history)、最近跟进=最新 follow 时间、预计金额=project_amount。详情三皮肤（个人/管理/公海）=同一聚合按视角展不同操作区，非三套数据。 Avoid: 视图=状态切片（同一商机可跨视图）、预计成交时间（产品二次拍板：商机列表删除该列、不上主表；仅方案卡内部字段票07）

进入公海原因: 商机抢公海/回收时的分类 pool_reason（票 10 原型 A3-3-1 筛选项）：销售主动释放 / 特殊原因暂停 / 领导释放 / 超期回收。公海列表按此筛选；「领导释放」=管理侧强制抛公海(操作人≠owner)；「超期回收」=票 05 executeRecycle。抢公海时亦快照入池前工作节点。 Avoid: 抢公海无原因（已分四类，回填票 04/05）

方案卡模板: 方案卡的版本化字段集配置（选哪些字段/顺序/显示/必填/适用范围），住 crm-rule 的 opportunity_scheme_card_template（票 07 原型 A7-3-2-2）。与票 05 公海规则、票 06 阶段模板同族（公共约定 V-CONFIG：template_code+version_no+草稿/发布中/已停用，绑定锁版发新版不迁移）。字段来自系统字段库非自由造（删字段不删系统字段定义）；字段库 = 自建 opportunity_scheme_field_def（字段元数据：控件类型/关联对象目标/自动回填来源，crm-dict 码表模型不匹配故不复用；下拉类字段选项集可 option_source 引用 crm-dict 分组）；适用范围两档（所有部门通用/对应部门专用，同票 05，异于票 06 三档）。 Avoid: 方案卡（运行时单据，模板是配置） 商机业务阶段轴（轴2）的版本化配置，住 crm-rule 的 opportunity_stage_template（票 06 原型 A7-3-2-1）。范式 = template_code+version_no+草稿/发布中/已停用 + 适用范围(所有商机/指定部门 两档单选，本期不做指定业务类型) + 是否默认，与票 05 公海规则、票 07 方案卡模板同族（公共约定 V-CONFIG）。子表：_dept(适用对象，apply_scope=2)、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 改写（本决策副作用）。