crm-backend-matt/docs/platform-tech-blueprint.md

# CRM 信息化平台技术方案

## 1 建设目标

面向销售组织的一体化 CRM 业务中台，围绕**线索→商机→客户→项目**销售全链路提供业务承载，围绕**用户/组织/权限/规则/日志**提供治理支撑，围绕**检索/AI**提供智能放大。

建设范围覆盖原型文档《【原型】itc 信息化业务中台 web 端 V1.0-202607》170 页所定型的六大业务模块与后台治理体系：

| 模块 | 页数 | 关键子域 |
| --- | --- | --- |
| A1 销售工作台 | 2 | 首页 · 消息中心 |
| A2 线索管理 | 13 | 线索公海（分屏/列表）· 我的线索 · 我的关注 · 线索管理 · 线索设置 |
| A3 商机管理 | 51 | 销售机会 · 商机详情（概览/客户/方案卡/现场勘察/附件/跟进/工作计划/团队/日志）· 商机公海 · 商机管理设置（阶段/方案卡模板/方案推送规则/查重规则/公海与提醒规则/字典）· 督办 |
| A4 客户管理 | 39 | 客户公海 · 客户总览 · 我的客户 · OCR 快捷新增 · 客户详情（含联系人/跟进/关联商机/关联项目/战略协议/团队/日志）· 联系人 · 客户查重合并 · 客户交割 |
| A5 项目管理 | 14 | 项目管理（看板/分屏/列表）· 项目详情七阶段状态机（冲突处理→方案设计→商务报价→招投标准备→赢单/输单→结项→关闭）· 项目统计 |
| A6 数据看板 | 3 | 运营看板 · 客户看板 · 营销看板 |
| A7 后台管理 | 30+ | 用户管理与 OA 同步 · 角色管理与权限点管理 · 业务规则四模块 · 日志三类（操作/登录/批量）· 数据字典 |

平台在此范围内提供：统一登录与免登、组织架构与部门层级、基于资源树的角色权限体系、行级数据权限、文件与预览、检索与向量化、规则引擎、审计日志、AI 网关与融入点。

## 2 总体架构

平台采用 **Spring Boot 多模块单仓库** 形态，每个业务域或横切能力为独立 Maven 模块，统一由 `crm-app` 聚合启动。所有业务模块共享 `crm-base` 通用能力与 `crm-auth` 认证权限地基。

### 2.1 分层架构

**顶层分层视图**：前端 · API 网关 · 应用 · 基础设施四层竖向叠放。应用层再拆三带——业务域 / 平台域 / 通用基座——自上而下依赖，`crm-app` 横切聚合三带统一打包启动。模块级依赖细节见 §2.2。

```mermaid
flowchart TB
    FE["<b>① 前端层</b>　React + Ant Design<br/>菜单树 / 权限码 / 字典 由后端下发驱动 UI"]
    GW["<b>② API 网关层</b>　Nginx 反向代理 · JWT Bearer 鉴权"]

    subgraph APP["<b>③ 应用层</b>　crm-app 聚合打包 · 唯一启动入口"]
        direction TB
        BIZ["业务域　客户 · 线索 · 商机 · 项目 · 数据看板"]
        PLAT["平台域　认证 · 文件 · AI · 检索 · 规则 · 审计 · 通知 · OA同步"]
        BASE["通用基座　crm-base（异常/ID/字典/数据权限/统一信封/ORM 增强）"]
        BIZ --> PLAT --> BASE
    end

    INFRA["<b>④ 基础设施层</b><br/>MySQL · Redis · MinIO · Elasticsearch · 向量库 · 钉钉 · LLM/OCR/自研算法服务"]

    FE --> GW --> APP --> INFRA

    classDef edge fill:#f5f7fa,stroke:#4a5568,stroke-width:2px,color:#1a202c
    classDef biz fill:#e6f4ff,stroke:#0958d9,color:#003a8c,stroke-width:1.5px
    classDef plat fill:#f6ffed,stroke:#389e0d,color:#135200,stroke-width:1.5px
    classDef base fill:#fff7e6,stroke:#d46b08,color:#873800,stroke-width:2px

    class FE,GW,INFRA edge
    class BIZ biz
    class PLAT plat
    class BASE base
```

前端与网关经由后端下发的菜单树/权限码/字典驱动，不含业务逻辑；应用层三带自上而下依赖（业务→平台→基座），任一带均可跨带直依赖基座；基础设施由平台域各模块封装，业务域不直接触达（详见 §2.3）。

### 2.2 应用层模块依赖

**依赖走向自上而下**：业务域 → 平台域 → `crm-base`，共三层。上层可跨层直依赖 `crm-base`。`crm-app` 不在依赖链内，仅聚合全部模块打包。为保持可读，层间依赖以**层代表节点**间的粗箭头示意，非逐模块连线（逐模块依赖矩阵见 §2.4）。

