crm-backend-matt/.scratch/opportunity-module/issues/07-scheme-card.md

# 07 方案卡子表 + 方案卡模板

Type: grilling
Status: resolved
Blocked by: 03, 06

## 一、定位与两层拆分

方案卡（scheme card）= 商机推进过程中沉淀「客户需求 / 预算 / 招标形式 / 介入阶段 / 方案状态」的业务单据，是**转项目的基础档案**（转项目本身 out of scope → A5）。

分两层（对称阶段模板 票 06、公海规则 票 05）：

| 层 | 住哪 | 是什么 | 原型 |
|---|---|---|---|
| **方案卡模板** | `crm-rule` | 版本化**字段集配置**（哪些字段/顺序/显示/必填/适用范围） | A7-3-2-2（列表/详情/新增编辑） |
| **方案卡（运行时）** | `crm-opportunity` | 商机下的实际填写单据，一商机可多张 | A3-1-1-1-3 方案卡Tab / -3-1 编辑 |

存档：`research-a7322-scheme-card-template.md`（模板 3 页）、`research-a31113-scheme-card-runtime.md`（运行时 2 页）。

**边界**：推送方案（A3-1-1-2-5）+ 方案推送规则（A7-3-2-3）+ 查重规则（A7-3-2-4）**不在本票**——本票只定方案卡**本体与字段模板**，不定推送/查重。

---

## 二、方案卡模板（住 `crm-rule`）

### 2.1 复用 V-CONFIG（票 06 公共约定），本票不重述

原型 A7-3-2-2 已核实**完全命中 V-CONFIG**：模板编码(系统生成，跨版本一致) + 版本号(系统生成) + 草稿/发布中/已停用；同 code 同时仅一草稿+一发布中；发布使原发布中→已停用；仅草稿可删；编辑发布中/停用→生新草稿；复制→新 code 新主体；列表按版本维度一版一行；**绑定商机记录具体版本、发新版不迁移**（在途方案卡续用原版本，新建方案卡用最新发布版本）。

### 2.2 与阶段/公海模板的**关键差异**（⚠ 落地须留意）

- **适用范围 = 两档**（`所有部门通用` / `对应部门专用`）——**与票 05 公海规则同（两档），与票 06 阶段模板不同（三档）**。选「对应部门专用」→ 必选至少一个部门、且**不允许设为默认**；选「所有部门通用」→ 无适用对象、**可设为默认**。
- **默认唯一**：仅「所有部门通用」可设默认；同一有效范围仅一套发布中默认；发新默认原默认自动取消（V-CONFIG）。

### 2.3 表结构（`crm-rule`）

**`opportunity_scheme_card_template`**（模板头，版本行）
| 字段 | 说明 |
|---|---|
| `id` | 主键（= 版本行 id，绑定实体锁这个） |
| `template_code` | 模板编码，系统生成，跨版本一致 |
| `template_name` | 模板名称，同 code 各版本沿用 |
| `version_no` | 版本号，系统生成，varchar |
| `status` | 草稿1/发布中2/已停用3 |
| `apply_scope` | 1 所有部门通用 / 2 对应部门专用（**两档**） |
| `is_default` | 是否默认（仅 apply_scope=1 可为 1，同范围唯一） |
| `template_desc` | 模板说明 |
| BaseEntity | |

**`opportunity_scheme_card_template_dept`**（适用对象，apply_scope=2 时）：`template_id` + `dept_id`。

**`opportunity_scheme_card_field`**（模板字段项，有序）
| 字段 | 说明 |
|---|---|
| `id` / `template_id` | 主键 / 属哪个模板版本 |
| `seq_no` | 序号 = 方案卡填写页展示顺序（上移/下移重算） |
| `field_key` | **引用系统字段定义**（见 2.4），非自由造 |
| `field_name` | 展示字段名（快照，来自系统字段） |
| `field_type` | 控件/数据类型（快照，见 2.4 枚举） |
| `is_visible` | 显示开关（关闭→不出现在填写页，且强制 `is_required=0`） |
| `is_required` | 必填（仅 `is_visible=1` 时可为 1；关显示同步清必填——硬约束） |

### 2.4 字段来源 = 系统字段库（非自由造）

