luoweijian
/
crm-backend-matt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
145 Commits
1 Branch
0 Tags
401 MiB
 
 
 
 
 
Tree: 746b032092
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '746b032092'
${ noResults }
crm-backend-matt/.scratch/customer-module/issues/07-detail-follow-oplog.md

9.9 KiB
Raw Blame History

07 — 客户详情 8 页签 + 跟进记录 + 操作日志

Type: research Status: resolved Blocked by: 02, 05

问题

定客户详情页公共头部 + 8 页签数据源、跟进记录 customer_follow 子表、操作日志 customer_oplog 子表（字段级审计口径，对称商机 oplog 票 09）。

一手证据（蓝湖缓存 txt）

  • a4-4-1_客户详情_客户信息_.txt — 公共头部 + 客户信息页签 + 权限/敏感信息/加载/异常规则（这是详情页的顶层 spec，务必细读）
  • a4-4-2_客户详情_联系人_.txt — 联系人页签（复用票 06 数据源）
  • a4-4-3_客户详情_跟进记录_.txt — 跟进记录页签
  • a4-4-4_客户详情_关联商机_.txt — 关联商机页签（读 crm-opportunity ✅ 已建）
  • a4-4-5_客户详情_关联项目_.txt — 关联项目页签（读 A5 未建 → 划出本图，页签保留骨架显"—")
  • a4-4-6_客户详情_团队成员_.txt / a4-4-7_客户详情_团队成员_.txt — 团队成员页签
  • a4-4-6_客户详情_战略协议_.txt — 战略协议页签（战略协议子域划出 → 本图页签保留骨架显"—")
  • a4-4-1_客户详情_已归档客户_.txt / a4-4-1_客户详情_已被合并客户_.txt — 归档/合并态的详情皮肤
  • a4-4-7_客户详情_操作日志_.txt / a4-4-8_客户详情_操作日志_.txt — 操作日志页签

8 页签清单

  1. 客户信息 — 主表字段展开（票 02 字段集），支持折叠区块，「编辑客户信息」跳编辑页；「工商信息更新」→ 企查查回填 seam（票 04 复用）。
  2. 联系人 — 票 06 数据源，GET /api/customer/{id}/contacts。
  3. 跟进记录 — 本票新建 customer_follow 子表。
  4. 关联商机 — 反查 crm-opportunity（GET /api/opportunity/by-customer/{customerId} 需商机侧新增或本票新增反查接口）。
  5. 关联项目 — 划出（A5 未建），页签骨架保留。
  6. 战略协议 — 划出（战略协议子域），页签骨架保留。
  7. 团队成员 — 显示销售负责人 + 协同人；领导可维护。
  8. 操作日志 — 本票新建 customer_oplog 子表。

已知事实

  • 公共头部：客户阶段(潜在/重潜/已成交)/客户星级/销售负责人+部门/战略协议等级(快照)/已成交VIP等级/客户档案状态/最近跟进摘要/汇总卡片（已中标项目总额=A5读、跟进中方案预估总额=方案卡读、进行中商机总额=crm-opportunity读）/关联业务计数/快捷操作(关注/标记重点客户/跟进/添加联系人/新增商机/新增项目/新增战略协议/工商信息更新)。
  • 敏感信息：完整/脱敏/无权限三档；脱敏对电话/金额；完整值只当前页面会话生效，刷新恢复脱敏；每次完整查看记录敏感信息查询日志。
  • 加载/异常：局部区域独立加载/失败/重试；关联模块接口失败只影响该区域，客户基本信息继续展示。
  • 跟进记录：跟进方式必选(字典 follow_way 复用商机)、跟进内容必填(1-500)、下次跟进时间(非必填、不得早于当前)；本期不做跟进附件；提交后刷新最近跟进+跟进记录页签；商机行也可点跟进复用同一弹窗，自动关联当前客户+该商机(即 customer_follow.opportunity_id 可选)。
  • 操作日志（口径纠偏，对称商机票 09）：字段级审计——实体(customer/contact/follow/team)/字段/旧值/新值/操作人(系统 vs 人工)/操作时间/来源；非动作枚举模型。归属变更(领取/分配/抛公海/交割/归档)/阶段变更/工商信息更新/编辑保存/联系人增删改/团队成员变更/敏感信息查询/仍要创建重复客户/相似客户仍创建 均写日志；未保存/取消/校验失败不写。日志脱敏电话/金额；工商查询 raw / OCR 图片不写日志。默认全记 + 短黑名单排除（非白名单）。

待拍板点

  1. customer_follow 表字段：id/customer_id/opportunity_id(可选)/follow_way/content/next_follow_time/creator/create_time；无草稿态（对称商机票 09）；无附件本期。
  2. customer_oplog 表字段：id/biz_type(customer/contact/follow/team/company_info)/biz_id/entity_field/old_value/new_value/operator_user_id(null=系统)/operator_source/create_time；金额/电话脱敏存原值再回显时脱敏 or 存已脱敏值？→ 推荐存原值+回显时按查看者权限脱敏。
  3. 关联商机反查接口：本模块调 crm-opportunity 新增 list-by-customer 还是 crm-opportunity 直接暴露？→ 推荐 crm-opportunity 侧加，本模块调（对称票 09 的模块边界）。
  4. 公共头部汇总金额脱敏：无权限=***万元；无数据=0.00万元；接口失败=--+重试（原型明说）。
  5. 关注 / 标记重点客户 = 用户维度个人状态（对称商机票 14 followed）——本表建 user_customer_focus(user_id, customer_id, is_starred)。
  6. 归档/合并态详情皮肤：只读，隐藏编辑/新增入口；仍展示历史数据。合并态划出（合并不做），归档态本图做。

