group_xinghuo_jinrong/docs/项目框架设计/表设计/02-redis-keys.md

# Redis · 短期记忆 Key 设计（P0）

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

---

## 1. Key 命名规范

```text
{domain}:{agent}:{entity}:{id}[:{sub}]
```

| 占位 | 示例 |
| --- | --- |
| domain | `sess` `profile` `risk` `guard` `cache` |
| agent | `customer` `advisor` `analyst` `risk` |
| entity | `ctx` `msgs` `pub` |

---

## 2. P0 Key 清单

### 2.1 会话短期记忆（四 Agent 共用模式）

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

**落盘策略**：每条 user/assistant 消息 **同步或 5s 内异步** 写 MySQL `agent_message`；Redis 只保滑动窗口。

### 2.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 |

### 2.3 代理人 A-01 资产概况快照缓存

| Key | 类型 | TTL | 说明 |
| --- | --- | --- | --- |
| `cache:advisor:snapshot:{advisor_id}:{customer_id}` | String(JSON) | 15m | Core RO 查数 + 结构化摘要；过期后重新 Tool 查询 |

权威副本同时写 MySQL `customer_profile_l2.asset_snapshot`。

### 2.4 风控实时通道（R-01 / R-03）

| Key | 类型 | TTL | 说明 |
| --- | --- | --- | --- |
| `risk:pub:alert` | Pub/Sub | — | 新预警广播，payload=`{alert_id, alert_type, customer_id_mask, risk_score, trace_id, notify_role}`，风控追加 v1.1 起**可带附加字段**：`alert_subtype`（C4/C6 出单子类型数组，如 `["concentration"]`/`["agent_behavior"]`）、`escalation_level`（C5 升级级别 `LEVEL_1`/`LEVEL_2`）；两者仅在非空时下发（口径以 `docs/PRD/PRD-风控监测Agent.md` FR-4 + §4A 为准，2026-09-07 修订） |
| `risk:dedup:{customer_id}:{rule_id}:{date}` | String | 24h | 同日同规则防重复预警风暴 |

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

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

### 2.6 代理人行为链联动（C6 · RISK-008）

| 联动点 | 说明 |
| --- | --- |
| 出单线 | `agent_behavior` 为**代理人维度**独立 pattern 单（payload.actor_id 指向代理人、actor_type='agent'），**不并入**客户维度事件单（find_pending_event_alert 已排除 agent_behavior 单）；同日同代理人一张单（find_agent_behavior_alert 去重锚点） |
| 推送范围 | `notify_role=["risk_officer","risk_manager"]`（`risk:pub:alert` 可带 `alert_subtype=["agent_behavior"]`）；risk_manager 仅阅知、无处置权（红线） |
| 数据源 | audit_log（trade_request 的 input_summary.trade_id 回查 core_trade 取 traded_at/trade_type/product_id；authz forbidden 的 input_summary.code 区分 AUTH_403_SCOPE / NOT_OWNER / NOT_ASSIGNED）——**不改表、审计仅 INSERT** |
| 审计留痕 | 每代理人每次命中一条 `event_type=agent_behavior_detected`（decision='detected'，risk_score=75，仅 INSERT，写库失败降级不阻塞扫描） |
| 去重口径 | 代理人维度去重走 MySQL `risk_alert`（actor_id + 日界），**不复用** §2.4 的 `risk:dedup:{customer_id}:{rule_id}:{date}` 客户维度键（两者维度不同，互不干扰） |

---

## 3. 各 Agent 使用范围

| Agent | 读 | 写 |
| --- | --- | --- |
| 客户财富 | sess:customer:*, profile:l1:self, profile:l3:self(只读) | sess:customer:*, profile:l1 |
| 代理人助手 | sess:advisor:*, profile:l1/l2/l3, cache:advisor:snapshot | sess:advisor:*, profile:l2, cache:advisor:snapshot |
| 数据分析 | sess:analyst:* | sess:analyst:*（不写画像） |
| 风控监测 | profile:l1/l2, risk:dedup | profile:l3, risk:pub:alert, risk:dedup |

---

## 4. 不放入 Redis 的数据

- 审计主记录（`audit_log`）
- 预警单最终状态（`risk_alert.status`）
- 草稿审核结果（`advisor_draft.review_status`）
- SQL 留痕（`analytics_query_log`）