# M1 客户 360° 与主数据 — FSD（功能设计说明书）

| 项 | 值 |
|---|---|
| 模块 | M1 客户 360° 与主数据 |
| 文档类型 | FSD（功能设计说明书） |
| 对应 PRD | [requirements/M1](../requirements/M1-客户360与主数据.md) |
| 对应 LDD | [ldd/M1](../ldd/M1-客户360与主数据-设计.md) · [数据字典](../ldd/数据字典.md) |
| 配套 | [业务流程图-M1.txt](业务流程图-M1.txt) · [测试用例-M1.md](测试用例-M1.md) |
| 上级 | [需求分析总纲](../需求分析总纲.md) · [FSD 模板](FSD-模板.md) |

> 逐功能规格；数据模型/同步机制/签署子流程见 ldd/M1，字段定义见数据字典，**引用不复制**。类型为逻辑类型，物理类型留待 SDD。

## 1. 概述与范围
客户主数据与 360° 聚合视图，一切业务锚点。承载主数据、联系人、三类合同、Quota、Cluster 与 360° 视图。

**PRD 覆盖追溯（FR → 功能）**

| FR | 功能 |
|---|---|
| FR-CUST-02 | §4.1 客户入库 |
| FR-CUST-01/03/04 | §4.2 Nexus 同步与对账 |
| FR-CUST-07/08a/08b/08c | §4.3 虚拟合同审批与客户签署 |
| FR-CUST-05/06/12 | §4.4 绑定与联系人/干系人 |
| FR-CUST-08 | §4.5 Quota 视图 |
| FR-CUST-09/10/11/13 | §4.6 客户 360° 视图与时间线 |
| FR-CUST-14 | §4.7 Cluster 管理 |

**不在本模块**：健康度算法（M4）、签署引擎实现（M8）、审批链（M9）、工时/额度消耗（M7）。

## 2. 角色与权限点（角色 × 操作，接 M2）

| 操作 \ 角色 | 全员 | 绑定 TAM/CSM | PS | Leader(Region) | Admin | Customer_External |
|---|---|---|---|---|---|---|
| 查看客户 360° | ✓只读 | ✓ | ✓参与项目 | ✓本 Region | ✓ | ✗（仅自己项目） |
| 手动入库/绑定 TAM·CSM | — | ✓(相关) | — | ✓ | ✓ | — |
| 编辑 Contact/干系人 | — | ✓ | — | — | ✓ | — |
| 发起虚拟合同审批 | — | ✓ | ✓ | — | ✓ | — |
| 客户签署（外部） | — | — | — | — | — | ✓(自己合同) |
| 维护 Cluster 本地字段 | — | ✓ | ✓ | — | ✓ | — |
| Nexus 来源字段 | 全只读 | 只读 | 只读 | 只读 | 只读 | — |

> 数据范围由 M2 ABAC 计算；来源字段全局只读（不回写 Nexus，D-C1）。

## 3. 状态流转与业务流程图
> 图见 [业务流程图-M1.txt](业务流程图-M1.txt)。含：① 客户(Account) 活跃→失效（保留不删）；② 虚拟合同 草稿→待审批→[待签署]→已生效（未生效期间立项阻断）；③ 入库 / 同步对账 / 虚拟合同审批签署 三条泳道。

## 4. 功能规格

### 4.1 客户入库

**4.1.1 功能说明**　把客户首次纳入 CSP：五触发路径并集（D-C2）或手动指定，任一命中即建档，并按合同类型驱动角色域（D-C10）。

**4.1.2 业务流程**　见 [业务流程图-M1.txt](业务流程图-M1.txt) §三。要点：触发→查重→建档/合并→点亮角色域→写时间线。

**4.1.3 界面设计**
- **手动入库弹窗**：Nexus 账户搜索（按名/account_id）→ 选中带出只读主数据 → 选归属 TAM/CSM → 确认。
- 入库后跳客户 360° 详情页；重复入库给"该客户已在库，是否补充触发来源？"确认。

**4.1.4 字段定义**

