GaoYiYuan_0626
f056fcd007
AIcoding 第 5 步 todo 开发（开发计划 v2.0）前半段： - T-1 3 张新表 DDL（core_convert_request 6 态 ENUM / core_trade_calendar / core_share_rule）+ 种子 + sqlite 单一事实源同步 + 列清单断言 - T-2/T-2b calc 扩展（product_round/redeem_amount/partial_qty）+ 真实净值实算回填 - T-3 convert_request_repository（6 态 + 条件 UPDATE 守卫）+ core_ro 三读方法 + share_lot_repository.available_qty_with_inflight（R-3 在途占用推导） - T-4 convert_repository.sync_mirror 成为 risk_convert_detail 唯一进度镜像写入口 （旧三方法标 Deprecated，T-7 后删） - T-5 locks.py 锁键构造器 convert_req_lock_key / convert_confirm_lock_key - T-6 convert_service.accept_convert 受理事务（八步：锁→幂等→校验→受理日顺延 →在途占用校验→落单→镜像+审计→202；不扣份额/不折算/不写流水） + tests/test_convert_accept.py（16 用例） + scripts/dev/verify_convert_accept.py（真库 36/36 一致） + trading_calendar.py 纯函数包（R-5）+ 21 用例 T-6 真库实测暴露并修复：confirm_eta 在日历数据边界抛 ValueError，会让已落库 的受理单在调用方眼里变 500；改为展示性字段容错 + 单测守护。 基线：798 passed / 10 skipped，零回归。
106 lines
7.4 KiB
Markdown
106 lines
7.4 KiB
Markdown
# 项目框架
|
||
|
||
> 选型详情：`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 | **已实现（T-01，2026-09-07）**：`service/auth_service.py`（验签/吊销）+ `api/deps.py`（Bearer 全环境优先 + dev debug 头兜底 + AGENT_ACCESS_MATRIX 准入） |
|
||
| 客户财富 Agent | L1 画像、事实查询、阈值提醒 | Core RO、Milvus 产品库 | 空壳 service（chat 骨架已通） |
|
||
| 代理人助手 Agent | L2 画像、RAG、草稿 | L1 只读、Milvus | 空壳 service（chat 骨架已通） |
|
||
| 数据分析 Agent | NL→SQL→解读 | Core RO、画像只读 | 空壳 service（chat 骨架已通） |
|
||
| 风控监测 Agent | 预警、L3、R-02 适当性 | 交易事件、AML 名单 | **已实现 B1~B7 + C1~C3（对话线四 Tool + risk 分支 StateGraph，A-6 验收）**；追加 FR-8/9/10（C4~C6：集中度/时效升级/行为链）方案已定稿待编码 |
|
||
| **基金转换（convert）交易** | 转出赎回 + 转入申购、逐批次计费、补差费、批次维护 | Core 写（仅 `app/gateway/`）、`core_share_lot` 批次表、规则引擎 | ✅ **v0.x 两阶段实时模型已实现（T-0 ~ T-13 全部完成 · 2026-09-10，739 passed / 10 skipped）**；**下一线 T+1 受理/确认分离模型（2026-09-11 进行中）**：PRD **v1.1** + 架构 **v2.1** 已整体重写并通过独立 AI 联网审查（已定稿 2026-09-11）+ 开发计划 **v2.0** 已重做并经三轮独立审核闭环（已定稿 → 第 5 步 todo 开发进行中 T-1~T-6 ✅，下一步 T-7）；入口 项目根 `交接文档.md` §B.11 |
|
||
| 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 | **已实现（T-07 骨架 + T-04 Tool 节点 + C1 风控四 Tool + C5 追加 query_overdue_alerts 共五只 + C2 risk 分支）**：tool（分组关键词意图→Tool，customer/advisor/risk）→llm→guard（免责声明）；analyst 分支与 LLM intent 待后续 |
|
||
| 同步脚本 | 归属、Neo4j | Core → agent / 图库 | **sync_*.py 已实现** |
|
||
|
||
------
|
||
|
||
## 3. 后端分层（app/）
|
||
|
||
```text
|
||
api/ → risk / simulate / chat / deps / 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 → 路由挂载 + trace 中间件（双 ID 贯通 + 500 兜底）+ audit 中间件 + lifespan（B7/T-02） 【已集成】
|
||
|
||
允许：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 后重跑）+ 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/ → （C5/C6 规划）escalation_scan.py / agent_behavior_scan.py 定时任务
|
||
```
|
||
|
||
------
|
||
|
||
## 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)
|