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 写入点）。
• ⚠ 各类字典具体选项集（跟进方式/结果标签/资料类型）待产品。

---

落地记录（20260825）

结构落地完成（对齐票 03「实体+Mapper骨架」粒度，§7.4–7.7 四张表）：

• 实体：OpportunityFollow / OpportunityAttachment / OpportunityWorkPlan / OpportunityOplog（均 @Entity+@TableName+继承 BaseEntity）。
• 枚举：AttachmentBizType（4 值）/ OplogKind（3 值 FIELD_CHANGE/ROW_ADD/ROW_DELETE）/ OplogLogType（7 值，SYSTEM_INTERNAL 记库不显）。
• Mapper：四个 *Mapper extends CrmBaseMapper。
• 软删口径：跟进/附件/工作计划 = 软删 + delete_key（存活0/删写id）；操作日志 = 只增不删无 delete_key。
• 测试：OpportunityChildTablesMapperTest（表绑定+列映射+逻辑删验证）+ OpportunityChildTablesEnumTest（值域），crm-opportunity 100→108 全绿。

接线待后续票（本票只落结构）：

• 跟进读写 Service/Controller + 保存跟进刷 last_valid_follow_time（票 05 联动）+ 删除记 ROW_DELETE oplog。
• 附件读写 Service/Controller（跟进限 10 个/条应用层校验）。
• 统一审计切面自动写 opportunity_oplog（写入点驱动）——字段级审计切面是独立机制，随主表/子表写入接线。
• crm-dict 新增分组「跟进方式/跟进结果标签/商机资料类型」= 字典种子子票。