group_xinghuo_jinrong/docs/项目框架设计/表设计/02-mysql-agent 专用表设计总结.md

02-mysql-agent 专用表设计总结

源文件：docs/项目框架设计/表设计/02-mysql-agent专用.sql 数据库：jinrong_agent（Agent 专用库，与核心业务库 jinrong_core 分离） 配套文件：01-mysql-共用底座.sql（会话/消息/RBAC 等共用底座）

一、文件定位

• 用途：各 Agent 组开发自有功能时建表，也可一次性全建。
• 引擎：全部 InnoDB。
• 表数量：文件实际包含 7 张表。

  注意：文件头注释写「单 Agent 专用 MySQL（5 张）」，实际为 7 张——conversation_archive、customer_notes 为客服 Agent 后期（CS-C-11 / Wave 5）追加，头部计数未同步更新。

二、表清单（按 Agent 分组）

#	表名	归属 Agent	作用
1	customer_threshold_config	客户财富 Agent	客户亏损阈值配置
2	customer_notify_log	客户财富 Agent	提醒发送留痕
3	advisor_draft	代理人助手 Agent	话术/跟进草稿（含人工审核）
4	compliance_hit_log	代理人助手 Agent	违规话术命中日志
5	analytics_query_log	数据分析 Agent	NL2SQL 查数留痕
6	conversation_archive	客服 Agent（跨 Agent 通用）	会话归档摘要
7	customer_notes	客服 Agent	客户显式备注（独立于 L1 画像）

---

三、客户财富 Agent（2 张）

3.1 customer_threshold_config — 亏损阈值配置

客户自定义亏损提醒线。

字段	类型	说明
id	BIGINT UNSIGNED PK	自增主键
customer_id	VARCHAR(64) NOT NULL	客户 ID
scope_type	ENUM('portfolio','product')	作用范围：组合 / 单产品，默认 portfolio
scope_ref	VARCHAR(64) NULL	产品引用（scope_type=product 时使用）
loss_threshold_pct	DECIMAL(5,2) NOT NULL	亏损阈值百分比
notify_channel	SET('app','sms','email')	通知渠道，支持多选，默认 app
is_enabled	TINYINT(1)	启用开关，默认 1
created_at / updated_at	DATETIME(3)	创建/更新时间（毫秒精度，updated_at 自动刷新）

• 索引：idx_customer(customer_id, is_enabled)

3.2 customer_notify_log — 提醒留痕

每次阈值/波动提醒的发送审计记录。

字段	类型	说明
id	BIGINT UNSIGNED PK	自增主键
customer_id	VARCHAR(64) NOT NULL	客户 ID
trace_id	VARCHAR(64) NOT NULL	全链路追踪 ID
notify_type	ENUM('loss_threshold','market_volatility')	提醒类型：亏损阈值 / 市场波动
threshold_config_id	BIGINT UNSIGNED NULL	关联阈值配置（可空）
payload	JSON NOT NULL	提醒详情
channel	VARCHAR(16) NOT NULL	实际发送渠道
send_status	ENUM('sent','failed')	发送状态
created_at	DATETIME(3)	创建时间

• 索引：idx_customer_time(customer_id, created_at)

---

四、代理人助手 Agent（2 张）

4.1 advisor_draft — 话术/跟进草稿

AI 为代理人生成的话术或跟进记录，走人工审核闭环。

字段	类型	说明
id	BIGINT UNSIGNED PK	自增主键
draft_id	VARCHAR(64) NOT NULL	草稿业务 ID（唯一键 uk_draft_id）
session_id	VARCHAR(64) NOT NULL	会话 ID
trace_id	VARCHAR(64) NOT NULL	全链路追踪 ID
advisor_id	VARCHAR(64) NOT NULL	代理人 ID
customer_id	VARCHAR(64) NOT NULL	客户 ID
draft_type	ENUM('script','follow_up')	草稿类型：话术 / 跟进
content	MEDIUMTEXT NOT NULL	草稿正文
review_status	ENUM('pending','approved','rejected')	审核状态，默认 pending
reviewer_id	VARCHAR(64) NULL	审核人 ID
reviewed_at	DATETIME(3) NULL	审核时间
created_at	DATETIME(3)	创建时间