Answer

Status: resolved

A. 客户详情页骨架（定稿）

公共头部（8 页签共享）：客户名称 / 客户阶段(只读条) / 客户星级 / 关系星级 / 战略协议等级(快照) / 已成交VIP等级(快照) / 客户档案状态 / 销售负责人+部门 / 最近跟进摘要 / 待跟进提醒(下次跟进时间) / 关联业务计数(1商机/1项目)。

汇总卡片（4 张，均外部模块提供，接口失败显"--"+重试，不显 0）：已中标项目总额(A5) / 跟进中方案预估总额(方案卡) / 进行中商机总额(crm-opportunity) / 合同总额·累计回款(预留占位显"--")。

8 页签（默认进「客户信息」；首次打开才加载，切回保留条件/分页）：

# 页签 数据源 本图
1 客户信息 主表（票 02） ✅
2 联系人 GET /api/customer/{id}/contacts（票 06） ✅
3 跟进记录 customer_follow（B） ✅
4 关联商机 反查 crm-opportunity（C） ✅
5 关联项目 A5 项目模块 ❌ 骨架显"--"
6 战略协议 战略协议子域 ❌ 骨架显"--"
7 团队成员 负责人+协同人（D） ✅
8 操作日志 customer_oplog（E） ✅

B. 跟进记录 customer_follow（定稿）

Java 字段 列名 类型 必填 说明
id id bigint 主键
customerId customer_id bigint ✅ 客户 ID
followWay follow_way varchar(20) ✅ 跟进方式字典 follow_way：微信/拜访/电话/邮件/会议
followContent follow_content text ✅ 跟进内容
nextFollowTime next_follow_time datetime 下次跟进时间（有则进"待跟进"筛选）
followBy / followByName / followDeptName follow_by / follow_by_name / follow_dept_name — 跟进人快照（对称商机跟进范式）
createTime create_time — 跟进时间（=创建时间，不可改）

无孤立单大写字母陷阱。nextFollowTime→next_follow_time ✅。

约束：

  • 提交后不可修改/删除；纠错 = 新增补充记录（原型 7 明文）。
  • 提交中禁止重复提交（原型公共规则）。
  • 写库副作用（关键）：customer.last_valid_follow_time = now（超期提醒锚点刷新，票 10 回填）；更新"待跟进"状态。

契约：

POST /api/customer/{id}/follow          新增跟进（刷新 last_valid_follow_time）
GET  /api/customer/{id}/follow/page     跟进记录分页（时间倒序 + 日期分组；按 follow_way/关键字/时间范围过滤）

C. 关联商机页签（定稿，只读反查）

  • 数据源：反查 crm-opportunity（按 customer_id 查该客户全部商机）。
  • 列：商机名称 / 商机编号 / 阶段 / 预计金额 / 销售负责人 / 最近更新；点商机名跳 crm-opportunity 商机详情（新窗口）。
  • 只读，不在客户详情内做商机写操作（对称：商机详情反查客户也只是带出）。
  • 接口失败显"--" + 重试，不显 0 条。

D. 团队成员页签（定稿）

  • 数据：销售负责人（owner_user_id 快照）+ 协同人列表（团队成员关联表）。
  • 展示：姓名 / 部门 / 角色（负责人/协同人）；GET /api/customer/{id}/members。

E. 操作日志 customer_oplog（定稿，对称商机 oplog 范式）

Java 字段 列名 类型 说明
id id bigint 主键
customerId customer_id bigint 客户 ID
action action varchar(50) 动作类型：CREATE/UPDATE/FOLLOW/ARCHIVE/RESTORE/TRANSFER/CLAIM/POOL/STAGE_CHANGE
detail detail varchar(1000) 变更描述，形态 把 {字段} 从 {旧} 修改为 {新}（原型 8 明文）
operatorId / operatorName / operatorDeptName operator_id / operator_name / operator_dept_name — 操作人快照
createTime create_time — 操作时间
  • 只追加、不可改删；GET /api/customer/{id}/oplog/page（时间倒序 + 日期分组 + 关键字/时间范围过滤）。
  • 写 oplog 的动作（回填各票）：新增/编辑（票 02）/ 归属迁移·归档·恢复·领取·分配·抛公海（票 03）/ 阶段变化 operator=系统（票 05）/ 交割（票 08）。

F. 回填 / 下游

  • 票 02：last_valid_follow_time 已含（B 刷新）。
  • 票 03：归属迁移写 oplog（E）。
  • 票 05：阶段变化写 oplog（operator=系统）。
  • 票 10：跟进刷新锚点 → 超期提醒计时重启（B 副作用）。
  • crm-dict：新增 follow_way 分组（微信/拜访/电话/邮件/会议）。

G. ⚠ 挂号（需拍板）

  1. 汇总卡片 4 张里「合同总额/累计回款」原型即预留占位——是否本期就显"--"，还是连卡片都不渲染？推荐：渲染卡片但值显"--"（保持布局稳定）。