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 8.10.1 | :6379 |
| 图库 | 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 7 + AntD 5 + TS strict | 不用 Streamlit；`web/` 待 init |
| 对象存储 | 本地目录 `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 | **过渡版已实现**（`api/deps.py` debug 头 AuthContext + 归属断言 + 越权审计，B6；JWT 解析归 T-01，仅换工厂内部） |
| 客户财富 Agent | L1 画像、事实查询、阈值提醒 | Core RO、Milvus 产品库 | 空壳 service |
| 代理人助手 Agent | L2 画像、RAG、草稿 | L1 只读、Milvus | 空壳 service |
| 数据分析 Agent | NL→SQL→解读 | Core RO、画像只读 | 空壳 service |
| 风控监测 Agent | 预警、L3、R-02 适当性 | 交易事件、AML 名单 | **已实现**（B1~B7：rules/alert_service/profile_l3/aml_service/engine/scoring 占位 + 4 API + suitability + main 集成与挂账①~⑦） |
| Core 只读层 | L0 事实查询 | `jinrong_core` | **core_ro.py 已实现**（含风控扩展查询） |
| 共用底座 | 会话、审计、输入防护 | MySQL 11 表 + Redis | **部分接入**（风控审计落库 / Redis 推送已接；会话、全量审计中间件、输入防护待 T-02/T-03） |
| 同步脚本 | 归属、Neo4j | Core → agent / 图库 | **sync_*.py 已实现** |

------

## 3. 后端分层（app/）

```text
api/          → 风控 risk / simulate / deps 已实现（main 已挂载）；chat、knowledge、admin 空壳【部分】
service/      → risk/*（rules/alert/aml/engine/l3/scoring/locks/redis_gateway）+ suitability 已实现；
                agent_service、rag_service、memory_service 空壳                          【部分】
tool/         → document_parser、embedding_tool、milvus_tool                              【空壳】
repository/   → core_ro（Core 只读）+ risk_repository（风控四表）                         【已实现】
gateway/      → 模拟交易网关（trade_gateway + gateway_repository 仅 INSERT core_trade）   【已实现 B5】
model/        → schemas（Pydantic）、entities（ORM）                                      【占位】（风控暂用 dict，收敛待后续）
config/       → settings（双库 + risk_* 阈值）、database                                  【settings 已实现】
utils/        → trace / desensitize / db（引擎工厂）/ response（统一错误体）/ exceptions   【基本就绪；logger 占位】
main.py       → 路由挂载 + trace 中间件 + lifespan（B7）                                  【已集成】

允许：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 包）：**

```text
scripts/core/       → jinrong_core DDL + 种子 + reset.ps1
scripts/agent/      → jinrong_agent 种子（risk_aml_list AML 名单等）
scripts/demo/       → 演示数据准备（prepare_risk_demo.sql，reset 后重跑）
scripts/sync/       → sync_advisor_rel.py、sync_neo4j.py
scripts/dev/        → rbac-seed-reference.md（联调账号）
```

------

## 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](../业务记忆管理/业务记忆管理手册.md)