crm-backend-matt/.scratch/opportunity-module/issues/09-child-tables-followup-attachment-log.md

# 09 商机子表族：跟进记录 / 附件 / 工作计划(表) / 操作日志

Type: grilling
Status: resolved
Blocked by: 03

定商机详情剩余子表族。原型均已拉取核实，存档 `research-a3111-followup-log.md`（跟进/写跟进/操作日志）、`research-a3111-attachment-workplan.md`（附件/工作计划）。

---

## P2 跟进记录 `opportunity_follow`（原型 A3-1-1-1-6 / 写跟进 A3-1-1-2-2）

### 已核实事实
- **无草稿态**：写跟进弹窗「确认」即校验+提交，无暂存/草稿（**异于线索反馈记录**，对齐时须注意）。
- 保存后**不建议删除**（保留销售过程痕迹）。
- **保存跟进 → 刷新商机「最近跟进」**（原型明证「保存后销售机会列表『最近跟进』同步更新」）= 票 05 `last_valid_follow_time` 锚点刷新点之一（**回填票 05/03**）。
- 与阶段推进**不联动**（写跟进不自动推阶段；阶段是独立自由切换，票 06）。

### 字段（原型「写跟进」核实，★=必填）
| 字段 | 落库 | 说明 |
|---|---|---|
| 跟进内容★ | `follow_content` | 长文本 |
| 跟进时间★ | `follow_time` | 默认当前时间可改 |
| 跟进方式★ | `follow_way` | 电话沟通/上门拜访/微信对接/线上会议/展会沟通（→ `crm-dict` 字典） |
| 关联客户★ | `customer_id` | 默认带出商机关联客户；引用商机下关联客户 |
| 客户联系人 | `contact_id` | 选填 |
| 跟进结果标签 | `result_tag` | 选填：暂无进展/需求确认/方案推进/资料采集/关系维护/预算沟通/勘探现场/方案深化（→ 字典） |
| 计划下次跟进时间 | `next_follow_time` | 选填；不得早于本次跟进时间（校验）；可生成后续提醒/工作计划 |
| 附件 | → P4 附件子表 | `biz_type=FOLLOW_UP`；最多 10 个，格式见 P4 |

表 `opportunity_follow`：上述字段 + `opp_id` + BaseEntity（保留 create_by/create_time = 记录人/时间）。

---

## P4 附件 `opportunity_attachment`（原型 A3-1-1-1-5，复用 `crm-file`）

### 已核实事实
- **附件归属商机**（无孤立附件，硬约束）。
- **按资料类型分类**；**原型明证：「资料类型要做字典，该模块固定写入所有『商机资料类型』」→ 走 `crm-dict`**（资料类型样例：现场资料/设计清单·图纸/客户需求资料/招投标相关资料/其它）。
- 记录：资料类型/附件内容(文件)/上传人/上传时间/说明。

### 统一附件子表（票 07/08 均复用此表，避免各建一套）
表 `opportunity_attachment`（`crm-opportunity`，文件本体走 `crm-file`）
| 字段 | 说明 |
|---|---|
| `id` / `opp_id` | 主键 / 归属商机 |
| `biz_type` | **业务类型枚举**：`OPP`(商机通用) / `FOLLOW_UP`(跟进) / `SITE_SURVEY`(勘察, 票08) / `SCHEME_CARD`(方案卡, 票07) … |
| `biz_id` | 业务对象 id（跟进记录/勘察记录/方案卡 id；商机通用时=opp_id 或空） |
| `material_type` | 资料类型（`crm-dict`「商机资料类型」分组） |
| `file_id` | 引用 `crm-file` 文件 |
| `remark` | 附件说明 |
| BaseEntity | 上传人=create_by / 上传时间=create_time |

> **这是票 07/08 传出的附件契约落点**：一张附件表 + `biz_type`+`biz_id` 定位，不为每个子表各建附件表。

---

## P5 工作计划 `opportunity_work_plan`（原型 A3-1-1-1-7，**结构 only**）

### 已核实事实
- 商机下多条工作计划（待办/后续动作：客户拜访/资料补充/方案确认/内部协调/投标准备）。
- 有**执行状态**：原型 line 994「例如：未完成、已完成、已逾期等」——「例如…等」系 analyze 归纳措辞；唯一状态动作是「标记完成」(line 1048)，无「标记逾期」按钮，逾期由 `now>deadline` 派生(line 972/980)。操作：编辑/删除/标记完成。
- 「剩余时间」= 由 `deadline` 实时算，逾期展示提示（不落库）。

