group_xinghuo_jinrong/docs/memory/FLOW.md

# 实现流程

> To-Be 端到端链路；As-Is 见 `ENVIRONMENT.md`  
> 画像分层见 `docs/项目框架设计/表设计/00-架构总览.md`

------

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

```text
前置：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 + 28 客户 / 12 产品 / 持仓交易种子
   （风控演示：再执行 scripts/demo/prepare_risk_demo.sql 刷新测评日期 · PRD §10.2）

④ Agent 共用底座（若库未建）
   mysql -u root -p < docs/项目框架设计/表设计/01-mysql-共用底座.sql
   （风控：再建 02-mysql-agent专用.sql 的 risk_aml_list + 灌 scripts/agent/seed-aml-list.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
```

**尚未自动化：** Milvus 建 Collection、JWT 中间件（现 `api/deps.py` debug 头过渡，T-01 就绪换工厂内部）— 见 `TODO.md`；agent 专用表已有 `02-mysql-agent专用.sql`（手工执行，含 risk_aml_list）。

------

## 1. 链路总览（目标）

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

当前：**风控事件线已集成 + 测试基建完成**（交易网关 → 规则引擎 → 预警/AML/L3 → 4 API，`main.py` 路由挂载 + trace 中间件 + lifespan 完成，B1~B8；B8 = conftest 演示数据校验 + 集成测试 A-1~A-5/A-7/A-9 + `tests/_ddl.py` DDL 单一事实源；B7/B8 均经独立 AI 评审闭环；B9a = subscribe_alerts/rebuild_alerts 演示与补偿脚本；B9b = 演示走查 + B6/B7/B8 核查单①~⑥收口（disclaimer/aml scan 幂等/集成测试前置断言），演示 SOP 见 docs/项目框架设计/演示SOP-风控模块.md；B9b 复审有条件通过→闭环：P2-1 SOP 交互重灌补 DROP agent / P2-2 补做 T-31 名下 P2-8 手工 SQL 对照收口 / P2-3 走查口径统一，209 测试绿，M2 tag risk-m2）；阶段 B 完结；对话链路待 T-01/T-07。

**本机已就位状态（2026-09-07 更新 · 已完成上述 ①~⑤，无需重做）：** `.env` 已配置（学习项目，`MYSQL_PASSWORD=123456`；NEO4J/DEEPSEEK 留空暂不影响风控）；`jinrong_core` + `jinrong_agent` 已灌库（28 客户 / AML 名单 8 条 / 演示测评已刷新 / 归属同步 28 行）；`python -m pytest` 209 用例（重灌后全绿；集成测试真连本机 MySQL，未灌库的机器自动 skip 集成模块。**演示库当前含 B9b 走查残留，跑集成前先按演示 SOP §2 重灌**——核查单⑥前置断言会对残留数据显式 fail）；本机 Redis 服务在跑（`redis://127.0.0.1:6379/0`，B9a 订阅脚本已验证）。

**本机已知坑：** `mysql.exe` 不在 PATH（位于 `C:\Program Files\MySQL\MySQL Server 8.0\bin`）；`reset.ps1` 的交互式 `-p` 在自动化执行时会卡死——脚本化重灌用 `MYSQL_PWD` 环境变量传密码（交互执行不受影响，不把密码写进仓库脚本）；`redis` 包 requirements 有但初始 `pip install -r` 漏装（B9a 于 2026-09-07 补装，重装环境时留意）。

------

## 2. 主链路 · 对话

```text
输入：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（自动注入 customer_id）  【Repository 已有，Tool 未接】
  - 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 |
| Core RO | customer_id | L0/持仓/流水 | 只读 jinrong_core |
| 审计 | 任意判定 | audit_log INSERT | 不可删改 |

------

## 6. 关键数据约定

- Agent 库 SQL：`docs/项目框架设计/表设计/01-mysql-共用底座.sql`、`02-mysql-agent专用.sql`
- 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