crm-backend-matt/.scratch/opportunity-module/产品待确认清单.md

# 商机模块 — 产品待确认清单

> 生成自 `.scratch/opportunity-module/issues/01–14` 全部 ⚠ 待核项汇总。
> **建模现状**：票 01–10 + 13/14 spec 已 resolved，下列待确认项**均不阻塞建模/表结构**（各票已给默认处置），仅在**落地实现前**须产品拍板。按「是否影响数据模型」分 P0/P1/P2 三档。
> 票 11/12 是实现票（改代码），另见文末。

---

## P0 — 影响数据模型，改动代价大（优先确认）

### ✅ P0-1 「预计成交时间」字段归属 — 已拍板（含二次修订）
- **来源**：票 03、票 07、票 10
- **结论**（产品二次拍板）：**「预计成交时间」列从商机列表删除，不上商机主表**。它是方案卡内部字段（票 07，由方案卡模板决定是否出现/必填），仅在方案卡内部录入回显，**不进商机四视图列表**。
- **演进**：首拍“它是方案卡字段、列表 join 主要方案卡展示” → 二次拍板直接“列表不展示该列”。两版都不建主表字段，结论一致收敛。
- **已落**：票 03（不建主表字段）、票 10（列头/计算列均删除该列）、票 07（字段库保留为方案卡内部字段，注明列表不展示）。

### ✅ P0-2 阶段模板「适用范围」 — 已拍板
- **来源**：票 06、票 07
- **结论**（产品拍板）：**两档单选 — 仅 所有商机 / 指定部门，本期不做“指定业务类型”档，不交叉**。原型三档收为两档，与票 05 公海规则 / 票 07 方案卡模板的两档对齐。
- **已落**：票 06（`apply_scope` 改两档、删 `_biztype` 子表）、CONTEXT.md、map.md。票 07 方案卡模板本就是两档（不受影响）。
- **向后兼容**：若将来要业务类型维度，`apply_scope` 扩一档 + 加子表即可，现有两档数据兼容，非推翻式改动。

### ✅ P0-3 字段定义表归属（方案卡系统字段库） — 已拍板
- **来源**：票 07
- **结论**（产品/架构拍板：**A 自建**）：方案卡字段库 = **自建 `opportunity_scheme_field_def`**（crm-rule）。它是**字段元数据**（`field_key`/`field_name`/`field_type`控件类型/`ref_target`关联对象指向/`autofill_source`自动回填来源/`option_source`选项来源/`default_value`/`is_deletable`）。
- **为何不用 crm-dict**：查了现有结构，crm-dict = DictGroup+DictItem 码表模型（`name/code/value`），只能表“一组可选值”，**无 field_type / 关联目标 / 回填来源列**，形状不匹配；硬塑会污染通用字典。
- **组合而非二选一**：“单选下拉”类字段的**选项集**仍 `option_source=dict_group_code` 引用 crm-dict 分组——该走字典的选项走字典，字段定义本身自建。
- **已落**：票 07（字段定义表 + 待核项）、CONTEXT.md（方案卡模板术语）、map.md。

### ✅ P0-4 方案卡状态枚举 + 列表派生列取值锚点 — 已拍板
- **来源**：票 07 / 票 10
- **结论（产品拍板）**：
  1. **单卡状态枚举** = `草稿1 / 已提交2 / 已推送3`（“保存草稿”→草稿；“确认”→已提交；推送 A7-3-2-3→已推送，本期预留）。**「未创建」= 0 卡展示态**（不入库；卡一经创建至少为草稿）。原型角标“草稿/待提交”归一为草稿，“填写中”= 草稿展示别名。
  2. **不做「主要方案卡（主卡 `is_primary`）」**——原型无“设为主卡”入口，属脑补，**删除**。
  3. **取值锚点 = 主要意向客户**（客户级 `is_primary_intended`，新建 **票 13** 商机-客户关联子表）。**一客户一卡** `UNIQUE(opportunity_id,customer_id)`；列表「方案预算」列 + 「方案卡状态」列均取主要意向客户那张卡的对应值（无主客户卡→预算空/状态未创建）。