| 字段 | 逻辑类型 | 必填 | 校验规则 | 数据来源 | 可编辑性 | 备注 |
|---|---|---|---|---|---|---|
| account_id | 文本 | 是 | 非空 + Nexus 存在 | Nexus | 只读 | 主键；禁用别名键 |
| name/alias | 文本 | 是 | 非空 | Nexus | 只读 | 头部标题 |
| level | 枚举 | 是 | KA/SKA/… | Nexus | 只读 | 战略分层；≠ 服务等级 |
| technical_support_level | 枚举 | 是 | 如 Premium | Nexus | 只读 | 服务等级 |
| region | 枚举 | 是 | 非空 | Nexus | 只读 | 驱动 ABAC |
| 触发来源 | 枚举[多] | 是 | 五路径∪手动 | 系统/输入 | 追加 | 可多来源 |
| 归属 TAM/CSM | 引用[多] | 否 | 用户须存在 | CSP 本地 | 可编辑 | 多人、留历史（D-C3） |

**4.1.5 业务规则**
- 五触发为**并集**，任一即入库（D-C2）；TAM/CSM 绑定是本地分配、**非入库触发**（D-C3）。
- 合同类型**驱动**角色域（D-C10）；同客户可并存多类合同。
- 上游字段只读不回写（D-C1）。

**4.1.6 异常处理**

| 异常场景 | 提示文案 | 处理 |
|---|---|---|
| 重复入库 | "该客户已在库，是否补充触发来源？" | 合并去重、追加来源 |
| Nexus 查无此账户 | "未在 Nexus 找到该账户，请确认 account_id" | 阻断，重查 |
| 手动入库权限不足 | "仅 TAM/CSM/Leader/Admin 可手动入库" | 拒绝 + 记审计 |

**4.1.7 权限控制**　TAM/CSM/Leader/Admin 可手动入库与绑定；其余只读；外部账号不可见入库入口。

### 4.2 Nexus 同步与对账

**4.2.1 功能说明**　Nexus 无事件推送 → **定时轮询 + 变化检测 + 每日全量对账**，单向只读同步主数据/合同（D-C4）。

**4.2.2 业务流程**　见 [业务流程图-M1.txt](业务流程图-M1.txt) §四。要点：轮询→变化检测→更新只读字段+记版本→每日对账→差异清单待人工核。

**4.2.3 界面设计**　同步状态区（最近同步时间/来源版本）；**对账差异清单**（差异字段、CSP 值 vs Nexus 值、处理动作）；失效客户列表。

**4.2.4 字段定义**

| 字段 | 逻辑类型 | 必填 | 校验规则 | 数据来源 | 可编辑性 | 备注 |
|---|---|---|---|---|---|---|
| last_sync_at | 日期时间 | 系统 | — | 系统 | 只读 | 展示"最近同步" |
| source_version | 文本 | 系统 | — | Nexus | 只读 | 溯源 |
| account_status | 枚举 | 系统 | 活跃/失效 | 派生 | 只读 | 失效→banner |
| 对账差异项 | 结构 | 系统 | — | 对账 | 只读 | 字段/CSP值/Nexus值 |

**4.2.5 业务规则**　轮询周期可配（D-C4，待业务）；每日全量对账兜底；失效**保留+提醒不硬删**（D-C9，FR-CUST-04）。

**4.2.6 异常处理**

| 异常场景 | 提示文案 | 处理 |
|---|---|---|
| 同步接口失败 | "Nexus 同步失败，已重试并告警" | 重试 + 告警可重放（NFR-06），保留上次快照 |
| 对账漂移 | "发现 N 条与 Nexus 不一致" | 生成差异清单，人工核，不自动覆盖 |
| 账户失效 | "该客户在 Nexus 已失效（保留）" | 保留 + banner + 提醒 TAM |

**4.2.7 权限控制**　同步为系统任务；对账差异处理限 Admin/归属 TAM；全员只读同步状态。

### 4.3 虚拟合同审批与客户签署

**4.3.1 功能说明**　无 Nexus 来源的合同（Exceptional Premium / Sponsored）经审批生成虚拟合同，按配置强制或可选客户签署（D-C11/D-C12）。

