group_xinghuo_jinrong/docs/memory/FRAMEWORK.md

项目框架

选型详情：docs/项目框架设计/技术选型和版本/01-技术栈与版本.md
表设计：docs/项目框架设计/表设计/
鉴权：docs/项目框架设计/技术选型和版本/02-JWT-RBAC鉴权手册.md
Core 模拟：docs/项目框架设计/Core模拟底座/

---

1. 技术选型（已定）

技术栈	已定（用户已同意）	备注
后端语言/框架	Python 3.13.14 + FastAPI	系统 Python
Agent 编排	LangGraph 1.2.x + langchain-core / langchain-openai 1.6.0	DeepSeek API；StateGraph + Tool 节点
关系库	MySQL 8.0.46	双库：jinrong_agent + jinrong_core
缓存	Redis 7（Docker redis:7-alpine）	宿主机 6380→容器 6379 · .env REDIS_URL=redis://127.0.0.1:6380/0 · scripts/dev/start-redis.ps1
图库	Neo4j 5.26.19 Enterprise	Desktop；sync_neo4j.py 灌图
向量库	Milvus Lite + pymilvus 3.0.1	本地 ./data/milvus.db；1024 维
Embedding	Ollama bge-m3	本地，不出内网
LLM 生成	DeepSeek API	对话/推理
前端	React 19 + Vite 8 + AntD 6 + Tailwind CSS v4 + TS strict	web/ P0 主链路已真接（ChatPanel · 四 Agent 对话 · 平台只读 · 行情 · 风控台账）；见 docs/frontend/FRONTEND-HANDOFF.md
对象存储	本地目录 data/kb/	不用 MinIO
部署	Windows 原生	Docker 仅答辩备选

不用：MinIO（日常）、Docker 日常开发、Streamlit、Agent 互调 LLM
取舍：内存 15.4GB → Milvus Lite 替代 Docker Milvus 三容器

---

2. 能力模块