- **关键纠正**：之前 `is_primary`（卡级主卡）是脑补；真正概念是 **主要意向客户**（客户级，原型 line 769/1235 实有）。主键是客户不是卡。
- **已落**：新建票 13；票 07（状态机/字段行/3.3段/一客户一卡 UNIQUE/两条待核项）、票 03（C3 主客户冗余+子表指票 13）、票 10（两列锚点）、CONTEXT.md（关联客户/方案卡/方案预算三术语）、map.md（交付清01-13/票 13 决策行/Not-yet-specified 提升）。
- **遗留**（不阻塑）：提交/推送后哪些核心字段锁 待产品细化。

---

## P1 — 枚举/状态精度，影响校验与状态机（次优先）

### ✅ P1-1 方案卡状态精确枚举 + 提交/推送后锁字段集 — 已拍板
- **来源**：票 07
- **结论**：① 状态机 = `草稿1/已提交2/已推送3`（未创建=0卡展示态；待提交/草稿不独立成态，P0-4 已定）。② **可编辑性**：**草稿/已提交均可继续修改，仅已推送整卡只读**（`card_status<3` 可编辑）。已推送要改→新建卡。不做字段级锁。
- **已落**：票 07（line 87 可编辑性行 + 待核项）。原型 line 802 “由业务规则控制”→本项定为“仅已推送锁”。

### ✅ P1-2 现场勘察「勘察次数」生成方式 — 已拍板
- **来源**：票 08
- **结论（产品拍板）**：**手选四档枚举** = 第一次 / 第二次 / 第三次 / 三次以上（原型 line 919-922 实有四档，非三档）。走 `crm-dict`「勘察次数」分组，**非系统自增**（“三次以上”是封顶枚举、不是序号，自增模型表达不了）。
- **已落**：票 08（`survey_seq` 字段行 + 字典回填 + 待核项）。crm-dict 新增「勘察次数」分组。

### ✅ P1-3 现场勘察「勘察补充说明」必填强度 — 已拍板
- **来源**：票 08
- **结论（产品拍板）**：**选填**。原型录入表单无 `*`（用户图上确认：带星的是勘察次数 + 现场勘察日期）。之前票 08 写“建议必填”系脑补加码，已改回选填，不给原型加它没有的约束。
- **附带修正**：日期字段——原型带星必填，标签=「现场勘察日期」（图上确认；存档 line 924/1020 的“预计重启/看场日期”系 analyze 噪声）；票 08 字段由选填 `plan_survey_date` 改为必填 `survey_date`。
- **已落**：票 08（补充说明选填行 + 日期必填行 + 待核项）、map.md。

### 🅿️ P1-4 工作计划执行状态精确枚举 — 挂起（归 A1X 独立模块）
- **来源**：票 09（工作计划段）
- **结论（产品拍板）**：**工作计划是独立业务模块（A1X），本期挂起不做**。执行状态精确枚举、状态机、联动全部归 A1X 模块决策，**不在商机模块本期范围内**。
- **本期商机侧只保留**：`opportunity_work_plan` 子表结构 + 归属契约（结构 only，票 09 P5）；`plan_status` 已按 未完成0/已完成1 占位（逾期实时派生不存态），精确态待 A1X。
- **已落**：票 09（P5 段标注 🅿️ 挂起 + plan_status 归属说明）。

### ✅ P1-5 操作日志「关键字段」范围 — 已拍板
- **来源**：票 09（P6 操作日志段）
- **结论（产品拍板）**：**默认全记 + 短黑名单排除**，不做白名单。商机主表及各子表业务字段变更默认全部记审计；黑名单排除技术字段(`create_time`/`update_time`/`version`)、系统自动刷新无业务含义字段(`last_valid_follow_time`)、不落库派生列。状态流转/阶段迁移照记，与专用快照表并存不重复。
- **依据**：原型 line 1745 给的是行为类别（字段变更/状态流转/附件/推送）非字段白名单；白名单是长期负债（加字段易漏审计），商机低频写全记扛得住且审计更全。
- **已落**：票 09（P6 写入点 + 待核项）。