• 索引：uk_draft_id(draft_id)、idx_advisor_customer(advisor_id, customer_id, created_at)、idx_review(review_status, created_at)

4.2 compliance_hit_log — 违规话术命中日志

合规护栏命中留痕（客户/代理人两端通用）。

字段	类型	说明
id	BIGINT UNSIGNED PK	自增主键
session_id	VARCHAR(64) NOT NULL	会话 ID
trace_id	VARCHAR(64) NOT NULL	全链路追踪 ID
agent_type	ENUM('customer','advisor')	触发端：客户侧 / 代理人侧
actor_id	VARCHAR(64) NOT NULL	操作者 ID
hit_category	ENUM('return_promise','principal_guarantee','buy_sell_guide','product_recommend','other')	命中类别：收益承诺 / 保本承诺 / 买卖指导 / 产品推荐 / 其他
matched_terms	JSON NOT NULL	命中词明细
severity	ENUM('low','medium','high')	严重程度
action_taken	ENUM('flagged','blocked','alerted')	处置动作：标记 / 拦截 / 告警
created_at	DATETIME(3)	创建时间

• 索引：idx_severity_time(severity, created_at)、idx_session(session_id)

---

五、数据分析 Agent（1 张）

5.1 analytics_query_log — 查数 SQL 留痕

自然语言查数（NL2SQL）的完整审计链。

字段	类型	说明
id	BIGINT UNSIGNED PK	自增主键
session_id	VARCHAR(64) NOT NULL	会话 ID
trace_id	VARCHAR(64) NOT NULL	全链路追踪 ID
staff_id	VARCHAR(64) NOT NULL	员工 ID
nl_question	TEXT NOT NULL	自然语言问题原文
generated_sql	TEXT NOT NULL	生成的 SQL
sql_hash	CHAR(64) NOT NULL	SQL 哈希（去重/统计用）
row_count	INT UNSIGNED NULL	返回行数
exec_status	ENUM('success','error','blocked')	执行状态：成功 / 报错 / 被拦截
exec_latency_ms	INT UNSIGNED NULL	执行耗时（毫秒）
result_summary	JSON NULL	结果摘要
has_disclaimer	TINYINT(1)	是否附带免责声明，默认 0
error_message	VARCHAR(512) NULL	报错信息
created_at	DATETIME(3)	创建时间

• 索引：idx_staff_time(staff_id, created_at)、idx_trace(trace_id)、idx_sql_hash(sql_hash)

---

六、客服 Agent（2 张）

6.1 conversation_archive — 会话归档摘要（CS-C-11，跨 Agent 通用）

会话结束时生成摘要写入；设计上 customer/advisor/analyst/risk 四类 Agent 通用。

字段	类型	说明
id	BIGINT UNSIGNED PK	自增主键
session_id	VARCHAR(64) NOT NULL	关联 agent_session.session_id，一会话一归档（唯一键 uk_session_id）
trace_id	VARCHAR(64) NOT NULL	全链路追踪 ID
agent_type	ENUM('customer','advisor','analyst','risk')	Agent 类型
actor_id	VARCHAR(64) NOT NULL	操作者：客户=customer_id / 游客=VISITOR
summary	TEXT NOT NULL	LLM 生成的会话摘要
msg_count	INT UNSIGNED	消息条数（count agent_message），默认 0
archive_reason	ENUM('timeout','explicit','manual')	归档原因：超时 / 显式结束 / 手动
created_at	DATETIME(3)	创建时间

• 索引：uk_session_id(session_id)、idx_trace(trace_id)、idx_actor(agent_type, actor_id, created_at)
• 刻意不冗余：
  • 消息明细不存，见共用底座 agent_message；
  • 会话起止时间不存：起 = agent_session.created_at，止 = agent_session.closed_at（归档动作同时将 agent_session.status 置为 closed）。