```mermaid
flowchart TB
    subgraph L1["① 业务域　5 模块"]
        direction LR
        Customer[crm-customer] --- Lead[crm-lead] --- Opp[crm-opportunity] --- Project[crm-project] --- Analytics[crm-analytics]
    end

    subgraph L2["② 平台域　8 模块"]
        direction LR
        Auth[crm-auth] --- File[crm-file] --- AI[crm-ai] --- Search[crm-search] --- Rule[crm-rule] --- Audit[crm-audit] --- Notify[crm-notify] --- OaSync[crm-oa-sync]
    end

    subgraph L3["③ 通用基座　1 模块"]
        Base[crm-base]
    end

    Customer ==> Auth
    Auth ==> Base
    Project -. 跨层直依赖 .-> Base

    App[["crm-app<br/>聚合打包 · 唯一启动入口"]]
    App -. 聚合全部 .-> L1

    linkStyle 11,12 stroke:#0958d9,stroke-width:3px
    linkStyle 13 stroke:#8c8c8c,stroke-dasharray:4 3
    linkStyle 14 stroke:#722ed1,stroke-dasharray:4 3

    classDef biz fill:#e6f4ff,stroke:#0958d9,color:#003a8c,stroke-width:1.5px
    classDef plat fill:#f6ffed,stroke:#389e0d,color:#135200,stroke-width:1.5px
    classDef base fill:#fff7e6,stroke:#d46b08,color:#873800,stroke-width:2px
    classDef app fill:#f9f0ff,stroke:#722ed1,color:#391085,stroke-width:1.5px

    class Customer,Lead,Opp,Project,Analytics biz
    class Auth,File,AI,Search,Rule,Audit,Notify,OaSync plat
    class Base base
    class App app
```

层内模块以细连线水平排列示意同级并列（无依赖含义）；粗蓝箭头为主依赖走向，灰虚线为跨层直依赖，紫虚线为 `crm-app` 聚合。各模块简称对照见 §2.4 模块职责表。

### 2.3 外部依赖

**基础设施与外部服务的接入位置**：每类基础设施由特定平台域模块封装，业务模块通过平台域门面调用（`FileApi` / `AiApi` / `SearchApi` 等），不直接接触基础设施 SDK。左列平台域模块，中列存储，右列外部服务；箭头为"谁封装谁"。`MySQL` 为全模块共用，单列示意不逐一连线。

```mermaid
flowchart LR
    subgraph PLAT["平台域模块"]
        direction TB
        Auth[crm-auth]
        File[crm-file]
        AI[crm-ai]
        Search[crm-search]
        OaSync[crm-oa-sync]
        Notify[crm-notify]
    end

    subgraph STORE["存储层"]
        direction TB
        Redis[(Redis<br/>会话/缓存)]
        MinIO[(MinIO<br/>对象存储)]
        ES[(Elasticsearch<br/>全文索引)]
        Vec[(向量库<br/>Milvus/Qdrant)]
    end

    subgraph EXT["外部服务"]
        direction TB
        DingTalk[钉钉开放平台]
        LLM[大模型 Provider<br/>通义/DeepSeek/自托管]
        OCR[OCR Provider<br/>阿里云/腾讯云]
        AlgoTeam[自研算法接口<br/>HTTP + gRPC]
    end

    MySQL[(MySQL · 全模块共用)]

    Auth --> Redis
    Auth --> DingTalk
    File --> MinIO
    Search --> ES
    Search --> Vec
    AI --> LLM
    AI --> OCR
    AI --> AlgoTeam
    OaSync --> DingTalk
    Notify --> DingTalk
    PLAT -.-> MySQL

    classDef plat fill:#f6ffed,stroke:#389e0d,color:#135200,stroke-width:1.5px
    classDef store fill:#e6fffb,stroke:#08979c,color:#00474f
    classDef ext fill:#fff1f0,stroke:#cf1322,color:#5c0011

    class Auth,File,AI,Search,OaSync,Notify plat
    class MySQL,Redis,MinIO,ES,Vec store
    class DingTalk,LLM,OCR,AlgoTeam ext
```

### 2.4 模块职责

| 模块 | 职责 | 关键能力 |
| --- | --- | --- |
| `crm-base` | 通用能力基座 | 全局异常、雪花 ID、公共字段填充、Jackson（Long→String/日期）、Redis 序列化、Knife4j、TraceId、数据字典、`@DataScope` 声明、`Result<T>` 统一信封、MyBatis-Plus 增强（分页/防全表更新/批量 upsert）、`BaseEntity/BaseDTO/BaseParam` |
| `crm-auth` | 认证与组织权限 | 钉钉扫码/免登（同一 OAuth 换取逻辑）、组织准入、JWT+Redis 滑动会话、统一用户（OA 唯一来源）、部门（主/兼职/部门集合）、RBAC 权限资源树（catalog/menu/button 扁平存储）、行级数据权限四档（fail-closed）、动态 API 拦截（apiUrl+Caffeine） |
| `crm-file` | 文件承载 | 直传、三阶段分片上传（断点续传+孤儿清理）、下载、kkFileView 预览（内网 presigned 回源） |
| `crm-ai` | AI 能力网关 | 封装 OCR、摘要、推荐、结构化抽取、评分、相似度等能力，每种能力支持多种策略（第三方 API 或自研算法），由能力路由层按配置选路 |
| `crm-search` | 检索能力 | 全文检索（ES + IK 分词）、向量检索（Milvus/Qdrant）、异步建索引（事件驱动，最终一致）、失败降级 DB |
| `crm-rule` | 业务规则引擎 | 公海规则、查重规则、方案推送规则、超期提醒规则的配置化承载与热更新 |
| `crm-audit` | 审计日志 | AOP + `@Audited` 白名单，覆盖用户操作/登录/批量操作三类 |
| `crm-notify` | 消息通知 | 应用内消息、多通道分发（钉钉/短信/邮件）、消息模板、事件消费 |
| `crm-oa-sync` | OA 同步 | 定时/手动触发拉 OA 用户与部门、幂等匹配（unionId/工号）、字段映射规则、承载在职状态流转 |
| `crm-customer` | 客户域 | 客户、联系人、战略协议、跟进记录、团队成员、客户查重合并、客户交割 |
| `crm-lead` | 线索域 | 线索、线索公海池、领取四关、超时回收、软失效 |
| `crm-opportunity` | 商机域 | 商机、方案卡、方案推送规则、现场勘察、跟进、工作计划、督办 |
| `crm-project` | 项目域 | 项目、七阶段状态机、方案设计、商务报价、招投标准备、赢单/输单/结项/关闭 |
| `crm-analytics` | 数据看板域 | 运营/客户/营销三看板、预聚合汇总表、定时物化 |
| `crm-app` | 唯一启动入口 | 聚合全部模块打可执行 jar，其他模块不 repackage |

