8.9 KiB

Raw Blame History

06 — 联系人建模 CRUD + 全局搜索 + 商机侧硬依赖接口

Type: research Status: resolved Blocked by: 02

问题

定 customer_contact 实体表、CRUD 接口、全局搜索（商机侧硬依赖）、联系人电话查重、职务字段占位（图谱划出但字段留占位）。归属客户不孤立、权限继承客户团队。

一手证据（蓝湖缓存 txt）

a4-3-3-1_新增客户信息.txt — 新增客户内嵌联系人明细表（序号/*联系人/*职务/联系电话/是否内线/礼品备注/来源/操作），OCR/批量导入按钮划出
a4-5-1_联系人列表_列表视图_.txt / a4-5-1_联系人列表_分屏视图_.txt — 顶级联系人菜单
a4-5-2_新增联系人.txt / a4-5-3_编辑联系人.txt — 独立联系人 CRUD
a4-5-4_联系人详情_联系人信息_.txt / a4-5-5_联系人详情_联系人信息_.txt — 联系人详情
a4-5-5_联系人详情_操作日志_.txt / a4-5-6_联系人详情_操作日志_.txt — 联系人操作日志
a4-3-4_添加联系人.txt — 客户下快速添加联系人
a4-4-2_客户详情_联系人_.txt — 客户详情联系人页签
.scratch/opp-customer-dependency/商机模块前置客户接口依赖分析报告.md — 商机硬依赖清单

已知字段线索

联系人（必填）— 姓名。
职务（必填）— 见 a4-3-3-1.txt 底部「职务 - 搜索二级联动下拉框」需求：图谱划出但存储字段留占位：job_title_name(文本必填) + job_title_id(标准职务id可空) + job_title_category(类别可空) + job_title_level(层级 int 可空)。自定义职务时后三列空。
联系电话 — 手机号格式；全库按电话查重：新增/编辑时电话完全相同禁止创建；同表格内不同行电话相同禁止提交。
是否内线 — 布尔。
是否关键联系人 — 布尔（原型有）。
礼品备注 — 文本。
来源 — 字典 contact_source：组会/组局/转介绍/其他。
归属客户 — customer_id NOT NULL（无孤立联系人）。
系统字段 — 创建人/时间、修改人/时间。

商机侧硬依赖（对齐 opp-customer-dependency P0/P1）

优先级	接口	商机侧用途
P0	`POST /api/customer/search`	商机新增关联客户下拉数据源
P0	`GET /api/customer/{id}/contacts`	商机字段17按客户筛选联系人
P0	`GET /api/customer/{id}`	商机编辑回显客户带出
P1	`GET /api/customer/contact/search`	商机字段13全局搜联系人+带出所属公司
P1	`POST /api/customer/quick-create`	商机弹窗「+快速创建客户」入口

本票产出：以上契约签名 + 请求/响应 DTO（复用已有的分析报告，把它 promote 成正式契约稿）。

待拍板点

联系人权限模型：明说「继承客户团队权限」——本票落成契约：无独立 @DataScope 注解，服务层显式按 customer 校验（对客户有读权限即对全部联系人有读权限）。
联系人删除：软删还是硬删？→ 推荐软删（联系人可能被商机/项目引用做快照）；主表加 deleted 位。
联系人电话唯一 vs 允许一号多人：原型「联系电话完全相同禁止新建」听起来是全库唯一——但同一联系人可能有座机 vs 手机？→ 拍板：仅手机号做唯一约束，座机不查重；或直接单一 phone 列全库唯一，用户共号自己处理。先按后者简化。
快速创建客户 POST /api/customer/quick-create：字段集是新增客户表单的必填最小子集？还是就用完整表单？→ 推荐最小集（客户名称/客户类型/所属地区/行业/星级/关系星级）+ 服务端默认（销售负责人=当前用户/is_child=否）。
联系人的操作日志：单独一张 customer_contact_oplog 还是并入客户 oplog（票 07）用 biz_type=CONTACT？→ 推荐后者，参商机 oplog 口径。
人脉关系单位 与联系人是独立集合，仅是标签（非联系人子表）——归客户主表 JSON/子表（票 02 决定）。

Answer

Status: resolved

A. 实体 `customer_contact`（crm-customer，独立表）

Java 字段	列名	类型	必填	说明
id	id	bigint		主键 ASSIGN_ID
customerId	customer_id	bigint	✅	所属客户；NOT NULL，无孤立联系人
name	name	varchar(50)	✅	联系人姓名
jobTitleName	job_title_name	varchar(100)	✅	职务名称（文本，始终存）
jobTitleId	job_title_id	bigint		标准职务 id（字典/预置表），自定义职务时为 NULL
jobTitleCategory	job_title_category	varchar(50)		职务类别（高层管理/采购/…），自定义职务时为 NULL
jobTitleLevel	job_title_level	int		职务层级（图谱用），自定义职务时为 NULL
phone	phone	varchar(20)		联系电话；手机号格式校验
isKeyContact	is_key_contact	tinyint		是否关键联系人（是1/否0）
isInternal	is_internal	tinyint		是否内线（是1/否0）
giftRemark	gift_remark	varchar(500)		礼品备注
source	source	varchar(20)		来源字典 `contact_source`：组会/组局/转介绍/其他
createBy / createTime / updateBy / updateTime	—	—		BaseEntity
deleted	deleted	tinyint default 0		逻辑删除

⚠ 孤立单大写字母检查（AGENTS.md）：isKeyContact→is_key_contact、isInternal→is_internal、jobTitleName/jobTitleId/jobTitleCategory/jobTitleLevel——均为「完整词 + 完整词」，无需 @Column(name=...)。

索引：

idx_contact_customer (customer_id, deleted)
uk_contact_phone (phone) — 仅手机号唯一；NULL 不参与（无电话时允许，票 04 B4 内联查重兜底）
idx_contact_name (name) — 全局搜索

权限模型（定稿，原型明文「联系人不设独立 ACL，继承客户权限」）：

无独立 @DataScope 注解；服务层显式按 customer 校验（对客户有读权限 → 对其全部联系人有读权限）。
无客户读写权限时隐藏联系人新增/编辑/删除入口；服务端仍校验。

B. 契约（对齐商机硬依赖，promote 自 opp-customer-dependency 分析报告）

优先级	接口	说明
P0	`POST /api/customer/search`	客户搜索（名称/联系人/电话/类型四维模糊 + 分页），商机新增关联客户数据源
P0	`GET /api/customer/{id}/contacts`	按客户查联系人列表
P0	`GET /api/customer/{id}`	客户基础信息带出
P1	`GET /api/customer/contact/search`	联系人全局搜索（带出所属公司名），商机「商机关键联系人」数据源
P1	`POST /api/customer/quick-create`	快速创建客户（最小必填集），商机弹窗入口
P2	`GET /api/customer/{id}/detail`	客户详情（新窗口跳转），复用票 07 详情页

C. 联系人 CRUD 契约（定稿）

POST   /api/customer/contact               新增联系人（可指定 customer_id 或独立新增后关联）
PUT    /api/customer/contact/{id}          编辑
DELETE /api/customer/contact/{id}          删除（软删）
GET    /api/customer/contact/{id}          详情
GET    /api/customer/contact/page          顶级联系人列表（A4-5-1，跨客户，按 DataScope）
POST   /api/customer/contact/import        批量导入（划出本图 → 随图谱 effort，本图只留接口占位）

D. 随客户新增的内嵌明细（定稿）

新增客户表单「联系人」Tab = 明细表数组，客户保存成功后与客户建立关联（原型 3.5 §1）。
电话内联查重：同表电话相同两行禁止提交；全库电话精确查重（票 04 B4）。
删除仅移除本次未保存行；已输入内容行删除前确认。

E. 待产品确认（⚠）

#	问题	影响
P0-1	联系人电话唯一约束：手机号全局唯一 vs 允许一号多人（共号场景）？原型「完全相同禁止新建」倾向唯一——但座机分机号可能重复。推荐：仅手机号(11位)唯一，座机/短号不做唯一，`phone` 单列存但唯一索引带条件（`phone IS NOT NULL AND LENGTH(phone)=11` 或用生成列）。	`uk_contact_phone` 实现
P1-1	「来源」字典 `contact_source` 完整值（组会/组局/转介绍/其他，原型明列 4 项，是否还要更多）	crm-dict 种子

F. 回填 / 下游

票 02：无主表字段变化（联系人是子表）。
票 04：联系人内联查重（B4）已回填。
票 07：客户详情「联系人」页签复用 GET /api/customer/{id}/contacts。
票 01：CONTEXT.md 术语「联系人」「关键联系人」。
crm-dict：新增 contact_source 分组 + job_title 标准职务预置（图谱 effort 用它，本图只留 jobTitleId 引用位）。

8.9 KiB Raw Blame History