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/两入口创建）— 已拍板（产品回复 20260821）
- **来源**：票 03/04/05 交叉缝隙（grill 20260821 发现）
- **问题**：回收公式 = `now − last_valid_follow_time ≥ recycle_days`，但该锚点在三处归属起点未统一初始化：E1 领取已设两者；E2 分配只设 `claim_time` 不刷锚点（票 04 疏漏）；两入口新建（线索转入/直接新建）出生即「推进中」+有负责人，不经过领取边，两字段均未定义（票 02 未提）。
- **产品回复**：① 回收按最近一次有效跟进时间判断；② 领取、分配**重置**回收计时；③ 首次进入名下（新建/转商机）时不存在跟进记录，**以进入名下的时间作为起点**。
- **结论**：E1 领取/E2 分配均 `claim_time=now` + 锚点重置=now；两入口创建时 `claim_time=now` + 锚点=now（「进入名下时间」即创建时刻）。锚点永不空，回收公式维持 `now − 锚点` 不改。
- **已落**：PRD §2.2/§3.2 去 ⚠、侧效口径固化。

### ✅ P1-7 暂缓期间子表可写范围 — 已拍板（产品回复 20260821）
- **来源**：票 04/09 缝隙（原型 A3-1-1-2-6 只说「暂停部分推进动作」，未枚举）。
- **产品回复**：**暂缓/关闭状态：先解除状态，才能编辑操作。**
- **结论**：暂缓中(3) 与已关闭(4) 同口径——一切编辑操作（写跟进/方案卡/勘察/附件/关联客户/团队成员等子表写）全禁，必须先 取消暂缓/重启 回到推进中才能写。暂缓中(3) 允许的只有 E5 取消暂缓/E6 关闭/E9 移交。
- **已落**：PRD §3.3 暂缓行去 ⚠、口径固化；CONTEXT「暂缓」术语。

### ✅ P1-8 有效跟进定义修订 + 配置化 — 已拍板（产品二次修订 20260821）
- **来源**：票 05/09 原定义「写跟进记录/上附件/编辑字段（非浏览）」。
- **产品回复（首次）**：暂定为【推进中 + 写跟进、工作计划、标记完成、新增方案卡、新增现场勘察】五类。
- **产品回复（二次修订 20260821）**：动作收缩——**本期只有「写跟进」才算有效跟进**；配置机制保留，以后可能新增动作。
- **结论**：有效跟进 = **商机状态推进中(2) 且动作 = 写跟进**；上附件/编辑字段不计（已移出）；「工作计划/标记完成/新增方案卡/新增现场勘察」本期不计（后续经配置新增）。
- **配置落地（已拍板 20260821）**：`crm-rule` 第四族「有效跟进规则」`opportunity_follow_rule`（V-CONFIG 同族，动作类型多选子表，本期默认仅含「写跟进」），回收 Job 按商机 `owner_dept_id` 实时匹配当前发布中规则。
- **已落**：PRD §5.3 有效跟进定义更新。

### 🅿️ P1-9 公海视图可见范围 — 暂定口径（按产品意见，PRD 定稿后终审，grill 20260821）
- **来源**：票 05 line 106「谁能看/领某条公海商机 = 按匹配到的公海规则适用范围判定」与 PRD §2.4 索引注释「公海视图 + 部门天花板」两处口径缝隙。
- **问题**：公海视图（A3-3-1）查询时，可见范围是纯规则适用范围，还是叠加查看者自身 DataScope？
- **产品意见（20260821）**：公海视图与管理视图**同口径**——DataScope 按模块配置自动生效（配「本部门及以下」则公海也是本部门及以下），无需规则额外过滤。
- **暂定结论**：**公海可见 = `@DataScope` 自动叠加**（按 `owner_dept_id` 部门锚点，同管理视图口径）；**公海规则适用范围管「谁能领」（领取资格）+ 规则参数匹配**，不管可见性。「看得到但领不了」场景领取按钮置灰提示。
- **已落**：PRD §5.4（专属规则管领取不辖可见）/§6.1（公海工作区数据范围）；待产品终审后固化 CONTEXT「抛公海」相关术语与票 05 原文差异说明。

## 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。

### ✅ P2-9 跟进记录编辑/删除 — 已拍板（grill 20260821）
- **拍板**：**支持删除、删除不回退回收锚点**（`last_valid_follow_time` 保持不变，防「写了又删」刷锚点）；「最近跟进」按删除后最新留存行自然变化；删除入 oplog。**编辑本期不做**——写错以删除+补写修正。
- **已落**：PRD §7.4、CONTEXT「跟进记录」。

---

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

### 票 11 — CreateOpportunityCmd 新增 customerId + 线索侧意向客户下拉
- **性质**：改代码实现票（决策已在票 02 钉死）。
- **契约现状（grill 补拍 20260821）**：代码中 `CreateOpportunityCmd` **尚未含 `customerId`**，且字段命名（`intendedCustomer`/`regionCode`/`industryCode`）与主表 §2.1 不对齐。PRD 描述目标契约，本票 = 差量：① 新增 `customerId`；② `regionCode`→`province_code`/`city_code`；③ `intendedCustomer`→`customerId`+客户名快照。
- **阻塞**：**依赖 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