### 2.5 核心实体关系

```mermaid
erDiagram
    AuthUser ||--o{ SysUserRole : "持有"
    SysRole ||--o{ SysUserRole : "被持有"
    SysRole ||--o{ SysRoleMenu : "授权"
    SysMenu ||--o{ SysRoleMenu : "被授权"
    SysMenu }o--|| SysMenu : "父子(parentId)"
    AuthUser }o--|| SysDept : "主部门"
    AuthUser }o--o{ SysDept : "兼职(user_dept)"
    SysDept }o--|| SysDept : "父子(parentId)"

    Customer ||--o{ Contact : "包含"
    Customer ||--o{ StrategicAgreement : "签订"
    Customer ||--o{ FollowUp : "跟进"
    Customer ||--o{ Opportunity : "关联"
    Customer ||--o{ Project : "衍生"
    Customer }o--|| AuthUser : "负责人"

    Lead }o--|| LeadSeaPool : "归属公海"
    Lead ||--o| Opportunity : "转化"
    Lead }o--|| AuthUser : "负责人"

    Opportunity ||--o{ SolutionCard : "含方案"
    Opportunity ||--o{ SiteSurvey : "现场勘察"
    Opportunity ||--o{ FollowUp : "跟进"
    Opportunity }o--|| Customer : "属于"
    Opportunity }o--|| AuthUser : "负责人"

    Project }o--|| Customer : "服务"
    Project }o--|| AuthUser : "负责人"

    SolutionCardTemplate ||--o{ SolutionCard : "生成"
    SolutionPushRule }o--|| SolutionCardTemplate : "推荐"

    FileMeta }o--|| AuthUser : "上传人"
    Customer ||--o{ FileMeta : "附件"
    Opportunity ||--o{ FileMeta : "附件"
    Project ||--o{ FileMeta : "附件"
```

### 2.6 请求处理链路

```mermaid
sequenceDiagram
    participant FE as 前端
    participant Nginx
    participant JWT as JwtAuthFilter
    participant DS as DataScope Init
    participant API as ApiPermissionInterceptor
    participant CTL as Controller
    participant SVC as Service
    participant DSI as DataScopeInterceptor (MyBatis)
    participant DB as MySQL

    FE->>Nginx: HTTP + Bearer Token
    Nginx->>JWT: 转发
    JWT->>JWT: 验签 + 查 Redis + 滑动续期
    JWT->>DS: 载入 PermissionGrant/DataVisibility
    DS->>API: 载入 ThreadLocal
    API->>API: 匹配 apiUrl pattern + 校验权限码
    API->>CTL: 通过
    CTL->>SVC: 调用
    SVC->>DSI: 发起查询
    DSI->>DSI: 注入 WHERE (owner_id / dept_id / 1=0 fail-closed)
    DSI->>DB: 执行
    DB-->>FE: Result<T>
```

## 3 模块与能力

### 3.1 认证与组织权限

- **登录方式**：钉钉扫码登录、钉钉免登（前端 OAuth 重定向 authCode，后端与扫码同一逻辑），扩展新渠道只需实现 `ThirdPartyAuthClient` SPI。跨平台身份映射键为手机号。
- **组织准入**：登录时对新用户用企业级 access token 调钉钉通讯录 API 校验组织归属，非本组织拒绝登录，已在库用户不再重复校验。
- **会话**：JWT + Redis 双重校验，剩余有效期不足一半自动续满，强制下线即删 Redis key。
- **用户主数据**：全 CRM 统一用户来源于 OA，业务表里的负责人/创建人等 id 均指向 `crm_auth_user`。CRM 侧唯一可写字段为角色分配。
- **部门**：主部门/兼职部门/部门集合三层语义，兼职为只读挂靠（可读该部门数据，但产出不入兼职部门）。
- **权限资源树**：菜单分组（catalog）/ 菜单页面（menu）/ 按钮（button）三类节点扁平存储于 `sys_menu`，通过 parentId 组树。角色→资源多对多，保存时后端沿 parentId 补全祖先，读取即已补全的完整集合。
- **动态 API 拦截**：button 节点 apiUrl（Ant-style pattern）由 Caffeine 缓存驱动 `HandlerInterceptor`，未注册接口 fail-open，注册接口未授权返回 403。资源树变更立即失效缓存。
- **行级数据权限**：四档（仅本人 / 本部门 / 本部门及以下 / 全部）由角色 `data_scope` 决定，多角色取最宽。MyBatis 拦截器在 SQL 层自动注入 WHERE；按部门档位遇空部门集合注入 `1=0`（fail-closed，不静默放行）。业务实体标 `@DataScope(ownerColumn, deptColumn)` 生效，无标注不受影响。

### 3.2 客户域

