6.3 KiB
客户业务（crm-customer）
客户的全生命周期业务域：客户实体与三阶段（潜在 / 重潜 / 已成交）、三个 workspace（客户总览 / 我的客户 / 客户公海）、新增 / 编辑 / 导入、联系人子实体、跟进记录与操作日志（customer_oplog 无限期保留，审计日志不设清理/冷热分离，§5.5）、客户交割（离职/调岗批量换主），以及客户规则族「超期未跟进提醒」。依赖方向单向 crm-opportunity → crm-customer（商机读客户、建关联）；crm-customer → crm-rule → (crm-auth / crm-dict / crm-file)；客户读「关联商机」走下游反查上游（同库单体阶段可接受，见 ADR-0029 循环依赖技术债）。访问控制走三机制模型，@DataScope(module="customer", ownerColumn="owner_user_id", deptColumn="owner_dept_id")。
Language
客户:
crm-customer 的核心聚合根。归属由 owner_user_id（销售负责人）+ owner_dept_id（销售部门快照）表达，owner 空 = 在客户公海；档案正交维度 archive_status（有效 / 已归档）独立于归属（D19 去掉「已被合并」，合并 Out-of-scope）。阶段字段 customer_stage（潜在 / 重潜 / 已成交）只前进不回退，由外部成功结果驱动。
Avoid: 线索（转化前）、商机（下游）、联系人（子实体）
销售负责人:
客户的 owner_user_id，当前唯一持有该客户的销售。客户「我的客户」视图的第一层过滤依据（负责人 = 当前用户）；抛公海 / 交割 / 分配时变更。协同人可见客户但不视为负责人。
Avoid: 领取人（线索术语）、创建人、持有者
销售部门:
客户的 owner_dept_id，负责人所在部门的快照，随负责人变更而更新（非全生命周期不变，区别于线索的 dept_id）。是数据范围过滤的部门维度。
Avoid: 归属部门、池归属部门、owner_dept
协同人: 客户团队中非负责人的成员。协同人可见该客户（进「我的客户」），但不得归档 / 合并。抛公海时清空协同人；交割时不自动恢复原协同人（保留原有其他协同人）。 Avoid: 团队成员（泛指）、共享人
客户阶段:
customer_stage 单字段（潜在 1 / 重潜 2 / 已成交 3），只前进不回退、不可手动改，由外部成功结果驱动：潜在 →（任一方案卡提交并报备成功）→ 重潜 →（任一项目首次中标赢单）→ 已成交。本期两个跃迁均 seam 化不自动触发（D20 改票 B）：报备成功链路本期不可达（不用「已提交」凑合，避免造出错误的重潜状态），A5 项目模块未建；CustomerStagePort.promote 契约/只前进 CAS/幂等 全部建好，等对应链路就绪再由其调用。本期客户阶段实际只有「潜在」。
Avoid: 客户状态、归属状态、客户类型
档案状态:
archive_status 单字段（有效 1 / 已归档 2），正交于归属与阶段（D19 去掉「已被合并」态，合并 Out-of-scope，A4-6 不做）。已归档 = 删除语义（软删）：默认排除于列表筛选、加 archive_status 筛选可查，可恢复（恢复回有效）。仅销售负责人可归档。§5.3 拍板 A（一期只做归档）：不提供任何前端「删除客户」入口——系统级 deleted 软删标志仅在合并时由系统置 1，不开放手动删除、无前端删除按钮；DB 不做物理删除。归档与合并是仅有的两种"移除"用户动作，且归档可恢复、合并本体 Out-of-scope。
Avoid: 删除、禁用、作废
客户公海:
owner_user_id 为空 且 archive_status=有效 的客户的逻辑视图（无独立池实体，对称商机公海）。进入公海 = 清 owner + 协同人；领取 = 当前用户成为 owner。有进行中商机 / 项目的客户不得抛公海（项目侧留 seam）。
Avoid: 公海池实体（那是线索规则域概念）、池
客户总览:
管理视角 workspace，@DataScope 覆盖组织范围的未删除、未进入公海客户（含有效 / 已归档两态；默认只列 archive_status=有效，已归档走筛选）。管理职务本身不扩大「我的客户」数据范围。
Avoid: 全部客户、全局列表
我的客户:
销售视角 workspace，当前用户为销售负责人或协同人 且 archive_status=有效 且非公海的客户。已归档客户 = archive_status=已归档 的客户（负责人为当前用户），列表加筛选展示、不做独立子页/独立 tab（D19：删除了「已被合并」态、「已归档」用筛选条件承载）。
Avoid: 私海（那是线索术语）
联系人:
customer_contact 子实体，每条必属一个客户（customer_id NOT NULL），无孤立联系人。无独立 ACL，权限继承所属客户。电话查重=可配置软提示（跟随 crm-rule 客户查重设置「联系电话」开关，不建电话唯一索引，D26）、同客户内电话不重复为表单级校验；职务先存文本名 + 可选标准职务 id/类别/层级占位（二级联动图谱留后续）。
Avoid: 线索联系人、决策人（那是客户字段）
人脉关系单位: 客户下的关系单位名标签集（如「XX 集团」），是纯文本标签，非关联到 CRM 客户实体。 Avoid: 关联客户、子客户（父客户关联是另一字段）
客户交割: 销售因员工离职 / 岗位调动 / 区域调整，把本人名下客户批量交给直属销售总监，再由总监分配给具体销售。两段式：发起交接（owner → 总监，整批原子）+ 客户分配（owner → 销售）。同步变更关联商机 / 项目负责人（项目侧留 seam）。只允许离职/调动/调整的销售本人发起。 Avoid: 分配（那是公海/日常分配动作）、转交
超期未跟进提醒:
客户规则族唯一规则（crm-rule 全局单例配置）。客户 last_valid_follow_time（新建 = create_time，每次跟进刷新）距今超过首次触发天数（默认 30）触发首次提醒，之后每隔二次提醒间隔（默认 7）重复提醒。只落待发通知 customer_pending_notice，不直接发送（平台通知能力 spin-out）。公海 / 已归档客户不参与（「已被合并」态已随 D19 取消）。
Avoid: 超时回收（那是线索/商机公海回收）、逾期