### ⚠ P1-6 归属起点计时初始化（E1/E2/两入口创建）— 挂起，待产品确认
- **来源**：票 03/04/05 交叉缝隙（grill 20260821 发现，PRD §2.2/§3.2 已标注 ⚠）
- **问题**：回收公式 = `now − last_valid_follow_time ≥ recycle_days`，但该锚点在三处归属起点未统一初始化：
  1. **E1 领取**：已设 `claim_time` + 刷锚点=now（票 04）
  2. **E2 分配**：只设 `claim_time`，**不刷锚点**（票 04 疏漏）
  3. **两入口新建（线索转入/直接新建）**：出生即「推进中」+有负责人，不经过领取边，两字段均未定义（票 02 未提）
- **后果**：锚点为 NULL 时回收公式失效——分配/新建的商机若接手人从不跟进，将**永远不被回收**，回收机制有漏洞。
- **候选方案**：
  - A：四场景统一设 `claim_time=now` + 锚点=now（归属起点口径，锚点永不空，公式不改）
  - B：只补 `claim_time`，公式改 `now − COALESCE(锚点, claim_time)`
  - C：不补，锚点空不回收（有漏洞，不建议）
- **不阻塞建模**：两字段均已建表，仅侧效口径待定。

### ⚠ P1-7 暂缓期间子表可写范围 — 挂起，待产品确认
- **来源**：票 04/09 缝隙（grill 20260821；原型 A3-1-1-2-6 只说「暂停部分推进动作和常规跟进提醒」，未枚举具体项）
- **问题**：暂缓中(3) 的流转限制已定（票 04：允许 E5 取消暂缓/E6 关闭/E9 移交；推进节点/转项目/抛公海需先取消暂缓），但**写跟进、方案卡/勘察/附件/关联客户/团队成员等子表写**是否允许，原型未明确。
- **候选方案**：
  - A：写跟进 + 子表写全部允许（仅推进节点/转项目/抛公海受限）——「暂停推进动作」≠禁记录留痕
  - B：写跟进允许、子表写禁
  - C：全禁只读（同关闭口径）——与原型「保留已有业务数据、暂停部分动作」不符
- **已关闭(4) 不在此项内**：原型 A3-1-1-2-9 已明确（推进类隐藏/置灰/禁止、只读操作保留），已回填 PRD §3.3。

## P2 — 展示/交互口径 + 字典选项（可后置，不影响核心模型）

### P2-1 各类字典具体选项集（走 crm-dict）
- **来源**：票 05/07/08/09（多处）
- **需产品提供选项值**（本模块只定"要做字典"，不定值）：
  - 跟进方式（电话/上门/微信/线上会议/展会…）、跟进结果标签（暂无进展/需求确认/方案推进…）— 票 09
  - 商机资料类型（现场资料/设计清单·图纸/客户需求资料/招投标相关资料/其它）— 票 09（原型明确要做字典）
  - 申请方式（工单申请/线下申请…）— 票 08
  - 进入公海原因（销售主动释放/特殊原因暂停/领导释放/超期回收）— 票 10
  - 商机阶段字典 `OPP_STAGE_*`（客户圈定/关系摸排/资料采集/方案卡/已转项目…）— 票 06

### ✅ P2-2 最近访问视图：去重规则 + 条数上限 — 已拍板
- **来源**：票 10
- **结论（产品拍板）**：按商机 id **去重**（留最新访问时间）；**条数上限做成配置值，本期默认 50 条**。原型只画死"打开过详情/访问时间倒序/未访问不展示"(line 2672-2683)，去重·上限本由产品定。本期只商机用，做成可配置便于后续复用/调整。
- **已落**：票 10（最近访问视图行 + spin-out 段 + 待核项）、CONTEXT.md。

### ✅ P2-3 方案卡状态列在多卡场景的展示口径 — 已由 P0-4 拍板
- **来源**：票 10 / 票 07
- **结论**：**已在 P0-4 拍板**——列表「方案卡状态」列 + 「方案预算」列均取**主要意向客户（票 13）那张方案卡**的值（一客户一卡；不做主卡/汇总态）。见 P0-4。
- **已落**：票 07 / 票 10 / 票 13。

### P2-4 管理视角「领导 ▾」层级数据范围
- **来源**：票 10（line 86）
- **需产品定**：视角下拉「商机管理（领导）」的层级数据范围与 `@DataScope` 的精确映射。

