group_xinghuo_jinrong/docs/项目框架设计/表设计/00-架构总览.md

# 四 Agent 数据库底座 · 架构总览（可读版）

> 写给：项目经理、产品、刚接手的开发  
> 目的：说明 **四个 Agent 并行开发时，数据存哪儿、谁写谁读、为什么要分 L0~L3 画像**  
> 技术细节（建表 SQL、Redis Key）见同目录其他文件。

---

## ⭐ 要先搭底座？看这一份

**按「多 Agent 一起用」划分的完整清单（含 16 表 × 4 Agent 矩阵）：**  
👉 **[05-多Agent共用底座清单.md](./05-多Agent共用底座清单.md)**

| 你要建的 | 包含什么 | SQL |
| --- | --- | --- |
| **共用底座（先建）** | MySQL **11 张** + Redis 会话/画像 + Milvus 产品库 + Neo4j | [01-mysql-共用底座.sql](./01-mysql-共用底座.sql) |
| **各 Agent 专用（后建）** | MySQL **5 张** | [02-mysql-agent专用.sql](./02-mysql-agent专用.sql) |
| **技术栈与版本** | 组件版本、Windows 原生部署 | [01-技术栈与版本.md](../../技术选型和版本/01-技术栈与版本.md) |
| **业务记忆管理** | 短期/长期记忆、Redis vs SQL vs 图 vs 向量 | [业务记忆管理手册.md](../../业务记忆管理/业务记忆管理手册.md) |

---

## 先读这一页：这份文档在讲什么？

我们要做 4 个智能助手（Agent），服务 4 类人：

| Agent | 给谁用 | 干什么（一句话） |
| --- | --- | --- |
| **客户财富** | 买理财的客户 | 查持仓、看产品规则、亏多了提醒一下 |
| **代理人助手** | 一线理财经理 | 查客户情况、查产品规则、帮忙起草合规话术 |
| **数据分析** | 公司内部同事 | 用大白话问数据，系统查库后用普通话回答 |
| **风控监测** | 风控专员 | 大额/异常交易预警，买不匹配的产品要拦住 |

**四个 Agent 不互相「打电话」问 AI**，而是 **往同一套数据库里读写**。  
这样四个组可以 **同时开发**，只要事先约定好 **哪张表谁写、谁只能读**。

---

## 五种「仓库」分别是干什么的？

可以把它想成 **五种不同用途的仓库**：

| 仓库 | 技术名 | 通俗理解 | 里面主要放什么 | 丢了会怎样 |
| --- | --- | --- | --- | --- |
| **短期记事本** | Redis | 对话时临时用的草稿纸 | 最近几轮聊天、刚查过的客户画像副本 | 丢了可以从 MySQL 恢复，只是慢一点 |
| **正式档案柜** | MySQL | 必须长期保存、能审计的记录 | 聊天记录归档、客户画像、预警单、合规审计 | **不能丢**，监管和纠纷都要查 |
| **产品说明书索引** | Milvus | 按意思搜文档（向量检索） | 基金产品手册、交易规则、内部办事流程 | 更新了重新导入即可 |
| **关系图谱** | Neo4j | 「谁持有啥、谁管谁」的关系图 | 客户↔产品↔持仓、客户↔代理人、产品风险等级 | 从原有业务系统同步重建 |
| **原有业务系统** | Core（只读） | 公司本来就有的一套账 | 真实持仓、流水、正式 KYC、C1~C5、C×R 矩阵 | Agent **不复制一份**，只读 |

**记忆分层（和 Agent 文档里的说法对应）**

- **Redis** = 短期记忆（聊完这一阵可能就不用了）
- **MySQL** = 权威记忆（落库、可审计、跨 Agent 共享）
- **Milvus** = 知识库记忆（产品/制度文档，语义搜索）
- **Neo4j** = 关系记忆（客户-产品-代理人之间的网）

---

## 用户画像：L0 / L1 / L2 / L3 是什么意思？

