zhanghongyu_0626
2b4eaa9725
- Added `list_nav_history` method in `CoreReadOnlyRepository` to retrieve historical NAV data for products over a specified number of days. - Introduced `get_nav_history` endpoint in `product_service` to return historical NAV sequences, improving product data accessibility. - Updated `products.py` to include new API endpoint for fetching NAV history, ensuring compliance with access control. - Enhanced `ready.py` to include a health check for the new functionality, ensuring system readiness. - Updated documentation to reflect the new testing baseline of 833 passed tests, indicating improved stability and functionality across the application. This update significantly enhances the product API by providing access to historical NAV data, improving user insights into product performance.
155 lines
7.7 KiB
Markdown
155 lines
7.7 KiB
Markdown
# 实现流程
|
||
|
||
> To-Be 端到端链路；As-Is 见 `ENVIRONMENT.md`
|
||
> 画像分层见 `docs/项目框架设计/表设计/00-架构总览.md`
|
||
|
||
------
|
||
|
||
## 0. 本地 bootstrap（新环境 / 新 Agent）
|
||
|
||
```text
|
||
前置：MySQL 8、**Docker Desktop（Redis + 可选 Neo4j compose）**、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 + 客户/产品/持仓/交易 + **07 净值历史（14×365 日）**
|
||
（风控演示：`.\scripts\demo\prepare_all.ps1` 或 `prepare_risk_demo.sql` · PRD §10.2）
|
||
|
||
④b 数据分析问数（可选）
|
||
mysql … < scripts/agent/migrate-analyst-d07-d11.sql # 若未建 analyst 资产表
|
||
mysql … < scripts/agent/seed-analyst-metric-dict.sql
|
||
mysql … < scripts/agent/seed-analyst-query-templates.sql # 模板缓存演示
|
||
|
||
④ 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 → 关系图（需 compose neo4j 或 Desktop）
|
||
|
||
⑤b Redis（推荐 Docker）
|
||
docker compose up -d redis
|
||
# 或 .\scripts\dev\start-redis.ps1
|
||
# .env: REDIS_URL=redis://127.0.0.1:6380/0 （避开本机 Windows Redis 占 6379）
|
||
|
||
⑥ 验证
|
||
uvicorn app.main:app --reload
|
||
GET http://127.0.0.1:8000/health → {"status":"ok"}
|
||
GET http://127.0.0.1:8000/api/ready → Redis + 路由自检（前端 DevReadyBanner）
|
||
cd web && npm run dev → 5173 代理 8000
|
||
python -m pytest → 825 passed 1 skipped
|
||
问数答辩前：见 `docs/答辩/DEMO-SOP-答辩全流程.md` · 问数分册 `DEMO-SOP-问数.md`（`scripts/dev/seed_analyst.ps1` · battery 可选）
|
||
|
||
RBAC 联调账号：scripts/dev/rbac-seed-reference.md
|
||
```
|
||
|
||
**尚未自动化：** agent 专用表已有 `02-mysql-agent专用.sql`（手工执行，含 risk_aml_list）；Milvus 建 Collection 已随 T-21 自动化（`scripts/kb/build_kb.py` 可重灌）。JWT 中间件已完成（T-01：`app/service/auth_service.py` + `deps.py` 工厂；dev 联调签发 `scripts/dev/issue_dev_token.py`，debug 头兜底仅限 development 且未配 RS256 公钥）。
|
||
|
||
------
|
||
|
||
## 1. 链路总览（目标）
|
||
|
||
```text
|
||
Client → Gateway(JWT/RBAC) → api/chat → agent_service(LangGraph) → Tools → 存储 → 响应 + audit_log
|
||
```
|
||
|
||
当前：**风控全链路 + Wave 0 共用底座 + 代销平台 v0.1 + AL-09 + 客服 S2 Wave3 + 数据分析 D-06/N-03/N-07 + 前端 P0 Demo（2026-09-11，`merger`）**。**测试基线：`python -m pytest` → 825 passed 1 skipped** · **`web/` 22 Vitest 绿 · `npm run build` 绿**。
|
||
|
||
**下一步（统筹 P1）：** merger commit · 20 题 battery · 客服/风控 E2E 详测 · analyst **D-09 多轮** · **客服** L2 Redis（风控不做 L1/L2）。
|
||
|
||
**本机已就位状态（2026-09-11）：** `.env` 含 `REDIS_URL=redis://127.0.0.1:6380/0`；pytest **825 绿**；问数 D-06 + sample/escalate；`GET /api/ready`；前端四角色 Demo 可 walkthrough。
|
||
|
||
**本机已知坑：** `mysql.exe` 不在 PATH；`reset.ps1` 自动化用 `MYSQL_PWD`；**6379 常被 Windows Redis 3.x 占用** → 项目 Docker 映射 **6380**；Milvus 中文路径需英文 `MILVUS_URI`；问数模板需灌 `seed-analyst-query-templates.sql` 才见蓝色「模板命中」标签；`battery_report.json` **不入库**（`.gitignore`）。
|
||
|
||
------
|
||
|
||
## 2. 主链路 · 对话
|
||
|
||
```text
|
||
输入：Authorization + X-Agent-Type + X-Trace-Id + 用户消息
|
||
↓
|
||
Gateway：验签、角色准入、注入 AuthContext 【T-01 已做】（JWT 验签/吊销 + AGENT_ACCESS_MATRIX）
|
||
↓
|
||
输入防护：限流（429）→ 注入/超长（400） 【T-03 已做】（Redis 固定窗口 30 次/分 fail-open；被拒 fail-fast 不建会话，blocked 落 input_guard_log）
|
||
↓
|
||
api/chat：SessionGuard；创建/续 agent_session 【T-06 已做】（actor/agent_type 一致校验）
|
||
↓
|
||
memory_service：Redis 读最近 N 轮；MySQL 落盘 agent_message 【T-06 已做】（窗口 TTL2h N≤20，miss 回源；同步落盘）
|
||
↓
|
||
agent_service：LangGraph StateGraph + DeepSeek；tool(意图→Tool) → llm → guard 【T-04 + C2 已做（分组关键词意图 customer/advisor/risk；risk 分支接 C1 四 Tool）】
|
||
↓
|
||
Tool（tool_service.run_tool：白名单 → 归属校验 → 执行 → agent_tool_call 落库）：
|
||
- CoreReadOnlyRepository：持仓/流水/L0（customer_id 由会话注入，不来自 LLM） 【T-04 已做 app/tool/core_tools.py 三 Tool】
|
||
- 风控四 Tool：alert_query/customer_context/suitability_check/aml_lookup 【C1 已做 chat_tools（RISK_TOOL_REGISTRY）】
|
||
- milvus_tool：产品规则 RAG + source_refs 【已做 T-21（app/tool/kb_tools.py + rag_service/milvus_service；仅 customer/advisor 意图开放）】
|
||
- memory_service：读/写 L1/L2/L3（ProfileGuard） 【窗口读写已做；画像读写待做】
|
||
↓
|
||
输出：assistant 消息 + has_disclaimer（customer/risk 固定免责，T-07 guard 节点）
|
||
↓
|
||
落库：agent_message、agent_tool_call（T-04 已接：success/blocked/error 全留痕，message_id 一期 NULL）、audit_log（http_access 已接，同 trace_id）
|
||
```
|
||
|
||
**客户线并行分支（`X-Agent-Type: customer` · 2026-09-10）：**
|
||
|
||
```text
|
||
api/chat 或 /stream → auth_adapter → customer_service.run_customer_chat（14 节点 LangGraph）
|
||
→ intent_classify（关键词优先：数据查询 > save_note > nav/匹配）
|
||
→ core_ro_tool（持仓/流水/风评/适当性/净值）或 fin_* RAG 或 reject/transfer
|
||
→ interpret/generate/chitchat → sanitize_postprocess.finalize_sanitized_reply（1B）
|
||
→ profile_maybe_extract → threshold_service.sync（C-04 摘要写 config）
|
||
→ query_holdings 末尾 build_threshold_alert（达线追加提醒 + customer_notify_log）
|
||
SSE：prepare_customer_stream 整图跑完再 _chunk_reply_text 推块
|
||
```
|
||
|
||
------
|
||
|
||
## 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 + input_guard_log 双写（401 归 platform） |
|
||
| 会话 | session_id | Redis ctx + MySQL session | actor_id 一致（AUTH_403_SESSION_AGENT） |
|
||
| 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 | 不可删改；http_access 经 audit 中间件 |
|
||
|
||
------
|
||
|
||
## 6. 关键数据约定
|
||
|
||
- Agent 库 SQL：`docs/项目框架设计/表设计/01-mysql-共用底座.sql`、`02-mysql-agent专用.sql`
|
||
- Core 模拟：`scripts/core/01-ddl.sql` · **`07-seed-nav-history.sql`** · 说明 `docs/项目框架设计/Core模拟底座/01-表结构与种子说明.md`
|
||
- Redis Key：`docs/项目框架设计/表设计/02-redis-keys.md`
|
||
- Milvus：`kb_product_rules`、`kb_business_ops`；向量 **1024** 维
|
||
- 禁止：Agent 覆盖 L0 正式 C1~C5
|