**4.3.2 业务流程**　见 [业务流程图-M1.txt](业务流程图-M1.txt) §五。要点：发起→ARR 核定审批(M9)→先建合同(池)→按 SOW 立项(绑 remaining>0 Quota)→[强制签署]→生效。

**4.3.3 界面设计**　申请表单（合同类型/ARR/Man-days/事由）；审批进度条；签署页（版本预览 + 签署人/时间 + 确认）；外部账号受限签署视图。

**4.3.4 字段定义**

| 字段 | 逻辑类型 | 必填 | 校验规则 | 数据来源 | 可编辑性 | 备注 |
|---|---|---|---|---|---|---|
| type | 枚举 | 是 | Product/Premium_Support/PS_Service | 输入 | 建档时选 | — |
| source | 枚举 | 系统 | =virtual | 派生 | 只读 | 区别 nexus |
| arr_input | 数值 | 是 | > 0 | 输入 | 审批前可改 | 驱动核定（M9） |
| man_days | 数值 | PS_Service 必填 | ≤ 核定上限 | 输入/核定 | 审批前可改 | 建 Quota 池 |
| force_sign | 布尔 | 是 | — | 配置 | Admin 可配 | 默认：例外 Premium/付费 PS=是，Sponsored=否 |
| signed_by / signed_at / signed_version | 引用/日期/文本 | 强制签署时必填 | Contact 存在 | 签署 | 签署流程写 | 三要素留痕 |

**4.3.5 业务规则**　先批合同建池、再按 SOW 立项（选客户 + 绑定其一份 `remaining>0` 的 Quota；一份合同可含多个 Service Package、共用合同 Quota 池、不独立切预算）（D-C11）；强制签署可配（D-C12）；核定值 > ARR 档位上限 → 更高层特批（M9）。

**4.3.6 异常处理**

| 异常场景 | 提示文案 | 处理 |
|---|---|---|
| 未审批即用于立项 | "合同待审批，暂不可立项" | 阻断（M6 准入） |
| 核定超上限 | "申请 {x} 超 ARR 档位上限 {y}，需上级特批" | 触发更高层节点 |
| 强制签署未签 | "合同未签署，未生效" | 不生效、依赖立项阻断 |
| 外部账号签他人合同 | "无权签署该合同" | 拒绝 + 审计 |

**4.3.7 权限控制**　TAM/PS/Admin 发起；审批人按 M9 链；签署仅指定客户 Contact/外部账号；其余只读。

### 4.4 绑定与联系人/干系人

**4.4.1 功能说明**　TAM/CSM 多绑定（留历史，D-C3）；Contact 由 CSP 维护（含角色）；干系人关系图谱（影响力/态度/关系，FR-CUST-12）供 TAM/CSM 经营。

**4.4.2 业务流程**　绑定/解绑 TAM·CSM（留历史）；新增/编辑 Contact 与角色；在图谱上标注影响力/态度/汇报关系。

**4.4.3 界面设计**　详情页「团队」区（TAM/CSM 头像组 + 绑定历史）；「联系人」列表（角色标签）；「干系人图谱」Tab（组织关系图，节点=Contact，边=汇报/影响）。

**4.4.4 字段定义**

| 字段 | 逻辑类型 | 必填 | 校验规则 | 数据来源 | 可编辑性 | 备注 |
|---|---|---|---|---|---|---|
| 归属 TAM/CSM | 引用[多] | 否 | 用户存在 | CSP 本地 | 可编辑 | 留历史用于归因 |
| contact.name | 文本 | 是 | 非空 | CSP | 可编辑 | — |
| contact.role | 枚举 | 否 | Sponsor/Technical Owner/Procurement/… | CSP | 可编辑 | 干系人角色 |
| contact.influence | 枚举 | 否 | 高/中/低 | CSP | 可编辑 | 图谱权重 |
| contact.sentiment | 枚举 | 否 | 正/中/负 | CSP | 可编辑 | 态度 |
| contact.reports_to | 引用 | 否 | 同客户 Contact | CSP | 可编辑 | 组织关系边 |