原型明证（业务规则 10）：「删除字段**仅影响当前草稿版本，不删除系统字段定义**」——字段来自一套**系统字段定义**，模板做的是「选字段 + 排顺序 + 开关显示 + 开关必填」，不是自由输入字段名/类型。

- 字段类型枚举（原型「字段类型」列已核实值）：**关联对象 / 单选下拉 / 自动回填 / 是否(是/否) / 附件上传 / 金额 / 单行文本 / 多行文本**。
- 单选下拉的选项内容、默认值、提示信息随字段定义带出（预览页可见）。
- **字段定义表 `opportunity_scheme_field_def`（crm-rule，自建——产品/架构拍板 P0-3）**：方案卡字段库是**字段元数据**（含控件类型/关联对象目标/自动回填来源），**不复用 crm-dict**（其码表模型 DictGroup+DictItem 只能表“一组可选值”，无 field_type/关联目标/回填来源列，形状不匹配）。字段：`field_key`/`field_name`/`field_type`(控件类型)/`option_source`(选项来源)/`ref_target`(关联对象指向)/`autofill_source`(自动回填来源)/`default_value`/`is_deletable`。**组合而非二选一**：“单选下拉”类字段的**选项集**可 `option_source=dict_group_code` 引用 crm-dict 分组（该走字典的选项走字典，字段定义本身自建）。删字段仅影响当前草稿模板，**不删系统字段定义**（原型 line 2345/2519）。样例字段：客户名称(关联对象)、客户类型(单选下拉)、客户联系人(关联对象)、客户联系电话(自动回填)、项目阶段(单选下拉)、招标形式(单选下拉)、是否有看现场(是/否)、方案预算是否明确(是/否)、**方案预算金额(金额)**、设计配置(单选下拉)、品牌要求(单行文本)、客户需求描述(多行文本)、**预计成交时间(日期)**、预计成交概率、预计投标时间…（**样例值，非验收**）。⏩ **产品拍板：「预计成交时间」是方案卡内部字段**（非商机主表）；**且商机列表不展示该列（产品二次拍板，票 10）**——仅在方案卡内部按模板配置录入/回显。

### 2.5 预览

「预览填写效果」按当前配置（含未发布的最新草稿态）渲染方案卡填写页，只读、不产生业务数据。**本票不建预览专属结构**（纯前端按 field 配置渲染）。

---

## 三、方案卡（运行时，住 `crm-opportunity`）

### 3.1 已核实事实（原型 A3-1-1-1-3）

- **一个商机可关联多张方案卡**（多张分组展示）。
- **每张方案卡必关联当前商机下的一个关联客户**（不允许无客户归属的孤立方案卡——硬约束）。
- ✅ **一客户一卡（产品拍板 Q2）**：方案卡表加 `UNIQUE(opportunity_id, customer_id)`——同一商机下一个客户只能有一张方案卡（关联客户表见票 13）。
- 不同客户 / 不同介入阶段 / 不同招标形式 → 可对应不同方案卡。
- ✅ **单卡状态机（产品拍板 P0-4）**：`草稿1 / 已提交2 / 已推送3`（点“保存草稿”→草稿；点“确认”→已提交，核心字段锁；推送 A7-3-2-3→已推送，本期状态位预留）。**「未创建」= 0 卡展示态**（商机无任何方案卡时的列表/Tab 展示，不入库、不占 card_status 值；卡一经创建至少为草稿）。原型角标「草稿/待提交」归一为“草稿”，字段说明列「填写中」= 草稿的展示别名。
- 方案卡字段值来自绑定的**方案卡模板版本**（动态字段）。
- ✅ **提交/推送后可编辑性（产品拍板 P1-1）**：**草稿(1) / 已提交(2) 均可继续修改全部字段**；**仅已推送(3) 整卡只读**（推送出去后不允许改，要改新建卡）。即可编辑判定 = `card_status < 3`。不做字段级锁（锁粒度=卡+状态）。

### 3.2 表结构（`crm-opportunity`）

