diff --git a/.cursor/rules/project-memory.mdc b/.cursor/rules/project-memory.mdc new file mode 100644 index 0000000..7df8bc2 --- /dev/null +++ b/.cursor/rules/project-memory.mdc @@ -0,0 +1,11 @@ +--- +description: 日常只读 MEMORY 快照；细节回源文件。完整阅读表见 MEMORY 第 5 节。 +alwaysApply: true +--- + +# 项目记忆 + +改代码前默认只读 `docs/memory/MEMORY.md`。 +对照条目再读 REQUIREMENTS；模块/选型再读 FRAMEWORK；端到端再读 FLOW；现状再读 ENVIRONMENT。 +维护、口令、技术选型硬阀门：见 MEMORY 第 3、5–7 节。 +缺文件：同名补回；禁止静默用空模板盖进度。 diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..5848ddb --- /dev/null +++ b/.env.example @@ -0,0 +1,31 @@ +# Application +APP_ENV=development + +# MySQL +MYSQL_HOST=127.0.0.1 +MYSQL_PORT=3306 +MYSQL_DATABASE=jinrong_agent +MYSQL_USER=root +MYSQL_PASSWORD= + +# Redis +REDIS_URL=redis://127.0.0.1:6379/0 + +# Neo4j +NEO4J_URI=bolt://localhost:7687 +NEO4J_USER=neo4j +NEO4J_PASSWORD= + +# Milvus Lite +MILVUS_URI=./data/milvus.db + +# Ollama Embedding +OLLAMA_BASE_URL=http://127.0.0.1:11434 +EMBED_MODEL=bge-m3 + +# DeepSeek LLM +DEEPSEEK_API_KEY= +DEEPSEEK_BASE_URL=https://api.deepseek.com + +# JWT (dev only — production use RS256 + IdP) +JWT_DEV_SECRET=change-me-in-dev-only diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0840093 --- /dev/null +++ b/.gitignore @@ -0,0 +1,41 @@ +# App +.env +.env.local +*.pyc +__pycache__/ +.pytest_cache/ +.mypy_cache/ +.ruff_cache/ +venv/ +.venv/ + +# Data & secrets +data/milvus.db +data/kb/* +!data/kb/.gitkeep +*.pem +*.key + +# IDE +.idea/ +.vscode/ +*.swp + +# Node (frontend) +node_modules/ +dist/ +web/dist/ + +# OS +Thumbs.db +.DS_Store + +# Logs +*.log +logs/ + +# Milvus / Neo4j local +.milvus/ + +# Archives +docs/项目框架设计/表设计.zip diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..311e1b4 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,12 @@ +# Agent + +日常只读 [docs/memory/MEMORY.md](docs/memory/MEMORY.md)。 + +- 对照开发：`docs/memory/REQUIREMENTS.md`（场景 ID：F/C/A/D/R） +- 框架/选型：`docs/memory/FRAMEWORK.md` → `docs/项目框架设计/技术选型和版本/` +- 表结构：`docs/项目框架设计/表设计/` +- 业务需求原文：`docs/需求拆解/` + +技术选型硬阀门见 MEMORY 第 3、7 节。Cursor 以 `.cursor/rules/project-memory.mdc` 为准。 + +后端入口：`app/main.py` · 分层见 `docs/memory/FRAMEWORK.md` §3。 diff --git a/README.md b/README.md new file mode 100644 index 0000000..0ca4c1a --- /dev/null +++ b/README.md @@ -0,0 +1,43 @@ +# JinRong · 金融四 Agent 智能管家 + +四个 Agent（客户财富 / 代理人助手 / 数据分析 / 风控监测）共用统一数据层与合规底座。 + +## 文档 + +| 目录 | 内容 | +| --- | --- | +| [docs/memory/MEMORY.md](docs/memory/MEMORY.md) | 项目记忆入口（Agent 先读） | +| [docs/需求拆解/](docs/需求拆解/) | 业务场景、数据矩阵、合规 | +| [docs/项目框架设计/](docs/项目框架设计/) | 表设计、技术选型、JWT 手册 | + +## 后端结构 + +```text +app/ +├── api/ # 路由：chat、knowledge、admin +├── service/ # Agent、RAG、记忆 +├── tool/ # 解析、Embedding、Milvus +├── model/ # Pydantic + ORM +├── config/ # settings、database +├── utils/ +└── main.py +``` + +## 环境要求 + +- Python 3.13+、MySQL 8.0、Redis 8、Neo4j Desktop、Ollama（bge-m3） +- Windows 原生部署（见技术选型文档） + +## 快速启动 + +```bash +cp .env.example .env +pip install -r requirements.txt +uvicorn app.main:app --reload +``` + +健康检查：`GET http://127.0.0.1:8000/health` + +## 前端 + +React 19 + Vite 7 + Ant Design 5（待 init `web/` 目录）。 diff --git a/app/__init__.py b/app/__init__.py new file mode 100644 index 0000000..07008ac --- /dev/null +++ b/app/__init__.py @@ -0,0 +1 @@ +"""JinRong 四 Agent 智能管家 · 后端应用包。""" diff --git a/app/api/__init__.py b/app/api/__init__.py new file mode 100644 index 0000000..d8bce07 --- /dev/null +++ b/app/api/__init__.py @@ -0,0 +1 @@ +"""API 路由层。""" diff --git a/app/api/admin.py b/app/api/admin.py new file mode 100644 index 0000000..0b883d8 --- /dev/null +++ b/app/api/admin.py @@ -0,0 +1 @@ +"""管理接口：审计查询、合规巡检、会话/Tool 留痕（RBAC 保护）。""" diff --git a/app/api/chat.py b/app/api/chat.py new file mode 100644 index 0000000..1243c84 --- /dev/null +++ b/app/api/chat.py @@ -0,0 +1 @@ +"""对话接口：四 Agent 统一 chat 入口（按 X-Agent-Type 分流）。""" diff --git a/app/api/knowledge.py b/app/api/knowledge.py new file mode 100644 index 0000000..579ac9f --- /dev/null +++ b/app/api/knowledge.py @@ -0,0 +1 @@ +"""知识库管理：文档入库、Milvus Collection、产品规则 RAG。""" diff --git a/app/config/__init__.py b/app/config/__init__.py new file mode 100644 index 0000000..7c88203 --- /dev/null +++ b/app/config/__init__.py @@ -0,0 +1 @@ +"""应用配置。""" diff --git a/app/config/database.py b/app/config/database.py new file mode 100644 index 0000000..896acc2 --- /dev/null +++ b/app/config/database.py @@ -0,0 +1 @@ +"""MySQL / Redis / Neo4j 连接工厂。""" diff --git a/app/config/settings.py b/app/config/settings.py new file mode 100644 index 0000000..a9753ae --- /dev/null +++ b/app/config/settings.py @@ -0,0 +1,32 @@ +"""环境配置（从 .env 读取，见 .env.example）。""" + +from pydantic_settings import BaseSettings, SettingsConfigDict + + +class Settings(BaseSettings): + model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", extra="ignore") + + app_env: str = "development" + + mysql_host: str = "127.0.0.1" + mysql_port: int = 3306 + mysql_database: str = "jinrong_agent" + mysql_user: str = "root" + mysql_password: str = "" + + redis_url: str = "redis://127.0.0.1:6379/0" + + neo4j_uri: str = "bolt://localhost:7687" + neo4j_user: str = "neo4j" + neo4j_password: str = "" + + milvus_uri: str = "./data/milvus.db" + + ollama_base_url: str = "http://127.0.0.1:11434" + embed_model: str = "bge-m3" + + deepseek_api_key: str = "" + deepseek_base_url: str = "https://api.deepseek.com" + + +settings = Settings() diff --git a/app/main.py b/app/main.py new file mode 100644 index 0000000..12fbe63 --- /dev/null +++ b/app/main.py @@ -0,0 +1,15 @@ +"""FastAPI 入口：挂载路由、中间件（JWT/RBAC）、生命周期。""" + +from fastapi import FastAPI + +from app.config.settings import settings + +app = FastAPI(title="JinRong Agent Platform", version="0.1.0") + + +@app.get("/health") +def health(): + return {"status": "ok", "env": settings.app_env} + + +# TODO: 挂载 app.api 路由；接入 Auth SDK 中间件 diff --git a/app/model/__init__.py b/app/model/__init__.py new file mode 100644 index 0000000..71c2523 --- /dev/null +++ b/app/model/__init__.py @@ -0,0 +1 @@ +"""数据模型：Pydantic 与 ORM。""" diff --git a/app/model/entities.py b/app/model/entities.py new file mode 100644 index 0000000..875d628 --- /dev/null +++ b/app/model/entities.py @@ -0,0 +1 @@ +"""SQLAlchemy ORM 实体（对齐 docs/项目框架设计/表设计 SQL）。""" diff --git a/app/model/schemas.py b/app/model/schemas.py new file mode 100644 index 0000000..ffcf983 --- /dev/null +++ b/app/model/schemas.py @@ -0,0 +1 @@ +"""Pydantic 请求/响应模型、AuthContext 等。""" diff --git a/app/service/__init__.py b/app/service/__init__.py new file mode 100644 index 0000000..3dbb67f --- /dev/null +++ b/app/service/__init__.py @@ -0,0 +1 @@ +"""业务逻辑层。""" diff --git a/app/service/agent_service.py b/app/service/agent_service.py new file mode 100644 index 0000000..4d671b9 --- /dev/null +++ b/app/service/agent_service.py @@ -0,0 +1 @@ +"""Agent 编排：LangChain + DeepSeek；Tool 调用；四 Agent 能力边界。""" diff --git a/app/service/memory_service.py b/app/service/memory_service.py new file mode 100644 index 0000000..44ee227 --- /dev/null +++ b/app/service/memory_service.py @@ -0,0 +1 @@ +"""记忆服务：Redis 会话窗口 + MySQL 落盘；L1/L2/L3 画像读写。""" diff --git a/app/service/rag_service.py b/app/service/rag_service.py new file mode 100644 index 0000000..18ca77b --- /dev/null +++ b/app/service/rag_service.py @@ -0,0 +1 @@ +"""RAG 编排：检索 kb_product_rules / kb_business_ops + 溯源。""" diff --git a/app/tool/__init__.py b/app/tool/__init__.py new file mode 100644 index 0000000..f0e3eb2 --- /dev/null +++ b/app/tool/__init__.py @@ -0,0 +1 @@ +"""工具层：文档解析、Embedding、Milvus 等外部能力封装。""" diff --git a/app/tool/document_parser.py b/app/tool/document_parser.py new file mode 100644 index 0000000..9d93bcf --- /dev/null +++ b/app/tool/document_parser.py @@ -0,0 +1 @@ +"""文档解析：PDF/Word → 文本块（本地 data/kb/，不用 MinIO）。""" diff --git a/app/tool/embedding_tool.py b/app/tool/embedding_tool.py new file mode 100644 index 0000000..6787d69 --- /dev/null +++ b/app/tool/embedding_tool.py @@ -0,0 +1 @@ +"""向量化：Ollama bge-m3，1024 维。""" diff --git a/app/tool/milvus_tool.py b/app/tool/milvus_tool.py new file mode 100644 index 0000000..d3f63c8 --- /dev/null +++ b/app/tool/milvus_tool.py @@ -0,0 +1 @@ +"""Milvus 封装：Milvus Lite 连接、Collection CRUD、语义检索。""" diff --git a/app/utils/__init__.py b/app/utils/__init__.py new file mode 100644 index 0000000..a68c643 --- /dev/null +++ b/app/utils/__init__.py @@ -0,0 +1 @@ +"""通用工具。""" diff --git a/app/utils/exceptions.py b/app/utils/exceptions.py new file mode 100644 index 0000000..a7f5d40 --- /dev/null +++ b/app/utils/exceptions.py @@ -0,0 +1 @@ +"""业务异常与鉴权错误码（对齐 JWT-RBAC 手册）。""" diff --git a/app/utils/logger.py b/app/utils/logger.py new file mode 100644 index 0000000..3bc6aa2 --- /dev/null +++ b/app/utils/logger.py @@ -0,0 +1 @@ +"""日志模块。""" diff --git a/app/utils/response.py b/app/utils/response.py new file mode 100644 index 0000000..a868c47 --- /dev/null +++ b/app/utils/response.py @@ -0,0 +1 @@ +"""统一 API 响应格式。""" diff --git a/data/kb/.gitkeep b/data/kb/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/data/kb/.gitkeep @@ -0,0 +1 @@ + diff --git a/docs/memory/ENVIRONMENT.md b/docs/memory/ENVIRONMENT.md new file mode 100644 index 0000000..c5e8b60 --- /dev/null +++ b/docs/memory/ENVIRONMENT.md @@ -0,0 +1,55 @@ +# 服务对象大环境（现状 / As-Is） + +> 来源：`docs/需求拆解/业务场景优先级清单.md`、`docs/需求拆解/用户故事/` + +------ + +## 1. 服务对象与角色（现在） + +| 角色 | 谁 | 在环境里干什么 | +| --- | --- | --- | +| C 端客户 | 公募投资者 | 看持仓、查产品、交易；正式 C1~C5 在测评系统 | +| 理财代理人 | 一线理财经理 | 服务名下客户、多系统查持仓、讲解规则、跟进 | +| 内部员工 | 分析、运营、合规 | 问数、报表、抽检会话、协同风控 | +| 风控 / 合规官 | 风控专员 | 监测大额/适当性/AML；人工审核，不自动冻户 | + +**Core：** 持仓、流水、交易、正式风险等级、客户-代理人归属的权威来源。 + +------ + +## 2. 对方现在怎么办事 + +- **客户**：App/柜台看持仓；亏损无 Agent 式阈值提醒。 +- **代理人**：多后台手工汇总；话术自写，合规靠事后检查。 +- **内部分析**：SQL 或 IT 导表。 +- **风控**：事后/T+1 发现异常；适当性靠交易前规则；AML 批处理或人工。 + +Agent **尚未上线**。 + +------ + +## 3. 主路径（现状） + +1. 开户/测评 → Core 写 L0（C1~C5、归属代理人） +2. 交易 → Core 流水；交易前适当性（若有） +3. 代理人服务 → 查 Core + 口头沟通（无统一 L2 画像库） +4. 风控 → 规则/人工台账；合规事后抽检 + +------ + +## 4. 环境里的关键对象 + +| 名称 | 含义 | +| --- | --- | +| L0 正式档案 | customer_id、C1~C5、年龄、职业、advisor | +| 持仓/流水 | 产品、份额、盈亏 | +| 代理人-客户归属 | customer_advisor_rel（Core 同步） | + +------ + +## 5. 痛点与约束 + +```text +痛点：客户看不清持仓与规则；代理人多系统慢、话术易违规；问数靠 SQL；风控感知滞后 +不能动：正式 C1~C5 仅测评/人工变更；事实账以 Core 为准；监管要求审计与适当性 +``` diff --git a/docs/memory/FLOW.md b/docs/memory/FLOW.md new file mode 100644 index 0000000..a8ad714 --- /dev/null +++ b/docs/memory/FLOW.md @@ -0,0 +1,80 @@ +# 实现流程 + +> To-Be 端到端链路；As-Is 见 `ENVIRONMENT.md` +> 画像分层见 `docs/项目框架设计/表设计/00-架构总览.md` + +------ + +## 1. 链路总览 + +```text +Client → Gateway(JWT/RBAC) → api/chat → agent_service → Tools → 存储 → 响应 + audit_log +``` + +------ + +## 2. 主链路 · 对话 + +```text +输入：Authorization + X-Agent-Type + X-Trace-Id + 用户消息 +↓ +Gateway：验签、角色准入、注入 AuthContext +↓ +api/chat：SessionGuard；创建/续 agent_session +↓ +memory_service：Redis 读最近 N 轮；异步写 agent_message +↓ +agent_service：LangChain + DeepSeek；按 Agent 类型选 Tool 集 +↓ +Tool 示例： + - Core RO：持仓/流水（自动注入 customer_id） + - milvus_tool：产品规则 RAG + source_refs + - memory_service：读/写 L1/L2/L3（ProfileGuard） + - 风控 service 账号：R-02 适当性（无会话） +↓ +输出：assistant 消息 + has_disclaimer（客户/对外） +↓ +落库：agent_message、agent_tool_call、audit_log（同 trace_id） +``` + +------ + +## 3. 主链路 · 知识库入库 + +```text +admin/knowledge 上传 → document_parser → embedding_tool(Ollama bge-m3) +→ milvus_tool 写入 Collection（dim=1024） +→ 元数据可选写 MySQL；原文件存 data/kb/ +``` + +------ + +## 4. 分支 · 四 Agent + +| X-Agent-Type | 写画像 | 特殊 | +| --- | --- | --- | +| customer | L1 | 仅本人；读 suitability 本人 | +| advisor | L2 | customer_advisor_rel 校验 | +| analyst | 无 | 仅 SELECT SQL | +| risk | L3、预警、适当性 | R-02 可 blocked | + +------ + +## 5. 每步 I/O + +| 步骤 | 输入 | 输出 | 约定 | +| --- | --- | --- | --- | +| 鉴权 | JWT | AuthContext | 失败 401/403 + audit | +| 会话 | session_id | Redis ctx + MySQL session | actor_id 一致 | +| RAG | question + product_id? | chunks + source_doc_id | 必须溯源 | +| 画像读 | customer_id | L1/L2/L3 JSON | RBAC 矩阵 §8 | +| 审计 | 任意判定 | audit_log INSERT | 不可删改 | + +------ + +## 6. 关键数据约定 + +- MySQL 脚本：`docs/项目框架设计/表设计/01-mysql-共用底座.sql`、`02-mysql-agent专用.sql` +- Redis Key：`docs/项目框架设计/表设计/02-redis-keys.md` +- Milvus：`kb_product_rules`、`kb_business_ops`；向量 **1024** 维 +- 禁止：Agent 覆盖 L0 正式 C1~C5 diff --git a/docs/memory/FRAMEWORK.md b/docs/memory/FRAMEWORK.md new file mode 100644 index 0000000..1921a2e --- /dev/null +++ b/docs/memory/FRAMEWORK.md @@ -0,0 +1,76 @@ +# 项目框架 + +> 选型详情：`docs/项目框架设计/技术选型和版本/01-技术栈与版本.md` +> 表设计：`docs/项目框架设计/表设计/` +> 鉴权：`docs/项目框架设计/技术选型和版本/02-JWT-RBAC鉴权手册.md` + +------ + +## 1. 技术选型（已定） + +| 技术栈 | 已定（用户已同意） | 备注 | +| --- | --- | --- | +| 后端语言/框架 | Python 3.13.14 + FastAPI | 系统 Python | +| Agent 编排 | langchain 1.3.18 / langchain-openai 1.6.0 | DeepSeek API | +| 关系库 | MySQL 8.0.46 | jinrong_agent，:3306 | +| 缓存 | Redis 8.10.1 | :6379 | +| 图库 | Neo4j 5.26.19 Enterprise | Desktop，关系查询 | +| 向量库 | Milvus Lite + pymilvus 3.0.1 | 本地文件；1024 维 | +| Embedding | Ollama bge-m3 | 本地，不出内网 | +| LLM 生成 | DeepSeek API | 对话/推理 | +| 前端 | React 19 + Vite 7 + AntD 5 + TS strict | 不用 Streamlit | +| 对象存储 | 本地目录 data/kb/ | 不用 MinIO | +| 部署 | Windows 原生 | Docker 仅答辩备选 | + +```text +不用：MinIO（日常）、Docker 日常开发、Streamlit、Agent 互调 LLM +取舍：内存 15.4GB → Milvus Lite 替代 Docker Milvus 三容器 +``` + +------ + +## 2. 能力模块 + +| 模块 | 职责 | 依赖 | +| --- | --- | --- | +| Agent Gateway / Auth SDK | JWT、RBAC、归属校验 | Redis、MySQL customer_advisor_rel | +| 客户财富 Agent | L1 画像、事实查询、阈值提醒 | Core RO、Milvus 产品库 | +| 代理人助手 Agent | L2 画像、RAG、草稿 | L1 只读、Milvus | +| 数据分析 Agent | NL→SQL→解读 | Core RO、画像只读 | +| 风控监测 Agent | 预警、L3、R-02 适当性 | 交易事件、AML 名单 | +| 共用底座 | 会话、审计、输入防护 | MySQL 11 表 + Redis | + +------ + +## 3. 后端分层（app/） + +```text +api/ → 路由（chat、knowledge、admin）；薄，不含业务 +service/ → agent_service、rag_service、memory_service +tool/ → document_parser、embedding_tool、milvus_tool +model/ → schemas（Pydantic）、entities（ORM） +config/ → settings、database +utils/ → response、exceptions、logger +main.py → FastAPI 入口 + +允许：api → service → tool / model / config +禁止：api 直连 Milvus/MySQL 写复杂逻辑；tool 写业务流程 +``` + +------ + +## 4. 数据分层（跨模块） + +| 层 | 存储 | 说明 | +| --- | --- | --- | +| L0 | Core 只读 | 正式 C1~C5、持仓 | +| L1/L2/L3 | MySQL 画像表 | 客户/代理人/风控 enrich | +| 会话 | Redis + MySQL | 窗口 + 永久审计 | +| RAG | Milvus + 本地文件 | kb_product_rules 等 | +| 关系 | Neo4j | 客户-产品-代理人（Core 同步） | + +------ + +## 5. 骨架一句话 + +Gateway 鉴权 → FastAPI api → service 编排 Agent → tool 访问 MySQL/Redis/Milvus/Neo4j/Core → 审计落库。 diff --git a/docs/memory/ITERATION.md b/docs/memory/ITERATION.md new file mode 100644 index 0000000..0a25f3f --- /dev/null +++ b/docs/memory/ITERATION.md @@ -0,0 +1,8 @@ +# 需求迭代 + +| 日期 | 变更 | 原因 | 影响 | +| --- | --- | --- | --- | +| 2026-09-05 | init 项目记忆 + app 脚手架 | 用户要求 memory kit + 目录结构 | MEMORY / ENVIRONMENT / REQUIREMENTS / FRAMEWORK / FLOW / TODO | +| 2026-09-05 | 需求拆解四 Agent P0 场景定稿 | 用户故事归纳 | REQUIREMENTS（对照 docs/需求拆解/） | +| 2026-09-05 | 技术栈 Windows 原生 + Milvus Lite | 本机内存限制 | FRAMEWORK | +| 2026-09-05 | MySQL 16 表 + L0~L3 画像 + JWT 统一鉴权 | 多 Agent 共用底座 | FRAMEWORK / FLOW | diff --git a/docs/memory/MEMORY.md b/docs/memory/MEMORY.md new file mode 100644 index 0000000..10b2296 --- /dev/null +++ b/docs/memory/MEMORY.md @@ -0,0 +1,101 @@ +# 项目记忆（人 + Agent 共用） + +> 各阶段的**简化快照**（门闸索引）。只留基础信息，不写源文件正文。 +> 详细需求见 `docs/需求拆解/`；表设计与技术选型见 `docs/项目框架设计/`。 + +------ + +## 1. 项目简介 + +- **名称：** JinRong 金融四 Agent 智能管家 +- **当前阶段：** MVP（需求与底座设计已定，后端脚手架已 init） +- **当前优先级：** 交付速度（先 Wave 0 共用底座 + Wave 1 内部 Agent 闭环） + +------ + +## 2. 阶段快照 + +| 阶段 | 当前一句话 | 源文件 | +| --- | --- | --- | +| 服务对象大环境 | 公募场景下四类角色各自痛点明确，数据以 Core 为准、Agent 只读事实 | `ENVIRONMENT.md` | +| 需求目的 | 四个 Agent 服务四类人群，统一数据层交换画像与预警，合规可审计 | `REQUIREMENTS.md` | +| 项目框架 | FastAPI 分层 app + MySQL/Redis/Milvus Lite/Neo4j + React；Windows 原生 | `FRAMEWORK.md` | +| 实现流程 | Gateway JWT/RBAC → Agent 编排 → Tool/画像库 → 审计落库 | `FLOW.md` | + +------ + +## 3. 约束 + +**硬阀门：技术选型** + +`docs/项目框架设计/技术选型和版本/01-技术栈与版本.md` 中已标「已定」视为用户确认；新增依赖须再确认。 + +**禁止触碰：** + +```text +Core 正式 C1~C5、持仓/交易真账（Agent 只读） +audit_log 等审计表（只 INSERT） +代理人草稿自动外发客户 +风控自动冻户 / 改正式风险等级 +各 Agent 自建第二套 JWT/RBAC +``` + +**高风险（改前需确认）：** 数据库表结构、JWT/RBAC、部署密钥、删生产数据。 + +**开发开关：** + +| 项 | YES / NO | +| --- | --- | +| 允许新增依赖 | YES（对齐技术选型文档） | +| 允许重构 | YES（最小范围） | +| 允许改表 / schema | 需确认 | +| 允许改接口协议 | 需确认 | + +**特殊规则：** + +```text +四 Agent 不互调 LLM；跨 Agent 走 L1/L2/L3 画像与预警表 +客户 Agent：无投资建议/收益承诺/自动下单 +代理人：不对 C 端直发 +数据分析：仅 SELECT，不处置预警 +画像不得覆盖 L0 正式测评 +``` + +------ + +## 4. 入口与运行 + +```text +关键文件：app/main.py · app/config/settings.py · docs/项目框架设计/表设计/*.sql +如何启动：MySQL/Redis/Neo4j/Ollama 就绪后 → uvicorn app.main:app --reload +配置位置：.env（见 .env.example） +``` + +------ + +## 5. 文档资产约定 + +| 文件 | 何时更新 | +| --- | --- | +| `docs/memory/*.md` | 见 project-memory-kit 约定 | +| `docs/需求拆解/` | 业务场景与合规（参考） | +| `docs/项目框架设计/` | 表结构、鉴权、技术版本 | + +日常改代码只读本文件；验收对照 `REQUIREMENTS.md`。 + +------ + +## 6. 协作口令 + +【大环境】→ ENVIRONMENT · 【需求讨论】→ REQUIREMENTS · 【框架讨论】→ FRAMEWORK · 【实现流程】→ FLOW · 【Plan】→ TODO + +------ + +## 7. 阅读完成门闸（Agent） + +1. 四个 Agent 服务谁、禁止什么？ +2. 改动属于 api / service / tool 哪一层？ +3. 是否需 customer_id 归属与 JWT RBAC？ +4. 如何验证？ + +大任务：FRAMEWORK/FLOW 为空时先补再编码（用户确认跳过除外）。 diff --git a/docs/memory/REQUIREMENTS.md b/docs/memory/REQUIREMENTS.md new file mode 100644 index 0000000..4d23cb3 --- /dev/null +++ b/docs/memory/REQUIREMENTS.md @@ -0,0 +1,47 @@ +# 需求拆解（对照开发） + +> 来源：`docs/需求拆解/业务场景优先级清单.md`（P0） +> 合规：`docs/需求拆解/Agent风险与合规约束汇总.md` +> 数据：`docs/需求拆解/数据交互矩阵.md` + +------ + +## 本轮范围 + +- **目的：** 四 Agent 服务四类人群，统一数据层 + 合规底座，可对话闭环。 +- **明确不做：** 自动交易、营销推荐、Agent 互调 LLM、自动冻户、Streamlit、P3 平台能力。 + +------ + +## Wave 0 · 共用底座 + +| ID | 需求 | 验收对照 | 状态 | TODO | +| --- | --- | --- | --- | --- | +| F-01 | JWT + RBAC + 数据归属 | 越权 403 + audit；JWT 手册 §13 | 未做 | T-01 | +| F-02 | 全量审计留痕 | trace_id 可还原 | 未做 | T-02 | +| F-03 | 输入防护 | input_guard_log | 未做 | T-03 | +| F-04 | Core 只读层 | 不改 Core 账 | 未做 | T-04 | +| R0-DB | MySQL 共用 11 表 + Redis | 01-mysql-共用底座.sql | 未做 | T-05 | + +## Wave 1 · 内部 Agent P0 + +| ID | 需求 | 验收对照 | 状态 | TODO | +| --- | --- | --- | --- | --- | +| D-01~D-04 | 分析：客户/产品/预警查数 + SQL 留痕 | analytics_query_log | 未做 | T-10 | +| A-01~A-05 | 代理人：画像/规则/草稿/流程/合规巡检 | 非归属 403；草稿不外发 | 未做 | T-20 | + +## Wave 2 · 风控 P0 + +| ID | 需求 | 验收对照 | 状态 | TODO | +| --- | --- | --- | --- | --- | +| R-01 | 大额预警 | risk_alert pending_review | 未做 | T-30 | +| R-02 | 适当性阻断请求 | 唯一阻断场景 | 未做 | T-31 | +| R-03 | AML 命中通知 | 不自动冻户 | 未做 | T-32 | + +## Wave 3 · 客户 P0 + +| ID | 需求 | 验收对照 | 状态 | TODO | +| --- | --- | --- | --- | --- | +| C-01~C-05 | 持仓/产品/规则/阈值/净值 | 无买卖指导 | 未做 | T-40 | + +P1+ 见 `docs/需求拆解/业务场景优先级清单.md` §3。 diff --git a/docs/memory/TODO.md b/docs/memory/TODO.md new file mode 100644 index 0000000..bed9135 --- /dev/null +++ b/docs/memory/TODO.md @@ -0,0 +1,21 @@ +# TODO + +> 大任务开始时更新；完成一步打钩并验证后再往下。 + +## 进行中 + +- [ ] Wave 0 共用底座 — 验收：F-01~F-04 + MySQL 11 表可连 + +## 待办 + +- [ ] T-01 Auth SDK / JWT 中间件（对照 JWT 手册） +- [ ] T-05 执行 01-mysql-共用底座.sql + database.py 连接 +- [ ] T-21 Milvus Lite + kb_product_rules 首批入库 +- [ ] T-20 代理人 A-01 持仓 Tool + 归属校验 +- [ ] 前端 React 多 Agent 入口（HashRouter） + +## 已完成 + +- [x] 2026-09-05 init 项目记忆目录 + app/ 脚手架 +- [x] 2026-09-05 需求拆解文档（业务场景/矩阵/合规） +- [x] 2026-09-05 表设计 + 技术选型 + JWT 手册 diff --git a/docs/memory/tests/_TEMPLATE.md b/docs/memory/tests/_TEMPLATE.md new file mode 100644 index 0000000..aeee8d9 --- /dev/null +++ b/docs/memory/tests/_TEMPLATE.md @@ -0,0 +1,34 @@ +# 测试日志模板 + +复制为 `YYYYMMDD-短任务名.md` 后填写。 + +```markdown +# 测试日志：<任务名> + +- 日期： +- 关联 TODO： +- 风险等级：LOW / MEDIUM / HIGH + +## 改了什么 + +- 文件： +- 行为变化： + +## 已执行 + +| 类型 | 命令或步骤 | 结果 | +| --- | --- | --- | +| 手工 / 单测 / 集成 | | PASS / FAIL / 未执行 | + +## 未执行 + +- 项： +- 原因： + +## 结论 + +- 需求是否覆盖： +- 旧功能是否破坏： +- 剩余风险： +- 建议人工再验： +``` diff --git a/docs/需求拆解/Agent风险与合规约束汇总.md b/docs/需求拆解/Agent风险与合规约束汇总.md new file mode 100644 index 0000000..040baec --- /dev/null +++ b/docs/需求拆解/Agent风险与合规约束汇总.md @@ -0,0 +1,350 @@ +# 四个 Agent 风险与合规约束汇总 + +> 需求拆解阶段产物 · 2026-09-05 +> 依据：`docs/需求拆解/用户故事`、`业务场景优先级清单.md`、`数据交互矩阵.md` +> 用途：研发验收、Prompt/Tool 边界设计、合规评审、测试用例编写 + +--- + +## 1. 全局合规前提（四个 Agent 共用） + +以下约束**全部 Agent 必须遵守**，作为上线前提（对应 F-01~F-04）。 + +| 编号 | 约束类别 | 必须做 | 严禁做 | 关联场景 | +| --- | --- | --- | --- | --- | +| G-01 | 身份与权限 | JWT + RBAC + 数据层归属校验；客户只看本人，代理人只看名下客户 | 跨权限查客户、互看他人会话 | F-01 | +| G-02 | 审计留痕 | 每次对话、Tool 调用、SQL、风控判定全量落库，含 trace_id、时间戳、操作者 | 隐藏、篡改、删除审计记录 | F-02 | +| G-03 | 输入安全 | 清洗高危 Prompt、注入指令、超长非法参数 | 原始用户输入不经校验直接拼进 Tool/SQL | F-03 | +| G-04 | 数据写入 | 通过统一只读层读业务事实；Agent 自有产出（画像、预警、草稿）写专用表 | 改持仓、改交易、改正式风险等级、改预警处置状态 | F-04 | +| G-05 | 事实口径 | 持仓、盈亏、正式风险等级读核心业务系统同一数据源 | 各 Agent 各算一套口径 | 全场景 | +| G-06 | 适当性权威 | 正式风险等级 C1~C5 以开户/测评系统为准 | Agent 画像层覆盖或替代 L0 正式等级 | 画像库 | +| G-07 | Agent 互调 | 跨 Agent 通过统一数据层交换，不直接互调 LLM | Agent A 直接调用 Agent B 的对话接口做决策 | 架构 | +| G-08 | 免责声明 | 面向客户或可能被外用的输出，须带标准风险提示 / 免责声明 | 输出看似投顾结论却无免责表述 | C-09、D-04 | + +**四个 Agent 唯一例外（阻断能力）** +全系统仅 **风控监测 Agent · R-02 适当性不匹配** 可在**交易请求进入流程前**阻断；其余 Agent **一律不得阻断、冻结、拦截已发生交易**。 + +--- + +## 2. 客户财富 Agent + +**服务对象**：C 端客户 +**角色定位**：事实查询、规则解读、阈值提醒；**不是投顾、不是交易员** + +### 2.1 能力边界 + +| 可以做 | 不可以做 | +| --- | --- | +| 汇总持仓、资金进出、资产分布（纯事实） | 执行转换、下单、自动调仓 | +| 介绍基金/产品官方信息，业绩须溯源 | 对比产品优劣、暗示收益、推荐买卖 | +| 解读 T+1、涨跌幅等官方交易规则 | 给走势买卖点、替代客户下单 | +| 达阈值时陈述跌幅，列出可选动作（加仓/撤出由客户自决） | 说「应该买/卖/加仓/止损」；自动执行 | +| 回答现价/净值/涨跌（可用延迟行情） | 承诺实盘时延；做专业毫秒盘口终端 | +| 整理基金经理公开履历与历史回报 | 给出「该不该买这只基金」结论 | +| 问卷+行为出风格标签；给同类方向事实清单 | 输出具体买卖指令 | +| 按客户确认的规划做偏离提醒 | 超配自动调仓（阻断归风控 R-02） | +| 生成盈亏归因复盘（事实） | 承诺未来收益 | +| 推送持仓相关风险事件（陈述关联事实） | 给应对买卖建议 | +| 按条件说明产品是否匹配（风险/期限/起购） | 千人千面营销话术；替代投顾推荐 | +| 规则内税费提示 | 税务筹划承诺；替代会计师/税务师 | +| 采集 L1 用户画像（风格、规划、阈值、行为标签） | 画像用于投资建议或收益承诺 | + +### 2.2 输出合规要求 + +| 输出类型 | 合规要求 | +| --- | --- | +| 产品/规则解读 | 必须溯源官方材料；禁止模型幻觉内容 | +| 亏损/波动提醒 | 只陈述事实 + 可选动作清单；禁止指导性买卖语句 | +| 风格匹配 / 产品匹配 | 须联动风控适当性（R-02）；只做「是否匹配」说明 | +| 投后复盘 / 归因报告 | 必须附免责声明；禁止收益预测 | +| 税务提示 | 标明「仅供参考，不构成税务意见」 | +| 所有对外可见回复 | 含标准风险提示语（如「投资有风险，决策需自担」类表述） | + +### 2.3 数据与隐私约束 + +| 约束 | 说明 | +| --- | --- | +| 读写范围 | 仅读写**本人** L1 画像与会话；只读本人 L0 与持仓 | +| 画像共享 | L1 写入统一画像库，供代理人/风控/内部分析只读（RBAC 范围内） | +| 不可见 | L2 服务侧画像、L3 监测标签（客户侧不展示） | +| 禁止 | 读取其他客户数据；将内部分析口径直接展示给客户 | + +### 2.4 一期验收红线（P0） + +- 能答持仓/分布、基金规则与业绩、净值问答、阈值提醒 +- **不能**出现：自动交易、营销推荐、收益承诺、买卖指导 +- 越权访问他人账户必须被拒绝并留痕 + +### 2.5 关联场景 + +C-01 ~ C-13（P0~P2）；C-14~C-18 为 P3 暂缓，一期不做 + +--- + +## 3. 代理人助手 Agent + +**服务对象**：一线理财代理人（配套：合规专员、运营人员） +**角色定位**：内部辅助工具；**不对 C 端投资者直接输出** + +### 3.1 前置统一约束（全部故事通用） + +| 编号 | 约束 | 说明 | +| --- | --- | --- | +| A-G-01 | 仅内部使用 | 不对 C 端直发、不推送、不自动发消息给客户 | +| A-G-02 | 禁止投顾输出 | 严禁投资建议、收益预测、买卖指导、保本表述 | +| A-G-03 | 权限跟随 RBAC | 代理人只能查看**自己归属**的客户 | +| A-G-04 | 全量审计 | 问答、Tool 调用、LLM 输出全部留痕 | +| A-G-05 | 人工复核 | 所有对外话术草稿**必须人工复核**后方可使用 | +| A-G-06 | 只查不写核心 | 只查不写原有公募核心业务数据 | + +### 3.2 分场景约束 + +| 场景 | 可以做 | 不可以做 | +| --- | --- | --- | +| A-01 客户持仓梳理 | 结构化汇总持仓、类型分布、风险等级、期限、盈亏（纯事实） | 评价持仓好坏；建议加减仓；预测收益；查非本人客户 | +| A-02 产品规则答疑 | 基于官方手册答费率、申赎、封闭期、风险等级、适配人群；**必须溯源** | 对比基金优劣；推荐产品；超出官方文档的自定义解读 | +| A-03 合规话术草稿 | 结合持仓事实 + 合规规范生成草稿，自动带风险提示 | 含投资建议/保本/收益承诺；**自动发送客户** | +| A-04 业务流程查询 | 输出标准办理流程、前置条件、禁忌场景 | 承诺办理结果；绕过官方流程指导 | +| A-05 合规巡检 | 检索会话、Tool、LLM 输出；行为统计 | 隐藏、篡改、省略任何记录 | +| A-06 跟进记录整理 | 提炼诉求、要点、待办，生成日志**草稿** | **自动写入**正式客户档案 | +| A-07 违规话术识别 | 按合规词库标记；高风险强制告警 | 私自放行高风险内容 | +| A-08 高频问题统计 | 热点聚类、失败咨询 TOP | 导出具体客户隐私明细 | +| A-09 知识库校验 | 用最新 Skill/知识库做对齐抽检 | 输出过期、废弃规则 | + +### 3.3 输出合规要求 + +| 输出类型 | 合规要求 | +| --- | --- | +| 产品规则回答 | 必须溯源官方文档；禁止幻觉 | +| 话术草稿 | 自动携带标准风险提示；标记「草稿·需人工复核」 | +| 客户资产概况 | 纯事实汇总，禁止评价性语言 | +| 运营统计 | 仅脱敏聚合，不可还原个人 | + +### 3.4 数据与隐私约束 + +| 约束 | 说明 | +| --- | --- | +| 读写范围 | 名下客户 L0/L1 只读；L2 服务画像读写；L3 监测标签只读 | +| 画像使用 | 可读客户 Agent 采集的 L1，用于 A-03 话术与沟通准备 | +| 草稿与档案 | 话术/跟进草稿不得自动进入正式档案或触达客户 | +| 合规角色 | 合规专员可审计全部代理人 Agent 会话（专属 RBAC） | + +### 3.5 一期验收红线（P0） + +- 输入客户 ID 出事实画像；产品规则可溯源；话术草稿不外发 +- 合规可抽检全量会话 +- **不能**出现：自动发客户、产品推荐、收益预测、跨权限查客户 + +### 3.6 关联场景 + +A-01 ~ A-09；合规台能力归入本 Agent 配套工作台 + +--- + +## 4. 数据分析 Agent + +**服务对象**：内部员工（数据分析师、业务同事） +**角色定位**：**只统计、只解读**；为其他业务提供数据支撑，**不处置、不改数** + +### 4.1 能力边界 + +| 可以做 | 不可以做 | +| --- | --- | +| 大白话 → 只读 SQL → 人话解读 | 修改任何业务数据 | +| 查客户：持仓、流水、规模、风险等级分布 | 替客户做投资决策 | +| 查产品：收益、申购、持仓规模 | 产品推荐（归投顾/客户 Agent，且受各自合规约束） | +| 查风险台账：预警数量、状态分布 | **处置**预警（归风控专员人工） | +| 跨表聚合解读（授权范围内） | 发明未授权宽表；访问超权限字段 | +| 读 L1/L2/L3 画像做人群统计（脱敏/聚合） | 修改画像库 | +| 每次对话与 SQL 强制留痕 | 生成可执行的买卖/冻结/处置指令 | + +### 4.2 输出合规要求 + +| 输出类型 | 合规要求 | +| --- | --- | +| 内部查数结果 | 标明数据来源与时间；SQL 可追溯 | +| 偏「对外报告」风格的输出 | **强制免责声明**（D-04） | +| 聚合统计 | 脱敏；不可还原个人身份 | +| 预警相关 | 只报数量/状态，不代为审核或关闭预警 | + +### 4.3 职责分界（硬规矩） + +| 事项 | 负责方 | 数据分析 Agent | +| --- | --- | --- | +| 产品推荐 | 投顾 / 客户 Agent（受限） | **不做** | +| 可疑交易判定与处理 | 风控专员 | **不做** | +| 对外产品规则讲解 | 客服 / 代理人 Agent | **不做** | +| 事实数据查询与解读 | — | **只做这个** | + +### 4.4 数据与隐私约束 + +| 约束 | 说明 | +| --- | --- | +| SQL | 仅允许 **SELECT**；禁止 INSERT/UPDATE/DELETE | +| 权限 | 跟随员工 RBAC；超权限字段拒绝并留痕 | +| 画像 | L1/L2/L3 只读，且优先聚合输出 | +| 审计 | 每次 NL→SQL→结果 全链路归档 | + +### 4.5 一期验收红线（P0） + +- 人话问客户/产品/预警三类数，返回解读 + SQL 留痕 +- **不能**出现：改数、关预警、当投顾用、无免责的对外型报告 + +### 4.6 关联场景 + +D-01 ~ D-05 + +--- + +## 5. 风控监测 Agent + +**服务对象**：风控专员（配套：合规官） +**角色定位**：**监测 → 预警 → 通知 → 记录**；不是自动执法系统 + +### 5.1 能力边界总则 + +| 可以做 | 不可以做 | +| --- | --- | +| 实时/准实时监测交易事件 | 自动冻结账户 | +| 规则匹配与风险评分（0–100，仅供参考） | 自动拦截**已发起/已发生**的交易 | +| 生成预警单（状态：**待人工审核**） | 自动标记为「确认可疑」 | +| 推送脱敏通知给风控专员 | 自动调整客户**正式**风险等级 | +| 关联查询客户历史交易与画像 | 代替客户重新测评 | +| 交易**请求前**适当性校验并阻断不匹配请求（**唯一阻断场景**） | 限制客户交易次数或金额上限 | +| 向客户发送适当性提示（仅提示，不阻止已放行操作） | 代替客户执行任何交易 | +| 标记客户监测状态标签（L3） | 自动上报监管（须人工复核后操作） | +| 记录完整审计日志 | 删除或修改审计日志 | +| 生成收益承诺或投资建议 | — | + +### 5.2 分场景约束 + +| 场景 | 触发 | 可以做 | 不可以做 | 预警/阻断 | +| --- | --- | --- | --- | --- | +| R-01 大额交易 | 单笔/日累计 ≥50 万等 | 实时监测、评分、预警单、通知 | 冻户、拦已发生交易、自动确认可疑 | 预警，不阻断 | +| R-02 适当性不匹配 | C1/C2 买 R4/R5；年龄≥70 与高风险等 | 交易前校验；**阻断请求**；记录预警 | 改风险等级；代替重测 | **可阻断请求** | +| R-03 AML 名单 | 开户/变更/大额交易/日批 | 名单比对；最高级预警；紧急通知 | 自动冻户；自动上报监管 | 预警，不自动冻户 | +| R-04 频繁/试探交易 | 单日多次操作；先小后大 | 频率统计、模式识别、预警；可选客户提示 | 限制次数；自动下调风险等级 | 预警为主 | +| R-05 风险评分 | 定时/事件触发 | 评分、分层（正常/关注/高风险）、报告 | 评分自动改正式等级；限制交易 | 报告与提醒 | + +### 5.3 输出合规要求 + +| 输出类型 | 合规要求 | +| --- | --- | +| 预警单 | 含 trace_id、规则编号、脱敏客户信息；状态默认 `pending_review` | +| 阻断响应（R-02） | 明确不匹配原因；引导联系投顾；**记录请求与响应** | +| 风险评分 | 标注「仅供参考，不自动决策」 | +| 客户适当性提示 | 仅成本/频率类关怀提示，不含买卖建议 | +| API 响应 | 含固定 disclaimer：「本预警由系统自动生成，最终判定需经风控专员人工审核」 | + +### 5.4 审计留痕（强制字段） + +所有风控判定必须记录：`trace_id`、`timestamp`、`rule_id`、`customer_id`（脱敏）、`event_type`、`input_data`（脱敏）、`decision`、`risk_score`（如有）、`handler_id`、`handler_result`（人工介入后）、`handler_comment`（可选）。 + +### 5.5 数据与隐私约束 + +| 约束 | 说明 | +| --- | --- | +| 画像使用 | 可读 L0+L1+L2 辅助 R-02/R-05；只写 L3，不改 L0 | +| 通知 | 推送内容脱敏；AML 命中多渠道通知合规官 | +| 预警处置 | 状态变更只能由风控专员人工完成 | +| 数据分析 | 预警台账可被 D-03 只读统计，Agent 不得代为处置 | + +### 5.6 一期验收红线（P0） + +- 大额预警单、适当性拒单、名单命中通知均可演示 +- 全部预警待人工审核 +- **不能**出现：自动冻户、自动上报、自动改正式风险等级 + +### 5.7 关联场景 + +R-01 ~ R-05 + +--- + +## 6. 跨 Agent 合规对照表 + +| 合规维度 | 客户财富 | 代理人助手 | 数据分析 | 风控监测 | +| --- | --- | --- | --- | --- | +| 面向 C 端输出 | **是**（本人） | **否**（严禁直发） | **否**（内部） | **间接**（适当性提示/拒单文案） | +| 投资建议 / 收益预测 | **禁止** | **禁止** | **禁止** | **禁止** | +| 产品推荐 | **禁止**（仅匹配说明） | **禁止** | **禁止** | **禁止** | +| 修改核心业务数据 | **禁止** | **禁止** | **禁止** | **禁止** | +| 阻断交易/请求 | **禁止** | **禁止** | **禁止** | **仅 R-02 可阻断请求** | +| 冻结账户 | **禁止** | **禁止** | **禁止** | **禁止**（人工冻户） | +| 改正式风险等级 | **禁止** | **禁止** | **禁止** | **禁止** | +| 处置预警 | **禁止** | **禁止** | **禁止** | **禁止**（人工处置） | +| 自动外发消息 | 提醒通道（事实提醒） | **禁止** | **禁止** | 通知风控/合规（脱敏） | +| 人工复核门禁 | 无（客户自用） | **话术/档案必须** | 无 | 预警/AML **必须** | +| 审计留痕 | **必须** | **必须** | **必须** | **必须** | +| 用户画像写入 | L1 | L2 | **禁止写** | L3 | + +--- + +## 7. 违规话术与高风险内容（代理人 + 客户侧宜共用词库） + +以下表述在 **客户财富、代理人助手** 输出中 **一律禁止**（代理人侧 A-07 须自动识别）： + +| 类别 | 禁止示例 | +| --- | --- | +| 收益承诺 | 「保证收益」「稳赚不赔」「预期 XX% 回报」 | +| 保本暗示 | 「零风险」「本金无忧」「绝对安全」 | +| 买卖指导 | 「建议现在买入/卖出」「赶紧加仓/止损」 | +| 产品推荐 | 「这只更好」「强烈推荐 XX 基金」 | +| 预测 | 「明天必涨」「肯定反弹」 | +| 替代决策 | 「我已帮您下单」「系统已为您调仓」 | +| 超范围承诺 | 「一定帮您办下来」「Tax 可节税 XX%」 | + +**客户财富** 特殊允许：陈述可选动作清单时须用**中性表述**（如「可选操作包括加仓或撤出，由您自行决定」），不得替客户做选择。 + +--- + +## 8. 合规验收检查清单（按 Agent） + +### 客户财富 Agent + +- [ ] 输出不含买卖指导、收益承诺、产品推荐 +- [ ] 产品/规则内容可溯源官方材料 +- [ ] 复盘/报告含免责声明 +- [ ] 不能访问他人账户 +- [ ] 不能自动下单或调仓 +- [ ] L1 画像不覆盖 L0 正式风险等级 + +### 代理人助手 Agent + +- [ ] 不能向 C 端自动推送任何内容 +- [ ] 话术草稿含风险提示且标记需人工复核 +- [ ] 不能查非归属客户 +- [ ] 产品回答可溯源，无推荐对比 +- [ ] 全量会话可审计 +- [ ] 高风险话术被标记或拦截 + +### 数据分析 Agent + +- [ ] 仅执行只读 SQL +- [ ] 不能修改业务数据或画像 +- [ ] 不能处置或关闭预警 +- [ ] 对外型输出含免责声明 +- [ ] SQL 与对话全留痕 +- [ ] 超权限访问被拒绝 + +### 风控监测 Agent + +- [ ] 预警单默认待人工审核 +- [ ] 除 R-02 外不阻断交易 +- [ ] 不自动冻户、不自动上报监管 +- [ ] 不自动修改正式风险等级 +- [ ] 阻断/预警/通知均可审计追溯 +- [ ] 推送内容脱敏 + +--- + +## 9. 与需求文档的索引 + +| 本文档章节 | 关联文档 | +| --- | --- | +| 全局约束 G-01~G-08 | `业务场景优先级清单` §3.1 F-01~F-04 | +| 客户财富 §2 | `业务场景优先级清单` §3.2 C-01~C-18 | +| 代理人助手 §3 | 用户故事 `02-代理人.docx` 前置统一约束 + A-01~A-09 | +| 数据分析 §4 | 用户故事 `03-数据分析师.docx` 硬规矩 + D-01~D-05 | +| 风控监测 §5 | 用户故事 `04-风控师.docx` 能力边界 + R-01~R-05 | +| 画像与权限 | `数据交互矩阵` §2、§8、§9 | diff --git a/docs/需求拆解/业务场景优先级清单.md b/docs/需求拆解/业务场景优先级清单.md new file mode 100644 index 0000000..858cd87 --- /dev/null +++ b/docs/需求拆解/业务场景优先级清单.md @@ -0,0 +1,168 @@ +# 业务场景优先级清单 + +> 需求拆解阶段产物 · 2026-09-05 +> 依据：`docs/需求拆解/用户故事` 中四类人群故事，以及《基础信息与数据监控模块》17 条结构化场景 +> 定位：四个 Agent 分别服务四类人群，本清单只收「业务场景」，并给出实现优先级 + +--- + +## 1. 四个 Agent 与服务对象 + +| Agent | 服务对象 | 核心痛点（一句话） | 角色边界 | +| --- | --- | --- | --- | +| 客户财富 Agent | C 端客户 | 看不清持仓、看不懂产品、亏了不知道怎么办 | 只做事实查询、规则解读、阈值提醒；不承诺收益、不自动下单 | +| 代理人助手 Agent | 一线理财代理人（配套：合规、运营） | 多系统翻页慢、怕讲错规则、话术易违规 | 内部辅助；不对 C 端直发；严禁投资建议与收益预测 | +| 数据分析 Agent | 内部数据分析师 / 业务同事 | 不会写 SQL、不想翻报表，但天天要问数 | 只统计、只解读，不处置、不改数 | +| 风控监测 Agent | 风控专员（配套：合规官） | 大额/异常/适当性/名单风险感知滞后 | 监测 → 预警 → 通知 → 记录；禁止自动冻结账户 | + +说明：代理人故事里的「合规专员 / 运营」不单开第五个 Agent，作为代理人助手的配套工作台能力落地。 + +--- + +## 2. 优先级原则 + +按「四类人群是否立刻痛」「四个 Agent 能否独立闭环」「合规能否上线」「是否依赖重型交易基础设施」四维打分。 + +| 优先级 | 含义 | 收口标准 | +| --- | --- | --- | +| P0 一期必做 | 没有它，对应 Agent 不能上线 | 该人群最痛 + Agent 可对话闭环 + 合规底座齐备 | +| P1 二期增强 | 有了更好用，但不阻塞首发 | 依赖 P0 的持仓/知识库/审计已经跑通 | +| P2 三期增值 | 高净值或运营深化 | 合规面更大，或模型/数据成熟度要求更高 | +| P3 暂缓 | 更像完整财富平台，不是四个 Agent 主线 | 毫秒行情终端、自动交易、家庭全景、跨境、社区等 | + +**排期建议（实现顺序，不是人数顺序）：** + +1. **第 0 波 · 共用底座**：鉴权隔离、审计留痕、输入防护、只读数据层 +2. **第 1 波 · 内部闭环**：数据分析 Agent P0 + 代理人助手 P0（不对 C 端给建议，验收快） +3. **第 2 波 · 监测闭环**：风控监测 Agent P0（依赖交易事件流与适当性校验） +4. **第 3 波 · C 端事实助手**：客户财富 Agent P0（只查事实、只提醒，严禁推荐买卖） +5. **第 4 波**：全部 P1 +6. **第 5 波**：全部 P2 +7. **暂缓**：全部 P3 + +--- + +## 3. 业务场景总表 + +列说明： + +- **场景 ID**：稳定编号，后续 PRD / 测试用例沿用 +- **对应 Agent**：主责 Agent；底座行标为「共用」 +- **Agent 做什么 / 明确不做**：能力边界，评审时按此验收 +- **来源**：回溯用户故事原文 + +### 3.1 共用底座（四个 Agent 的上线前提） + +| 场景 ID | 业务场景 | 服务对象 | 对应 Agent | 痛点 | Agent / 系统做什么 | 明确不做 | 优先级 | 关键依赖 | 来源 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| F-01 | 身份鉴权与数据归属隔离 | 全部内部角色 + 客户本人 | 共用 | 越权看到别人的客户或会话 | JWT + RBAC + 数据层归属校验；代理人只看自己名下客户 | 跨权限查询、会话互看 | P0 | 现有公募 RBAC | 代理人故事 10 | +| F-02 | 会话 / Tool / SQL / 判定全量审计 | 合规、系统负责人 | 共用 | 出事后无法追溯「谁问了什么、系统依据什么」 | 每次对话、工具调用、SQL、风控判定强制落库且不可删 | 隐藏、篡改、省略记录 | P0 | 统一审计服务 | 代理人 11；分析师硬规矩；风控通用规范 | +| F-03 | 输入清洗与 Prompt 注入防护 | 系统负责人 | 共用 | 恶意指令诱导 Agent 越权或改行为 | 高危 Prompt、超长非法参数拦截 | 信任原始用户输入直接拼进工具 | P0 | 统一输入清洗 | 代理人故事 12 | +| F-04 | 只读业务数据访问 | 四个 Agent | 共用 | Agent 误写核心账务 / 交易 | 统一只读查询层；Agent 只查不写 | 改持仓、改风险等级、改交易状态 | P0 | 客户/交易/产品只读接口 | 代理人总结；分析师硬规矩 | + +### 3.2 客户财富 Agent + +| 场景 ID | 业务场景 | 服务对象 | 对应 Agent | 痛点 | Agent 做什么 | 明确不做 | 优先级 | 关键依赖 | 来源 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| C-01 | 持仓、资金进出与资产分布问答 | 客户 | 客户财富 | 不知道钱在哪、进出不清、比例看不懂 | 用对话汇总转入转出、持仓分布、仓位现状（事实） | 不执行转换/下单；不评价仓位好坏 | P0 | 资金流水、持仓接口 | 客户 3；模块一 | +| C-02 | 基金产品事实介绍 | 客户 | 客户财富 | 不知道基金买的什么、近况怎样 | 重仓方向、近 1/3/12 月业绩、费率与申赎规则，必须溯源官方材料 | 不对比优劣、不暗示收益、不推荐买卖 | P0 | 产品知识库 / 行情业绩 | 客户 2；模块二 | +| C-03 | 股票/产品交易规则解读 | 客户 | 客户财富 | 不懂 T+1、涨跌幅等规则，怕操作违规 | 按产品输出官方交易规则与限制 | 不给走势买卖点；不替代下单 | P0 | 产品/交易规则库 | 客户 4；模块一 | +| C-04 | 持仓亏损阈值提醒 | 客户 | 客户财富 | 本金跌过心理线却没人提醒 | 达到用户自设阈值（如 -10% / -20%）时提醒，只陈述跌幅与可选动作清单（加仓/撤出由客户自己决定） | 不自动加仓或撤单；不说「应该买/卖」 | P0 | 持仓盈亏、提醒通道 | 客户 5；模块四 | +| C-05 | 行情与持仓相关问答 | 客户 | 客户财富 | 想随时知道自己标的现在怎样 | 基于已有行情/净值接口回答「这只现在什么价/净值、今日涨跌」 | 不做毫秒级盘口终端；不保证实盘交易时延 | P0 | 行情/净值接口（可用延迟行情） | 客户 1 | +| C-06 | 基金经理履历与任职回报 | 客户 | 客户财富 | 不知道管理人过往水平 | 整理任职基金、收益率、回撤等公开事实 | 不给「该不该买这只基金」结论 | P1 | 基金经理公开数据 | 客户 8；模块二 | +| C-07 | 投资风格测评与同类标的匹配 | 客户 | 客户财富 | 不知道自己是哪类投资者 | 问卷 + 行为标签出风格；只匹配「同类风格常见关注方向」的事实清单 | 不输出具体买卖指导；需适当性校验 | P1 | 测评、适当性、风控 R-02 | 客户 9；模块三 | +| C-08 | 资金比例规划与偏离提醒 | 客户 | 客户财富 | 加仓无计划、超配了自己不知道 | 按客户已确认的规划比例做偏离提醒 | 不自动调仓；超配只提醒不阻断（阻断归风控适当性） | P1 | 客户规划、持仓 | 客户 10；模块三 | +| C-09 | 投后复盘与盈亏归因 | 客户 | 客户财富 | 不知道钱怎么赚/亏的 | 按日/周/月生成行业、个股、择时等归因复盘（事实） | 对外报告须免责声明；不承诺未来收益 | P1 | 成交、持仓、行业分类 | 客户「投后复盘」；模块四 | +| C-10 | 市场波动 / 持仓利空提醒 | 客户 | 客户财富 | 极端行情或政策变化反应慢 | 持仓相关风险事件推送，只陈述事件与持仓关联事实 | 不给应对买卖建议 | P1 | 资讯、持仓映射 | 客户 7；模块二 | +| C-11 | 理财产品匹配说明 | 客户 | 客户财富 | 产品太多，不知道哪类和自己条件相符 | 按风险等级、期限、起购金额做「条件是否匹配」说明 | 不做千人千面营销话术；不替代投顾推荐 | P2 | 产品库、适当性 | 客户 6；模块二 | +| C-12 | 税务与合规成本提醒 | 高净值 / 特定产品客户 | 客户财富 | 税费、分红税、养老金抵扣是隐性成本 | 计算已发生或规则内的税费提示 | 不做税务筹划承诺；不替代会计师 | P2 | 税务规则库 | 客户「税务」；模块五 | +| C-13 | 宏观资讯与持仓传导解读 | 客户 | 客户财富 | 资讯噪音大，不知道和自己仓位有没有关系 | 过滤与持仓相关的政策/事件，说明可能影响的标的（事实） | 不给结构化「应对建议」中的买卖指令 | P2 | 资讯、持仓 | 模块四 | +| C-14 | 毫秒级全市场看盘终端 | 客户 | 非 Agent 主线 | 想要专业交易软件级盘口 | — | 一期不做独立看盘终端 | P3 | 行情中台 | 模块一「实时看盘」 | +| C-15 | 智能条件单与自动交易 | 客户 | 非 Agent 主线 | 想 7×24 自动网格/止盈止损 | — | Agent 禁止自动下单 | P3 | 交易执行引擎 | 模块四 | +| C-16 | 家庭全景资产 / 心愿账户 | 客户家庭 | 非 Agent 主线 | 跨平台资产看不全 | — | 超出四个 Agent 一期范围 | P3 | 多账户聚合 | 模块五 | +| C-17 | 社区情绪与观点碰撞 | 客户 | 非 Agent 主线 | 信息茧房 | — | 不做社区产品 | P3 | 舆情 | 模块五 | +| C-18 | 跨境与全球资产配置通道 | 客户 | 非 Agent 主线 | 单一市场风险 | — | 不做跨境开户/交易通道 | P3 | 跨境牌照与通道 | 模块五 | + +### 3.3 代理人助手 Agent + +| 场景 ID | 业务场景 | 服务对象 | 对应 Agent | 痛点 | Agent 做什么 | 明确不做 | 优先级 | 关键依赖 | 来源 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| A-01 | 客户持仓与风险情况梳理 | 理财代理人 | 代理人助手 | 多后台手工统计，沟通前准备慢 | 按客户姓名/ID 汇总公募持仓、类型分布、风险等级、持有期限、盈亏概况（纯事实） | 不评价持仓、不建议加减仓、不预测收益、不查非本人客户 | P0 | 持仓 Tool、风险测评、F-01 | 代理人故事 1 | +| A-02 | 基金产品规则合规答疑 | 理财代理人 | 代理人助手 | 记错费率/封闭期/适配人群会违规宣讲 | RAG/Skill 按官方手册答费率、申赎、封闭期、风险等级、适配人群 | 不对比基金优劣、不推荐产品、不超文档解读 | P0 | 产品知识库，必须可溯源 | 代理人故事 2 | +| A-03 | 客户沟通合规话术草稿 | 理财代理人 | 代理人助手 | 自己写话术费时且易踩收益承诺 | 结合持仓事实 + 合规规范生成草稿，带标准风险提示 | 草稿不含投资建议/保本/收益承诺；禁止自动发给客户 | P0 | 客户信息、话术规范、人工复核 | 代理人故事 3 | +| A-04 | 公募业务流程与办理规则查询 | 理财代理人 | 代理人助手 | 定投/转换/赎回到账规则记不清，客户投诉 | 输出标准化流程、前置条件、禁忌场景 | 不承诺办理结果、不绕过官方流程 | P0 | 内部业务制度库 | 代理人故事 4 | +| A-05 | Agent 问答合规巡检 | 合规专员 | 代理人助手（审计台） | 无法检查越权查询和违规话术 | 检索会话、Tool 调用、LLM 输出；账号行为统计 | 不得隐藏任何记录 | P0 | F-02，合规专属 RBAC | 代理人故事 6 | +| A-06 | 客户跟进记录整理 | 理财代理人 | 代理人助手 | 沟通内容散乱，归档费时 | 提炼诉求、要点、待办，生成规范日志草稿 | 禁止自动写入正式档案 | P1 | 客户档案规范 | 代理人故事 5 | +| A-07 | 违规话术识别与拦截提示 | 合规专员 | 代理人助手 | 收益预测/保本/推荐暗示难以及时发现 | 按合规词库标记风险会话，高风险强制告警 | 禁止私自放行高风险内容 | P1 | 合规词库、F-02 | 代理人故事 7 | +| A-08 | 高频咨询问题汇总 | 运营人员 | 代理人助手 | 培训和 FAQ 不知道该补什么 | 会话热点聚类、失败咨询 TOP；仅聚合统计 | 不导出具体客户隐私 | P1 | 会话日志（脱敏） | 代理人故事 8 | +| A-09 | 知识库更新后的问答校验 | 产品运营 | 代理人助手 | 规则更新后 Agent 仍答旧条款 | 用最新 Skill/知识库做对齐抽检 | 输出过期规则 | P1 | 知识库版本管理 | 代理人故事 9 | + +### 3.4 数据分析 Agent + +| 场景 ID | 业务场景 | 服务对象 | 对应 Agent | 痛点 | Agent 做什么 | 明确不做 | 优先级 | 关键依赖 | 来源 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| D-01 | 客户侧查数（持仓 / 流水 / 规模 / 风险等级分布） | 内部员工 | 数据分析 | 不会写 SQL，又要立刻知道客户现状 | 大白话 → 只读 SQL → 人话解读 | 不改数据；不给客户出投顾报告（若偏客户报告必须免责声明） | P0 | 客户/持仓/流水只读库、F-02 | 分析师「查客户」 | +| D-02 | 产品侧查数（收益、申购、持仓规模） | 内部员工 | 数据分析 | 多张报表来回翻，问「这类产品卖得怎样」很慢 | 单只/某类产品的销售与规模事实查询 | 不做产品推荐（推荐归投顾/客户 Agent 且受合规约束） | P0 | 产品销售汇总表 | 分析师「查产品」 | +| D-03 | 风险台账统计（预警未处理数量等） | 内部员工 | 数据分析 | 预警积压情况要找风控台账 | 统计预警数量、状态分布等 | 不处置预警（处置归风控专员） | P0 | 风控预警台账只读 | 分析师「查风险台账」 | +| D-04 | 查数过程留痕与输出边界 | 合规 / 分析师 | 数据分析 | 查数被误当成对外投顾结论 | 每次对话与 SQL 归档；对外风格输出强制免责声明 | 生成可执行的买卖/处置指令 | P0 | F-02 | 分析师硬规矩 | +| D-05 | 复杂交叉问数与报表解读 | 内部员工 | 数据分析 | 跨客户×产品×风险的组合问题一次问不清 | 在只读范围内做多表聚合解读 | 不发明未授权的宽表；超权限字段拒绝 | P1 | 数据权限目录、D-01~D-03 | 分析师扩展问法 | + +### 3.5 风控监测 Agent + +| 场景 ID | 业务场景 | 服务对象 | 对应 Agent | 痛点 | Agent 做什么 | 明确不做 | 优先级 | 关键依赖 | 来源 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| R-01 | 大额交易实时监测 | 风控专员 | 风控监测 | 大额资金流动感知慢，缺上下文 | 单笔/当日累计 ≥ 50 万预警；关联近 30 天交易与画像；预警单待人工审核 | 不冻结账户、不拦截已发生交易、不自动标「确认可疑」 | P0 | 交易事件流、画像、规则引擎 | 风控场景一 | +| R-02 | 客户身份与交易适当性不匹配 | 风控专员 + 交易前校验 | 风控监测 | C 低风险买高风险产品、老年/职业冲突难以及时拦住 | 交易前校验；C1/C2 买 R4/R5、年龄≥70 与高风险等硬规则可拒绝请求进入交易流程 | 不改客户风险等级、不代替客户重测 | P0 | 适当性服务、交易前钩子 | 风控场景三 | +| R-03 | 反洗钱（AML）名单监测 | 风控专员 + 合规官 | 风控监测 | 开户/大额交易可能命中制裁、恐怖分子、PEP 名单 | 开户、信息变更、大额交易时比对名单；命中最高级预警并多渠道通知 | 不自动冻结、不自动上报监管 | P0 | AML 名单服务、开户/变更事件 | 风控场景四 | +| R-04 | 频繁交易 / 试探后大额监测 | 风控专员 | 风控监测 | 洗单、倒仓、小额试探后大额不易发现 | 频率与模式识别；「先小后大」按 P0 规则升舱；可向客户发适当性提示 | 不限制交易次数、不自动下调风险等级 | P1 | 交易事件、模式库 | 风控场景二 | +| R-05 | 客户风险评分与持续监测 | 风控专员 | 风控监测 | 高风险客户缺少动态分层和定期复核 | 定时/事件触发评分，分层为正常/关注/高风险，出监测报告 | 评分不自动改正式风险等级、不限制交易 | P2 | 批量客户与交易数据 | 风控场景五 | + +补充触发（并入上表，不单开场景）：短时多笔接近阈值（5 分钟 ≥ 3 笔且每笔 ≥ 40 万）随 R-01 做 P1 准实时；每日全量名单扫描随 R-03 做 P1 定时任务。 + +--- + +## 4. 按 Agent 的一期范围（P0 验收包） + +| Agent | 一期必须能演示的闭环 | 一期明确砍掉 | +| --- | --- | --- | +| 共用底座 | 登录后越权被拒；任意一次问答可在审计里还原 | 无 | +| 客户财富 | 「我的持仓/资金分布」；「这只基金规则和近期业绩」；「跌过阈值提醒我」；「现在净值/价格多少」 | 自动交易、家庭账户、跨境、社区、专业看盘终端、营销式推荐 | +| 代理人助手 | 输入客户 ID 出事实画像；问产品规则可溯源；出合规话术草稿且不外发；合规能抽检会话 | 自动写档案、自动发客户、产品对比推荐 | +| 数据分析 | 人话问客户/产品/预警三类数，返回解读 + SQL 留痕 | 改数、处置预警、当投顾用 | +| 风控监测 | 大额预警单、适当性不匹配拒单、名单命中紧急通知，全部待人工 | 自动冻户、自动上报、自动改风险等级 | + +--- + +## 5. 跨 Agent 依赖（避免重复造能力） + +```text +共用底座（F-01~F-04） + │ + ├── 数据分析 Agent ──只读查数──► 代理人 / 风控 / 客户 的事实口径 + ├── 代理人助手 ──产品知识库──► 客户财富（规则解读共用，输出话术不同） + ├── 风控监测 ──适当性结果──► 客户 C-07 / 交易前 R-02 + └── 客户财富 ──持仓阈值事件──► 可复用风控规则引擎，但提醒文案面向客户且禁止买卖指令 +``` + +口径约定：同一客户的持仓、盈亏、风险等级，四个 Agent 读同一只读数据源，禁止各 Agent 各算一套。 + +--- + +## 6. 统计 + +| 优先级 | 场景数 | 构成 | +| --- | --- | --- | +| P0 | 18 | 底座 4 + 客户 5 + 代理人 5 + 分析 4 + 风控 3 | +| P1 | 10 | 客户 5 + 代理人 4 + 分析 1 + 风控 1（含并入的准实时规则） | +| P2 | 4 | 客户 3 + 风控 1 | +| P3 暂缓 | 5 | 客户侧平台能力，不进四个 Agent 排期 | +| **合计** | **37** | 其中 Agent 主线 32，平台暂缓 5 | + +--- + +## 7. 待评审的拍板项 + +1. 客户侧「推荐」类需求（C-07 / C-11）是否坚持 **只做匹配说明、不做推荐话术**（推荐与代理人 Agent 的禁止项对齐）。 +2. 风控 R-02 是四个 Agent 里 **唯一允许阻断请求** 的场景，需产品/交易确认交易前钩子是否已有。 +3. 客户 C-05 一期用 **延迟行情/净值** 还是必须接实盘毫秒行情（后者会把 C-14 从暂缓拉回，工期显著变长）。 +4. 是否接受「先内部三个 Agent，再开放 C 端客户 Agent」的波次，以降低首发合规面。 diff --git a/docs/需求拆解/数据交互矩阵.md b/docs/需求拆解/数据交互矩阵.md new file mode 100644 index 0000000..d4b4744 --- /dev/null +++ b/docs/需求拆解/数据交互矩阵.md @@ -0,0 +1,240 @@ +# 四个 Agent 数据交互矩阵 + +> 需求拆解阶段产物 · 2026-09-05（v2 修正：用户画像采集与共享） +> 依据：`docs/需求拆解/业务场景优先级清单.md` 与四类用户故事 +> 说明：本表描述 **谁产生/采集哪些数据、谁消费这些数据**；外部业务系统单独列出，不当作 Agent。 + +--- + +## 1. 图例 + +| 符号 | 含义 | +| --- | --- | +| **采集** | 该 Agent 在运行过程中**写入/落库/产出**的数据（含用户输入、对话提炼、问卷结果） | +| **使用** | 该 Agent **读取**的数据，来源可以是外部系统、统一画像库或其他 Agent 产出 | +| **只读** | 只查不改 | +| **读写** | 可创建/更新 | +| **—** | 无直接关系 | + +**原则** + +- 四个 Agent **不直接互调 LLM**；跨 Agent 数据通过 **统一数据层（含用户画像库）+ 各 Agent 产出表/事件流** 交换。 +- **用户画像**由 **客户财富 Agent、代理人助手 Agent** 在前台交互中持续采集与丰富，写入 **统一用户画像库**，供代理人、风控、数据分析及客户本人读取。 +- 核心系统的 **正式风险测评等级（C1~C5）** 仍是权威来源；Agent 采集的是 **偏好、风格、诉求、规划** 等画像 enrich 层，**不替代**正式测评，但可辅助适当性与服务。 +- 客户持仓、盈亏等**事实口径**来自核心业务系统，禁止各 Agent 各算一套。 + +--- + +## 2. 用户画像：谁采集、谁使用（核心修正） + +### 2.1 画像分层 + +| 层级 | 来源 | 谁写入 | 谁读取 | 说明 | +| --- | --- | --- | --- | --- | +| **L0 基础画像** | 核心业务系统 | 非 Agent（开户/测评系统） | 四 Agent 只读 | 姓名、年龄、职业、正式风险等级 C1~C5、资产规模 | +| **L1 客户侧 enrich** | 客户财富 Agent 交互 | **客户财富 Agent** | 客户本人；代理人；风控；数据分析 | 风格测评、资金规划、阈值偏好、对话行为标签 | +| **L2 服务侧 enrich** | 代理人助手 Agent 交互 | **代理人助手 Agent** | 代理人；风控；数据分析 | 沟通诉求、跟进要点、代理人侧资产概况快照、服务标签 | +| **L3 监测 enrich** | 风控监测 Agent | **风控监测 Agent** | 风控；数据分析；代理人（只读） | 监测分层、预警关联标签（不改 L0 正式风险等级） | + +### 2.2 用户画像字段明细（Agent 采集项） + +| 画像字段 | 采集方 Agent | 采集方式 | 使用方 | 关联场景 | 优先级 | +| --- | --- | --- | --- | --- | --- | +| 投资风格标签（价值/成长/趋势等） | **客户财富** | 问卷 + 行为分析 | 客户财富；**代理人**；**风控**；**数据分析** | C-07 | P1 | +| 资金比例规划（股债比、加仓比例等） | **客户财富** | 客户确认的规划方案 | 客户财富；**代理人**；**风控** | C-08 | P1 | +| 亏损阈值与提醒偏好 | **客户财富** | 客户自设配置 | 客户财富；**风控**（规则参考） | C-04 | P0 | +| 对话行为标签（关注行业、产品偏好等） | **客户财富** | 会话提炼（非投资建议） | **代理人**；**数据分析** | C-01~C-02 等 | P1 | +| 投后复盘偏好与归因摘要 | **客户财富** | 定期复盘产出 | 客户本人；**代理人** | C-09 | P1 | +| 客户资产概况快照（结构化） | **代理人助手** | A-01 查数后结构化缓存 | **代理人**；**数据分析** | A-01 | P0 | +| 沟通诉求、关注点、待办 | **代理人助手** | A-06 跟进整理 / A-03 上下文 | **代理人**；**风控**（服务适当性参考） | A-03、A-06 | P0/P1 | +| 服务侧标签（如「关注赎回」「咨询转换」） | **代理人助手** | 会话与跟进提炼 | **代理人**；**数据分析** | A-01、A-06 | P1 | +| 监测分层（正常/关注/高风险） | **风控监测** | R-05 评分 / 预警关联 | **风控**；**数据分析**；代理人（只读） | R-05 | P2 | +| 适当性校验历史摘要 | **风控监测** | R-02 每次校验 | **客户财富**；**代理人**；交易系统 | R-02 | P0 | + +--- + +## 3. Agent × Agent 总览矩阵（含用户画像） + +行 = **数据采集方（产出方）**；列 = **数据使用方（消费方）**。 +**粗体** = 用户画像相关流向。 + +| 采集 ↓ \ 使用 → | 客户财富 | 代理人助手 | 数据分析 | 风控监测 | 共用底座 | +| --- | --- | --- | --- | --- | --- | +| **客户财富** | 自身画像读写 | **L1 用户画像**（风格/规划/偏好） | **L1 用户画像**（统计/解读） | **L1 用户画像**（适当性辅助） | 会话/Tool 审计 | +| **代理人助手** | — | 自身 + **L2 服务画像** | **L2 服务画像**（诉求/标签统计） | **L2 服务画像**（服务适当性参考） | 会话/Tool/草稿审计 | +| **数据分析** | — | — | — | — | SQL/查数审计 | +| **风控监测** | 适当性结果、**L3 监测标签** | **L3 监测标签**（只读） | 预警台账 + **画像监测统计** | — | 判定/预警审计 | +| **共用底座** | 鉴权上下文 | 鉴权 + 合规巡检 | 鉴权 + SQL 留痕 | 鉴权 + 判定留痕 | — | + +> **修正说明**：上一版错误地将「代理人、数据分析不消费其他 Agent 产出」写死。按需求，**客户与代理人 Agent 是用户画像的主要采集方**，画像写入统一库后，**代理人、风控、数据分析** 均应能读取（在 RBAC 范围内）。 + +--- + +## 4. 数据对象明细矩阵（主表） + +| 数据对象 | 数据类型 | 采集方 | 使用方 | 读写 | 用途 | 优先级 | +| --- | --- | --- | --- | --- | --- | --- | +| **统一用户画像库（L1 客户 enrich）** | **画像** | **客户财富** | 客户财富；**代理人**；**风控**；**数据分析** | 写 / 只读 | 风格、规划、阈值、行为标签共享 | P0/P1 | +| **统一用户画像库（L2 服务 enrich）** | **画像** | **代理人助手** | 代理人；**风控**；**数据分析** | 写 / 只读 | 诉求、跟进、服务标签共享 | P0/P1 | +| 客户对话与会话上下文 | 会话 | 客户财富 | 客户财富；共用底座 | 读写 / 只读 | 多轮问答；画像提炼原料；审计 | P0 | +| 用户亏损阈值配置 | 客户配置 | 客户财富 | 客户财富；风控；**画像库** | 读写 / 只读 | C-04 提醒；风控规则参考 | P0 | +| 投资风格测评答卷与标签 | 客户配置 | 客户财富 | 客户财富；**代理人**；**风控**；**数据分析** | 读写 / 只读 | C-07；适当性辅助；人群统计 | P1 | +| 资金比例规划与偏离记录 | 客户配置 | 客户财富 | 客户财富；**代理人**；**风控** | 读写 / 只读 | C-08 偏离提醒；服务准备 | P1 | +| 对话行为标签（非投资建议） | 画像 | 客户财富 | **代理人**；**数据分析** | 写 / 只读 | 了解客户关注点 | P1 | +| 客户侧提醒推送记录 | 事件日志 | 客户财富 | 客户财富；共用底座 | 写 / 只读 | 阈值/波动提醒留痕 | P0/P1 | +| 客户资产概况快照 | 画像 | 代理人助手 | 代理人；**数据分析** | 写 / 只读 | A-01 沟通前快速画像 | P0 | +| 沟通诉求 / 跟进要点 / 待办 | 画像 | 代理人助手 | 代理人；**风控** | 写 / 只读 | A-03/A-06；服务侧风险参考 | P0/P1 | +| 服务侧标签 | 画像 | 代理人助手 | 代理人；**数据分析** | 写 / 只读 | 诉求分类、运营统计 | P1 | +| 代理人 Agent 会话与 Tool 调用 | 会话 | 代理人助手 | 代理人；共用底座 | 读写 / 只读 | 答疑、画像汇总；A-05 合规巡检 | P0 | +| 合规话术草稿 | 草稿 | 代理人助手 | 代理人（人工复核后外用） | 读写 | A-03，读取 **L1+L2 画像** 生成 | P0 | +| 客户跟进日志草稿 | 草稿 | 代理人助手 | 代理人（人工确认后归档） | 读写 | A-06；确认后回写 **L2 画像** | P1 | +| 违规话术标记与会话风险标签 | 合规事件 | 代理人助手 | 代理人；共用底座 | 写 / 只读 | A-07 | P1 | +| 高频咨询聚合统计（脱敏） | 聚合统计 | 代理人助手 | 运营人员 | 写 / 只读 | A-08 | P1 | +| 自然语言查数请求与解读结果 | 会话 | 数据分析 | 数据分析；内部员工 | 读写 | D-01~D-05；可问「某风格客户有多少」 | P0 | +| 只读 SQL 及执行留痕 | 审计 | 数据分析 | 数据分析；共用底座；合规 | 写 / 只读 | D-04 | P0 | +| 交易事件监测快照 | 事件 | 风控监测 | 风控监测 | 读写 | R-01/R-04 | P0 | +| 风控预警单 | 业务单据 | 风控监测 | 风控；**数据分析** | 写 / 只读 | D-03 台账统计 | P0 | +| 适当性校验与阻断结果 | 判定结果 | 风控监测 | 风控；客户财富；**代理人**；交易系统 | 写 / 只读 | R-02；C-07/C-11；代理人知悉客户边界 | P0 | +| 风险评分与监测分层（L3） | 画像 | 风控监测 | 风控；**数据分析**；代理人（只读） | 写 / 只读 | R-05；不改 L0 正式等级 | P2 | +| AML 名单命中记录 | 合规事件 | 风控监测 | 风控；合规官 | 写 / 只读 | R-03 | P0 | +| 全链路审计日志 | 审计 | 共用底座 | 四 Agent；合规 | 写 / 只读 | F-02 | P0 | +| 鉴权与数据归属上下文 | 安全上下文 | 共用底座 | 四 Agent | 只读 | F-01；代理人只看名下客户画像 | P0 | +| 输入清洗与拦截记录 | 安全事件 | 共用底座 | 共用底座；合规 | 写 / 只读 | F-03 | P0 | + +--- + +## 5. 外部系统 → Agent 数据流（非 Agent 采集） + +| 外部数据源 | 使用方 Agent | 读写 | 典型用途 | 优先级 | +| --- | --- | --- | --- | --- | +| **L0 基础画像**（正式风险等级、年龄、职业等） | 四 Agent | 只读 | 适当性硬约束、权限校验 | P0 | +| 持仓 / 资金流水 / 资产分布 | 四 Agent | 只读 | 事实查询；A-01 概况；R-01 上下文 | P0 | +| 交易记录 / 交易事件流 | 风控、分析、客户 | 只读 | 大额监测、复盘 | P0 | +| 产品知识库 / 交易规则库 | 客户、代理人 | 只读 | 规则解读 | P0 | +| 行情 / 净值 | 客户财富 | 只读 | C-05 | P0 | +| 适当性规则引擎 | 风控监测 | 只读 | R-02 校验逻辑 | P0 | +| AML 名单 | 风控监测 | 只读 | R-03 | P0 | +| 产品销售汇总表 | 数据分析 | 只读 | D-02 | P0 | +| 业务制度 / 合规话术规范 | 代理人助手 | 只读 | A-03/A-04 | P0 | + +--- + +## 6. 按 Agent 汇总：采集 vs 使用 + +### 6.1 客户财富 Agent + +| 方向 | 数据 | +| --- | --- | +| **采集（产出）** | **L1 用户画像**（风格、规划、阈值、行为标签）；会话；提醒记录 | +| **使用（外部 L0）** | 正式风险等级、持仓/流水/分布；产品库；行情 | +| **使用（其他 Agent）** | 风控 → 适当性结果、L3 监测标签 | +| **画像被谁用** | **代理人**（沟通准备）；**风控**（适当性辅助）；**数据分析**（人群统计） | + +### 6.2 代理人助手 Agent + +| 方向 | 数据 | +| --- | --- | +| **采集（产出）** | **L2 服务画像**（资产概况快照、诉求、跟进、服务标签）；话术/跟进草稿；合规事件 | +| **使用（外部 L0）** | 正式风险等级、持仓事实 | +| **使用（其他 Agent 画像）** | **客户财富 → L1 画像**（A-03 话术、沟通前了解客户） | +| **使用（风控）** | 适当性结果、L3 监测标签（只读，服务边界参考） | +| **画像被谁用** | **风控**（服务适当性）；**数据分析**（诉求/标签分布统计） | + +### 6.3 数据分析 Agent + +| 方向 | 数据 | +| --- | --- | +| **采集（产出）** | 查数请求；只读 SQL；解读；留痕 | +| **使用（外部）** | 持仓/流水/产品汇总 | +| **使用（画像）** | **L1 客户画像 + L2 服务画像 + L3 监测标签**（如「C4 客户有多少」「关注赎回标签分布」） | +| **使用（风控）** | 预警台账（D-03） | + +### 6.4 风控监测 Agent + +| 方向 | 数据 | +| --- | --- | +| **采集（产出）** | 预警单；适当性结果；**L3 监测标签**；AML 命中 | +| **使用（外部 L0）** | 正式风险等级、交易流、AML 名单 | +| **使用（画像）** | **L1 客户画像 + L2 服务画像**（R-02 辅助判断、R-05 评分维度） | +| **画像被谁用** | 客户财富、代理人（只读）；数据分析（统计） | + +--- + +## 7. 关键跨 Agent 链路（时序） + +### 7.1 用户画像：双端采集 → 统一库 → 多方使用 + +```text +客户对话 / 问卷 / 规划确认 + → 客户财富 Agent 采集 L1（风格、阈值、规划、行为标签） + → 写入【统一用户画像库】 + +代理人查客户 / 跟进整理 / 沟通记录 + → 代理人助手 Agent 采集 L2（概况快照、诉求、待办、服务标签） + → 写入【统一用户画像库】 + +【统一用户画像库】 + ├→ 代理人助手：A-03 话术草稿、沟通前准备（读 L1+L2） + ├→ 风控监测：R-02/R-05 适当性与评分辅助（读 L0+L1+L2，不改 L0） + ├→ 数据分析：人群分布、交叉统计（读 L1+L2+L3，只读） + └→ 客户财富：客户本人查看/更新 L1 +``` + +### 7.2 适当性：风控采集 → 客户 + 代理人使用 + +```text +交易/推荐请求 + 画像库（L0+L1） + → 风控监测（R-02）采集：校验结果、阻断原因 + → 客户财富：匹配说明（C-07/C-11） + → 代理人助手：知悉客户可购买边界（服务时不踩线） +``` + +### 7.3 预警台账：风控采集 → 分析使用 + +```text +交易事件流 → 风控采集预警单 → 数据分析（D-03）只读统计 → 风控专员人工处置 +``` + +### 7.4 合规审计 + +```text +四 Agent 会话/Tool/SQL/判定 → 共用底座审计 → 代理人合规台（A-05） +``` + +--- + +## 8. 画像读写权限（RBAC） + +| 角色 | L1 客户 enrich | L2 服务 enrich | L3 监测 enrich | +| --- | --- | --- | --- | +| 客户本人 | 读写（自己的） | 不可见 | 不可见 | +| 理财代理人 | 只读（名下客户） | 读写（名下客户） | 只读（名下客户） | +| 风控专员 | 只读 | 只读 | 读写 | +| 数据分析（内部） | 只读（脱敏/聚合） | 只读（脱敏/聚合） | 只读 | +| 合规 | 审计只读 | 审计只读 | 审计只读 | + +--- + +## 9. 禁止的数据流向 + +| 禁止项 | 原因 | +| --- | --- | +| Agent 画像层 **覆盖** L0 正式风险等级 | 正式 C1~C5 只能由测评系统或人工审核变更 | +| 数据分析 **修改** 画像库 | 只统计、只解读 | +| 代理人 **自动** 将 L2 画像或话术推送给客户 | A-03/A-06 须人工复核 | +| 风控 **自动** 冻户 / 改正式风险等级 | 仅写 L3 监测标签与预警 | +| 跨代理人读取他人客户画像 | F-01 数据归属 | +| 画像用于 **投资建议 / 收益承诺** | 合规边界 | + +--- + +## 10. 与业务场景的映射索引 + +| 数据对象 | 关联场景 ID | +| --- | --- | +| L1 用户画像 | C-04, C-07, C-08, C-09 → A-03, R-02, D-01/D-05 | +| L2 服务画像 | A-01, A-03, A-06 → R-02, D-01/D-05 | +| L3 监测画像 | R-05 → 代理人/分析只读 | +| 持仓/流水/分布 | C-01, A-01, D-01, R-01 | +| 预警单 | R-01~R-04, D-03 | +| 适当性结果 | R-02, C-07, C-11, A-03 | diff --git a/docs/需求拆解/用户故事/01-客户.docx b/docs/需求拆解/用户故事/01-客户.docx new file mode 100644 index 0000000..8950f16 Binary files /dev/null and b/docs/需求拆解/用户故事/01-客户.docx differ diff --git a/docs/需求拆解/用户故事/02-代理人.docx b/docs/需求拆解/用户故事/02-代理人.docx new file mode 100644 index 0000000..e0f7425 Binary files /dev/null and b/docs/需求拆解/用户故事/02-代理人.docx differ diff --git a/docs/需求拆解/用户故事/03-数据分析师.docx b/docs/需求拆解/用户故事/03-数据分析师.docx new file mode 100644 index 0000000..fdf3499 Binary files /dev/null and b/docs/需求拆解/用户故事/03-数据分析师.docx differ diff --git a/docs/需求拆解/用户故事/04-风控师.docx b/docs/需求拆解/用户故事/04-风控师.docx new file mode 100644 index 0000000..c29a047 Binary files /dev/null and b/docs/需求拆解/用户故事/04-风控师.docx differ diff --git a/docs/需求拆解/用户故事/【一、 基础信息与数据监控模块】.docx b/docs/需求拆解/用户故事/【一、 基础信息与数据监控模块】.docx new file mode 100644 index 0000000..e097419 Binary files /dev/null and b/docs/需求拆解/用户故事/【一、 基础信息与数据监控模块】.docx differ diff --git a/docs/项目框架设计/技术选型和版本/01-技术栈与版本.md b/docs/项目框架设计/技术选型和版本/01-技术栈与版本.md new file mode 100644 index 0000000..79bff6c --- /dev/null +++ b/docs/项目框架设计/技术选型和版本/01-技术栈与版本.md @@ -0,0 +1,129 @@ +# 技术栈与版本（已定） + +> 更新日期：2026-09-05 +> 环境：Windows 本机开发 · 内存 15.4 GB（可用约 3.7 GB） +> 原则：**日常开发走 Windows 原生安装**；Docker 仅作答辩/生产备选，不用于日常联调。 + +--- + +## 1. 组件一览 + +| 组件 | 版本 / 状态 | 备注 | +| --- | --- | --- | +| **后端** | Python 3.13.14 + FastAPI | 系统 Python；已装 `langchain` 1.3.18 / `langchain-openai` 1.6.0 / `pymilvus` 3.0.1 | +| **关系库** | MySQL 8.0.46 | 原生安装，端口 **3306** ✓ | +| **缓存** | Redis 8.10.1 | 原生安装，路径 `F:\Redis\...`，端口 **6379** ✓ | +| **图库** | Neo4j 5.26.19（Enterprise） | Neo4j Desktop 2，已建库 ✓ | +| **向量库** | Milvus Lite（本地文件模式） | 见 §3 踩坑说明；Collection 设计见 [03-milvus-collections.md](../项目框架设计/表设计/03-milvus-collections.md) | +| **前端** | React 19 + Vite 7 + TS strict + Ant Design 5 + HashRouter + Vitest | 沿用既有前端栈；**不用**需求文档中的 Streamlit | +| **LLM 生成** | DeepSeek API | 对话 / 推理走云端 API | +| **LLM 向量化** | Ollama + **bge-m3**，**1024 维** | 本地运行；文档向量不出内网 | +| **对象存储** | **不使用 MinIO** | 文档落本地目录；元数据进 MySQL（可选 P1 索引表） | +| **容器** | Docker 29.7.2 Client | Daemon **未启动**；仅答辩/生产备选，**非日常开发** | + +--- + +## 2. 部署方式：Windows 原生（已定） + +### 2.1 为何不用 Docker 做日常开发 + +| 项 | 说明 | +| --- | --- | +| **本机内存** | 总计 15.4 GB，可用约 **3.7 GB**（使用率 ~75%） | +| **Docker 开销** | Docker Desktop WSL2 VM ~**2 GB** + Milvus 三容器（etcd / minio / milvus）~**3.5 GB** ≈ **5.5 GB** | +| **原生套件占用** | MySQL + Redis + Neo4j + Milvus Lite ≈ **1.9 GB** | + +在现有内存下，**必须采用 Windows 原生部署**，否则 Milvus / Docker 与 IDE、浏览器、Neo4j 同时运行易 OOM。 + +### 2.2 日常开发启动顺序（建议） + +```text +1. MySQL 8.0.46 → :3306 +2. Redis 8.10.1 → :6379 +3. Neo4j Desktop → 默认 bolt :7687 +4. Ollama + bge-m3 → 本地 embedding +5. FastAPI 后端 → 连接上述服务 + Milvus Lite 文件 +6. Vite 前端 → dev server +``` + +### 2.3 生产 / 答辩备选 + +- 可使用 Docker Compose 拉起完整 Milvus Standalone（etcd + minio + milvus），**与开发环境 Milvus Lite 通过同一 pymilvus API 切换 URI**。 +- 对象存储生产环境可再评估 MinIO / OSS；当前阶段本地目录 + MySQL 元数据即可。 + +--- + +## 3. 连接与配置约定 + +| 服务 | 开发默认 | 环境变量示例 | +| --- | --- | --- | +| MySQL | `127.0.0.1:3306` | `MYSQL_HOST`, `MYSQL_PORT`, `MYSQL_DATABASE=jinrong_agent` | +| Redis | `127.0.0.1:6379` | `REDIS_URL=redis://127.0.0.1:6379/0` | +| Neo4j | Desktop 本地 | `NEO4J_URI=bolt://localhost:7687` | +| Milvus Lite | 项目内 `.milvus/` 或配置路径 | `MILVUS_URI=./data/milvus.db`（Lite 文件 URI 以 pymilvus 文档为准） | +| Ollama | `http://127.0.0.1:11434` | `OLLAMA_BASE_URL`, `EMBED_MODEL=bge-m3` | +| DeepSeek | HTTPS API | `DEEPSEEK_API_KEY`, `DEEPSEEK_BASE_URL` | + +Agent 业务库脚本：[01-mysql-共用底座.sql](../项目框架设计/表设计/01-mysql-共用底座.sql)、[02-mysql-agent专用.sql](../项目框架设计/表设计/02-mysql-agent专用.sql)。 + +--- + +## 4. 向量与 RAG 对齐 + +| 项 | 约定 | +| --- | --- | +| Embedding 模型 | Ollama `bge-m3` | +| 向量维度 | **1024**（Milvus Collection `FLOAT_VECTOR(dim=1024)` 必须一致） | +| Python 客户端 | `pymilvus` 3.0.1 | +| 开发向量库 | Milvus Lite 单文件，免 etcd/minio | +| 共用 Collection | `kb_product_rules`（客户 + 代理人）；`kb_business_ops`（代理人） | + +--- + +## 5. 踩坑说明 + +### 5.1 Milvus：Lite vs Standalone + +| 模式 | 适用 | 注意 | +| --- | --- | --- | +| **Milvus Lite**（当前） | 本机开发、内存受限 | 与 Standalone **数据不自动互通**；迁移需 re-embed + import | +| **Milvus Standalone**（Docker） | 答辩演示、生产 | 需额外 ~3.5 GB+ 内存；开发机日常不启 | + +代码层通过 `MILVUS_URI` / 连接模式开关切换，**Collection 字段与 1024 维不变**。 + +### 5.2 不用 MinIO + +- 原始 PDF/Word 存 **本地目录**（如 `data/kb/`）。 +- Milvus 存 chunk 文本或本地文件相对路径；`source_doc_id` / `source_version` 进 MySQL 或 Milvus 标量字段（见 Collection 设计）。 +- 后续若上云，再替换为 OSS 适配层，不改 Agent 业务接口。 + +### 5.3 前端栈与需求文档差异 + +- 需求/用户故事中可能出现的 Streamlit **不作为本项目前端**。 +- 统一：**React 19 + Vite 7 + Ant Design 5**，四 Agent 可共用组件库与 HashRouter 多入口。 + +### 5.4 LLM 分工 + +| 能力 | 选型 | 数据出境 | +| --- | --- | --- | +| 对话 / 推理 / Tool 编排 | DeepSeek API | 按 API 协议；敏感字段需脱敏 | +| 文档 Embedding | Ollama bge-m3 本地 | **不出内网** | + +--- + +## 6. 与项目其他文档的关系 + +| 文档 | 关系 | +| --- | --- | +| [02-JWT-RBAC鉴权手册.md](./02-JWT-RBAC鉴权手册.md) | 鉴权与网关（FastAPI 中间件 / SDK） | +| [05-多Agent共用底座清单.md](../项目框架设计/表设计/05-多Agent共用底座清单.md) | MySQL / Redis / Milvus / Neo4j 底座 | +| [03-milvus-collections.md](../项目框架设计/表设计/03-milvus-collections.md) | 向量 Collection 字段 | +| [业务场景优先级清单.md](../需求拆解/业务场景优先级清单.md) | 业务 P0 范围 | + +--- + +## 7. 版本变更记录 + +| 日期 | 变更 | +| --- | --- | +| 2026-09-05 | 初版：Windows 原生 + Milvus Lite + 不用 MinIO + React 前端栈 | diff --git a/docs/项目框架设计/技术选型和版本/02-JWT-RBAC鉴权手册.md b/docs/项目框架设计/技术选型和版本/02-JWT-RBAC鉴权手册.md new file mode 100644 index 0000000..7968ed1 --- /dev/null +++ b/docs/项目框架设计/技术选型和版本/02-JWT-RBAC鉴权手册.md @@ -0,0 +1,585 @@ +# 四 Agent 统一 JWT + RBAC 鉴权手册 + +> 需求拆解阶段产物 · 2026-09-05 +> 依据：`业务场景优先级清单` F-01、`数据交互矩阵` §8、`Agent风险与合规约束汇总` G-01 +> 适用范围：**客户财富 / 代理人助手 / 数据分析 / 风控监测** 四个 Agent 及共用底座 +> 目标：**一套身份源、一套 Token 规范、一套 RBAC 模型、一套数据归属校验**，禁止各 Agent 自建鉴权 + +--- + +## 1. 设计原则 + +| 编号 | 原则 | 说明 | +| --- | --- | --- | +| P-01 | **统一入口** | 所有 Agent HTTP/WebSocket/API 请求经 **Agent Gateway（或共用 Auth SDK）** 校验，业务服务不自行解析裸 JWT | +| P-02 | **身份与权限分离** | JWT 只携带 **身份（who）** 与 **角色（roles）**；**数据归属（which customer）** 在数据层二次校验 | +| P-03 | **最小权限** | 默认拒绝；显式授予 `permission` 才允许读/写/审计 | +| P-04 | **Agent 边界** | Token 绑定 `agent_type`；客户 Token **不能**调代理人 Agent；内部 Token **不能**冒充客户 | +| P-05 | **全量留痕** | 鉴权失败、越权尝试必须写 `audit_log` + `input_guard_log`（`illegal_param` / 自定义 `auth_denied`） | +| P-06 | **与 Core 对齐** | 员工角色、客户 ID、代理人-客户归属以 **Core RBAC + `customer_advisor_rel`** 为准，Agent 库不维护第二套账号体系 | + +--- + +## 2. 架构总览 + +```text +┌──────────────┐ ┌──────────────┐ ┌─────────────────────────────┐ +│ C 端 App │ │ 内部工作台 │ │ 交易前钩子 / 批处理 Job │ +│ (客户登录) │ │ (员工 SSO) │ │ (Service Account) │ +└──────┬───────┘ └──────┬───────┘ └──────────────┬──────────────┘ + │ │ │ + └────────────────────┴──────────────────────────────┘ + │ + ┌───────────▼───────────┐ + │ Identity Provider │ + │ (Core / 统一 IdP) │ + └───────────┬───────────┘ + │ 签发 JWT + ┌───────────▼───────────┐ + │ Agent Gateway │ + │ ① 验签 ② 过期 ③ RBAC │ + │ ④ 注入 AuthContext │ + └───────────┬───────────┘ + ┌─────────────────────┼─────────────────────┐ + │ │ │ + ┌──────▼──────┐ ┌───────▼───────┐ ┌───────▼───────┐ + │ 客户财富 │ │ 代理人助手 │ │ 数据分析 │ + │ Agent │ │ Agent │ │ Agent │ + └──────┬──────┘ └───────┬───────┘ └───────┬───────┘ + │ │ │ + └─────────────────────┼─────────────────────┘ + │ + ┌───────────▼───────────┐ + │ Data Access Layer │ + │ ⑤ 归属校验 │ + │ ⑥ 画像 L1/L2/L3 RBAC │ + └───────────────────────┘ +``` + +**两层校验（必须都做）** + +1. **网关层 RBAC**：角色是否允许访问该 Agent、该 API、该 Tool。 +2. **数据层归属**：操作的目标 `customer_id` / `session_id` 是否属于当前操作者（代理人名下、客户本人等）。 + +仅做第 1 层而不做第 2 层，视为 **F-01 未实现**。 + +--- + +## 3. 身份来源与 Token 类型 + +| Token 类型 | 签发方 | 使用者 | `sub` 含义 | 典型 `agent_type` 入口 | +| --- | --- | --- | --- | --- | +| `customer` | C 端登录 / Core 客户中心 | 客户本人 | `customer_id` | 仅 **客户财富 Agent** | +| `staff` | 内部 SSO / Core HR | 员工 | `staff_id` | 代理人 / 分析 / 风控 / 合规 | +| `service` | 平台密钥 + mTLS | 系统 Job、交易前钩子 | `service_name` | 风控 R-02 钩子、批处理 | + +> **禁止**：用 `staff` Token 访问客户 Agent 接口冒充客户；用 `customer` Token 访问内部 Agent。 + +--- + +## 4. JWT 规范（四 Agent 共用） + +### 4.1 Header + +```json +{ + "alg": "RS256", + "typ": "JWT", + "kid": "2026-09-key-1" +} +``` + +- 算法：**RS256**（公钥网关校验，私钥仅 IdP 持有）。 +- 不支持 `none`、HS256 对称密钥（除非开发环境显式开关）。 + +### 4.2 Payload 标准 Claims + +| Claim | 必填 | 类型 | 说明 | +| --- | --- | --- | --- | +| `iss` | 是 | string | 签发者，如 `https://idp.jinrong.internal` | +| `sub` | 是 | string | 主体 ID：`customer_id` 或 `staff_id` 或 `service_name` | +| `aud` | 是 | string[] | 受众，如 `["agent-gateway"]` | +| `exp` | 是 | number | 过期时间（Unix 秒） | +| `iat` | 是 | number | 签发时间 | +| `jti` | 是 | string | Token 唯一 ID，便于吊销与审计 | +| `token_type` | 是 | enum | `customer` \| `staff` \| `service` | +| `roles` | 是 | string[] | RBAC 角色，见 §5 | +| `permissions` | 否 | string[] | 细粒度权限（可选；推荐员工 Token 携带） | +| `tenant_id` | 是 | string | 租户/法人主体，多法人场景隔离 | +| `customer_id` | 条件 | string | **仅 `token_type=customer`**：必须等于 `sub` | +| `advisor_id` | 条件 | string | **代理人角色**：当前员工 ID，等于 `sub` | +| `session_hint` | 否 | string | 可选，绑定 C 端设备/session，防 Token 盗用 | + +### 4.3 员工 Token 示例 + +```json +{ + "iss": "https://idp.jinrong.internal", + "sub": "STAFF-10086", + "aud": ["agent-gateway"], + "exp": 1735689600, + "iat": 1735686000, + "jti": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "token_type": "staff", + "tenant_id": "TENANT-001", + "roles": ["advisor"], + "permissions": [ + "agent:advisor:chat", + "profile:l1:read", + "profile:l2:write", + "profile:l3:read", + "core:holding:read" + ], + "advisor_id": "STAFF-10086" +} +``` + +### 4.4 客户 Token 示例 + +```json +{ + "iss": "https://idp.jinrong.internal", + "sub": "CUST-9527", + "aud": ["agent-gateway"], + "exp": 1735689600, + "iat": 1735686000, + "jti": "f0e1d2c3-b4a5-6789-0123-456789abcdef", + "token_type": "customer", + "tenant_id": "TENANT-001", + "roles": ["customer"], + "permissions": [ + "agent:customer:chat", + "profile:l1:read", + "profile:l1:write", + "core:holding:read:self" + ], + "customer_id": "CUST-9527" +} +``` + +### 4.5 服务账号 Token（交易前适当性 R-02） + +```json +{ + "token_type": "service", + "sub": "svc-trade-suitability", + "roles": ["service_risk"], + "permissions": [ + "agent:risk:suitability_check", + "profile:l1:read", + "profile:l2:read", + "audit:write" + ] +} +``` + +- 有效期建议 **≤ 5 分钟**，且绑定调用方 IP / mTLS 证书。 + +### 4.6 请求头约定 + +| Header | 必填 | 说明 | +| --- | --- | --- | +| `Authorization` | 是 | `Bearer ` | +| `X-Trace-Id` | 是 | 全链路 ID；网关可补发 | +| `X-Agent-Type` | 是 | `customer` \| `advisor` \| `analyst` \| `risk` | +| `X-Request-Id` | 否 | 幂等 / 重试 | + +网关校验 **`X-Agent-Type` 与 Token 允许访问的 Agent 列表一致**，不一致直接 403。 + +--- + +## 5. RBAC 角色与权限模型 + +### 5.1 角色定义（`roles`） + +| 角色代码 | 中文名 | 可进入 Agent | 说明 | +| --- | --- | --- | --- | +| `customer` | 客户本人 | 客户财富 | 仅本人数据 | +| `advisor` | 理财代理人 | 代理人助手 | 名下客户 | +| `analyst` | 数据分析员 | 数据分析 | 内部只读 + 聚合 | +| `risk_officer` | 风控专员 | 风控监测 | 预警处置、L3 写 | +| `compliance` | 合规专员 | 代理人（审计台）、共用审计 API | **只读审计**，不看客户业务对话内容除非授权 | +| `ops` | 运营 | 代理人（A-08 统计） | 仅脱敏聚合 | +| `service_risk` | 风控服务账号 | 风控 API | 交易前钩子，无人机交互 | + +一人可多角色，如 `["advisor", "compliance"]`；权限取 **并集**，数据归属仍按 **最窄范围** 校验。 + +### 5.2 权限命名规范 + +```text +{scope}:{resource}:{action}[:{qualifier}] +``` + +| 前缀 scope | 示例 | 含义 | +| --- | --- | --- | +| `agent` | `agent:customer:chat` | 访问某 Agent 的对话能力 | +| `profile` | `profile:l2:write` | 画像 L1/L2/L3 | +| `core` | `core:holding:read` | Core 只读业务数据 | +| `risk` | `risk:alert:write` | 预警写入 | +| `audit` | `audit:read:all` | 合规审计读 | +| `sql` | `sql:execute:readonly` | 分析 Agent 只读 SQL | + +### 5.3 角色 → 默认权限包 + +| 角色 | 默认 permissions（摘要） | +| --- | --- | +| `customer` | `agent:customer:chat`, `profile:l1:read`, `profile:l1:write`, `core:*:read:self` | +| `advisor` | `agent:advisor:chat`, `profile:l1:read`, `profile:l2:read`, `profile:l2:write`, `profile:l3:read`, `core:*:read:assigned` | +| `analyst` | `agent:analyst:chat`, `profile:l1:read`, `profile:l2:read`, `profile:l3:read`, `core:*:read:scoped`, `sql:execute:readonly`, `risk:alert:read` | +| `risk_officer` | `agent:risk:chat`, `profile:l1:read`, `profile:l2:read`, `profile:l3:read`, `profile:l3:write`, `risk:alert:write`, `risk:suitability:write`, `core:*:read:all` | +| `compliance` | `audit:read:all`, `agent:advisor:audit`, `compliance:hit:read` | +| `ops` | `agent:advisor:stats`, `audit:read:aggregated` | +| `service_risk` | `agent:risk:suitability_check`, `risk:suitability:write`, `profile:l1:read`, `profile:l2:read`, `audit:write` | + +> 实际权限以 Core RBAC 同步为准；上表为 **Agent 平台最低基线**。 + +### 5.4 Agent × 角色 准入矩阵 + +| Agent (`X-Agent-Type`) | 允许 `token_type` | 允许 `roles` | +| --- | --- | --- | +| `customer` | `customer` | `customer` | +| `advisor` | `staff` | `advisor`, `compliance`, `ops` | +| `analyst` | `staff` | `analyst`, `compliance` | +| `risk` | `staff`, `service` | `risk_officer`, `service_risk` | + +--- + +## 6. 数据层归属校验（第二层） + +JWT 通过后，**任何涉及 `customer_id` 的读写** 必须执行归属校验。 + +### 6.1 校验规则表 + +| 操作者角色 | 目标资源 | 校验逻辑 | 失败错误码 | +| --- | --- | --- | --- | +| `customer` | 任意含 `customer_id` 的资源 | `token.customer_id == resource.customer_id` | `AUTH_403_NOT_OWNER` | +| `advisor` | 客户画像 / 持仓 / 会话 | `customer_advisor_rel` 存在 `advisor_id=sub AND customer_id=? AND rel_status=active` | `AUTH_403_NOT_ASSIGNED` | +| `analyst` | 客户级明细 | 走 **数据权限目录**；无明细权限则 **仅允许聚合 SQL**（`COUNT`/`GROUP BY`，结果 ≥ k-匿名阈值） | `AUTH_403_SCOPE` | +| `risk_officer` | 全量客户 | 允许读全部；写仅限 L3 / 预警 / 适当性 | — | +| `compliance` | 审计 / 会话 | 可跨客户读 **审计类表**；读 `agent_message` 需 `audit:read:content` 额外权限 | `AUTH_403_AUDIT_SCOPE` | +| 跨 Agent 读会话 | `agent_session` | 角色只能读 **同 agent_type** 会话；合规除外 | `AUTH_403_SESSION_AGENT` | + +### 6.2 归属校验伪代码（共用 SDK） + +```python +def assert_customer_access(ctx: AuthContext, customer_id: str, action: str): + if ctx.token_type == "customer": + if ctx.sub != customer_id: + audit_denied(ctx, "AUTH_403_NOT_OWNER", customer_id) + raise Forbidden(...) + + elif "advisor" in ctx.roles: + if not rel_exists(ctx.sub, customer_id, status="active"): + audit_denied(ctx, "AUTH_403_NOT_ASSIGNED", customer_id) + raise Forbidden(...) + + elif "analyst" in ctx.roles: + if action == "detail" and not ctx.has_perm("core:customer:read:detail"): + audit_denied(ctx, "AUTH_403_SCOPE", customer_id) + raise Forbidden(...) + # aggregate 走 SQL 网关白名单 + + elif "risk_officer" in ctx.roles: + return # 读全开；写由 permission 再判 + + else: + audit_denied(ctx, "AUTH_403_ROLE", customer_id) + raise Forbidden(...) +``` + +### 6.3 画像 L1 / L2 / L3 RBAC（与数据矩阵对齐） + +| 资源 | customer | advisor | analyst | risk_officer | compliance | +| --- | --- | --- | --- | --- | --- | +| L1 读 | 本人 | 名下客户 | 脱敏/聚合 | 全部 | 审计 | +| L1 写 | 本人 | — | — | — | — | +| L2 读 | — | 名下客户 | 脱敏/聚合 | 全部 | 审计 | +| L2 写 | — | 名下客户 | — | — | — | +| L3 读 | — | 名下客户 | 脱敏/聚合 | 全部 | 审计 | +| L3 写 | — | — | — | ✓ | — | + +**客户永远不可见 L2/L3**（API 层直接 404，避免泄露存在性）。 + +--- + +## 7. 各 Agent 鉴权要点 + +### 7.1 客户财富 Agent + +| 检查点 | 规则 | +| --- | --- | +| 入口 | 仅 `token_type=customer` | +| 会话 | `agent_session.actor_id` 必须 = `customer_id` | +| Core 只读 | 持仓/流水 API 自动注入 `customer_id=ctx.sub` | +| Tool | 禁止传入他人 `customer_id`；传入则 `AUTH_403` + 审计 | +| 画像 | 只写 L1；读 L3 禁止 | +| 适当性 | 只读 `risk_suitability_log` 本人记录 | + +### 7.2 代理人助手 Agent + +| 检查点 | 规则 | +| --- | --- | +| 入口 | `staff` + `advisor`/`compliance`/`ops` | +| 查客户 | 请求体/Tool 中 `customer_id` **必过** `customer_advisor_rel` | +| 合规台 A-05 | `compliance` 角色 + `audit:read:all`；可按 `advisor_id` 过滤，不能改数据 | +| 草稿 A-03 | `advisor_draft.advisor_id` 必须 = `ctx.sub` | +| 外发 | 无 `message:send:customer` 权限；系统级禁止代理人 Agent 直发客户 | + +### 7.3 数据分析 Agent + +| 检查点 | 规则 | +| --- | --- | +| 入口 | `staff` + `analyst` | +| SQL | 仅 `SELECT`；SQL 网关白名单 schema；禁止 `INSERT/UPDATE/DELETE` | +| 明细 vs 聚合 | 无明细权限时，拦截含 `customer_id` 单行输出的查询 | +| 画像 | L1/L2/L3 **只读**；写请求一律 403 | +| 预警 | `risk_alert` 只读；无 `risk:alert:handle` | +| 留痕 | 每次查询写 `analytics_query_log`，含 `staff_id=ctx.sub` | + +### 7.4 风控监测 Agent + +| 检查点 | 规则 | +| --- | --- | +| 人机入口 | `staff` + `risk_officer` | +| 交易钩子 R-02 | `service` + `service_risk` + mTLS；不创建会话 | +| 写权限 | 可写 `risk_alert`, `customer_profile_l3`, `risk_suitability_log` | +| 读权限 | L0/L1/L2 全读；**不可写** L1/L2 | +| 阻断 | 仅 R-02 API 可返回 `blocked`；须写 `audit_log` + `risk_suitability_log` | + +--- + +## 8. Tool / API 统一鉴权流程 + +```mermaid +sequenceDiagram + participant Client + participant Gateway + participant Agent + participant AuthSDK + participant DB + + Client->>Gateway: Request + JWT + X-Agent-Type + Gateway->>Gateway: 验签 / exp / aud / token_type + Gateway->>Gateway: RBAC: role ∈ allowed? + Gateway->>Agent: AuthContext (sub, roles, perms, trace_id) + Agent->>AuthSDK: check_resource(customer_id, action) + AuthSDK->>DB: customer_advisor_rel / self check + alt 通过 + AuthSDK-->>Agent: OK + Agent->>DB: 业务读写 + else 拒绝 + AuthSDK->>DB: audit_log (auth_denied) + AuthSDK-->>Agent: Forbidden + Agent-->>Client: 403 + error_code + end +``` + +### 8.1 AuthContext（注入给各 Agent 服务） + +```typescript +interface AuthContext { + traceId: string; + tokenType: 'customer' | 'staff' | 'service'; + subjectId: string; // sub + roles: string[]; + permissions: string[]; + tenantId: string; + customerId?: string; // token_type=customer + advisorId?: string; // 代理人 + agentType: 'customer' | 'advisor' | 'analyst' | 'risk'; + jti: string; +} +``` + +### 8.2 共用 SDK 能力清单 + +| 模块 | 方法 | 说明 | +| --- | --- | --- | +| `JwtVerifier` | `verify(token)` | 验签、解析、吊销列表检查 | +| `RbacGuard` | `can(ctx, permission)` | 权限判断 | +| `OwnershipGuard` | `assertCustomer(ctx, customerId)` | 归属校验 | +| `ProfileGuard` | `assertProfileAccess(ctx, layer, op)` | L1/L2/L3 | +| `SessionGuard` | `assertSession(ctx, sessionId)` | 会话归属 + agent_type | +| `AuditService` | `logDenied(ctx, code, detail)` | 越权审计 | + +--- + +## 9. 会话与 Trace 绑定 + +创建 `agent_session` 时： + +| 字段 | 赋值规则 | +| --- | --- | +| `agent_type` | = `X-Agent-Type` | +| `actor_id` | = `ctx.sub` | +| `actor_role` | = 主角色（`customer`/`advisor`/…） | +| `customer_id` | 客户 Agent：`ctx.customer_id`；代理人 Agent：请求指定且通过归属校验 | +| `advisor_id` | 代理人 Agent：`ctx.advisor_id` | +| `trace_id` | = `X-Trace-Id` | + +后续同会话所有 `agent_message` / `agent_tool_call` / `audit_log` 必须带同一 `trace_id`。 + +**禁止**：使用他人 `session_id` 续聊（`SessionGuard` 校验 `actor_id`）。 + +--- + +## 10. 错误码与 HTTP 状态 + +| HTTP | error_code | 含义 | 是否写审计 | +| --- | --- | --- | --- | +| 401 | `AUTH_401_INVALID_TOKEN` | 签名无效 / 过期 / 格式错误 | 是 | +| 401 | `AUTH_401_REVOKED` | jti 已吊销 | 是 | +| 403 | `AUTH_403_ROLE` | 角色不允许进该 Agent | 是 | +| 403 | `AUTH_403_PERMISSION` | 缺少 permission | 是 | +| 403 | `AUTH_403_NOT_OWNER` | 客户访问非本人数据 | 是 | +| 403 | `AUTH_403_NOT_ASSIGNED` | 代理人访问非名下客户 | 是 | +| 403 | `AUTH_403_SCOPE` | 分析员超数据范围 | 是 | +| 403 | `AUTH_403_SESSION_AGENT` | 跨 Agent 读会话 | 是 | +| 403 | `AUTH_403_AGENT_MISMATCH` | X-Agent-Type 与 Token 不符 | 是 | + +响应体统一： + +```json +{ + "error_code": "AUTH_403_NOT_ASSIGNED", + "message": "无权访问该客户数据", + "trace_id": "trace-xxx", + "request_id": "req-xxx" +} +``` + +**禁止**在 403 响应中返回「该客户是否存在」等可被枚举的信息（客户 Agent 对外统一话术）。 + +--- + +## 11. 安全补充要求 + +| 项 | 要求 | +| --- | --- | +| Token 有效期 | 客户 Access Token ≤ 2h，Refresh 走 IdP；员工 ≤ 8h | +| 吊销 | 支持 jti 黑名单（Redis `auth:revoked:{jti}`） | +| 限流 | 复用 Redis `guard:rate:{actor_id}:{agent}` | +| 高危越权 | 同一 `actor_id` 10 分钟内 ≥ 5 次 `AUTH_403_*` → 临时 `guard:block` | +| 日志 | 不在日志打印完整 JWT；只打 `sub`、`jti` 前 8 位 | +| 开发环境 | 可用 HS256 + 固定 dev secret，**与生产密钥物理隔离** | + +--- + +## 12. 与现有表结构的关系 + +| 表 | 鉴权用途 | +| --- | --- | +| `customer_advisor_rel` | 代理人 **数据归属** 权威来源（Core 同步） | +| `agent_session` | 会话 `actor_id` / `advisor_id` / `customer_id` 一致性 | +| `audit_log` | 越权、鉴权失败、`event_type=auth_denied` | +| `input_guard_log` | 恶意参数、伪造 `customer_id` | + +--- + +## 13. 验收检查清单（F-01 P0） + +### 平台 / 网关 + +- [ ] 四个 Agent 共用同一 `JwtVerifier` 与 `RbacGuard` +- [ ] 错误 Token 一律 401，且不进入业务逻辑 +- [ ] `X-Agent-Type` 与客户/员工 Token 交叉校验生效 + +### 客户财富 Agent + +- [ ] 客户 A 不能查客户 B 持仓（403 + 审计） +- [ ] 客户 Token 不能访问 advisor/analyst/risk 路由 + +### 代理人助手 Agent + +- [ ] 代理人 A 不能查代理人 B 名下客户 +- [ ] 合规角色可审计会话，但不能写 L2 画像 + +### 数据分析 Agent + +- [ ] 非授权明细 SQL 被拦截 +- [ ] 不能 UPDATE 任何业务表 + +### 风控监测 Agent + +- [ ] 服务账号可调用 R-02，但不能登录人机聊天台 +- [ ] 风控不能写 L1/L2 + +--- + +## 14. 实施分工建议 + +| 负责方 | 交付物 | +| --- | --- | +| **平台组** | Agent Gateway、Auth SDK、`customer_advisor_rel` 同步 Job | +| **IdP / Core** | 角色权限源、JWT 签发与吊销 API | +| **各 Agent 组** | 接入 SDK；Tool 入口调用 `OwnershipGuard`；禁止本地 JWT 解析 | +| **合规** | 验收 §13 用例 + A-05 审计台权限 | + +--- + +## 15. 关联文档 + +| 文档 | 关系 | +| --- | --- | +| [业务场景优先级清单](../../需求拆解/业务场景优先级清单.md) §3.1 F-01 | 需求来源 | +| [数据交互矩阵](../../需求拆解/数据交互矩阵.md) §8 | 画像 RBAC | +| [Agent风险与合规约束汇总](../../需求拆解/Agent风险与合规约束汇总.md) G-01 | 全局约束 | +| [05-多Agent共用底座清单](../项目框架设计/表设计/05-多Agent共用底座清单.md) | 平台 SDK 与 `customer_advisor_rel` | +| [02-redis-keys.md](../项目框架设计/表设计/02-redis-keys.md) | 限流 / 封禁 Key | +| [01-技术栈与版本.md](./01-技术栈与版本.md) | FastAPI / Redis / 部署环境 | + +--- + +## 附录 A：权限全集（实现时可裁剪） + +```text +# Agent 入口 +agent:customer:chat +agent:advisor:chat +agent:analyst:chat +agent:risk:chat +agent:risk:suitability_check +agent:advisor:audit +agent:advisor:stats + +# 画像 +profile:l1:read +profile:l1:write +profile:l2:read +profile:l2:write +profile:l3:read +profile:l3:write + +# Core 只读 +core:holding:read:self +core:holding:read:assigned +core:holding:read:scoped +core:holding:read:all +core:customer:read:detail + +# 风控 +risk:alert:read +risk:alert:write +risk:suitability:write +risk:suitability:read + +# 分析与审计 +sql:execute:readonly +audit:read:all +audit:read:aggregated +audit:read:content +audit:write +compliance:hit:read +``` + +## 附录 B：Core RBAC 同步建议 + +| Core 角色 | 映射 Agent roles | 同步频率 | +| --- | --- | --- | +| 理财师 | `advisor` | 实时 / 5min | +| 风控经理 | `risk_officer` | 实时 | +| 合规 | `compliance` | 实时 | +| 数据分析师 | `analyst` | 实时 | +| 运营 | `ops` | 日批 | + +员工离职 / 转岗：Core 禁用账号 → IdP 吊销 Refresh Token → Redis 黑名单现有 Access Token `jti`。 diff --git a/docs/项目框架设计/技术选型和版本/README.md b/docs/项目框架设计/技术选型和版本/README.md new file mode 100644 index 0000000..0d4b45e --- /dev/null +++ b/docs/项目框架设计/技术选型和版本/README.md @@ -0,0 +1,9 @@ +# 技术选型与版本 + +> 本目录：**开发环境已定型的技术栈、版本号、部署方式**，以及 **四 Agent 统一鉴权规范**。 +> 表结构 / Redis / Milvus Collection 设计见 [../项目框架设计/表设计/](../项目框架设计/表设计/)。 + +| 文档 | 说明 | +| --- | --- | +| [01-技术栈与版本.md](./01-技术栈与版本.md) | 组件版本、连接方式、Windows 原生部署决策 | +| [02-JWT-RBAC鉴权手册.md](./02-JWT-RBAC鉴权手册.md) | 四 Agent 统一 JWT + RBAC + 数据归属校验（F-01） | diff --git a/docs/项目框架设计/表设计/00-架构总览.md b/docs/项目框架设计/表设计/00-架构总览.md new file mode 100644 index 0000000..079752e --- /dev/null +++ b/docs/项目框架设计/表设计/00-架构总览.md @@ -0,0 +1,274 @@ +# 四 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) | + +--- + +## 先读这一页：这份文档在讲什么？ + +我们要做 4 个智能助手（Agent），服务 4 类人： + +| Agent | 给谁用 | 干什么（一句话） | +| --- | --- | --- | +| **客户财富** | 买理财的客户 | 查持仓、看产品规则、亏多了提醒一下 | +| **代理人助手** | 一线理财经理 | 查客户情况、查产品规则、帮忙起草合规话术 | +| **数据分析** | 公司内部同事 | 用大白话问数据，系统查库后用普通话回答 | +| **风控监测** | 风控专员 | 大额/异常交易预警，买不匹配的产品要拦住 | + +**四个 Agent 不互相「打电话」问 AI**，而是 **往同一套数据库里读写**。 +这样四个组可以 **同时开发**，只要事先约定好 **哪张表谁写、谁只能读**。 + +--- + +## 五种「仓库」分别是干什么的？ + +可以把它想成 **五种不同用途的仓库**： + +| 仓库 | 技术名 | 通俗理解 | 里面主要放什么 | 丢了会怎样 | +| --- | --- | --- | --- | --- | +| **短期记事本** | Redis | 对话时临时用的草稿纸 | 最近几轮聊天、刚查过的客户画像副本 | 丢了可以从 MySQL 恢复，只是慢一点 | +| **正式档案柜** | MySQL | 必须长期保存、能审计的记录 | 聊天记录归档、客户画像、预警单、合规审计 | **不能丢**，监管和纠纷都要查 | +| **产品说明书索引** | Milvus | 按意思搜文档（向量检索） | 基金产品手册、交易规则、内部办事流程 | 更新了重新导入即可 | +| **关系图谱** | Neo4j | 「谁持有啥、谁管谁」的关系图 | 客户↔产品↔持仓、客户↔代理人、产品风险等级 | 从原有业务系统同步重建 | +| **原有业务系统** | Core（只读） | 公司本来就有的一套账 | 真实持仓、流水、正式风险测评 C1~C5 | 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` + +--- + +## 系统长什么样？（一张图） + +```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 留痕 | + +> 完整字段见 [01-mysql-共用底座.sql](./01-mysql-共用底座.sql) + [02-mysql-agent专用.sql](./02-mysql-agent专用.sql) + +--- + +## 四个 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 张 | +| [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/需求拆解/` | 完整业务场景与合规细则 | diff --git a/docs/项目框架设计/表设计/01-mysql-共用底座.sql b/docs/项目框架设计/表设计/01-mysql-共用底座.sql new file mode 100644 index 0000000..5242071 --- /dev/null +++ b/docs/项目框架设计/表设计/01-mysql-共用底座.sql @@ -0,0 +1,194 @@ +-- ============================================================================= +-- 多 Agent 共用底座 MySQL（11 张） +-- 执行时机：四个 Agent 并行开发之前，平台统一建好 +-- 不含单 Agent 专用表 → 见 02-mysql-agent专用.sql +-- ============================================================================= + +CREATE DATABASE IF NOT EXISTS jinrong_agent DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +USE jinrong_agent; + +-- ============================================================================= +-- 🔴 第一批：全员共用（6 张） +-- ============================================================================= + +CREATE TABLE agent_session ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + session_id VARCHAR(64) NOT NULL COMMENT '对外会话 UUID', + trace_id VARCHAR(64) NOT NULL COMMENT '全链路追踪 ID', + agent_type ENUM('customer','advisor','analyst','risk') NOT NULL, + actor_id VARCHAR(64) NOT NULL COMMENT '操作者：customer_id / staff_id / SYSTEM', + actor_role VARCHAR(32) NOT NULL COMMENT 'customer/advisor/analyst/risk_officer/compliance', + customer_id VARCHAR(64) NULL COMMENT '会话关联客户', + advisor_id VARCHAR(64) NULL COMMENT '代理人归属校验用', + title VARCHAR(256) NULL, + status ENUM('active','closed','blocked') NOT NULL DEFAULT 'active', + metadata JSON NULL, + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), + closed_at DATETIME(3) NULL, + UNIQUE KEY uk_session_id (session_id), + KEY idx_trace (trace_id), + KEY idx_actor (agent_type, actor_id, created_at), + KEY idx_customer (customer_id, created_at), + KEY idx_advisor_customer (advisor_id, customer_id) +) ENGINE=InnoDB COMMENT='【共用】Agent 会话主表'; + +CREATE TABLE agent_message ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + session_id VARCHAR(64) NOT NULL, + trace_id VARCHAR(64) NOT NULL, + seq_no INT UNSIGNED NOT NULL, + role ENUM('user','assistant','system','tool') NOT NULL, + content MEDIUMTEXT NOT NULL, + content_hash CHAR(64) NULL, + token_est INT UNSIGNED NULL, + has_disclaimer TINYINT(1) NOT NULL DEFAULT 0, + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + KEY idx_session_seq (session_id, seq_no), + KEY idx_trace (trace_id), + KEY idx_created (created_at) +) ENGINE=InnoDB COMMENT='【共用】消息明细'; + +CREATE TABLE agent_tool_call ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + session_id VARCHAR(64) NOT NULL, + trace_id VARCHAR(64) NOT NULL, + message_id BIGINT UNSIGNED NULL, + tool_name VARCHAR(128) NOT NULL, + tool_input JSON NOT NULL, + tool_output JSON NULL, + status ENUM('success','error','blocked','timeout') NOT NULL, + error_code VARCHAR(64) NULL, + latency_ms INT UNSIGNED NULL, + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + KEY idx_session (session_id, created_at), + KEY idx_trace (trace_id), + KEY idx_tool (tool_name, created_at) +) ENGINE=InnoDB COMMENT='【共用】Tool 调用审计'; + +CREATE TABLE audit_log ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + trace_id VARCHAR(64) NOT NULL, + event_type VARCHAR(64) NOT NULL, + agent_type ENUM('customer','advisor','analyst','risk','platform') NOT NULL, + actor_id VARCHAR(64) NOT NULL, + customer_id VARCHAR(64) NULL, + rule_id VARCHAR(64) NULL, + input_summary JSON NULL, + decision VARCHAR(64) NULL, + risk_score SMALLINT UNSIGNED NULL, + handler_id VARCHAR(64) NULL, + handler_result VARCHAR(64) NULL, + handler_comment VARCHAR(512) NULL, + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + KEY idx_trace (trace_id), + KEY idx_event_time (event_type, created_at), + KEY idx_customer (customer_id, created_at), + KEY idx_actor (actor_id, created_at) +) ENGINE=InnoDB COMMENT='【共用】审计总账（只 INSERT）'; + +CREATE TABLE input_guard_log ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + trace_id VARCHAR(64) NOT NULL, + session_id VARCHAR(64) NULL, + agent_type ENUM('customer','advisor','analyst','risk') NOT NULL, + actor_id VARCHAR(64) NOT NULL, + guard_type ENUM('prompt_injection','oversize','illegal_param','rate_limit') NOT NULL, + raw_excerpt VARCHAR(1024) NULL, + action ENUM('blocked','sanitized','passed') NOT NULL, + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + KEY idx_session (session_id), + KEY idx_time (created_at) +) ENGINE=InnoDB COMMENT='【共用】输入安全防护'; + +CREATE TABLE customer_advisor_rel ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + customer_id VARCHAR(64) NOT NULL, + advisor_id VARCHAR(64) NOT NULL, + rel_status ENUM('active','transferred','closed') NOT NULL DEFAULT 'active', + effective_from DATE NOT NULL, + effective_to DATE NULL, + synced_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + UNIQUE KEY uk_customer_advisor (customer_id, advisor_id, effective_from), + KEY idx_advisor (advisor_id, rel_status) +) ENGINE=InnoDB COMMENT='【共用】客户-代理人归属（Core 同步）'; + +-- ============================================================================= +-- 🟡 第二批：跨 Agent 交换（5 张） +-- ============================================================================= + +CREATE TABLE customer_profile_l1 ( + customer_id VARCHAR(64) NOT NULL PRIMARY KEY, + style_tags JSON NULL, + style_questionnaire JSON NULL, + allocation_plan JSON NULL, + behavior_tags JSON NULL, + attribution_pref VARCHAR(32) NULL, + version INT UNSIGNED NOT NULL DEFAULT 1, + updated_by ENUM('customer_agent','system') NOT NULL DEFAULT 'customer_agent', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) +) ENGINE=InnoDB COMMENT='【交换】L1 客户画像 · 客户 Agent 写'; + +CREATE TABLE customer_profile_l2 ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + customer_id VARCHAR(64) NOT NULL, + advisor_id VARCHAR(64) NOT NULL, + asset_snapshot JSON NULL, + demands JSON NULL, + follow_up_todos JSON NULL, + service_tags JSON NULL, + source_session_id VARCHAR(64) NULL, + version INT UNSIGNED NOT NULL DEFAULT 1, + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), + UNIQUE KEY uk_customer_advisor (customer_id, advisor_id), + KEY idx_advisor (advisor_id) +) ENGINE=InnoDB COMMENT='【交换】L2 服务画像 · 代理人 Agent 写'; + +CREATE TABLE customer_profile_l3 ( + customer_id VARCHAR(64) NOT NULL PRIMARY KEY, + monitor_tier ENUM('normal','watch','high') NOT NULL DEFAULT 'normal', + risk_score SMALLINT UNSIGNED NULL, + score_dimensions JSON NULL, + monitor_tags JSON NULL, + last_alert_id VARCHAR(64) NULL, + computed_at DATETIME(3) NOT NULL, + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) +) ENGINE=InnoDB COMMENT='【交换】L3 监测画像 · 风控 Agent 写'; + +CREATE TABLE risk_alert ( + alert_id VARCHAR(64) NOT NULL PRIMARY KEY, + trace_id VARCHAR(64) NOT NULL, + customer_id VARCHAR(64) NOT NULL, + trade_id VARCHAR(64) NULL, + alert_type ENUM('large_amount','freq_trade','suitability','aml','pattern') NOT NULL, + triggered_rules JSON NOT NULL, + risk_score SMALLINT UNSIGNED NULL, + status ENUM('pending_review','confirmed_normal','confirmed_suspicious','reported') NOT NULL DEFAULT 'pending_review', + payload JSON NOT NULL, + handler_id VARCHAR(64) NULL, + handler_result VARCHAR(64) NULL, + handler_comment VARCHAR(512) NULL, + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + handled_at DATETIME(3) NULL, + KEY idx_status_time (status, created_at), + KEY idx_customer (customer_id, created_at), + KEY idx_type (alert_type, created_at) +) ENGINE=InnoDB COMMENT='【交换】预警单 · 风控写 / 分析读'; + +CREATE TABLE risk_suitability_log ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + trace_id VARCHAR(64) NOT NULL, + customer_id VARCHAR(64) NOT NULL, + product_id VARCHAR(64) NOT NULL, + customer_risk_level CHAR(2) NOT NULL, + product_risk_level CHAR(2) NOT NULL, + is_matched TINYINT(1) NOT NULL, + is_blocked TINYINT(1) NOT NULL DEFAULT 0, + block_reason VARCHAR(512) NULL, + request_ref VARCHAR(64) NULL, + profile_l1_version INT UNSIGNED NULL, + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + KEY idx_customer (customer_id, created_at), + KEY idx_product (product_id, created_at), + KEY idx_blocked (is_blocked, created_at) +) ENGINE=InnoDB COMMENT='【交换】适当性记录 · 风控写 / 客户+代理人读'; diff --git a/docs/项目框架设计/表设计/02-mysql-agent专用.sql b/docs/项目框架设计/表设计/02-mysql-agent专用.sql new file mode 100644 index 0000000..1222c8a --- /dev/null +++ b/docs/项目框架设计/表设计/02-mysql-agent专用.sql @@ -0,0 +1,89 @@ +-- ============================================================================= +-- 单 Agent 专用 MySQL（5 张） +-- 执行时机：各 Agent 组开发自己的功能时创建（也可一次性全建） +-- 共用底座见 01-mysql-共用底座.sql +-- ============================================================================= + +USE jinrong_agent; + +-- ⚪ 客户财富 Agent +CREATE TABLE customer_threshold_config ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + customer_id VARCHAR(64) NOT NULL, + scope_type ENUM('portfolio','product') NOT NULL DEFAULT 'portfolio', + scope_ref VARCHAR(64) NULL, + loss_threshold_pct DECIMAL(5,2) NOT NULL, + notify_channel SET('app','sms','email') NOT NULL DEFAULT 'app', + is_enabled TINYINT(1) NOT NULL DEFAULT 1, + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), + KEY idx_customer (customer_id, is_enabled) +) ENGINE=InnoDB COMMENT='【客户专用】亏损阈值配置'; + +CREATE TABLE customer_notify_log ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + customer_id VARCHAR(64) NOT NULL, + trace_id VARCHAR(64) NOT NULL, + notify_type ENUM('loss_threshold','market_volatility') NOT NULL, + threshold_config_id BIGINT UNSIGNED NULL, + payload JSON NOT NULL, + channel VARCHAR(16) NOT NULL, + send_status ENUM('sent','failed') NOT NULL, + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + KEY idx_customer_time (customer_id, created_at) +) ENGINE=InnoDB COMMENT='【客户专用】提醒留痕'; + +-- ⚪ 代理人助手 Agent +CREATE TABLE advisor_draft ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + draft_id VARCHAR(64) NOT NULL, + session_id VARCHAR(64) NOT NULL, + trace_id VARCHAR(64) NOT NULL, + advisor_id VARCHAR(64) NOT NULL, + customer_id VARCHAR(64) NOT NULL, + draft_type ENUM('script','follow_up') NOT NULL, + content MEDIUMTEXT NOT NULL, + review_status ENUM('pending','approved','rejected') NOT NULL DEFAULT 'pending', + reviewer_id VARCHAR(64) NULL, + reviewed_at DATETIME(3) NULL, + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + UNIQUE KEY uk_draft_id (draft_id), + KEY idx_advisor_customer (advisor_id, customer_id, created_at), + KEY idx_review (review_status, created_at) +) ENGINE=InnoDB COMMENT='【代理人专用】话术/跟进草稿'; + +CREATE TABLE compliance_hit_log ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + session_id VARCHAR(64) NOT NULL, + trace_id VARCHAR(64) NOT NULL, + agent_type ENUM('customer','advisor') NOT NULL, + actor_id VARCHAR(64) NOT NULL, + hit_category ENUM('return_promise','principal_guarantee','buy_sell_guide','product_recommend','other') NOT NULL, + matched_terms JSON NOT NULL, + severity ENUM('low','medium','high') NOT NULL, + action_taken ENUM('flagged','blocked','alerted') NOT NULL, + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + KEY idx_severity_time (severity, created_at), + KEY idx_session (session_id) +) ENGINE=InnoDB COMMENT='【代理人专用】违规话术命中'; + +-- ⚪ 数据分析 Agent +CREATE TABLE analytics_query_log ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + session_id VARCHAR(64) NOT NULL, + trace_id VARCHAR(64) NOT NULL, + staff_id VARCHAR(64) NOT NULL, + nl_question TEXT NOT NULL, + generated_sql TEXT NOT NULL, + sql_hash CHAR(64) NOT NULL, + row_count INT UNSIGNED NULL, + exec_status ENUM('success','error','blocked') NOT NULL, + exec_latency_ms INT UNSIGNED NULL, + result_summary JSON NULL, + has_disclaimer TINYINT(1) NOT NULL DEFAULT 0, + error_message VARCHAR(512) NULL, + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + KEY idx_staff_time (staff_id, created_at), + KEY idx_trace (trace_id), + KEY idx_sql_hash (sql_hash) +) ENGINE=InnoDB COMMENT='【分析专用】查数 SQL 留痕'; diff --git a/docs/项目框架设计/表设计/02-redis-keys.md b/docs/项目框架设计/表设计/02-redis-keys.md new file mode 100644 index 0000000..862f490 --- /dev/null +++ b/docs/项目框架设计/表设计/02-redis-keys.md @@ -0,0 +1,81 @@ +# 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, type, customer_id_mask, risk_score}` | +| `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 | 命中高危规则临时封禁 | + +--- + +## 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`） diff --git a/docs/项目框架设计/表设计/03-milvus-collections.md b/docs/项目框架设计/表设计/03-milvus-collections.md new file mode 100644 index 0000000..f77c29f --- /dev/null +++ b/docs/项目框架设计/表设计/03-milvus-collections.md @@ -0,0 +1,89 @@ +# Milvus · 共享 RAG 记忆（P0） + +> **为何需要**：客户财富（C-02/C-03）与代理人助手（A-02/A-04）共用产品规则、业务制度知识库，属于 **跨 Agent 共同数据**，适合 Milvus。 +> **为何不存 MySQL**：原文档块大、需语义检索；MySQL 只存 doc 版本索引（可选 P1）。 + +--- + +## 1. P0 Collection 清单（2 个） + +| Collection | 共用 Agent | 来源文档 | 场景 | +| --- | --- | --- | --- | +| `kb_product_rules` | 客户财富、代理人助手 | 基金产品手册、交易规则 | C-02, C-03, A-02 | +| `kb_business_ops` | 代理人助手（客户只读 subset 可选） | 内部业务制度、办理流程 | A-04 | + +**P1 再加**：`kb_compliance_scripts`（A-03 话术规范模板） + +--- + +## 2. Collection：`kb_product_rules` + +### 2.1 字段 + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `id` | VARCHAR(64) PK | `{product_id}_{chunk_no}` | +| `embedding` | FLOAT_VECTOR(dim) | 文本向量，dim 与模型一致 | +| `product_id` | VARCHAR(64) | 产品代码 | +| `product_name` | VARCHAR(256) | 产品名称 | +| `doc_type` | VARCHAR(32) | `prospectus` `fee` `rule` `risk` | +| `risk_level` | CHAR(2) | R1~R5 | +| `source_doc_id` | VARCHAR(64) | 官方文档 ID，溯源必填 | +| `source_version` | VARCHAR(32) | 文档版本号 | +| `effective_date` | DATE | 生效日 | +| `chunk_text` | VARCHAR(8192) | 原文块（或存对象存储 URI） | +| `chunk_no` | INT | 块序号 | + +### 2.2 索引 + +- 向量：`IVF_FLAT` 或 `HNSW`（按数据量选型） +- 标量过滤：`product_id`, `doc_type`, `effective_date` + +### 2.3 检索约束（合规） + +- 回答 **必须** 返回 `source_doc_id` + `source_version` 用于溯源（A-02、C-02） +- 禁止跨 `effective_date` 过期文档（Agent 层过滤 `effective_date <= today`） + +--- + +## 3. Collection：`kb_business_ops` + +### 3.1 字段 + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `id` | VARCHAR(64) PK | `{process_code}_{chunk_no}` | +| `embedding` | FLOAT_VECTOR(dim) | | +| `process_code` | VARCHAR(64) | 如 `SUBSCRIBE` `REDEEM` `CONVERT` `AIP` | +| `process_name` | VARCHAR(128) | 定投设置、赎回到账等 | +| `source_doc_id` | VARCHAR(64) | 内部制度文档 ID | +| `source_version` | VARCHAR(32) | | +| `chunk_text` | VARCHAR(8192) | | +| `chunk_no` | INT | | + +### 3.2 使用边界 + +- **仅代理人 Agent** 默认检索；客户 Agent 不直接暴露内部流程全文（若客户问办理流程，走 C 端简化 FAQ subset，P1 再拆 collection） + +--- + +## 4. 写入与更新 + +| 操作 | 负责方 | 频率 | +| --- | --- | --- | +| 文档切块 + 向量化 | 平台 / 运营 | 产品制度变更时 | +| 版本切换 | 产品运营 A-09 | 抽检通过后 `source_version` 切换 | +| Agent 读取 | 客户 / 代理人 RAG Tool | 实时检索 | + +**不写回 Milvus**：会话内容、客户画像、预警 — 这些走 MySQL。 + +--- + +## 5. 不使用的场景（避免误用 Milvus） + +| 数据 | 应放 | +| --- | --- | +| 客户持仓/流水 | Core 只读 API | +| 用户画像 L1/L2/L3 | MySQL | +| 预警单 | MySQL `risk_alert` | +| 会话历史 | MySQL + Redis 窗口 | diff --git a/docs/项目框架设计/表设计/04-neo4j-model.md b/docs/项目框架设计/表设计/04-neo4j-model.md new file mode 100644 index 0000000..dc86d8f --- /dev/null +++ b/docs/项目框架设计/表设计/04-neo4j-model.md @@ -0,0 +1,84 @@ +# Neo4j · 共享关系记忆（P0 最小集） + +> **为何需要**：持仓-产品-客户、产品-适当性规则、客户-代理人归属是 **四 Agent 共同依赖的关系视图**，用于： +> C-01 持仓关联、A-01 客户概况、R-01/R-02 上下文、D-05 交叉问数。 +> **为何不存 MySQL 主表**：关系遍历与传导（持仓→行业→风险事件）在图上更高效；**事实金额仍以 Core RO 为准**。 + +--- + +## 1. P0 节点（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 同步 | 行业分类，P1 扩展 | + +**不在 Neo4j 存**：会话、审计、向量、画像 JSON（仍 MySQL）。 + +--- + +## 2. P0 关系（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 持仓传导，P1 | + +--- + +## 3. 同步策略 + +```text +Core 持仓/产品/归属变更（CDC 或 T+0 批） + → Sync Job 更新 Neo4j 节点与 HOLDS/ASSIGNED_TO + → 金额字段 as_of 戳记；Agent 展示时仍可调 Core API 二次确认 + +Agent 写入画像（L1/L2/L3） + → 不写 Neo4j（避免双写）；Neo4j 只读关系，画像走 MySQL +``` + +| 同步频率 | 数据 | +| --- | --- | +| 准实时（≤5min） | HOLDS 市值/盈亏 | +| 日批 | Industry、REQUIRES_MIN_RISK | +| 事件驱动 | ASSIGNED_TO 变更 | + +--- + +## 4. 各 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. P0 不建模（避免过度设计） + +| 不建 | 原因 | +| --- | --- | +| 会话/Message 节点 | MySQL + Redis 已覆盖 | +| 预警 Alert 节点 | MySQL `risk_alert` 权威 | +| 画像标签节点 | MySQL JSON + 分析用 SQL 聚合足够 P0 | +| 全文文档节点 | Milvus 负责 RAG | + +--- + +## 6. 示例 Cypher（R-02 适当性） + +```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 提供 **关系查询加速**，非唯一真相源。 diff --git a/docs/项目框架设计/表设计/05-多Agent共用底座清单.md b/docs/项目框架设计/表设计/05-多Agent共用底座清单.md new file mode 100644 index 0000000..f264879 --- /dev/null +++ b/docs/项目框架设计/表设计/05-多Agent共用底座清单.md @@ -0,0 +1,215 @@ +# 多 Agent 共用底座清单（先建这个） + +> **用途**：按「哪些东西必须多 Agent 一起用」划分，方便 **一次性把底座搭好**，再让四个组并行开发各自 Agent。 +> **不是**按工程上线顺序（Wave 0/1/2）划分。 + +--- + +## 一、怎么读这份清单 + +每张表 / 每个存储项都标了 **几个 Agent 会用到**，分三档： + +| 档位 | 含义 | 你要做什么 | +| --- | --- | --- | +| **🔴 全员共用** | 4 个 Agent **都要** 读或写 | **底座第一批必建** | +| **🟡 跨 Agent 交换** | 2~3 个 Agent 之间 **传数据** | **底座第二批必建**（不建则联调卡住） | +| **⚪ 单 Agent 专用** | mainly 1 个 Agent 自己写自己用 | **各组自己建**，不算公共底座 | + +**L0（原有业务系统）**：不算 Agent 库里的表，但底座要留 **只读接口**（查持仓、正式 C1~C5），四个 Agent 都要接。 + +--- + +## 二、总览：先建什么、后建什么 + +```text +【第一批 · 全员底座】MySQL 6 张 + Redis 会话/限流 + Core 只读接口 + │ +【第二批 · 跨 Agent 交换】MySQL 5 张 + Redis 画像缓存 + Milvus 1 库 + Neo4j 图 + │ +【第三批 · 各 Agent 专用】MySQL 5 张 + Milvus 1 库(仅代理人) + Redis 代理人快照 + │ + 四个 Agent 并行开发 +``` + +| 批次 | MySQL | Redis | Milvus | Neo4j | +| --- | --- | --- | --- | --- | +| **第一批** | 6 张 | 2 类 Key | — | — | +| **第二批** | 5 张 | 3 类 Key | 1 个 Collection | 整图 P0 | +| **第三批** | 5 张 | 1 类 Key | 1 个 Collection | — | +| **合计** | **16 张** | 6 类 | 2 个 | 1 套 | + +--- + +## 三、MySQL：完整对照表 + +### 🔴 第一批 — 全员共用（6 张） + +> 四个 Agent **任意一个** 要跑起来，这 6 张都必须有。 +> SQL 文件：[01-mysql-共用底座.sql](./01-mysql-共用底座.sql) 前半部分 + +| 表名 | 几个 Agent 用 | 谁写 | 谁读 | 干什么 | +| --- | --- | --- | --- | --- | +| `agent_session` | **4** | 四个都写 | 四个都读 | 一次对话会话 | +| `agent_message` | **4** | 四个都写 | 四个都读 | 每条聊天永久存档 | +| `agent_tool_call` | **4** | 四个都写 | 四个都读 | 调了哪些查数/检索接口 | +| `audit_log` | **4** + 合规 | 四个都写 | 合规巡检读 | 审计总账，只增不改 | +| `input_guard_log` | **4** | 平台/四个都写 | 安全/合规 | 恶意输入拦截记录 | +| `customer_advisor_rel` | **4** | 平台同步 Core | 四个都读 | 客户归哪个代理人管（权限） | + +### 🟡 第二批 — 跨 Agent 交换（5 张） + +> 多个 Agent **靠这些表传数据**；并行开发前必须建好，否则互相读不到。 +> SQL 文件：[01-mysql-共用底座.sql](./01-mysql-共用底座.sql) 后半部分 + +| 表名 | 几个 Agent 用 | 谁写 | 谁读 | 交换什么 | +| --- | --- | --- | --- | --- | +| `customer_profile_l1` | **4** | **客户** Agent | 客户、代理人、风控、分析 | 客户侧偏好：风格、规划、阈值偏好 | +| `customer_profile_l2` | **3** | **代理人** Agent | 代理人、风控、分析 | 服务侧记录：诉求、待办、服务标签 | +| `customer_profile_l3` | **4** | **风控** Agent | 客户(只读)、代理人、分析 | 监测标签：正常/关注/高风险 | +| `risk_alert` | **2~3** | **风控** Agent | 风控、**分析**、合规 | 预警单；分析统计「还有多少没审」 | +| `risk_suitability_log` | **3** | **风控** Agent | **客户**、**代理人**、交易钩子 | 买的产品是否匹配；可否拦截购买 | + +### ⚪ 第三批 — 单 Agent 专用（5 张，各组自建） + +> **不算公共底座**；对应组开发自己的 Agent 时再建即可。 +> SQL 文件：[02-mysql-agent专用.sql](./02-mysql-agent专用.sql) + +| 表名 | 主要使用者 | 干什么 | 为何不算共用 | +| --- | --- | --- | --- | +| `customer_threshold_config` | 仅客户 Agent | 客户设「亏 10% 提醒我」 | 只有客户 Agent 写；阈值偏好摘要也会进 L1 | +| `customer_notify_log` | 仅客户 Agent | 提醒发送留痕 | 只有客户 Agent 写 | +| `advisor_draft` | 仅代理人 Agent | 话术/跟进草稿 | 只有代理人用，不外泄给其他 Agent | +| `compliance_hit_log` | 仅代理人 Agent | 违规话术检测 | 主要服务代理人合规 | +| `analytics_query_log` | 仅分析 Agent | 人话查数 SQL 留痕 | 只有分析 Agent 写 | + +--- + +## 四、Redis：完整对照表 + +### 🔴 第一批 — 全员共用 + +| Key 模式 | 几个 Agent 用 | 干什么 | +| --- | --- | --- | +| `sess:{agent}:{session_id}:ctx` | **4** | 当前对话上下文（意图、槽位） | +| `sess:{agent}:{session_id}:msgs` | **4** | 最近 ~20 轮消息滑动窗口 | +| `sess:{agent}:{session_id}:lock` | **4** | 防并发写乱会话 | +| `guard:rate:{actor_id}:{agent}` | **4** | 限流 | +| `guard:block:{actor_id}` | **4** | 临时封禁 | + +### 🟡 第二批 — 跨 Agent 交换 + +| Key 模式 | 几个 Agent 用 | 谁写 | 谁读 | +| --- | --- | --- | --- | +| `profile:l1:{customer_id}` | **4** | 客户 Agent | 代理人、风控、分析 | +| `profile:l2:{customer_id}:{advisor_id}` | **3** | 代理人 Agent | 代理人、风控、分析 | +| `profile:l3:{customer_id}` | **4** | 风控 Agent | 客户、代理人、分析 | +| `risk:pub:alert` | **2+** | 风控 Agent | 风控工作台（Pub/Sub 推送） | + +### ⚪ 第三批 — 单 Agent + +| Key 模式 | 主要使用者 | 说明 | +| --- | --- | --- | +| `cache:advisor:snapshot:{advisor_id}:{customer_id}` | 代理人 Agent | A-01 资产概况缓存；权威副本在 L2 表 | +| `risk:dedup:{customer_id}:{rule_id}:{date}` | 风控 Agent | 内部防重复预警，别的 Agent 不读 | + +--- + +## 五、Milvus：完整对照表 + +| Collection | 档位 | 几个 Agent 用 | 干什么 | +| --- | --- | --- | --- | +| `kb_product_rules` | 🟡 **共用** | **客户 + 代理人** | 搜基金产品手册、交易规则（都要溯源） | +| `kb_business_ops` | ⚪ 专用 | **仅代理人** | 内部办事流程（定投、赎回到账等） | + +**底座建议**：先建 `kb_product_rules` 并导入产品文档；`kb_business_ops` 等代理人组开发时再建。 + +--- + +## 六、Neo4j：完整对照表 + +| 内容 | 档位 | 几个 Agent 用 | 干什么 | +| --- | --- | --- | --- | +| 整套 P0 图（Customer/Product/Advisor/RiskGrade + HOLDS 等关系） | 🟡 **共用** | **4** | 查「客户持有啥」「产品要什么风险等级」「归哪个代理人」 | + +**底座建议**：第二批与 MySQL 画像表一起建；数据从 Core **同步**，Agent 不往 Neo4j 写画像。 + +--- + +## 七、Core 只读接口（无表，但底座必接） + +| 数据 | 几个 Agent 用 | 说明 | +| --- | --- | --- | +| 正式客户信息、C1~C5 风险等级 | **4** | L0，Agent 库 **不建表** | +| 持仓、流水、交易 | **4** | 事实金额以 Core 为准 | +| 行情/净值 | 主要客户 Agent | 其他 Agent 按需 | + +--- + +## 八、搭建顺序检查表（复制即用） + +### 第一批：全员底座（Day 1） + +- [ ] MySQL：`agent_session` / `agent_message` / `agent_tool_call` / `audit_log` / `input_guard_log` / `customer_advisor_rel` +- [ ] Redis：`sess:*`、`guard:*` +- [ ] 平台 SDK：SessionService、AuditService、RBAC 校验（见 [02-JWT-RBAC鉴权手册.md](../../技术选型和版本/02-JWT-RBAC鉴权手册.md)） +- [ ] Core 只读 API 联调通过 + +### 第二批：跨 Agent 交换（Day 2~3） + +- [ ] MySQL：`customer_profile_l1` / `l2` / `l3` / `risk_alert` / `risk_suitability_log` +- [ ] Redis：`profile:l1/l2/l3`、`risk:pub:alert` +- [ ] Milvus：`kb_product_rules` + 首批产品文档入库 +- [ ] Neo4j：P0 节点关系 + Core 同步 Job + +### 第三批：各 Agent 专用（各组并行时自建） + +- [ ] 客户组：`customer_threshold_config`、`customer_notify_log` +- [ ] 代理人组：`advisor_draft`、`compliance_hit_log` + Milvus `kb_business_ops` +- [ ] 分析组：`analytics_query_log` +- [ ] 风控组：`risk:dedup`（可选，内部优化） + +--- + +## 九、一张矩阵：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 张表** + +--- + +## 十、SQL 文件怎么用 + +| 文件 | 内容 | 何时执行 | +| --- | --- | --- | +| [01-mysql-共用底座.sql](./01-mysql-共用底座.sql) | 🔴6 + 🟡5 = **11 张** | **并行开发前统一执行** | +| [02-mysql-agent专用.sql](./02-mysql-agent专用.sql) | ⚪ **5 张** | 各 Agent 组开发时执行（或一次性全建） | + +--- + +## 十一、和总览文档的关系 + +- 画像 L0/L1/L2/L3 含义 → [00-架构总览.md](./00-架构总览.md) 第四节 +- Redis / Milvus / Neo4j 字段细节 → `02`~`04` 号文档 +- JWT + RBAC 统一鉴权 → [02-JWT-RBAC鉴权手册.md](../../技术选型和版本/02-JWT-RBAC鉴权手册.md) +- 技术栈与版本 → [01-技术栈与版本.md](../../技术选型和版本/01-技术栈与版本.md) +- 业务需求来源 → `docs/需求拆解/` diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..477ffd6 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,22 @@ +# Core — versions aligned with docs/项目框架设计/技术选型和版本/01-技术栈与版本.md +fastapi>=0.115.0 +uvicorn[standard]>=0.32.0 +pydantic-settings>=2.6.0 + +# DB & cache +sqlalchemy>=2.0.36 +pymysql>=1.1.1 +redis>=5.2.0 +neo4j>=5.26.0 + +# Vector & LLM +pymilvus>=3.0.1 +langchain>=1.3.18 +langchain-openai>=1.6.0 +httpx>=0.28.0 + +# Auth (dev / gateway) +python-jose[cryptography]>=3.3.0 + +# Utils +python-multipart>=0.0.18