# M1 客户 360° 与主数据 — 逻辑设计文档（LDD · How）

| 项 | 值 |
|---|---|
| 模块 | M1 客户 360° 与主数据 |
| 类型 | 逻辑设计文档（LDD） |
| 对应需求 | [requirements/M1](../requirements/M1-客户360与主数据.md) |
| 上级 | [需求分析总纲](../需求分析总纲.md) |

> 本文档描述**实现方式（How）**：数据模型/字段 schema、同步机制、审批与签署子流程、集成字段映射；"做什么/为什么/验收"见对应需求文档。

## 1. 数据模型（本模块相关）
```
Customer 1──* Contact
Customer *──* User(TAM/CSM)                       （一客户多 TAM/CSM）
Customer 1──* Contract(type:Product|Premium_Support|PS_Service; source:nexus|virtual)
Contract(PS_Service) 1──* Quota                   （Man-days 共享池；立项=选客户+绑定其一份 remaining>0 Quota，范围由 SOW 约定）
Contract ──▶ signed_by_contact_id → Contact       （虚拟合同签署，可配置）
```

## 2. 字段 schema
**Customer（Nexus 只读同步）**：`account_id(IBG-…), account_uid(001…), jsm_org_id, name(Full Name)/alias, level, technical_support_level, region, country, time_zone`。
- `level` = 战略分层（KA/SKA/…）；`technical_support_level` = 服务等级（如 Premium）；二者独立。
- `jsm_org_id` = 关联 TiDB Support(Jira/JSM) 工单的键（M12）。

**Contract**：`id, customer_id, type(Product/Premium_Support/PS_Service), source(nexus/virtual), nexus_contract_id?, start/end, unit_price, status`。

**Quota**：`id, customer_id, contract_id(PS_Service), source, amount_type, mandays_total, used(derived), remaining(derived)`；一个 Paid 合同/Sponsored/Dedicated 授权 = 一份 Quota；项目↔Quota=M:N（限同客户，`ProjectQuota` 绑定）。

<!-- Order 实体已废除：以 Contract 为立项/预算单位、Service Package 为 Project 属性、范围由 SOW 约定。 -->

**虚拟合同签署记录**：`signed_by_contact_id`（引用 Contact）、`signed_at`、`signed_version`。

## 3. 同步机制（Nexus → CSP 单向）
- **单向只读**：来源字段只读、不回写（对应 D-C1）。
- **定时轮询拉取**：Nexus 无事件推送 → 周期读取 CRM 变化 + **变化检测**（识别新 Premium 客户 / 新 PS 单）+ **每日全量对账兜底**；每条记录留同步时间/来源版本（对应 D-C4）。
- **入库触发（并集）**：① Premium 服务（Nexus `Technical Support Level=Premium`）② 买 PS（Nexus 有 PS 合同）③ Sponsored 申请（CSP 内）④ Key Account 特批（CSP 内，无对应 Support Level）⑤ 手动指定（对应 D-C2）。
- **上游失效处理**：上游 Account 失效 → CSP 保留 + 提醒，不自动删（对应 D-C9）。

## 4. 虚拟合同审批与签署子流程
- **分层审批**：例外（Exceptional Premium / Sponsored）走审批（ARR 驱动核定，见 M9 FR-APR-05）→ **先批合同（建额度池）** → 再按 SOW 立项（选客户 + 绑定其一份 `remaining>0` 的 Quota；一份合同可含多个 Service Package，共用合同 Quota 池、不独立切预算）。
- **客户签署子流程**：经审批生成的虚拟合同支持客户签署；记录 `signed_by_contact_id`、`signed_at`、`signed_version`，走 M8 签署能力。
- **是否强制签署可配置**：默认 Exceptional Premium_Support 与付费 PS 需签，Sponsored（善意赠送）可选（对应 D-C12）。

## 5. 合同类型驱动域（路由机制）
- 有 Product → CSM(M5)；有 Premium_Support → TAM(M3/M4)；有 PS_Service → PS(M6)。
- 同一客户可并存多类合同，分别驱动对应角色域（对应 D-C10）。

## 6. 集成点 / 字段映射
- **Nexus CRM**：客户主数据、Support Plan(= Technical Support Level)、Level(KA/SKA)、Contract（`source:nexus`）。
- **JSM (Jira Service Management)**：`jsm_org_id` 关联工单（M12）。
- **Clinic**：产品用量（QPS/Connections 等）→ 360° 视图 + M4 健康度输入。
- **Ops**：技术画像（Orgs/Clusters）、Billing、新建集群 → 360° 视图 + M4 采用度/主动观测输入。
- **飞书 Wiki**：关联知识入 360°。
- （待补映射：三类合同在 Nexus 中的对应对象/字段，见需求 OQ-P7）