# 表设计文档（可读版）

> 路径：`docs/项目管理/03-表设计文档.md`
> 定位：**给人看的表设计字典**，不是 SQL 脚本。SQL 在 `docs/项目框架设计/表设计/`。
> 适用：新手团队当字典查「这张表干什么、谁写谁读、关键字段什么意思、和谁关联」。
> 关联：[00-架构总览.md](../项目框架设计/表设计/00-架构总览.md) · [05-多Agent共用底座清单.md](../项目框架设计/表设计/05-多Agent共用底座清单.md) · [06-用户画像L1-L3设计.md](../项目框架设计/表设计/06-用户画像L1-L3设计.md) · [07-risk_suitability_log说明.md](../项目框架设计/表设计/07-risk_suitability_log说明.md)

---

## 0. 怎么读这份文档

按 **存储分层** 组织，每张表/每个 Key/每个节点都给：

- **中文名 + 用途**（一句话）
- **关键字段**（中文释义，不列全字段，全字段看 SQL）
- **谁写谁读**（对照 05 清单的 4 Agent 矩阵）
- **关键查询场景**（什么业务会查它）
- **与其他表关联**（外键 / 同步 / 引用）

> 速查图例：🔴 全员共用底座 · 🟡 跨 Agent 交换 · ⚪ 单 Agent 专用 · 🔵 Core 只读

---

## 1. 存储分层总览

| 存储 | 库/文件 | 放什么 | 表/集合/节点数 |
| --- | --- | --- | --- |
| MySQL · agent 库 | `jinrong_agent` | 会话、审计、画像、预警、专用 | 11 共用 + 5 专用 |
| MySQL · core 库 | `jinrong_core` | L0 正式档案、持仓、流水、产品 | 11 表 |
| Redis | :6379 | 短期会话、画像热缓存、Pub/Sub、限流 | 6 类 Key |
| Neo4j | Desktop bolt:7687 | 客户-产品-代理人-风险等级关系图 | 5 节点 + 5 关系 |
| Milvus Lite | ./data/milvus.db | 产品/制度文档向量（1024 维 bge-m3） | 2 Collection |

---

## 2. MySQL · jinrong_agent 库

### 2.1 🔴 第一批 · 全员共用底座（6 张）

#### 2.1.1 `agent_session` · Agent 会话主表

| 项 | 内容 |
| --- | --- |
| 用途 | 记录一次对话会话（谁、哪个 Agent、何时开、关联哪个客户） |
| 谁写 | 四个 Agent 都写（创建会话） |
| 谁读 | 四个 Agent 都读（续聊）、合规巡检 |
| 关键字段 | `session_id`(对外UUID) · `trace_id`(全链路追踪) · `agent_type`(customer/advisor/analyst/risk) · `actor_id`(操作者) · `actor_role` · `customer_id` · `advisor_id` · `status`(active/closed/blocked) |
| 关键查询 | 按 `actor_id` 列历史会话；按 `trace_id` 还原链路 |
| 关联 | → `agent_message` · `agent_tool_call` · `audit_log`（同 trace_id） |

#### 2.1.2 `agent_message` · 消息明细

| 项 | 内容 |
| --- | --- |
| 用途 | 保存每条聊天内容（user/assistant/system/tool） |
| 谁写 | 四个 Agent 都写 |
| 谁读 | 四个 Agent 读（续聊上下文）、合规审计 |
| 关键字段 | `session_id` · `seq_no`(会话内序号) · `role` · `content` · `content_hash` · `has_disclaimer`(对外是否带免责) |
| 关键查询 | 按 `session_id + seq_no` 拉历史；按 `trace_id` 还原 |
| 关联 | ← `agent_session`；→ `agent_tool_call`(message_id) |

#### 2.1.3 `agent_tool_call` · Tool 调用审计

| 项 | 内容 |
| --- | --- |
| 用途 | 记录 Agent 调了哪些查数/检索接口（查持仓、查产品、NL2SQL 等） |
| 谁写 | 四个 Agent 都写 |
| 谁读 | 合规巡检、调试 |
| 关键字段 | `tool_name` · `tool_input`(JSON) · `tool_output`(JSON) · `status`(success/error/blocked/timeout) · `latency_ms` |
| 关键查询 | 按 `tool_name` 统计调用；按 `trace_id` 还原调用链 |
| 关联 | ← `agent_session` · `agent_message` |

#### 2.1.4 `audit_log` · 审计总账（只 INSERT）

| 项 | 内容 |
| --- | --- |
| 用途 | 合规审计总账，**只增不改不删**，出问题追溯「谁、何时、依据什么」 |
| 谁写 | 四个 Agent + 平台都写 |
| 谁读 | 合规专员（audit:read:all） |
| 关键字段 | `trace_id` · `event_type` · `agent_type` · `actor_id` · `customer_id` · `rule_id` · `decision` · `risk_score` · `handler_id`(人工处理者) · `handler_result` |
| 关键查询 | 按 `trace_id` 还原事件；按 `actor_id` 查行为；按 `event_type=auth_denied` 查越权 |
| 关联 | 与 `agent_session`/`agent_tool_call`/`risk_suitability_log` 同 trace_id |
| ⚠️ 红线 | **禁止 UPDATE/DELETE**，代码层加只 INSERT 断言 |