6.2 customer_notes — 客户显式备注（独立于 L1 画像）

用户主动要求记忆的自由文本（如「你要记住我每天看净值」），不进 L1 画像槽位表。

字段	类型	说明
id	BIGINT UNSIGNED PK	自增主键
customer_id	VARCHAR(64) NOT NULL	客户 ID（关联 customer_profile_l1.customer_id）
session_id	VARCHAR(64) NOT NULL	备注生成的会话 ID
trace_id	VARCHAR(64) NOT NULL	全链路追踪 ID
content	VARCHAR(500) NOT NULL	LLM 抽取后的纯净备注内容
category	VARCHAR(32) NULL	可选分类：habit / preference / reminder / other
source_text	VARCHAR(800) NULL	用户原话片段（审计用）
is_active	TINYINT(1)	1=有效，0=用户已删除（软删除，保留审计痕）
created_at	DATETIME(3)	创建时间

• 索引：idx_cid_active_time(customer_id, is_active, created_at)、idx_trace(trace_id)
• 写入与使用链路：
  1. keyword_route 命中「记住 / 记一下 / 帮我记 / 别忘了 / 记着」→ 路由到 save_note 意图；
  2. 调 LLM 从用户原话抽取纯净 content（≤500 字，超长裁剪）+ 可选 category（非枚举值写 NULL）；
  3. 写入本表，source_text 保留原话片段；
  4. 后续对话每轮读取该客户最近 N 条 active 备注，注入 chitchat/interpret 的 prompt；
  5. 用户要求「忘掉备注」时执行软删除（is_active=0）；LLM 抽取失败/异常则不写库并回落提示话术。

---

七、共性设计约定

1. 主键：统一 id BIGINT UNSIGNED AUTO_INCREMENT。
2. 时间字段：DATETIME(3) 毫秒精度；created_at 默认 CURRENT_TIMESTAMP(3)；配置类表（如 customer_threshold_config）带 updated_at ... ON UPDATE CURRENT_TIMESTAMP(3) 自动刷新。
3. 全链路追踪：业务流程表普遍携带 trace_id 并建索引。
4. 取值约束：状态/分类优先用 ENUM；多选用 SET（如通知渠道）；半结构化内容用 JSON（payload、matched_terms、result_summary）。
5. 索引设计：围绕最高频查询场景建联合索引，典型模式为「主体 ID + 时间」（如 customer_id, created_at）及「状态 + 时间」（如 review_status, created_at、severity, created_at）。
6. 审计思路：所有 AI 动作均有留痕——提醒发送、草稿审核、违规命中、SQL 查数、会话归档、客户备注，支持事后核查。
7. 软删除：customer_notes 通过 is_active 软删除保留审计痕迹；归档表通过唯一键保证一会话一归档。

---

八、各表与代码层对应关系

结论基于对 app/、tests/ 全量检索表名的实际结果（截至 2026-09-09）。 7 张表中 2 张已有完整代码落地（客服 Agent），1 张仅在注释中被引用，4 张尚无代码（属未来波次 Agent）。

8.1 落地状态总览

表名	Repository	Service	编排/入口	状态
customer_notes	app/repository/note_repository.py → CustomerNoteRepository	app/service/note_service.py	customer_service.py LangGraph save_note 节点	✅ 已落地（Wave 5）
conversation_archive	app/repository/profile_repository.py → ProfileRepository（归档段）	app/service/profile_service.py（archive_session 等）	customer_service.py archive_check / end_session	✅ 已落地（Wave 3）
customer_threshold_config	—	—	仅 app/config/profile_slots.py 槽位注释提及	⏳ 未实现（客户财富 Agent）
customer_notify_log	—	—	—	⏳ 未实现（客户财富 Agent）
advisor_draft	—	—	—	⏳ 未实现（代理人助手 Agent）
compliance_hit_log	—	—	现有合规护栏 app/utils/compliance_guard.py 仅内存正则，未落库	⏳ 未实现（代理人助手 Agent）
analytics_query_log	—	—	—	⏳ 未实现（数据分析 Agent）