**4.4.5 业务规则**　一客户多 TAM/CSM（D-C3），解绑留历史；Contact 完全 CSP 维护（D-C6）。

**4.4.6 异常处理**

| 异常场景 | 提示文案 | 处理 |
|---|---|---|
| 绑定不存在的用户 | "该用户不存在" | 阻断 |
| 汇报关系成环 | "组织关系不可成环" | 阻断 |

**4.4.7 权限控制**　TAM/CSM/Admin 可绑定与维护联系人/图谱；其余只读；外部账号不可见图谱。

### 4.5 Quota 视图

**4.5.1 功能说明**　展示该 **PS_Service 合同的 Quota**（FR-CUST-08；一合同一份、可被同客户多项目共用）：总量/已用/剩余；消耗只读、仅来自绑定项目 TimeEntry 汇总。

**4.5.2 业务流程**　打开客户/合同的 Quota Tab → 展示池汇总与消耗明细（下钻到项目/TimeEntry，M6/M7）。

**4.5.3 界面设计**　Quota 卡片（总量/已用/剩余进度条，remaining≤阈值标红）；消耗明细列表（按项目/时间）。

**4.5.4 字段定义**

| 字段 | 逻辑类型 | 必填 | 校验规则 | 数据来源 | 可编辑性 | 备注 |
|---|---|---|---|---|---|---|
| total | 数值 | 是 | ≥0 | 合同/核定 | 只读（随合同） | Man-days |
| used | 数值 | 系统 | =Σ交付 TimeEntry | 派生 | **不可手改** | 单向汇总 |
| remaining | 数值 | 系统 | =total−used | 派生 | 只读 | ≤阈值标红 |

**4.5.5 业务规则**　一个 Paid 合同/Sponsored/Dedicated 授权 = 一份 Quota；项目↔Quota=M:N、限同客户（D-C8）；`used` 仅来自绑定项目 TimeEntry、单向汇总不可手改；超用软预警（详见 M7）。

**4.5.6 异常处理**

| 异常场景 | 提示文案 | 处理 |
|---|---|---|
| 手改 used | "额度消耗由工时汇总，不可手改" | 拒绝 |
| 无 PS_Service 合同看 Quota | "该客户暂无 PS 额度池" | 空态 |

**4.5.7 权限控制**　PS/TAM/Admin 可见；消耗只读；无人可手改 used。

### 4.6 客户 360° 视图与时间线

**4.6.1 功能说明**　一屏聚合客户全景（FR-CUST-09）+ 统一事件时间线（FR-CUST-10）+ 健康度入口（FR-CUST-11）+ 用量/采用（FR-CUST-13）。

**4.6.2 业务流程**　进入详情页 → 各区域并行加载（部分来自 M4/M11/M12 异步）→ 时间线按事件分类法收口关键事件。

**4.6.3 界面设计**　头部（主数据+健康度徽标）；区域①技术画像 ②合同&Quota ③Projects ④参与人+工时 ⑤健康度 ⑥满意度 ⑦支持聚合 ⑧干系人图谱；右栏常驻**事件时间线**。时间线条目可跳源对象。

**4.6.4 字段定义**（时间线事件）

| 字段 | 逻辑类型 | 必填 | 校验规则 | 数据来源 | 可编辑性 | 备注 |
|---|---|---|---|---|---|---|
| event_type | 枚举 | 是 | Onboarding/Kickoff/签署/状态跳转/超支/投诉/续约/TAM变更/生命周期… | 各模块 | 系统写 | 排除普通评论噪声 |
| occurred_at | 日期时间 | 是 | — | 各模块 | 只读 | 排序 |
| source_ref | 引用 | 否 | — | 各模块 | 只读 | 跳源对象 |

**4.6.5 业务规则**　聚合项齐全度目标 8/8（固定 8 项见 §4.6.3 区域清单：技术画像/合同&Quota/项目/参与人&工时/健康度/满意度/支持聚合/干系人图谱）；**事件时间线为常驻栏、飞书 Wiki 为关联入口，单独验收、不计入 8 项**。时间线只收关键事件、排除普通评论（FR-CUST-10）。