- **客户主实体**：包含基本信息（名称/税号/行业/等级/地址）、负责人、归属部门、来源、创建/更新审计字段。支持列表/分屏/卡片三视图与客户公海/客户总览/我的客户三入口。
- **联系人**：客户下多联系人，独立列表页与详情，支持导入。
- **战略协议**：客户下的长期合作框架协议（框架合同/年度合同），含金额/年限/条款/附件，独立列表与详情。
- **跟进记录**：客户与商机共享的时间线记录，支持文本与附件。
- **团队成员**：客户可指派协作成员，与主负责人权限区分。
- **OCR 快捷新增**：上传名片/营业执照/证照 → OCR 结构化抽取 → 表单预填 → 人工确认落库。见 §5.1。
- **客户查重与合并**：主动扫描全量客户按规则（税号/名称/域名/电话）判疑似重复，卡片/列表视图供人工审核合并，主/从合并策略、字段选优、子实体（联系人/跟进/协议）归并、审计留痕。
- **客户交割**：客户从一负责人转到另一负责人的主动业务流程，含发起/分配/交接记录/详情四阶段。归属部门随负责人变更（避免接收人"本部门"档看不到自己名下数据）。离职回收角色场景走同一底层能力。

### 3.3 线索域

- **线索主实体**：来源/状态/意向度 extra 字段，负责人与归属部门跟随。
- **线索公海池**：`LeadSeaPool` 管理配置实体，绑定销售团队（Dept 树非叶子）与销售部门（Dept 树叶子），支持省份/城市多选、部门负责人、跨部门协作人手选、领取规则（成员自领 / 仅管理员分配）、个人领取上限、个人持有上限、超时回收天数、软失效天数。名称全局唯一，创建后 team/dept 锁定，池下线索计数用作删除防护。
- **部门成员动态计算**：部门成员=归属该部门的用户全集，实时按 deptId 推导不落库，后续入职者自动纳入。
- **领取四关**：领取模式 → 人员范围（部门成员∪协作人）→ 单次上限 → 持有上限，任一关不通过返回失败原因。
- **超时回收与软失效**：起算点=最后跟进时间；超回收天数进公海；公海停留超失效天数转软失效。规则参数化于 `crm-rule`。
- **导入**：Excel 按公海池名称口径导入，行级校验（团队/部门归属校验、领取规则映射、数字字段正整数）。

### 3.4 商机域

- **商机主实体**：金额、阶段、客户、负责人、归属部门。商机阶段由 A3-4-1 商机阶段设置维护，可配置。
- **商机详情**：概览 / 客户信息 / 方案卡 / 现场勘察 / 相关附件 / 跟进记录 / 工作计划 / 团队成员 / 操作日志 九个 tab。
- **相关操作**：写跟进、新增方案卡、添加关联客户、推送方案、暂缓、抛公海、关闭、督办、添加团队成员、新增现场勘察。
- **方案卡**：对客户可交付的产品/服务组合快照，含定价/条款/附件，作为商机下的核心子实体，可从方案卡模板生成。
- **方案卡模板**：可复用的方案卡蓝本，由管理员维护。
- **方案推送规则**：按客户属性（行业/等级/地域）与商机属性（阶段/金额）匹配推荐方案卡的可配置规则。承载于 `crm-rule`，AI 融入点见 §5.1。
- **查重规则**：新建商机时防重的可配置规则。
- **公海与提醒规则**：商机公海回收与超期提醒规则，与线索公海共享底层规则引擎。
- **商机公海**：无负责人商机的收纳池，支持领取/关注/分配。
- **督办**：管理者对下属商机的督办功能。

### 3.5 项目域

- **项目主实体**：由成交客户或商机派生，负责人与归属部门跟随。
- **状态机（七阶段）**：冲突处理 → 方案设计 → 商务报价 → 招投标准备 → 赢单/输单 → 结项 → 关闭。冲突处理区分本地/异地场景，用于多环境或多方协作时的状态协调。
- **视图**：看板（按阶段列聚合）、分屏、列表三视图；我的项目视图；项目统计。

### 3.6 数据看板域

- **运营看板**：全局漏斗、活动度、转化率。
- **客户看板**：客户分布、活跃度、TOP 客户。
- **营销看板**：线索来源、转化、公海流转。
- **实现**：预聚合汇总表 + 定时物化视图（`crm-analytics` 任务），前端 ECharts。查询按数据权限档位收窄，管理层与一线看到的口径一致。
- **AI 融入点**：NL2 看板问答与看板异动归因，见 §5.1。

### 3.7 后台治理

- **用户管理**：只读用户列表（OA 唯一来源），支持部门子树筛选、在职状态筛选、关键词（姓名/账号/手机号）搜索、最后登录时间范围。四指标卡（部门总数/在职/离职/待分配）随部门子树变。CRM 侧唯一写操作为分配角色。
- **同步任务**：OA 用户与部门定时/手动同步，字段映射规则可配，冲突记录可复核。
- **角色管理**：`/api/roles/*` 独立端点。分步保存：基本信息与权限分配解耦。祖先补全在服务端完成。roleCode 唯一，内置角色（`builtin=true`，如 ADMIN）禁删禁改 roleCode。删除级联 `sys_role_menu` + `sys_user_role`。
- **权限点管理**：`/api/resources/*` 独立端点，维护整棵权限资源树。button 节点携带 apiUrl（Ant pattern）驱动动态拦截。
- **业务规则**：线索规则 / 商机规则 / 客户规则（超期未跟进提醒、客户查重设置）/ 项目规则 四模块，配置化。
- **日志**：用户操作日志 / 登录日志 / 批量操作日志 三类，AOP + `@Audited` 白名单显式声明写入。
- **数据字典**：全平台枚举/下拉配置中心，`crm-base` 提供 `DictService`，业务模块引用字典 code。