### 表结构（本票只定 `商机-工作计划` 子表结构与归属契约，**不定** Tab 怎么读 A1X 工作计划模块）
表 `opportunity_work_plan`（`crm-opportunity`）
| 字段 | 说明 |
|---|---|
| `id` / `opp_id` | 主键 / 归属商机 |
| `plan_content` | 计划内容 |
| `deadline` | 截止时间（判临期/逾期） |
| `plan_status` | 未完成0/已完成1（逾期=未完成且 now>deadline，实时算，不单独存态）。**精确态枚举归 A1X 工作计划模块**（本期挂起，见下） |
| `finish_time` | 标记完成时间 |
| BaseEntity | 创建人=create_by |

- 🅿️ **工作计划 = 独立业务模块 A1X，本期挂起不做（产品拍板 P1-4）**：本商机模块**只保留 `商机-工作计划` 子表结构与归属契约**（多条/归属商机/内容/deadline/plan_status/finish_time）；**执行状态精确枚举、状态机、与「下次跟进时间生成工作计划」的联动、Tab 读中央模块** 全部归 A1X 模块定，不在本期商机模块内决策。

---

## P6 操作日志 `opportunity_oplog`（原型 A3-1-1-1-9）

### ⚠ 关键口径修正（与线索 `lead_history` 不同！）
- **线索 `LeadHistory`** = **动作类型枚举**（CREATE/CLAIM/ASSIGN/…）+ JSON detail。
- **商机原型操作日志** = **字段级变更审计**：实体对象 / **字段名称 / 旧值 / 新值** / 操作说明 / 操作时间 / 操作人 / **操作来源(系统自动 vs 人工)**。
- 原型明证：「商机关键字段发生变化时生成日志」「记录字段名称、旧值、新值」「系统自动与人工操作都记录并区分来源」「普通用户不可编辑/删除」「按时间范围查看、支持导出」。

**结论**：商机操作日志走**字段级变更审计模型**，不照搬线索的动作枚举模型。状态机(票04)/阶段切换(票06) 的迁移则各自另有 `opportunity_status_history` / `opportunity_stage_history`（专用快照表），操作日志是**通用字段变更审计**，两者并存不重复。

表 `opportunity_oplog`（`crm-opportunity`）
| 字段 | 说明 |
|---|---|
| `id` / `opp_id` | 主键 / 归属商机 |
| `entity_name` | 实体对象（哪张表/哪个业务对象变更） |
| `field_name` | 变更字段 |
| `old_value` / `new_value` | 旧值 / 新值 |
| `op_desc` | 操作说明 |
| `op_source` | 操作来源：系统自动 / 人工（区分） |
| `op_time` / `op_user_id` | 时间 / 操作人 |

- 普通用户只读（不可改删），支持按时间范围查询 + 导出。
- 写入点：商机主表及各子表**业务字段变更默认全部记**，由统一审计切面写入（实现细节建模定）。
- ✅ **「关键字段」范围 = 默认全记 + 短黑名单排除（产品拍板 P1-5）**：原型 line 1745 给的是行为类别（字段变更/状态流转/附件上传/方案推送），非字段白名单；不维护白名单（白名单是长期负债、加字段易漏审计）。**黑名单排除**：技术字段(`create_time`/`update_time`/`version` 乐观锁列)、系统自动刷新且无业务含义字段(`last_valid_follow_time`)、不落库的纯派生展示列。状态流转/阶段迁移**照记**（原型 line 1745 明列"状态流转"），与专用快照表(`opportunity_status_history`/`opportunity_stage_history`)并存不重复（快照=流转事实，日志=统一审计视图）。

---

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

- **回填票 05 + 票 03**：保存跟进记录 = `last_valid_follow_time` 刷新点之一（附件/字段编辑亦是，票 05 已列有效跟进口径）。
- **回填票 07 / 票 08**：附件契约落 `opportunity_attachment`（`biz_type`+`biz_id`），`biz_type` 枚举含 `SCHEME_CARD`/`SITE_SURVEY`/`FOLLOW_UP`/`OPP`。
- **回填 `crm-dict`**：新增分组 `跟进方式`、`跟进结果标签`、`商机资料类型`（原型明确要做字典）——列入字典清单。
- **口径纠偏**：商机操作日志 ≠ 线索 history 模型（字段级审计 vs 动作枚举），CONTEXT 应记此差异。
- **CONTEXT.md**：新增【跟进记录】【商机附件】【工作计划(子表)】【操作日志】术语。

## 待产品/原型核实（不阻塞建模）

- 🅿️ 工作计划整块（Tab 读 A1X + 执行状态精确枚举）= 独立模块 A1X，本期挂起（P1-4 拍板，见 P5 段）。
- ✅ 操作日志「关键字段」范围 = 默认全记 + 短黑名单排除（P1-5 拍板，见 P6 写入点）。
- ⚠ 各类字典具体选项集（跟进方式/结果标签/资料类型）待产品。