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