## 4 关键技术

### 4.1 技术栈

| 项 | 选型 |
| --- | --- |
| 运行时 | JDK 17 + Spring Boot 3.3.5 |
| ORM | MyBatis-Plus 3.5.7（运行时 CRUD）+ JPA 注解（`ddl-auto: update` 全环境建表） |
| 认证 | Spring Security + JWT |
| 缓存 | Redis（会话/字典/规则）+ Caffeine（进程内热点） |
| 文件 | MinIO（对象存储）+ kkFileView（在线预览） |
| 全文检索 | Elasticsearch 8 + IK 中文分词 |
| 向量检索 | Milvus 或 Qdrant |
| API 文档 | Knife4j |
| 调度 | Spring @Scheduled + ShedLock（分布式锁，多实例互斥）|
| 消息 | Redis Pub/Sub 或 RabbitMQ（事件驱动索引与通知） |
| AI 框架 | Spring AI 或自研薄适配层 |
| 工具库 | Hutool、Guava、EasyExcel、AntPathMatcher |

### 4.2 认证与登录

见 §3.1。JWT 载荷含 userId 与签发时间戳；Redis key 为 `jwt:{userId}:{jti}`。免登与扫码后端同一 OAuth2 userAccessToken 换取逻辑，区别仅在前端获取 authCode 的方式。

### 4.3 数据权限双管

- **读侧**：MyBatis `DataScopeInterceptor` 拦截 SELECT，按 `@DataScope` 注解与 `DataVisibilityContext`（ThreadLocal）注入 WHERE。
- **写侧**：`MetaObjectFillHandler` 取同一份身份填 `owner_id` / `dept_id`。
- **fail-closed**：按部门档遇空集合注入 `1=0`；未知档位配置直接失败不静默放行。

### 4.4 动态 API 拦截

button 节点 apiUrl（Ant pattern）通过 Caffeine 缓存驱动 `HandlerInterceptor`。写操作触发 `ResourceService.save/delete` 立即失效缓存。fail-open 策略：未注册 URL 放行，已注册 URL 校验权限码。与 `@PreAuthorize` 共存，二者均需通过。

### 4.5 文件与预览

直传 10MB 内一次请求；超过走三阶段分片（init/upload/complete），Redis 存会话状态支持断点续传，`chunks/{uploadId}/{序号}` 临时对象合并后清理，`OrphanChunkCleanupTask` 定时兜底清孤儿分片。预览走 kkFileView，后端对 MinIO 签内网 presigned GET 拼入 onlinePreview URL，浏览器仅接触 kkFileView，MinIO 不暴公网。

### 4.6 检索

业务实体保存后发领域事件，`crm-search` 异步消费：文本切片（滑动窗口）+ embedding → 同步入 ES 与向量库。索引与主库最终一致。检索接口暴露统一 `SearchApi`（关键词/向量/混合三种模式），失败降级 DB LIKE 保证可用。

### 4.7 规则引擎

轻量优先：规则参数配置化 + 策略模式实现，判定逻辑内聚为纯函数。表达式复杂场景引入 Aviator/QLExpress。规则数据存 MySQL，Redis + Caffeine 二级缓存，写操作发事件立即失效。

### 4.8 AI 能力网关

AI 层采用**能力路由 + 多后端 Provider**双级抽象设计，隔离业务代码与底层实现，确保接入商业大模型、开源自托管模型、自研算法团队接口三类后端可自由切换与组合。

#### 4.8.1 分层结构

调用自上而下贯穿五级：业务模块 → `AiApi` 门面 → `AiCapability` 能力路由 → 路由决策（yml）→ 四类 Provider SPI → 具体后端。网关治理为横切层，挂在 `AiApi` 入口，对所有能力与后端统一施加。

```mermaid
flowchart TB
    BIZ["业务模块<br/>（客户/线索/商机/项目/看板）"]
    AiApi["AiApi 门面<br/>业务唯一入口 · 不感知后端类型"]
    CAP["AiCapability 能力路由层<br/>ocr · extract · summarize · embed · rerank<br/>chat/rag · nlDsl · score · recommend<br/>similarity · classify · anomaly"]
    ROUTE["路由决策<br/>application.yml 编译时配置<br/>每能力 primary + fallback 降级链"]

    subgraph PROV["Provider SPI（四类并存）"]
        direction LR
        P1["LlmProvider<br/>大模型"]
        P2["OcrProvider<br/>专用 OCR"]
        P3["AlgoServiceProvider<br/>自研算法<br/>HTTP+gRPC"]
        P4["RuleProvider<br/>规则兜底"]
    end

    subgraph VEND["后端实现"]
        direction LR
        V1["通义/DeepSeek<br/>自托管 Qwen"]
        V2["阿里云/腾讯云<br/>PaddleOCR"]
        V3["自研评分/推荐<br/>查重/异常检测"]
        V4["Aviator<br/>策略规则"]
    end

    GW["网关治理（横切全后端）<br/>权限码 · 限流 · 审计 · 降级链 · 资源度量 · prompt/embedding 缓存"]

    BIZ --> AiApi
    AiApi --> CAP
    CAP --> ROUTE
    ROUTE --> P1 & P2 & P3 & P4
    P1 --> V1
    P2 --> V2
    P3 --> V3
    P4 --> V4
    AiApi -. 每次调用经治理 .-> GW

    classDef entry fill:#e6f4ff,stroke:#0958d9,color:#003a8c,stroke-width:1.5px
    classDef core fill:#f6ffed,stroke:#389e0d,color:#135200,stroke-width:1.5px
    classDef prov fill:#fff7e6,stroke:#d46b08,color:#873800,stroke-width:1.5px
    classDef vend fill:#f9f0ff,stroke:#722ed1,color:#391085
    classDef gw fill:#fff1f0,stroke:#cf1322,color:#5c0011,stroke-width:1.5px

    class BIZ entry
    class AiApi,CAP,ROUTE core
    class P1,P2,P3,P4 prov
    class V1,V2,V3,V4 vend
    class GW gw
```