### P2-5 视图默认排序
- **来源**：票 10（line 87）/ 票 14
- **现状**：原型「建议按最近跟进/节点停留时间」等（预计成交时间列已删）。自定义视图自带排序（票 14），内置视图默认排序仍待定。
- **需产品定**：确定内置视图默认排序维度。

### P2-7 自定义视图（票 14）— 交互口径待确认
- **来源**：票 14（demo 0803 `oppModule`）
- **已拍板**（票 14）：内置视图四个（最近访问/我负责的/我参与的/我关注的，固定不可增删改）；「我参与的」=团队成员且非负责人；自定义视图落 `crm-preference` 平台能力（用户私有、按 scope、本期 `opportunity.sales`）；检索字段=列表所有可筛选列；图钉设默认视图。
- **需产品定（不阻塞建模，落地前拍板）**：
  - 每用户自定义视图**数量上限**（demo 无限制，前端 localStorage）。
  - **多组条件（AND/OR 复合）+ 高级公式**——demo 标注「后续迭代」，本期契约按条件列表预留、前端只 1 组；何时开放待产品定。
  - 自定义视图是否**仅个人私有**（票 14 定私有；是否需要「共享给团队/角色」为后续需求）。
  - 「商机管理」「商机公海」workspace 是否也开自定义视图（票 14 定本期不开）。

### P2-6 公海规则数值样例
- **来源**：票 05（line 138）
- **说明**：原型 recycle_days/remind_days = 30/7、45/7、20/5 均为**样例非验收值**，实际由规则配置录入，无需产品预先定死。

### P2-8 grill 20260821 补录遗留项
- **暂缓到期提醒渠道**：提醒对象=当前领取人已定（CONTEXT），到期不自动恢复、提醒后人工选 取消暂缓/继续暂缓/关闭已定；提醒发送渠道（站内信/短信/邮件）属平台通知基础设施，待平台通知能力确定时拍板。不阻塞建模。
- 今日已拍板（已回填 PRD/CONTEXT）：直接新建必填主要意向客户；公海规则锚点=商机 `owner_dept_id`、实时匹配当前发布版、已执行动作不回溯（版本快照写 oplog，PRD 补 §5.4）；公海商机在管理视图按 DataScope 档位自然判定可见性；商机无删除动作；recent 视图任意详情皮肤都算访问；customer_role 全部选填；附件仅跟进限 10。

---

## 实现票（非 spec，待其他模块/编码阶段）

### 票 11 — CreateOpportunityCmd 新增 customerId + 线索侧意向客户下拉
- **性质**：改代码实现票（决策已在票 02 钉死）。
- **阻塞**：**依赖 A4 客户模块（未建）**——「下拉选客户」需线索侧能查客户列表，A4 到达前无法完整落地。

### 票 12 — 商机侧新增入口：关联线索校验
- **性质**：改代码实现票（决策已定）。
- **阻塞**：不阻塞其他票；实现顺序放主表(票03)+状态机(票04)编码之后。

---

## 已由产品拍板确认的项（备查，无需再确认）

- 按钮可见即可点，权限全由权限点定，与"是否领取人"无关（无 owner guard）— 票 01
- 无"转让"动作；负责人变更 = 团队成员页【移交】，只换负责人 — 票 01
- 抛公海只清负责人，不动团队成员 — 票 01
- 商机来源(oppSource) 与 来源线索(source_lead_id) 是两个独立字段，线索转入默认 oppSource=「线索转入」— 票 01
- 项目属地 = 本地/异地字典分类（非地理坐标）— 票 03
- 项目金额 project_amount 建；预计成交时间不上主表、且商机列表不展示（方案卡内部字段，见 P0-1）— 票 03/07/10
- 公海规则多规则匹配以最低层级为准 + 部门覆盖唯一（发布校验不重叠）— 票 05
- 暂缓中不参与回收、回收计时冻结 — 票 05
- 阶段除「已转项目」外可自由切换（连跳/回退）；「已转项目」不可手动点，仅方案卡转项目创建触发 — 票 06
- 意向客户下拉选客户 + 带 customerId（实现见票 11）— 票 02
- 商机侧新增入口选「线索转入」时关联线索必填（实现见票 12）— 票 02/12