### 一句话

**同一位客户，档案分四层；每层由不同的人/系统填写，给别人用，但谁也不能替官方改「正式风险等级」。**

### 用「客户档案袋」来理解

想象一个客户档案袋，里面有 4 个插槽：

```text
┌─────────────────────────────────────────────────────────────┐
│  L0 · 官方底稿（原有业务系统，Agent 只读，不能改）              │
│  姓名、年龄、职业、正式风险等级 C1~C5、真实资产规模              │
├─────────────────────────────────────────────────────────────┤
│  L1 · 客户自己聊出来的（客户财富 Agent 写入）                  │
│  投资风格、资金规划比例、亏损多少要提醒、平时关注什么            │
├─────────────────────────────────────────────────────────────┤
│  L2 · 代理人服务记录的（代理人助手 Agent 写入）                │
│  沟通诉求、待跟进事项、资产概况摘要、「最近在问赎回」等服务标签    │
├─────────────────────────────────────────────────────────────┤
│  L3 · 风控监测结论（风控监测 Agent 写入）                      │
│  正常 / 关注 / 高风险、监测评分、名单命中待复核等（不改 L0 等级） │
└─────────────────────────────────────────────────────────────┘
```

### 为什么要分 L1 / L2 / L3，不合成一张表？

| 层级 | 谁产生这些信息 | 为什么要单独一层 |
| --- | --- | --- |
| **L0** | 开户、测评、交易系统 | **法律效力最强**：正式能不能买高风险产品，以它为准 |
| **L1** | 客户和「客户 Agent」聊天、做问卷 | 客户 **自己表达** 的偏好和规划；代理人、风控可以 **参考**，但不能当成官方测评 |
| **L2** | 代理人和「代理人 Agent」服务客户 | **服务过程** 里才知道的诉求；客户本人 **看不到** 这层（隐私和服务记录） |
| **L3** | 风控系统监测 | **风险视角** 的标签；只用于监测和统计， **不会自动改** L0 的正式等级 |

**如果合成一张表会怎样？**

- 客户说「我比较激进」和正式测评 C1 保守 **混在一起**，容易误当成可以买高风险产品 → 合规风险  
- 代理人写的「客户想赎回」和客户自己填的「投资规划」 **权限不同**，客户不应看到服务侧备注  
- 风控的「重点关注」 **不能反写** 进官方测评记录  

所以：**三层 enrich（L1/L2/L3）+ 一层官方底稿（L0）**，各写各的、各读各的（在权限范围内）。

### 谁读谁写（不用记表名，记关系就行）

| 层级 | 谁写入 | 谁读取 |
| --- | --- | --- |
| L0 | 原有系统（Agent 不写） | 四个 Agent 都只读 |
| L1 | 客户财富 Agent | 客户本人、代理人、风控、数据分析 |
| L2 | 代理人助手 Agent | 代理人、风控、数据分析（客户不看） |
| L3 | 风控监测 Agent | 风控、代理人（只看）、数据分析 |

对应 MySQL 表名（给开发对照）：`customer_profile_l1` / `l2` / `l3`  
**详细 JSON 约定与 L0 边界：** [06-用户画像L1-L3设计.md](./06-用户画像L1-L3设计.md)

---

## 系统长什么样？（一张图）

```text
        客户 Agent    代理人 Agent    数据分析 Agent    风控 Agent
              │              │              │              │
              └──────────────┴──────┬───────┴──────────────┘
                                    │
                         平台公共能力（登录、权限、审计）
                                    │
         ┌──────────┬───────────────┼───────────────┬──────────┐
         ▼          ▼               ▼               ▼          ▼
      Redis      MySQL          Milvus          Neo4j    原有业务系统
     临时聊天    正式档案      搜产品文档      关系图谱    真实持仓/测评
```

---

## MySQL 16 张表：每张表 **干什么**（无编号版）