**两级抽象职责**：

- `AiApi` 门面：业务模块唯一入口，业务代码不感知后端类型（等同 `FileApi` 模式）。
- `AiCapability` 能力路由层：以**能力**（不是模型或厂商）为粒度暴露方法，如 `capability.score(input)`、`capability.recommend(input)`、`capability.similarity(a, b)`。同一能力可绑定不同后端，业务代码不需变更。
- Provider SPI：三类底层 SPI 并存，分别承载 LLM、OCR、自研算法服务；规则引擎作为兜底 Provider 以同一 SPI 形态接入，用于 AI 不可用时降级。

#### 4.8.2 后端类型

| Provider SPI | 承载 | 传输 | 典型能力 |
| --- | --- | --- | --- |
| `LlmProvider` | 大模型 | HTTP (SDK 封装) | chat / summarize / extract / rag / nlDsl |
| `OcrProvider` | 专用 OCR 服务 | HTTP | ocr（名片/证照识别） |
| `AlgoServiceProvider` | **自研算法团队接口** | HTTP REST + gRPC 双支持 | score / recommend / similarity / classify / anomaly / 或任何算法团队交付的能力 |
| `RuleProvider` | 规则引擎兜底 | 进程内调用 | 全部能力均可作为最终降级链末端 |

自研算法接口的接入路径：算法团队按 CRM 侧发布的 `AiCapability` 契约（JSON Schema 定义输入输出）交付 HTTP 或 gRPC 服务，CRM 侧无需为每次上线新增适配代码，配置切换即可生效。

#### 4.8.3 契约与路由配置

**契约由 CRM 侧主导**：每个 `AiCapability`（评分/推荐/相似度/OCR/...）在 CRM 侧定义 JSON Schema 契约，明确输入输出字段与语义。算法团队实现方须符合契约；不符合时由 Provider 适配层拒绝并返回明确错误，不做隐式兼容。契约稳定，后端多变，业务代码不感知。

**路由决策放在 `application.yml`**：每能力显式声明主 Provider 与降级链，变更需发版。

```yaml
crm:
  ai:
    capabilities:
      customer.ocr:
        primary: ocr-aliyun
        fallback: [ocr-tencent, llm-qwen]
      customer.dedup.similarity:
        primary: algo-team-similarity
        fallback: [embed-qwen, rule-string-match]
      lead.score:
        primary: algo-team-lead-scoring
        fallback: [rule-lead-score]
      opportunity.solution-recommend:
        primary: algo-team-recommend
        fallback: [rule-solution-match]
      customer.field-extract:
        primary: llm-deepseek
        fallback: [llm-qwen]
      analytics.nl-to-dsl:
        primary: llm-qwen
    providers:
      algo-team-similarity:
        type: algo-service
        transport: grpc
        endpoint: algo-service.internal:50051
        service: SimilarityService
        method: Compare
        timeout: 500ms
      algo-team-lead-scoring:
        type: algo-service
        transport: http
        endpoint: http://algo-service.internal/api/lead-score
        timeout: 800ms
      llm-qwen:
        type: llm
        vendor: dashscope
        model: qwen-plus
      ocr-aliyun:
        type: ocr
        vendor: aliyun
```

#### 4.8.4 网关治理（统一对待所有后端）

自研算法接口与商业厂商在治理侧同等对待，不做特权豁免：

- **权限码校验**：AI 功能视为权限点，`crm:ai:{capability}` 权限码控制哪些用户/角色可调用。
- **限流**：能力级 QPS + 并发上限，防止内部服务雪崩传导。
- **审计留痕**：每次调用记录 traceId、userId、capability、provider、input hash、output、耗时、结果状态。AI 建议是否被人工采纳一并留痕，为后续模型评估提供数据。
- **降级链**：`primary` 失败/超时按 `fallback` 顺序自动尝试，最终回落规则引擎兜底，业务不感知。
- **资源使用度量**：按能力+Provider 统计调用次数、Token 数、平均耗时。商业 API 换算为成本，自研接口作为资源使用度量（哪些能力吃自家 GPU 多），指导资源规划与算法团队优化方向。
- **prompt/embedding 缓存**：相同输入命中缓存复用，同时降低外部厂商开销与自研服务压力。

#### 4.8.5 数据权限与 AI 安全

- **数据权限约束贯穿**：AI 输入候选集与提示词上下文恒经 `DataScopeInterceptor` 过滤，无论后端是商业 LLM 还是自研算法服务，均不构成数据权限旁路。
- **结构化输出强制**：抽取/评分类任务由 CRM 侧定义 JSON Schema，Schema 违反自动重试；不合规输出丢弃不落库。
- **非确定性动作人工确认**：AI 产出为**建议**，不自动执行不可逆动作（分配/回收/合并/改归属）。人工确认或规则闸门放行后方可落地。

### 4.9 调度

