XingHuo/docs/memory/FLOW.md

实现流程

To-Be 端到端链路；As-Is 见 ENVIRONMENT.md
画像分层见 docs/项目框架设计/表设计/06-用户画像L1-L3设计.md · 适当性见 07-risk_suitability_log说明.md

---

0. 本地 bootstrap（新环境 / 新 Agent）

前置：MySQL 8、Redis、Neo4j Desktop、Ollama(bge-m3) 已安装并启动

① 配置
   cp .env.example .env
   必填：MYSQL_PASSWORD、NEO4J_PASSWORD、DEEPSEEK_API_KEY（对话阶段）

② 依赖
   pip install -r requirements.txt

③ Core 模拟库（L0）
   .\scripts\core\reset.ps1
   → 创建 jinrong_core + **33 客户** / **14 产品** / 持仓交易种子（含 CUST-DEMO-* 手册示范）

④ Agent 共用底座（若库未建）
   mysql -u root -p < docs/项目框架设计/表设计/01-mysql-共用底座.sql

⑤ 同步
   python scripts/sync/sync_advisor_rel.py   → customer_advisor_rel
   python scripts/sync/sync_neo4j.py         → 关系图

⑥ 验证
   uvicorn app.main:app --reload
   GET http://127.0.0.1:8000/health  → {"status":"ok"}
   （可选）Python 调 CoreReadOnlyRepository.get_customer_l0("CUST-10001")

RBAC 联调账号：scripts/dev/rbac-seed-reference.md

尚未自动化： agent 专用表 SQL、Milvus 建 Collection、JWT 中间件 — 见 TODO.md。

---

1. 链路总览（目标）

Client → Gateway(JWT/RBAC) → api/chat → agent_service(LangGraph) → Tools → 存储 → 响应 + audit_log

当前：main.py 仅 health；全链路待 Wave 0 起逐步挂载。

---

2. 主链路 · 对话

输入：Authorization + X-Agent-Type + X-Trace-Id + 用户消息
↓
Gateway：验签、角色准入、注入 AuthContext                    【待做 T-01】
↓
api/chat：SessionGuard；创建/续 agent_session               【待做】
↓
memory_service：Redis 读最近 N 轮；异步写 agent_message     【待做】
↓
agent_service：LangGraph StateGraph + DeepSeek；按 Agent 类型选 Tool 节点  【待做】
↓
Tool 示例：
  - CoreReadOnlyRepository：持仓/流水/L0 + check_suitability（R-02 计算）  【Repository 已有，Tool 未接】
  - model/suitability：check → risk_suitability_log 行映射              【已实现，风控 service 未接】
  - milvus_tool：产品规则 RAG + source_refs                   【待做】
  - memory_service：读/写 L1/L2/L3（ProfileGuard）              【待做】
  - 风控 service 账号：R-02 适当性 → check_suitability + INSERT log（无会话）  【待做】
↓
输出：assistant 消息 + has_disclaimer（客户/对外）
↓
落库：agent_message、agent_tool_call、audit_log（同 trace_id）

---

3. 主链路 · 知识库入库

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
Core RO	customer_id + product_id?	L0/持仓/流水；适当性判定 dict	只读 jinrong_core；R-02 见 07 文档
适当性落库	check_suitability 输出	risk_suitability_log 行	build_suitability_log_row
审计	任意判定	audit_log INSERT	不可删改

---

6. 关键数据约定

• Agent 库 SQL：docs/项目框架设计/表设计/01-mysql-共用底座.sql、02-mysql-agent专用.sql
• 画像 L1/L2/L3：docs/项目框架设计/表设计/06-用户画像L1-L3设计.md
• 适当性 log：docs/项目框架设计/表设计/07-risk_suitability_log说明.md
• Core 模拟：scripts/core/01-ddl.sql · 说明 docs/项目框架设计/Core模拟底座/01-表结构与种子说明.md
• Redis Key：docs/项目框架设计/表设计/02-redis-keys.md
• Milvus：kb_product_rules、kb_business_ops；向量 1024 维
• 禁止：Agent 覆盖 L0 正式 C1~C5