#### 2.1.5 `input_guard_log` · 输入安全防护

| 项 | 内容 |
| --- | --- |
| 用途 | 拦截恶意输入、Prompt 注入、超长非法参数（F-03） |
| 谁写 | 平台 + 四个 Agent |
| 谁读 | 安全/合规 |
| 关键字段 | `guard_type`(prompt_injection/oversize/illegal_param/rate_limit) · `raw_excerpt`(截样) · `action`(blocked/sanitized/passed) |
| 关键查询 | 按 `guard_type` 统计攻击；按 `actor_id` 查高频恶意 |
| 关联 | ← `agent_session`(session_id) |
| ⚠️ 红线 | 只 INSERT |

#### 2.1.6 `customer_advisor_rel` · 客户-代理人归属

| 项 | 内容 |
| --- | --- |
| 用途 | 这个客户归哪个代理人管（F-01 数据归属校验的权威源） |
| 谁写 | 平台同步脚本（sync_advisor_rel.py，从 Core 同步） |
| 谁读 | 四个 Agent 都读（做归属校验） |
| 关键字段 | `customer_id` · `advisor_id` · `rel_status`(active/transferred/closed) · `effective_from` · `effective_to` |
| 关键查询 | 代理人查自己名下客户列表；校验某客户是否归某代理人 |
| 关联 | ← `jinrong_core.core_customer_advisor`（同步源） |

---

### 2.2 🟡 第二批 · 跨 Agent 交换（5 张）

#### 2.2.1 `customer_profile_l1` · L1 客户画像

| 项 | 内容 |
| --- | --- |
| 用途 | 客户侧偏好：风格、规划、阈值偏好、行为标签（**不能改 L0 等级**） |
| 谁写 | **客户财富 Agent** |
| 谁读 | 客户本人、代理人、风控、数据分析 |
| 关键字段 | `customer_id`(PK) · `style_tags`(JSON 风格/财务/生命周期) · `style_questionnaire`(C-07 问卷) · `allocation_plan`(C-08 资金规划) · `behavior_tags` · `version`(乐观锁) · `updated_by` |
| 关键查询 | 代理人服务前读 L1 了解偏好；风控辅助判断；分析统计 |
| 关联 | → `risk_suitability_log.profile_l1_version`；Redis `profile:l1:{customer_id}` 缓存 |
| ⚠️ 边界 | **禁止存正式 C 等级**，以 L0 为准 |

#### 2.2.2 `customer_profile_l2` · L2 服务画像

| 项 | 内容 |
| --- | --- |
| 用途 | 代理人服务记录：诉求、待办、资产概况快照、服务标签（**客户不可见**） |
| 谁写 | **代理人助手 Agent** |
| 谁读 | 代理人、风控、数据分析（客户 API 层 404） |
| 关键字段 | `customer_id` + `advisor_id`(UK) · `asset_snapshot`(A-01 查 Core 后快照) · `demands`(沟通诉求) · `follow_up_todos` · `service_tags`(VIP/适老化) · `source_session_id` |
| 关键查询 | 代理人查名下客户服务记录；风控辅助 |
| 关联 | ← `customer_advisor_rel`(归属校验)；Redis `profile:l2:{customer_id}:{advisor_id}` |
| ⚠️ 边界 | 客户永远不可见 L2 |

#### 2.2.3 `customer_profile_l3` · L3 监测画像

| 项 | 内容 |
| --- | --- |
| 用途 | 风控监测结论：分层、评分、标签（**不改 L0 等级**） |
| 谁写 | **风控监测 Agent** |
| 谁读 | 风控、代理人(只读)、数据分析 |
| 关键字段 | `customer_id`(PK) · `monitor_tier`(normal/watch/high) · `risk_score`(监测分≠L0 C档) · `score_dimensions`(四维评分 JSON) · `monitor_tags`(AML/异常) · `last_alert_id` |
| 关键查询 | 风控工作台分层展示；分析统计高风险客户 |
| 关联 | → `risk_alert.alert_id`；Redis `profile:l3:{customer_id}` |
| ⚠️ 边界 | 监测分 ≠ 正式 C 档，不写回 L0 |

#### 2.2.4 `risk_alert` · 预警单

| 项 | 内容 |
| --- | --- |
| 用途 | 风控预警单（大额/频繁/适当性/AML/模式），**待人工审核** |
| 谁写 | **风控 Agent** |
| 谁读 | 风控专员、数据分析(只读统计)、合规 |
| 关键字段 | `alert_id`(PK) · `customer_id` · `trade_id` · `alert_type`(large_amount/freq_trade/suitability/aml/pattern) · `triggered_rules`(JSON) · `risk_score` · `status`(pending_review/confirmed_normal/confirmed_suspicious/reported) · `handler_id` · `handler_result` |
| 关键查询 | 风控台 pending_review 列表；分析统计「还有多少没审」 |
| 关联 | → `customer_profile_l3.last_alert_id`；Redis `risk:pub:alert` 推送 |
| ⚠️ 红线 | **不自动冻户**，状态由人工改 |