8.2 customer_notes 代码链路

层	文件	关键函数/位置	对应表操作
Repository	note_repository.py	CustomerNoteRepository.insert_note()（L26）	INSERT INTO customer_notes
Repository	同上	list_active_notes()（L59）	SELECT ... WHERE is_active=1 ORDER BY created_at DESC LIMIT N
Repository	同上	deactivate() / deactivate_all()（L76、L89）	软删除 UPDATE ... SET is_active=0
Service	note_service.py	save_note_from_message()（L40）	调 DeepSeek 抽取纯净 content+category → insert_note；抽取失败不写库
Service	同上	render_notes_context()（L90）	读最近 settings.note_max_inject 条 active 备注，格式化为 prompt 注入文本
Service	同上	forget_all_notes()（L114）	包装 deactivate_all，异常吞掉返回 0
编排	customer_service.py	LangGraph save_note 节点（L375，注册 L461，路由 L481）	save_note 意图分支入口
编排	同上	每轮 render_notes_context(cid)（L144）	备注注入 chitchat/interpret prompt
路由/Prompt	customer_prompts.py	keyword_route 命中「记住/记一下/帮我记/别忘了/记着」→ save_note（L153）；备注抽取 prompt（L277）	关键词前置路由 + LLM 抽取模板
测试	test_wave5_notes.py	Wave 5 共 13 例	写入/注入/软删除/抽取失败回落

8.3 conversation_archive 代码链路

层	文件	关键函数/位置	对应表操作
Repository	profile_repository.py	insert_archive()（L146）	INSERT INTO conversation_archive（agent_type 当前硬编码 'customer'）
Repository	同上	close_session()（L133）	先将 agent_session 置 closed；仅 active 可关，防重复归档、保 uk_session_id 不冲突
Repository	同上	count_session_messages()（L123）	msg_count 来源（COUNT agent_message）
Repository	同上	list_idle_customer_sessions()（L171）	懒扫描空闲超时的 active 客户会话
Service	profile_service.py	archive_session()（L430）	归档主流程：关会话 → 等 1s 避异步落库竞态 → 计数+取消息窗 → LLM 生成摘要（失败回落「会话已结束，共 N 条消息」）→ insert_archive → 后台触发画像全量抽槽 extract_profile + refresh_behavior_tags
Service	同上	archive_idle_sessions()（L477）	懒扫描批量归档，archive_reason='timeout'，每轮上限 settings.archive_idle_scan_limit
编排	customer_service.py	archive_check 节点（每轮 _spawn 后台调 archive_idle_sessions）	超时归档，失败不影响响应
编排	同上	显式结束 end_session → _spawn(archive_session, ..., "explicit")（L436）	用户主动结束会话归档

归档动作与共用底座表联动：消息明细读 agent_message，会话状态写 agent_session（均在 01-mysql-共用底座.sql），本表只存摘要。

8.4 未落地表的备注

• customer_threshold_config：目前唯一代码痕迹是 profile_slots.py L152 的画像槽位说明——lifecycle.threshold_pref_summary 槽位注释「客户主动提出的提醒阈值摘要（明细归 customer_threshold_config）」。即画像只存阈值偏好摘要，明细表待客户财富 Agent 波次实现。
• compliance_hit_log：现有合规护栏 compliance_guard.py 提供 scan_reply() / sanitize_reply() / should_add_disclaimer()，目前为内存级正则扫描（命中即替换回复），尚未落库；表结构预留给代理人助手/双端合规留痕。
• analytics_query_log：属数据分析 Agent 的 NL2SQL 留痕。客服侧数据查询（持仓/流水/风评/适当性）按硬约束走 app/tool/core_ro_tool.py 预定义函数工具、禁止 NL2SQL，因此客服链路不会写此表。
• customer_notify_log / advisor_draft：分别属客户财富 Agent（提醒发送留痕）与代理人助手 Agent（草稿+审核闭环），当前无代码。