> **共用 vs 专用** 的完整矩阵见 [05-多Agent共用底座清单.md](./05-多Agent共用底座清单.md) 第九节。

### 一、四个 Agent 共用的「基础设施」（6 张）🔴 底座第一批

| 表名 | 干什么 | 举例 |
| --- | --- | --- |
| `agent_session` | 记录一次对话会话 | 「张三月 5 日下午 3 点开了客户 Agent」 |
| `agent_message` | 保存每条聊天内容 | 客户问了什么、Agent 答了什么 |
| `agent_tool_call` | 记录 Agent 调用了哪些查数接口 | 查持仓、查产品规则 |
| `audit_log` | **合规审计总账**（只增不改不删） | 出问题时追溯「谁、何时、依据什么」 |
| `input_guard_log` | 拦截恶意输入、注入攻击 | 有人试图让 Agent 越权查别人数据 |
| `customer_advisor_rel` | 这个客户归哪个代理人管 | 代理人 A 只能看自己名下客户 |

### 二、跨 Agent 交换：用户画像（3 张）🟡 底座第二批

| 表名 | 对应层级 | 干什么 |
| --- | --- | --- |
| `customer_profile_l1` | L1 | 风格标签、资金规划、亏损提醒阈值、行为偏好 |
| `customer_profile_l2` | L2 | 资产概况快照、沟通诉求、待办、服务标签 |
| `customer_profile_l3` | L3 | 监测分层（正常/关注/高风险）、监测评分 |

### 三、跨 Agent 交换：风控产出（2 张，也在底座第二批）🟡

| 表名 | 谁写 | 谁读 | 干什么 |
| --- | --- | --- | --- |
| `risk_alert` | 风控 Agent | 分析 Agent、风控专员 | 预警单（待人工审核） |
| `risk_suitability_log` | 风控 Agent | 客户、代理人 Agent | 买的产品是否匹配、可否拦截 |

### 四、各 Agent 专用（5 张）⚪ 各组自建，不算公共底座

| 表名 | 哪个 Agent | 干什么 |
| --- | --- | --- |
| `customer_threshold_config` | 客户 | 亏损阈值配置 |
| `customer_notify_log` | 客户 | 提醒留痕 |
| `advisor_draft` | 代理人 | 话术/跟进草稿 |
| `compliance_hit_log` | 代理人 | 违规话术检测 |
| `analytics_query_log` | 分析 | 查数 SQL 留痕 |

> 完整 DDL 见 [01-mysql-共用底座.sql](./01-mysql-共用底座.sql) + [02-mysql-agent专用.sql](./02-mysql-agent专用.sql)  
> 适当性 log 字段契约：[07-risk_suitability_log说明.md](./07-risk_suitability_log说明.md)

---

## 四个 Agent 各自管哪块数据？

| Agent | 主要负责 **写入** | 主要 **读取** 别人的什么 |
| --- | --- | --- |
| **客户财富** | L1 画像、亏损阈值、提醒记录 | 原有系统持仓；风控的适当性结论（只读） |
| **代理人助手** | L2 画像、话术草稿、违规记录 | L1 画像（了解客户偏好）；产品文档（Milvus） |
| **数据分析** | 查数日志 | L1/L2/L3 做统计；预警单做「还有多少条没处理」 |
| **风控监测** | L3 画像、预警单、适当性记录 | L1/L2 辅助判断；原有系统交易流水 |
| **平台** | 会话、审计、权限关系 | — |

---

## 三条最常见的业务流程

### 1. 客户和 Agent 聊天

```text
客户说话
  → Redis 记住最近几轮（聊完可过期）
  → MySQL 永久保存聊天记录 + 审计
  → 若问产品规则 → 去 Milvus 搜官方文档，回答必须能溯源
  → 若问持仓 → 去原有系统查真实数据（金额以原系统为准）
  → 若客户说了偏好/设了阈值 → 更新 L1 画像
```

### 2. 代理人服务客户前「做功课」