模块	职责	依赖	代码状态
Agent Gateway / Auth SDK	JWT、RBAC、归属校验	Redis、MySQL customer_advisor_rel	已实现（T-01 + AL-09）：模块 service/auth_service.py + api/deps.py；宿主 gateway/ 四件套并存；/api/auth/login 统一走 issue_dev_token；S2 接缝 auth_adapter.module_auth_from_host
客户财富 Agent	L1 画像、事实查询、阈值提醒	Core RO、Milvus 产品库	S2 + Wave3（2026-09-11）：Chat SSE · 1B/R1 · C-04/C-05/C-11
代理人助手 Agent	L2 合规文案 · 复制门闸 · 话术 · 异动 · KYC	L1 只读、Milvus 话术向量	接缝已挂（integrate/advisor-agent · 2026-09-12）：/api/advisor-agent/* · advisor_auth_adapter · script_template_* / entities_advisor · LangGraph 深编排 / T-20 仍 open · sprint 集成测 未全绿
数据分析 Agent	NL→SQL→解读	Core RO、画像只读	S3+D-06（2026-09-12）：match_phrases · 内置 few-shot · /analyze · /template-prompts
风控监测 Agent	预警、L3、R-02 适当性	交易事件、AML 名单	已实现 B1B9b + C1C6（FR-1~10） + TEST-RISK-001 修复；AL-09 已并入 merger 分支
Core 只读层	L0 事实查询	jinrong_core	已实现 + 已接对话 Tool（T-04）：core_ro 经 app/tool/core_tools.py 三只读 Tool（L0/持仓/流水）进 chat；风控扩展查询照旧
共用底座	会话、审计、输入防护	MySQL 11 表 + Redis	已接入（2026-09-07）：会话（T-06 session_repository + memory_service 窗口）、审计中间件（T-02 http_access + input_guard_log 双写）、agent_tool_call Tool 留痕（T-04）、输入防护（T-03 input_guard：注入词表纯函数检测 + oversize + Redis 固定窗口限流，chat 链路 限流→注入/超长→归属）
对话编排	LangGraph StateGraph + DeepSeek	langgraph/langchain-openai	已实现：customer/advisor/risk/analyst 四线；analyst 问数独立 analyst_agent（非 chat StateGraph）
同步脚本	归属、Neo4j	Core → agent / 图库	sync_*.py 已实现
前端 Demo（web/）	四角色工作台、平台读 UI、Chat	FastAPI v0.1 + chat B/C	P0 Demo（2026-09-12）：问数常用问法/标星 · 分析助手 Modal · 27 Vitest

---

3. 后端分层（app/）

api/          → auth / risk / simulate / chat / **analyst** / **advisor-agent（advisor_compliance · advisor_script_templates · kyc · market · copy · guard · dashboard · allocation）** / deps / auth_adapter / audit_middleware 已实现；knowledge、admin 空壳   【大部分】
service/      → risk/*（rules/alert/aml/engine/l3/scoring/locks/redis_gateway/chat_tools）+ suitability +
                auth_service（T-01 JWT）+ agent_service（T-07 图 + T-04 tool 节点 + C2 risk 分支）+ memory_service（T-06）+
                tool_service（T-04 对话 Tool 编排：意图/归属校验/run_tool 落库）+ input_guard（T-03）+
                embedding/milvus_service/rag_service（T-21，已实现）                              【大部分】
tool/         → core_tools（T-04：L0/持仓/流水只读 Tool + TOOL_REGISTRY 白名单）+
                kb_tools（T21-5：search_knowledge，RISK/KB 注册表第三层）已实现；
                document_parser、embedding_tool、milvus_tool（早期占位壳，T-21 实现在 service 层）  【部分】
repository/   → core_ro（Core 只读）+ risk_repository（风控四表+审计双写）+
                session_repository（agent_session/agent_message/agent_tool_call，T-06/T-04）      【已实现】
gateway/      → 模拟交易网关（trade_gateway + gateway_repository 仅 INSERT core_trade）   【已实现 B5】
model/        → schemas（Pydantic）、entities（ORM）                                      【占位】（风控暂用 dict，收敛待后续）
config/       → settings（双库 + risk_* 阈值 + JWT 配置）、database                        【settings 已实现】
utils/        → trace（trace_id+request_id）/ desensitize / db（引擎工厂）/ response（统一错误体）/ exceptions   【基本就绪；logger 占位】
main.py       → 宿主 TraceMiddleware + 模块 audit/trace 中间件 + 路由挂载 + lifespan（AL-09）；trace 对 ApiError 等 re-raise   【已集成】

允许：api → service → tool / repository / model / config
禁止：api 直连 Milvus/MySQL 写复杂逻辑；tool 写业务流程；repository 写 Core
例外：app/gateway/ 为模拟外部系统模块（PRD v1.0），仅 gateway_repository
      可 INSERT jinrong_core.core_trade；生产环境由真实交易系统回调替代

脚本（非 app 包）：

scripts/core/       → jinrong_core DDL + 种子 + reset.ps1
scripts/agent/      → jinrong_agent 种子（risk_aml_list）· **migrate-advisor-agent-sprint1-3.sql** · import_compliance_rules / import_script_templates
scripts/demo/       → 演示数据准备（prepare_risk_demo.sql，reset 后重跑）+ subscribe/rebuild_alerts
scripts/sync/       → sync_advisor_rel.py、sync_neo4j.py
scripts/dev/        → issue_dev_token.py（JWT 签发）+ rbac-seed-reference.md（联调账号）
scripts/kb/         → build_kb.py（知识库入库，T-21）
scripts/cron/       → escalation_scan.py / agent_behavior_scan.py（C5/C6 定时任务，独立脚本非 lifespan 内嵌）

---

4. 数据分层（跨模块）

层	存储	说明
L0	jinrong_core 只读	正式 C1~C5、持仓、流水（模拟）
L1/L2/L3	MySQL 画像表（agent 库）	客户/代理人/风控 enrich
会话	Redis + MySQL	窗口 + 永久审计
RAG	Milvus + data/kb/	kb_product_rules 等
关系	Neo4j	客户-产品-代理人（Core 同步）

---

5. 骨架一句话

Gateway 鉴权 → FastAPI api → service（LangGraph）→ tool/repository → MySQL/Redis/Milvus/Neo4j/Core → 审计落库。

记忆分层详解： 业务记忆管理手册.md