**`opportunity_scheme_card`**（方案卡主）
| 字段 | 说明 |
|---|---|
| `id` / `opp_id` | 主键 / 属哪个商机 |
| `customer_id` | 关联客户（必填，商机下的某关联客户） |
| `template_id` | **绑定的方案卡模板版本行 id**（锁版本，发新版不迁移，对齐 V-CONFIG） |
| `template_version` | 冗余 `version_no` 展示用（免 join，对齐票 03/06 做法） |
| `card_status` | **草稿1 / 已提交2 / 已推送3**（tinyint；产品拍板 P0-4）。「未创建」不入库=0卡展示态。 |
| `scheme_budget` | **方案预算金额**（decimal(14,2)）= CONTEXT【方案预算】术语落点；商机列表「方案预算」列 = 查**主要意向客户**那张方案卡的此值（票 13；一客户一卡） |
| `bidding_form` / `enter_stage` | 招标形式 / 介入阶段（辅助推进优先级判断） |
| BaseEntity | |

**`opportunity_scheme_card_value`**（方案卡动态字段值，随模板字段）
| 字段 | 说明 |
|---|---|
| `id` / `card_id` | 主键 / 属哪张方案卡 |
| `field_key` | 对应模板 field |
| `field_value` | 值（文本/JSON，按 field_type 解析） |

> 结构化字段（预算/招标形式/介入阶段/客户）提升到主表便于列表 join 与筛选；其余按模板动态字段进 value 表。

### 3.3 列表派生列锚点 = 主要意向客户的卡（回填 CONTEXT【方案预算】）

CONTEXT【方案预算】术语：商机列表「方案预算」列 = 关联查**主要意向客户**（票 13 ）那张方案卡的 `scheme_budget`，主表不冗余。**方案卡状态列同锚点**（取主客户卡的 ，无主客户卡→未创建）。

- ✅ **不做「主要方案卡（主卡）」（产品拍板 P0-4）**：原型无“设为主卡”入口，`is_primary`（卡级）属脑补，**删除**。取值锚点 = **主要意向客户**（客户级 `is_primary_intended`，票 13）——主键是客户不是卡。列表「方案预算」列 + 「方案卡状态」列均取**主要意向客户那张方案卡**的对应值（一客户一卡）；无主客户卡 → 预算空、状态“未创建”。

---

## 四、方案卡 × 「已转项目」联动（对齐票 06「四」）

- 票 06 已定：轴2「已转项目」固定末节点，由**商机下任意一张方案卡转项目创建成功**触发。
- **触发源 = 方案卡**（本表某张卡走转项目 → A5 创建项目 → 回调驱动 轴1 `opp_status=5` + 轴2 `current_stage→已转项目节点`）。
- 转项目端口契约归 A5（票 04/06 已 spin-out），本票只承认「方案卡是触发源」这一事实。

---

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

- **回填 CONTEXT.md**：【方案卡】新增术语（多张、关联客户、模板驱动动态字段、状态机、转项目触发源）；【方案预算】落点确认 = `opportunity_scheme_card.scheme_budget`。
- **回填 map.md**：票 07 决策行；确认「方案预算」列 = 主要意向客户（票 13）那张方案卡 budget（不做主卡）。
- **V-CONFIG 印证**：方案卡模板是 V-CONFIG 第三个实例（票 05/06/07 三票同族确认），但**适用范围两档**（与公海规则同、与阶段模板三档不同）——V-CONFIG 抽象「版本状态机」，不抽象「适用范围档数」（各票按原型各自定）。

## 待产品/原型核实（落地前须核，不阻塞建模）

- ✅ **「主要方案卡」= 不做（产品拍板 P0-4）**：删 `is_primary`，列表用商机级聚合态。
- ✅ **方案卡状态枚举（产品拍板 P0-4）**：`草稿1/已提交2/已推送3`（未创建=0卡展示态）。✅ **提交/推送后可改（P1-1）**：草稿/已提交均可改，仅已推送只读（`card_status<3` 可编辑）。
- ✅ **字段定义表归属（产品/架构拍板 P0-3）**：**自建 `opportunity_scheme_field_def`**（字段元数据含控件类型/关联目标/回填来源，crm-dict 码表模型形状不匹配，不复用）；“单选下拉”类字段的选项集可 `option_source` 引用 crm-dict 分组（组合而非二选一）。
- ⚠ **`apply_scope` 交叉**（承票 06 同款待核项）：本票按原型两档单选。
- ⚠ 原型模板名/编码/字段/样例值均为样例，非验收值。