Spring `@Scheduled` + ShedLock（基于 Redis 或 DB 的分布式锁），保证多实例部署下同一任务全局只跑一次。承载定时任务：公海超时回收、线索软失效、客户超期未跟进提醒、孤儿分片清理、索引重建、OA 同步、看板物化视图刷新。

### 4.10 审计

Spring AOP 拦截 Controller 方法，`@Audited(bizDomain, action)` 白名单显式声明写审计。字段：userId、traceId、apiUrl、action、bizDomain、targetId、before、after、result、ipAddr、ua、耗时。同步写 audit 表，写失败仅告警不阻断主流程。

#### 4.8.6 AI 融入设计点

具体功能点清单见 §5.1。

## 5 系统易用性与自动化设计

汇总系统在易用性与自动化两方面的设计点。分两类：AI 类需模型或算法支撑；自动化类由规则、定时任务、事件驱动、批处理等常规工程手段承载。共通原则：**规则能解决的不喂模型**；**均受数据权限约束**；**不可逆动作不自动执行,由人工或规则闸门放行**。功能点为设计承载能力，是否实现按业务需要与排期取舍。

### 5.1 AI 融入设计点

表中"底层能力"仅列主要技术形态，实际每能力经 §4.8 的能力路由配置绑定到具体后端（商业 API / 自托管 / 自研算法 / 规则引擎），业务代码不感知。

| 业务模块 | AI 融入功能点 | 说明 | 底层能力 | 典型后端选择 |
| --- | --- | --- | --- | --- |
| **客户** | OCR 快捷新增 | 上传名片/营业执照/证照 → OCR 结构化抽取企业名/联系人/电话/地址/税号 → 表单预填 → 人工确认落库 | OCR + LLM 校验 | 商业 OCR API（阿里云/腾讯云）或自研 OCR 模型 |
| 客户 | 客户查重相似度 | 企业名/地址容错查重，规则（税号/域名精确）+ 相似度模型（"深圳市 XX 有限公司" vs "深圳 XX 公司"）+ 阈值可配 | 相似度算法 + 规则引擎 | 自研查重模型 / Embedding + 规则 / 商业 embedding |
| 客户 | 客户档案会话问答 | 对单客户档案自然语言提问（历史成交/风险点/关键联系人），后端检索客户维度全文本并生成 | RAG（ES + 向量 + 生成模型）+ 数据权限过滤 | 商业 LLM + 商业/自研 embedding |
| 客户 | 战略协议关键信息抽取 | 上传战略协议 PDF → 抽取金额/年限/条款要点写入元数据 | 文档解析 + 结构化抽取 | 商业 LLM 或自研合同解析模型 |
| **线索** | 线索评分与自动分配 | 按来源/地域/行为特征打分，高分线索优先分配给合适销售 | 评分模型 + 规则引擎 | **自研评分模型**主导 / 规则兜底 / LLM 补非结构化特征 |
| 线索 | 智能公海回收提醒 | 超天数硬规则叠加语义判断"跟进是否实质推进"，回收前预警 | 规则引擎 + 语义判断 | 规则主 / LLM 或自研文本分类模型补 |
| **商机** | 方案卡智能推荐 | 商机推方案时按客户+商机属性推荐 top-N 方案卡；规则命中多张时相似度重排（客户画像 vs 方案卡描述） | 推荐模型 + 相似度 + 规则 | **自研推荐服务**主导 / 商业 embedding 兜底 |
| 商机 | 商机赢率预测 | 按阶段/金额/跟进密度预测成交率，辅助漏斗复盘 | 预测模型 + 定性归因 | **自研 ML 模型**主导 / LLM 做归因说明 |
| 商机 | 跟进建议 | 基于商机上下文与阶段生成下一步动作建议 | RAG + 生成模型 | 商业 LLM |
| 商机 | 跟进记录摘要 | 长跟进记录一键摘要，档案概览自动生成 | 生成模型 | 商业 LLM 或自托管 |
| **项目** | 阶段材料智能校验 | 各阶段附件（方案/报价/招投标）合规性 AI 校验（要素齐全性/格式规范/敏感信息） | 结构化抽取 + 规则 | 商业 LLM 或自研合规校验模型 |
| **数据看板** | NL2 看板问答 | 自然语言问看板："本周华东转化率"→ 后端翻译为受控查询 DSL → 聚合查询 → 图表返回 | 自然语言转 DSL（字段白名单，禁止裸 SQL） | 商业 LLM |
| 数据看板 | 看板异动归因 | 指标下滑时自动定位维度："本周华东转化下滑" → 主因是某销售组线索转化异常 | 预聚合切片 + 异动识别 + 生成归因 | 规则+统计（识别）+ 商业 LLM（文案） |
| **平台交互** | 全局 NL 检索 | "上海本月未跟进的高等级客户" → 结构化查询条件（字段白名单，必过数据权限） | 自然语言转 DSL + 数据权限拦截器 | 商业 LLM |
| **审计与安全** | 异常行为检测 | 从审计日志识别异常访问（非工作时段大量导出、跨部门越权尝试），生成告警说明 | 规则 + 序列异常算法 + 告警文案 | **自研异常检测模型** / 规则兜底 / LLM 生成文案 |
| **消息中心** | 消息智能摘要与优先级 | 站内消息批量摘要与紧急度评估，避免通知刷屏 | 摘要 + 分类模型 | 商业 LLM 或自研分类模型 |

### 5.2 自动化处理设计点

不依赖模型，由规则、定时任务、事件驱动、批处理承载。