#### 2.2.5 `risk_suitability_log` · 适当性记录（R-02 落库）

| 项 | 内容 |
| --- | --- |
| 用途 | 一次 `check_suitability()` 判定 + 审计上下文，**唯一可阻断交易** 的场景 |
| 谁写 | **风控 Agent**（含交易前钩子 service 账号） |
| 谁读 | 客户(本人)、代理人(名下客户) |
| 关键字段 | `trace_id` · `customer_id` · `product_id` · `customer_risk_level`(L0 C档) · `product_risk_level`(R档) · `match_result`(allowed/allowed_with_disclosure/forbidden/risk_expired/professional_exempt) · `mismatch_type` · `is_blocked` · `requires_disclosure` · `needs_branch_confirm`(FM-01) · `risk_was_expired`(FM-03) · `block_response_code`(SUIT_*) · `check_source`(r02_trade/r02_chat/c11_inquiry/manual/**platform**) · `actor_id` · `rule_refs` |
| 关键查询 | 客户查本人能否买某产品；代理人查名下客户适当性历史 |
| 关联 | ← `core_ro.check_suitability()` 返回值逐项映射（见下方映射表） |
| ⚠️ 红线 | 阻断时同写 `audit_log`（同 trace_id）；`blocked=true` 仅 R-02 API 可对外返回 |

**与 check_suitability 字段映射（对照 07 文档）：**

| 表字段 | check_suitability 返回 | 说明 |
| --- | --- | --- |
| `customer_risk_level` | `customer_risk_code` | L0 正式 C 档 |
| `product_risk_level` | `product_risk_code` | 产品最低 R 档 |
| `match_result` | `match_result` | 枚举一致 |
| `mismatch_type` | `mismatch_type` | 枚举一致 |
| `is_matched` | `matched` | 是否可匹配 |
| `is_blocked` | `blocked` | 是否阻断 |
| `requires_disclosure` | `requires_disclosure` | 需风险揭示书 |
| `needs_branch_confirm` | `needs_branch_confirm` | FM-01 网点确认 |
| `risk_was_expired` | `risk_is_expired` | FM-03 风评过期 |
| `block_reason` | `reason` | 对人可读 |
| `block_response_code` | `block_response_code` | API 机器码 |

---

### 2.3 ⚪ 第三批 · 单 Agent 专用（5 张）

#### 2.3.1 `customer_threshold_config` · 亏损阈值配置（客户专用）

| 项 | 内容 |
| --- | --- |
| 用途 | 客户设「亏 10% 提醒我」（C-04） |
| 谁写 | 客户财富 Agent |
| 谁读 | 客户 Agent（触发提醒） |
| 关键字段 | `customer_id` · `scope_type`(portfolio/product) · `scope_ref` · `loss_threshold_pct` · `notify_channel`(app/sms/email) · `is_enabled` |
| 关键查询 | 持仓变动时查阈值命中 |
| 关联 | → `customer_notify_log`；摘要进 L1 `style_tags.threshold_pref_summary` |

#### 2.3.2 `customer_notify_log` · 提醒留痕（客户专用）

| 项 | 内容 |
| --- | --- |
| 用途 | 阈值/波动提醒发送记录 |
| 谁写 | 客户财富 Agent |
| 谁读 | 客户 Agent、合规审计 |
| 关键字段 | `customer_id` · `trace_id` · `notify_type`(loss_threshold/market_volatility) · `threshold_config_id` · `payload` · `channel` · `send_status`(sent/failed) |
| 关键查询 | 查某客户提醒历史；统计发送成功率 |
| 关联 | ← `customer_threshold_config` |

#### 2.3.3 `advisor_draft` · 话术/跟进草稿（代理人专用）

| 项 | 内容 |
| --- | --- |
| 用途 | 代理人话术草稿、跟进草稿（A-03），**不自动外发客户** |
| 谁写 | 代理人助手 Agent |
| 谁读 | 代理人、合规审核 |
| 关键字段 | `draft_id` · `session_id` · `advisor_id` · `customer_id` · `draft_type`(script/follow_up) · `content` · `review_status`(pending/approved/rejected) · `reviewer_id` · `reviewed_at` |
| 关键查询 | 代理人查自己草稿；合规查 pending 待审 |
| 关联 | ← `agent_session` |
| ⚠️ 红线 | 系统级禁止自动发客户；`review_status=pending` 默认 |

#### 2.3.4 `compliance_hit_log` · 违规话术命中（代理人专用）

| 项 | 内容 |
| --- | --- |
| 用途 | A-07 合规词库命中记录（收益承诺/保本/买卖指导/推荐） |
| 谁写 | 代理人助手 Agent |
| 谁读 | 合规专员 |
| 关键字段 | `session_id` · `agent_type` · `actor_id` · `hit_category`(return_promise/principal_guarantee/buy_sell_guide/product_recommend/other) · `matched_terms`(JSON) · `severity`(low/medium/high) · `action_taken`(flagged/blocked/alerted) |
| 关键查询 | 高风险命中告警；按 severity 统计 |
| 关联 | ← `agent_session` |

#### 2.3.5 `analytics_query_log` · 查数 SQL 留痕（分析专用）

| 项 | 内容 |
| --- | --- |
| 用途 | D-04 每次人话查数的 NL + SQL + 结果留痕 |
| 谁写 | 数据分析 Agent |
| 谁读 | 数据分析、合规审计 |
| 关键字段 | `session_id` · `staff_id` · `nl_question` · `generated_sql` · `sql_hash` · `row_count` · `exec_status`(success/error/blocked) · `result_summary`(JSON) · `has_disclaimer` |
| 关键查询 | 按 staff_id 查问数历史；按 sql_hash 统计高频查询 |
| 关联 | ← `agent_session` |
| ⚠️ 红线 | 仅 SELECT；对外输出强制免责声明 |

---

## 3. MySQL · jinrong_core 库（L0 只读，11 表）

> Agent 经 `CoreReadOnlyRepository` 只读 SELECT；**不改 Core 账**。建表 SQL：`scripts/core/01-ddl.sql`。

### 3.1 `core_risk_grade` · 风险等级字典

| 项 | 内容 |
| --- | --- |
| 用途 | C1~C5（客户）/ R1~R5（产品）字典 |
| 关键字段 | `code`(C1~C5/R1~R5) · `grade_type`(customer/product) · `display_name` · `sort_order` |
| 关联 | 被 `core_suitability_rule` / `core_customer_risk` / `core_product` 外键引用 |

### 3.2 `core_suitability_rule` · C×R 适当性矩阵

| 项 | 内容 |
| --- | --- |
| 用途 | 适当性匹配规则（L0 权威，对齐《适当性管理指南》第十二条） |
| 关键字段 | `customer_risk_code`(C1~C5) · `product_risk_code`(R1~R5) · `match_result`(allowed/allowed_with_disclosure/forbidden) · `rule_ref`(JR-AST-012) |
| 关键查询 | `check_suitability()` 查 C×R 是否匹配 |
| 关联 | ← `core_risk_grade` |

### 3.3 `core_staff` · 内部员工主档

| 项 | 内容 |
| --- | --- |
| 用途 | 模拟 IdP 账号源，含 RBAC roles JSON |
| 关键字段 | `staff_id`(PK，如 STAFF-10086) · `display_name` · `staff_type`(advisor/analyst/risk_officer/compliance/ops) · `roles`(JSON) · `tenant_id` · `is_active` |
| 关键查询 | JWT 签发时查 roles；联调账号对照 |
| 关联 | → `core_customer_advisor.advisor_id` |

### 3.4 `core_customer` · 客户主档 L0（KYC）

| 项 | 内容 |
| --- | --- |
| 用途 | 客户基础信息 + 财务概况 + AML/PEP 标记 |
| 关键字段 | `customer_id`(PK，如 CUST-9527) · `display_name`(脱敏) · `gender` · `birth_date` · `age` · `occupation` · `education` · `annual_income` · `financial_asset` · `monthly_investable` · `is_hnw` · `service_tier` · `is_pep` · `aml_risk_level`(low/medium/high) · `invest_experience_years` |
| 关键查询 | Agent 查客户 KYC；分析统计客户分布 |
| 关联 | → `core_customer_risk` · `core_holding` · `core_trade` · `core_cash_flow` |

### 3.5 `core_customer_risk` · 正式风险测评 L0

| 项 | 内容 |
| --- | --- |
| 用途 | 正式 C1~C5、问卷得分、风评过期（FM-03）、专业投资者 |
| 关键字段 | `customer_id` · `risk_code`(C1~C5) · `questionnaire_score` · `max_loss_tolerance_pct` · `investment_goal` · `investment_horizon` · `investor_category`(ordinary/professional/professional_pending) · `is_authoritative` · `evaluated_at` · `expires_at` |
| 关键查询 | `check_suitability()` 查正式 C 档 + 是否过期 |
| 关联 | ← `core_customer` · `core_risk_grade` |
| ⚠️ 边界 | Agent 只读，**不可改**；L1/L2/L3 不得覆盖 |

### 3.6 `core_customer_advisor` · 客户-代理人归属（Core 源）

| 项 | 内容 |
| --- | --- |
| 用途 | Core 侧归属关系，同步到 agent 库 `customer_advisor_rel` |
| 关键字段 | `customer_id` · `advisor_id` · `rel_status` · `effective_from` · `effective_to` |
| 关联 | → 同步到 `jinrong_agent.customer_advisor_rel` |

### 3.7 `core_product` · 产品主档

| 项 | 内容 |
| --- | --- |
| 用途 | 产品 + 起购金额/期限/风险揭示书（C-11） |
| 关键字段 | `product_id`(PK) · `product_name` · `product_type`(money/bond/mixed/stock/index/wealth_mgmt/private_fund/insurance/structured) · `min_risk_code`(R1~R5) · `min_subscribe_amount` · `term_days` · `requires_disclosure` · `industry_code` · `fee_rate` |
| 关键查询 | C-11 匹配说明；R-02 产品最低 R 档 |
| 关联 | ← `core_risk_grade` · `core_industry` |

### 3.8 `core_holding` · 持仓快照

| 项 | 内容 |
| --- | --- |
| 用途 | 客户持仓（份额、成本、市值、盈亏） |
| 关键字段 | `customer_id` · `product_id` · `qty` · `cost_amount` · `market_value` · `pnl_pct` · `as_of` |
| 关键查询 | C-01 持仓问答；A-01 客户概况 |
| 关联 | ← `core_customer` · `core_product` · **`core_share_lot`（FIFO 批次；申赎/转换确认后网关同步快照 qty）** |
| 2026-09-13 | 模拟申赎经 `trade_gateway` 维护批次并 **UPSERT `core_holding`**；读侧另有 `list_holdings_from_lots_gap` 补偿历史只写 lot 的演示态 |

### 3.8a `core_share_lot` · 份额批次（FIFO）

| 项 | 内容 |
| --- | --- |
| 用途 | 申赎/转换按批次扣减与追溯（赎回费按持有天数分档） |
| 关键字段 | `lot_id` · `remain_qty` · `nav` · `confirmed_at` |
| 谁写 | 模拟网关写侧（subscribe/redeem/convert 确认段） |
| 关联 | 与 `core_holding` 快照一致化；转换见 `core_convert_lot_detail` |

### 3.8b `core_convert_request` · 基金转换受理单（T+1）

| 项 | 内容 |
| --- | --- |
| 用途 | T 日**受理**（不扣份额）；T+1 **确认**扣批/写流水 |
| 关键字段 | `convert_group_id` · `client_request_id`（幂等）· `status` · `accept_date` / 确认日 |
| 深读 | [`架构设计-基金转换交易.md`](../项目框架设计/架构设计-基金转换交易.md) |

### 3.9 `core_trade` · 交易流水（含 AML 字段）

| 项 | 内容 |
| --- | --- |
| 用途 | 交易流水 + AML 渠道/对手方/代付（RW-001~020） |
| 关键字段 | `trade_id`(PK) · `customer_id` · `product_id` · `trade_type`(subscribe/redeem/convert) · `amount` · `channel` · `counterparty_account_mask` · `counterparty_name` · `is_cash` · `payer_name`(代付) · `is_third_party_pay` · `trade_status` · `traded_at` |
| 关键查询 | R-01 大额预警（单笔/当日≥50万）；R-04 频繁交易 |
| 关联 | ← `core_customer` · `core_product` |

### 3.10 `core_cash_flow` · 资金进出

| 项 | 内容 |
| --- | --- |
| 用途 | 资金进出流水（存/取/转/申赎） |
| 关键字段 | `customer_id` · `flow_type`(in/out) · `flow_subtype` · `amount` · `channel` · `counterparty_*` · `occurred_at` |
| 关键查询 | C-01 资金分布；AML 资金异动 |
| 关联 | ← `core_customer` |

### 3.11 `core_product_nav` · 产品净值

| 项 | 内容 |
| --- | --- |
| 用途 | 产品净值（C-05 行情） |
| 关键字段 | `product_id` · `nav` · `daily_chg_pct` · `nav_date` |
| 关键查询 | C-05「这只基金现在净值多少」 |
| 关联 | ← `core_product` |
| Phase B | 外部 REST → `sync_market_nav` UPSERT；见 [C-05-行情数据源选型对比.md](../项目框架设计/C-05-行情数据源选型对比.md) |

### 3.12 `core_industry` · 行业分类

| 项 | 内容 |
| --- | --- |
| 用途 | 行业字典（Neo4j BELONGS_TO） |
| 关键字段 | `industry_code`(PK) · `industry_name` |
| 关联 | ← `core_product.industry_code`；同步到 Neo4j `Industry` 节点 |

---

## 4. Redis · 短期记忆 Key（6 类）

> 原则：**权威结论落 MySQL**；Redis 只存会话窗口、热缓存、实时通知，丢失可重建。

### 4.1 🔴 会话短期记忆（四 Agent 共用）

| Key 模式 | 类型 | TTL | 写入方 | 读取方 | 内容 |
| --- | --- | --- | --- | --- | --- |
| `sess:{agent}:{session_id}:ctx` | Hash | 2h | 各 Agent | 各 Agent | 当前意图、槽位、上一轮 Tool 摘要 |
| `sess:{agent}:{session_id}:msgs` | List | 2h | 各 Agent | 各 Agent | 最近 ≤20 轮消息 JSON |
| `sess:{agent}:{session_id}:lock` | String | 30s | 平台 | 平台 | 并发写会话防重 |

### 4.2 🟡 画像热缓存（跨 Agent 读）

| Key 模式 | 类型 | TTL | 写入方 | 读取方 | 失效 |
| --- | --- | --- | --- | --- | --- |
| `profile:l1:{customer_id}` | String(JSON) | 10m | 客户 Agent | 代理人/风控/分析 | MySQL L1 UPDATE 时 DEL |
| `profile:l2:{customer_id}:{advisor_id}` | String(JSON) | 10m | 代理人 Agent | 代理人/风控 | MySQL L2 UPDATE 时 DEL |
| `profile:l3:{customer_id}` | String(JSON) | 5m | 风控 Agent | 客户/代理人/分析 | MySQL L3 UPDATE 时 DEL |

### 4.3 ⚪ 代理人 A-01 资产快照缓存

| Key 模式 | 类型 | TTL | 说明 |
| --- | --- | --- | --- |
| `cache:advisor:snapshot:{advisor_id}:{customer_id}` | String(JSON) | 15m | Core RO 查数 + 摘要；权威副本在 L2 `asset_snapshot` |

### 4.4 风控实时通道

| Key 模式 | 类型 | TTL | 说明 |
| --- | --- | --- | --- |
| `risk:pub:alert` | Pub/Sub | — | 新预警广播，payload=`{alert_id, type, customer_id_mask, risk_score}` |
| `risk:dedup:{customer_id}:{rule_id}:{date}` | String | 24h | 同日同规则防重复预警风暴 |

### 4.5 输入防护与限流（F-03）

| Key 模式 | 类型 | TTL | 说明 |
| --- | --- | --- | --- |
| `guard:rate:{actor_id}:{agent}` | String INCR | 1m | 每分钟请求计数 |
| `guard:block:{actor_id}` | String | 15m | 命中高危规则临时封禁 |

### 4.6 不放 Redis 的数据

- 审计主记录 `audit_log` → MySQL
- 预警单最终状态 `risk_alert.status` → MySQL
- 草稿审核结果 `advisor_draft.review_status` → MySQL
- SQL 留痕 `analytics_query_log` → MySQL
- 适当性阻断 `risk_suitability_log` → MySQL

---

## 5. Neo4j · 关系图谱（5 节点 + 5 关系）

> 同步自 Core（`sync_neo4j.py`）；Agent 不往 Neo4j 写画像，避免双写。

### 5.1 节点（Node Labels）

| Label | 主键属性 | 来源 | 说明 |
| --- | --- | --- | --- |
| `Customer` | `customer_id` | Core 同步 | 不含敏感明文，仅 ID + 脱敏标记 |
| `Advisor` | `advisor_id` | Core 同步 | 代理人 |
| `Product` | `product_id` | Core 同步 | 基金/产品 |
| `RiskGrade` | `code` | Core | C1~C5 或 R1~R5 |
| `Industry` | `industry_code` | Core 同步 | 行业分类 |

### 5.2 关系（Relationships）

| 关系 | 起 → 止 | 属性 | 用途 |
| --- | --- | --- | --- |
| `ASSIGNED_TO` | Customer → Advisor | `since`, `status` | F-01 归属校验 |
| `HAS_RISK_LEVEL` | Customer → RiskGrade | `source=l0`, `evaluated_at` | R-02 适当性（L0 权威） |
| `HOLDS` | Customer → Product | `qty`, `market_value`, `cost`, `pnl_pct`, `as_of` | C-01/A-01/R-01 上下文 |
| `REQUIRES_MIN_RISK` | Product → RiskGrade | `rule_id` | R-02 产品最低适配等级 |
| `BELONGS_TO` | Product → Industry | — | C-13 持仓传导 |

### 5.3 各 Agent 读图场景

| Agent | Cypher 意图 | 场景 |
| --- | --- | --- |
| 客户财富 | 我的某产品→所属行业→相关资讯标的 | C-01, C-13 |
| 代理人助手 | 客户→持仓→产品风险等级分布 | A-01 |
| 风控监测 | 客户→HOLDS→Product→REQUIRES_MIN_RISK vs HAS_RISK_LEVEL | R-02 |
| 数据分析 | 统计某 RiskGrade 下 HOLD 产品类别分布 | D-05 |

### 5.4 R-02 示例 Cypher

```cypher
MATCH (c:Customer {customer_id: $cid})-[:HAS_RISK_LEVEL]->(cr:RiskGrade)
MATCH (p:Product {product_id: $pid})-[:REQUIRES_MIN_RISK]->(pr:RiskGrade)
RETURN cr.code AS customer_risk, pr.code AS product_min_risk
```

> 硬判定逻辑仍在风控服务代码 + Core 规则引擎；Neo4j 提供 **关系查询加速**，非唯一真相源。

### 5.5 不在 Neo4j 存

会话/Message 节点、预警 Alert 节点、画像标签节点、全文文档节点（分别由 MySQL/Redis/Milvus 负责）。

---

## 6. Milvus · 知识库向量（2 Collection）

> Embedding：Ollama bge-m3，**1024 维**。原始文档存本地 `data/kb/`，不用 MinIO。

### 6.1 `kb_product_rules` · 产品规则知识库（共用 🟡）

| 项 | 内容 |
| --- | --- |
| 用途 | 基金产品手册、费率、申赎规则、风险说明（C-02/C-03/A-02） |
| 共用 Agent | 客户财富 + 代理人助手 |
| 关键字段 | `id`(`{product_id}_{chunk_no}`) · `embedding`(1024维) · `product_id` · `product_name` · `doc_type`(prospectus/fee/rule/risk) · `risk_level` · `source_doc_id`(溯源必填) · `source_version` · `effective_date` · `chunk_text` · `chunk_no` |
| 检索约束 | 回答**必须**返回 `source_doc_id` + `source_version`；过滤 `effective_date <= today` |
| 索引 | 向量 IVF_FLAT/HNSW；标量过滤 `product_id`/`doc_type`/`effective_date` |

### 6.2 `kb_business_ops` · 业务制度知识库（代理人专用 ⚪）

| 项 | 内容 |
| --- | --- |
| 用途 | 内部办事流程、办理条件（A-04 定投/赎回到账等） |
| 共用 Agent | 仅代理人助手（客户不直接暴露内部全文） |
| 关键字段 | `id`(`{process_code}_{chunk_no}`) · `embedding` · `process_code`(SUBSCRIBE/REDEEM/CONVERT/AIP) · `process_name` · `source_doc_id` · `source_version` · `chunk_text` · `chunk_no` |

### 6.3 P1 再加

`kb_compliance_scripts`（A-03 话术规范模板）

### 6.4 不放 Milvus

聊天记录、审计日志、客户 L1/L2/L3 画像 JSON、预警单、适当性结果（均走 MySQL）。

---

## 7. 画像 L1/L2/L3 分层详解（重点）

### 7.1 为什么分四层

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

| 层 | 存什么 | 权威库 | 谁写 | 谁读 |
| --- | --- | --- | --- | --- |
| **L0** | 官方 KYC、正式 C1~C5、持仓/流水 | `jinrong_core` | 非 Agent | 四 Agent 只读 |
| **L1** | 客户侧偏好、规划、行为（**不能改 L0 等级**） | `customer_profile_l1` | 客户 Agent | 客户本人、代理人、风控、分析 |
| **L2** | 代理人服务记录、诉求、待办（**客户不可见**） | `customer_profile_l2` | 代理人 Agent | 代理人、风控、分析 |
| **L3** | 监测分层、评分维度（**不改 L0 等级**） | `customer_profile_l3` | 风控 Agent | 风控、代理人/分析只读 |

### 7.2 为什么不合成一张表

| 问题 | 后果 |
| --- | --- |
| 客户说「我激进」和正式 C1 保守混在一起 | 容易误当成可买高风险 → 合规风险 |
| 代理人写的服务备注和客户自己填的规划权限不同 | 客户不应看到服务侧备注 |
| 风控的「重点关注」反写进官方测评 | 违规改正式等级 |

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

### 7.3 读写权限速查

| 角色 | L0 | L1 | L2 | L3 | suitability_log |
| --- | --- | --- | --- | --- | --- |
| 客户本人 | R | W/R 本人 | — | — | R 本人 |
| 代理人 | R | R 名下 | W/R 名下 | R 名下 | R 名下 |
| 风控 | R | R | R | W | **W** |
| 数据分析 | R | R 脱敏 | R 脱敏 | R 脱敏 | — |

> 客户永远不可见 L2/L3（API 层直接 404，避免泄露存在性）。

### 7.4 L1 `style_tags` JSON 示例

```json
{
  "basic": { "age_band": "25-30", "city": "上海", "education": "本科" },
  "financial": { "income_band": "10-20万", "monthly_investable": "3000-5000" },
  "investment": {
    "goal": "购房储蓄",
    "horizon": "1-3年",
    "product_preferences": ["指数基金", "货币基金"],
    "excluded_products": ["私募", "期货"]
  },
  "lifecycle": { "stage": "单身奋斗期", "near_term_goal": "购房" },
  "threshold_pref_summary": "亏损10%提醒"
}
```

> `threshold_pref_summary` 是 C-04 阈值偏好的**摘要**；明细在 `customer_threshold_config`。**禁止**在 L1 存正式 C 等级。

### 7.5 L3 `score_dimensions` JSON 示例（监测用，不写 L0）

```json
{
  "basic_attr": 17.5,
  "invest_experience": 17.5,
  "risk_preference": 8.0,
  "behavior_anomaly": 20.0,
  "computed_at": "2026-09-07T00:00:00Z",
  "model_ref": "JR-RULE-2024-001"
}
```

---

## 8. 审计表只 INSERT 约定（红线）

本项目有 4 张审计类表，**只允许 INSERT，禁止 UPDATE/DELETE**：

| 表 | 用途 | 谁写 | 谁读 |
| --- | --- | --- | --- |
| `audit_log` | 审计总账（鉴权、判定、人工处置） | 四 Agent + 平台 | 合规 |
| `agent_message` | 消息明细归档 | 四 Agent | 四 Agent + 合规 |
| `agent_tool_call` | Tool 调用审计 | 四 Agent | 合规、调试 |
| `input_guard_log` | 输入安全防护 | 平台 + 四 Agent | 安全/合规 |

**实现要求：**
- 代码层禁止任何 UPDATE/DELETE 这些表的业务路径
- 单测加只 INSERT 断言（尝试 UPDATE 应抛错或被拦截）
- 任何「修正」「撤回」需求都通过新 INSERT 一条对冲记录实现，不删原记录

---

## 9. 建表顺序（对应 bootstrap.ps1）

> 新环境按此顺序建库，对应 `scripts/dev/bootstrap.ps1` 执行步骤。

```text
① Docker Redis + Neo4j 启动
        ↓
② jinrong_core 模拟库（L0 只读）
   scripts/core/00-create-database.sql
   scripts/core/01-ddl.sql                  ← 11 表 DDL
   scripts/core/02-seed-base.sql            ← 风险等级/行业/员工/产品
   scripts/core/03-seed-customers.sql       ← 33 客户 + 风评 + 归属
   scripts/core/04-seed-holdings.sql         ← 持仓
   scripts/core/05-seed-trades.sql           ← 交易流水
   scripts/core/06-seed-nav.sql              ← 净值
        ↓
③ jinrong_agent 共用底座（11 表）
   docs/项目框架设计/表设计/01-mysql-共用底座.sql
        ↓
④ jinrong_agent Agent 专用（5 表）
   docs/项目框架设计/表设计/02-mysql-agent专用.sql
        ↓
⑤ 同步归属关系
   python scripts/sync/sync_advisor_rel.py  → customer_advisor_rel
        ↓
⑥ 同步 Neo4j 图
   python scripts/sync/sync_neo4j.py        → 节点 + 关系
        ↓
⑦ 验证计数
   jinrong_core.core_customer COUNT = 33
   jinrong_agent.customer_advisor_rel COUNT > 0
   jinrong_agent.agent_session 表存在
```

**为什么要这个顺序：**
- Core 先建：因为 agent 库的 `customer_advisor_rel` 由 Core 同步而来
- 共用底座先于专用：四 Agent 任意一个要跑都需要 11 张共用表
- Neo4j 最后同步：依赖 Core 的持仓/产品/归属数据

---

## 10. 一张矩阵速查：16 张 MySQL 表 × 4 Agent

图例：**W**=写入 **R**=读取 **·**=不用

| 表名 | 客户 | 代理人 | 分析 | 风控 | 档位 |
| --- | --- | --- | --- | --- | --- |
| `agent_session` | W/R | W/R | W/R | W/R | 🔴 |
| `agent_message` | W/R | W/R | W/R | W/R | 🔴 |
| `agent_tool_call` | W/R | W/R | W/R | W/R | 🔴 |
| `audit_log` | W | W | W | W | 🔴 |
| `input_guard_log` | W | W | W | W | 🔴 |
| `customer_advisor_rel` | R | R | R | R | 🔴 |
| `customer_profile_l1` | **W**/R | R | R | R | 🟡 |
| `customer_profile_l2` | · | **W**/R | R | R | 🟡 |
| `customer_profile_l3` | R | R | R | **W** | 🟡 |
| `risk_alert` | · | · | R | **W** | 🟡 |
| `risk_suitability_log` | R | R | · | **W** | 🟡 |
| `customer_threshold_config` | **W**/R | · | · | · | ⚪ |
| `customer_notify_log` | **W** | · | · | · | ⚪ |
| `advisor_draft` | · | **W**/R | · | · | ⚪ |
| `compliance_hit_log` | · | **W** | · | · | ⚪ |
| `analytics_query_log` | · | · | **W** | · | ⚪ |

> 底座 = 上表所有 🔴 + 🟡 行 = MySQL 11 张共用表；⚪ 5 张各 Agent 自建。

---

## 11. 关联文档

| 文档 | 用途 |
| --- | --- |
| [00-架构总览.md](../项目框架设计/表设计/00-架构总览.md) | 给新人的架构一页纸 |
| [05-多Agent共用底座清单.md](../项目框架设计/表设计/05-多Agent共用底座清单.md) | 16 表 × 4 Agent 完整矩阵 |
| [01-mysql-共用底座.sql](../项目框架设计/表设计/01-mysql-共用底座.sql) | 共用 11 表 DDL |
| [02-mysql-agent专用.sql](../项目框架设计/表设计/02-mysql-agent专用.sql) | 专用 5 表 DDL |
| [06-用户画像L1-L3设计.md](../项目框架设计/表设计/06-用户画像L1-L3设计.md) | 画像 JSON schema |
| [07-risk_suitability_log说明.md](../项目框架设计/表设计/07-risk_suitability_log说明.md) | R-02 落库字段契约 |
| [02-redis-keys.md](../项目框架设计/表设计/02-redis-keys.md) | Redis Key 明细 |
| [03-milvus-collections.md](../项目框架设计/表设计/03-milvus-collections.md) | Milvus Collection 字段 |
| [04-neo4j-model.md](../项目框架设计/表设计/04-neo4j-model.md) | Neo4j 图模型 |
| [../Core模拟底座/01-表结构与种子说明.md](../项目框架设计/Core模拟底座/01-表结构与种子说明.md) | Core 11 表 + 种子说明 |
| [../技术选型和版本/02-JWT-RBAC鉴权手册.md](../项目框架设计/技术选型和版本/02-JWT-RBAC鉴权手册.md) | 鉴权与归属校验 |
| [../../scripts/core/01-ddl.sql](../../scripts/core/01-ddl.sql) | Core 建表 SQL |
| [../../scripts/dev/bootstrap.ps1](../../scripts/dev/bootstrap.ps1) | 一键 bootstrap |
| [../业务记忆管理/业务记忆管理手册.md](../业务记忆管理/业务记忆管理手册.md) | 记忆分层详解 |