```text
代理人输入客户 ID
  → 读 L1（客户自己侧的偏好）
  → 读 L2（之前服务记录，没有就新建）
  → 读原有系统持仓 + Neo4j 看持有哪些产品
  → 生成话术草稿 → 存 advisor_draft → 代理人改完、审核后才能发给客户
```

### 3. 风控发现大额交易

```text
原有系统传来一笔交易
  → 风控 Agent 判断是否触发规则（如单笔 ≥50 万）
  → MySQL 生成预警单，状态 =「待人工审核」
  → Redis 推一条消息给风控工作台（实时弹窗）
  → 数据分析 Agent 可以统计「还有多少条没审」，但不能替风控审
  → 风控专员在系统里人工处理，改预警状态
```

---

## 搭建底座 vs 开发 Agent（两回事）

| | 搭建共用底座 | 四个 Agent 并行开发 |
| --- | --- | --- |
| **目标** | 把多 Agent 要一起用的表/缓存/向量库建好 | 各组写自己的 Agent 逻辑 |
| **谁做** | 平台组统一做 | 客户/代理人/分析/风控 四组 |
| **建什么** | MySQL 11 张 + Redis + Milvus(产品) + Neo4j | 各自专用 5 张表 + 业务代码 |
| **详细清单** | [05-多Agent共用底座清单.md](./05-多Agent共用底座清单.md) | 同上第五节「专用」 |

---

## 必须遵守的 6 条规矩（合规）

1. **审计日志只能追加，不能删改。**  
2. **正式风险等级 C1~C5 只有原有测评系统能改**；L1/L2/L3 都不能覆盖它。  
3. **全系统只有「买的产品和风险等级不匹配」这一种情况可以拦截购买**；其他 Agent 不能冻户、不能拦交易。  
4. **代理人 Agent 生成的话术，不能直接发给客户**，必须人工审核。  
5. **数据分析只能查数（SELECT），不能改业务数据。**  
6. **Redis 里的可以丢；MySQL 里的是准的。**

---

## 附录：需求编号对照（给开发追溯用）

阅读正文 **不需要** 记这些编号；联调需求文档时用。

| 编号 | 业务含义 |
| --- | --- |
| F-01 | 登录权限、代理人只能看名下客户 |
| F-02 | 所有对话和操作可审计 |
| F-03 | 输入安全、防注入 |
| F-04 | Agent 只读业务账，不改账 |
| C-01~C-05 | 客户 P0：持仓、产品、规则、阈值提醒、行情 |
| C-07/C-08 | 客户 P1：风格测评、资金规划 |
| A-01~A-07 | 代理人：客户概况、规则答疑、话术草稿、合规检测等 |
| D-01~D-04 | 数据分析：人话查数、SQL 留痕 |
| R-01~R-03 | 风控 P0：大额预警、适当性拦截、反洗钱名单 |

---

## 其他文件去哪看？

| 文件 | 什么时候看 |
| --- | --- |
| **[05-多Agent共用底座清单.md](./05-多Agent共用底座清单.md)** | **先搭底座：哪些表多 Agent 共用** |
| [01-mysql-共用底座.sql](./01-mysql-共用底座.sql) | 执行建库：共用 11 张 |
| [02-mysql-agent专用.sql](./02-mysql-agent专用.sql) | 各 Agent 专用 5 张 |
| [06-用户画像L1-L3设计.md](./06-用户画像L1-L3设计.md) | L0/L1/L2/L3 边界、JSON schema、适当性分工 |
| [07-risk_suitability_log说明.md](./07-risk_suitability_log说明.md) | R-02 落库字段契约 |
| [02-redis-keys.md](./02-redis-keys.md) | 做会话缓存、画像缓存 |
| [03-milvus-collections.md](./03-milvus-collections.md) | 做产品/制度文档检索 |
| [04-neo4j-model.md](./04-neo4j-model.md) | 做持仓关系、适当性关系查询 |
| `docs/需求拆解/` | 完整业务场景与合规细则 |