| 业务模块 | 自动化点 | 说明 | 承载机制 |
| --- | --- | --- | --- |
| **客户** | 客户交割自动化 | 离职/转岗触发客户批量交接下家，跟进记录/联系人/协议随人走，权限同步刷新 | 事件驱动 + 事务批处理 |
| 客户 | 超期未跟进提醒 | 按客户等级配置超期天数，达阈值自动生成提醒消息并推送责任人 | 定时任务 + 消息中心 |
| 客户 | 客户去重合并 | 后台批量识别疑似重复客户对，管理员一键合并，业务数据（联系人/跟进/协议）自动归并 | 规则引擎 + 批处理 |
| **线索** | 线索公海超时回收 | 领取四关（拨号/加微/首访/意向）未达成自动退回公海，可配置提前预警 | 定时任务 + 规则引擎 |
| 线索 | 线索软失效 | 长期无动作线索标记失效，从主视图隐藏但保留档案 | 定时任务 |
| 线索 | 领取节流 | 单用户单日/单月领取上限自动拦截 | 规则引擎 + Redis 计数 |
| **商机** | 阶段推进督办 | 商机停留阶段超期自动督办到人，链上升级到直属上级 | 定时任务 + 消息中心 |
| 商机 | 方案推送落库 | 命中推送规则自动生成方案卡关联记录，附推荐理由 | 规则引擎 + 事件驱动 |
| **项目** | 阶段状态机流转 | 七阶段流转按闸门条件自动放行/拦截，材料齐全性检查通过后进入下一阶段 | 状态机 + 规则引擎 |
| 项目 | 结项/关闭归档 | 触发终态自动冻结写入、归档附件、生成结项报告骨架 | 事件驱动 + 模板引擎 |
| **文件** | 分片上传断点续传 | 上传中断后续传免重传，会话过期自动清理孤儿分片 | Redis 会话 + 定时任务 |
| 文件 | kkFileView 预览 | 常见格式（PDF/Office/图片）在线预览免下载 | 内网 presigned 回源 |
| **数据看板** | 物化视图刷新 | 高频看板聚合结果按分钟/小时预聚合，查询走结果表 | 定时任务 + ShedLock 互斥 |
| **OA 同步** | 用户与部门自动同步 | 定时拉 OA 数据幂等匹配（unionId/工号），字段映射规则化，在职状态自动流转 | 定时任务 + 幂等匹配 |
| **审计** | 三类日志自动留痕 | Controller AOP + `@Audited` 白名单自动记录用户操作/登录/批量操作，前后镜像对比 | AOP + 白名单 |
| **消息** | 多通道分发 | 站内消息按用户偏好自动分发到钉钉/短信/邮件，模板化 | 事件驱动 + 模板引擎 |
| **检索** | 索引异步重建 | 业务实体保存发领域事件，ES 与向量库异步建索引，失败降级 DB LIKE | 事件驱动 + 消息队列 |
| **权限** | 权限热更新 | 角色/资源变更立即刷新 Caffeine 缓存，全实例失效 | 事件驱动 + 缓存失效 |
| **调度** | 分布式定时任务互斥 | 多实例部署同一任务全局只跑一次 | ShedLock + Redis/DB 锁 |

## 6 安全与治理

| 主题 | 措施 |
| --- | --- |
| 身份认证 | 钉钉 OAuth2 换取 userAccessToken；JWT + Redis 双重校验，滑动续期；强制下线即删 Redis key |
| 组织准入 | 新用户登录时企业级 access token 调组织通讯录 API 校验企业归属，非组织成员拒登 |
| 会话安全 | JWT secret 至少 32 位随机串，生产环境变量注入；HTTPS 强制；Bearer Token 请求头 |
| 权限体系 | 三层权限：登录校验 → 动态 API 拦截（apiUrl+权限码）→ `@PreAuthorize` 方法级细粒度；三者共存均需通过 |
| 行级数据权限 | 四档 SQL 层自动注入，fail-closed（空部门集合注入 `1=0`），未知档位失败不放行 |
| AI 越权防护 | AI 输入候选集与提示词上下文恒经 `DataScopeInterceptor` 过滤；AI 不构成数据权限旁路 |
| AI 输出治理 | 抽取/OCR/建议一律人工确认落库；AI 不自动写主数据、不执行不可逆动作；结构化输出强制 JSON Schema |
| 模型可控 | LLM/OCR/自研算法服务同为可插拔 Provider，能力路由层按 yml 显式绑定后端；敏感场景走自研或自托管同一 SPI，数据不出内网 |
| 文件安全 | MinIO 不暴公网，浏览器仅接触 kkFileView；扩展名黑名单、直传上限、单文件总大小上限守门 |
| 审计追溯 | 三类日志（操作/登录/批量）AOP 显式写入；所有 AI 调用经网关审计（能力名+后端+输入+输出+人工采纳记录），无论后端为商业厂商还是自研算法服务同等对待 |
| 请求追踪 | TraceIdFilter 为每个请求注入 traceId，透传请求头，日志 pattern 全模块统一含 `%X{traceId}` |
| 定时任务 | ShedLock 分布式锁保证多实例部署互斥，避免漏跑/重跑 |
| 数据一致性 | 索引异步最终一致，失败降级 DB LIKE，不阻塞写主链路；合并/交割等跨表操作事务保护 |
| 依赖管理 | 父 pom 统一版本，子模块不硬编码；内部模块经 dependencyManagement 集中管理 |
| 环境隔离 | 生产凭证（JWT secret / MinIO AK-SK / 钉钉 client-secret / LLM API key）一律环境变量注入 |