**4.6.6 异常处理**

| 异常场景 | 提示文案 | 处理 |
|---|---|---|
| 某聚合源不可用 | "该区域暂不可用" | 降级占位，整页可用 |
| 无事件 | "暂无重要事件" | 友好空态 |

**4.6.7 权限控制**　按 §2 与 M2 ABAC；外部账号不可进 360°。

### 4.7 Cluster 管理

**4.7.1 功能说明**　客户集群建为一等对象（FR-CUST-14），关联问题(M4)/告警(M12)/维护窗口/容量，来源 Ops/Clinic。

**4.7.2 业务流程**　从 Ops/Clinic 同步集群 → 展示集群列表/详情 → TAM 维护本地字段（用途/关键风险）→ 关联问题/告警。

**4.7.3 界面设计**　详情页「集群」Tab（列表：region/tier/环境/用途/风险）；集群详情（关联问题/告警/维护窗口/容量）。

**4.7.4 字段定义**

| 字段 | 逻辑类型 | 必填 | 校验规则 | 数据来源 | 可编辑性 | 备注 |
|---|---|---|---|---|---|---|
| cluster_id/name | 文本 | 是 | 非空 | Ops/Clinic | 只读 | 主键 |
| region/tier | 枚举 | 否 | — | Ops | 只读 | — |
| 环境/用途 | 文本 | 否 | — | CSP 本地 | 可编辑 | TAM 维护 |
| 关键风险 | 文本 | 否 | — | CSP 本地 | 可编辑 | — |

**4.7.5 业务规则**　集群来源只读（Ops/Clinic），本地补充字段可编辑；用于健康度/主动观测输入（M4）。

**4.7.6 异常处理**

| 异常场景 | 提示文案 | 处理 |
|---|---|---|
| Ops 同步失败 | "集群信息暂不可用" | 降级占位 |
| 无集群 | "暂无集群" | 空态 |

**4.7.7 权限控制**　TAM/PS/Admin 维护本地字段；来源字段只读；其余按 ABAC。

## 5. 接口与集成

| 接口 | 方向 | 触发/频率 | 字段映射 | 失败处理 |
|---|---|---|---|---|
| Nexus CRM（INT-01） | 上游读 | 定时轮询 + 每日对账 | Account/Contact/Contract；**合同字段映射待 OQ-P7** | 重试 + 告警可重放 |
| Ops（INT-03） | 读 | 周期 | Orgs/Clusters | 降级占位 |
| Clinic/遥测（INT-11） | 读 | 周期 | QPS/Connections/用量 | 降级占位 |
| TiDB Support/JSM（INT-02） | 关联键 | — | JSM Org ID（来自 Nexus） | 缺 Org ID → 工单区空态 |
| 飞书（INT-05） | 写 | 事件 | 签署通知/提醒 | 通知失败重试 |

## 6. 测试用例
> 见 [测试用例-M1.md](测试用例-M1.md)。覆盖入库/同步对账/虚拟合同签署/Quota/360°/Cluster 的正常/边界/异常；关键路径 100%、异常路径 ≥90%、硬约束（回写=0、生效率=0、used 不可改）100% 覆盖。

## 7. 风险与依赖

| 风险/依赖 | 影响 | 缓解 | 责任方 |
|---|---|---|---|
| Nexus 合同字段映射未定（OQ-P7） | 合同同步无法落地 | 详设阶段对接 Nexus 团队 | 后端/PM |
| Nexus 无事件推送 | 同步有延迟 | 轮询 + 每日对账兜底 | 后端 |
| 签署第三方选型未定（M8） | 强制签署落地待定 | 默认平台内轻量签署先行 | PM |

## 8. 遗留 / 待详设（TBD）
- **OQ-P7**：三类合同 Nexus 字段映射。（OQ-C2 已关闭：`Customer.level` = CRM Level，取值 KA/SKA/…；≠ `Cluster.tier` 集群等级。）
- 各页面线框/视觉稿（UX）；干系人图谱交互（缩放/分层）；Cluster 字段级 schema 深化。
- 轮询周期、Quota 预警阈值等数值待业务确认。