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，零回归。
128 lines
8.0 KiB
Markdown
128 lines
8.0 KiB
Markdown
# 实现流程
|
||
|
||
> 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
|
||
```
|
||
|
||
**尚未自动化：** 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
|
||
```
|
||
|
||
当前：**风控事件线（B1~B9b）+ Wave 0 共用底座 + 风控阶段 C（C1~C3 对话线，tag risk-m2/risk-m3）+ T-04 Tool 节点 + T-03 输入防护 + T-21 知识库全部完成**（交易网关 → 规则引擎 → 预警/AML/L3 → 4 API，`main.py` 路由挂载 + trace 中间件 + audit 中间件 + lifespan；T-01/T-02/T-06/T-07/T-04/T-03/T-21 均经独立 AI 评审闭环）。**阶段一「对齐 main 基准」AL-01~AL-08 已完成（2026-09-07，406 测试绿；适当性判定换核 core_ro.check_suitability，risk_suitability_log 21 列，Core 表 is_hnw/风评 expires_at 新列，种子 33 客户/14 产品）**。**下一步：阶段一验收门（用户目视确认）→ AL-09 合并 main → 阶段二 C4~C6 编码**（FR-8 集中度/FR-9 时效升级/FR-10 代理人行为链，实现方案《docs/项目框架设计/实现方案-风控追加需求v1.1-C4C6.md》已定稿并经独立 AI 评审修订闭环，含定时任务 scripts/cron/* 与新增对话 Tool；编码未开始）。**并行线：基金转换下一线（T+1 受理/确认分离模型，2026-09-11 进行中）——PRD v1.1 / 架构 v2.1 / 开发计划 v2.0 已整体重写并经独立审查收敛，已定稿 → 第 5 步 todo 开发进行中（T-1~T-6 ✅，797 绿，下一步 T-7），开工入口 交接文档.md §B.11**。
|
||
|
||
**本机已就位状态（2026-09-07 更新 · 已完成上述 ①~⑤，无需重做）：** `.env` 已配置（学习项目，`MYSQL_PASSWORD=123456`；NEO4J/DEEPSEEK 留空——DEEPSEEK_API_KEY 空时 chat 走降级回复，不阻塞演示；`.env` 无 JWT 项，签发走默认 `JWT_DEV_SECRET`，**启动时出现默认密钥 warning 属预期**，生产形态须配 `JWT_PUBLIC_KEY_PATH`）；`jinrong_core` + `jinrong_agent` 已灌库（**阶段一 AL-01/AL-08 后为 33 客户/14 产品/矩阵 25 行/风评 33** / AML 名单 8 条 / 演示测评 expires_at 新口径已刷新 / 归属同步 33 行）；`python -m pytest` **406** 用例全绿（集成测试真连本机 MySQL，未灌库的机器自动 skip 集成模块；pytest 依赖装在系统 Python 3.13.14）；**演示库已按阶段一新口径重灌并清理冒烟数据（2026-09-07），全量测试可直接跑，下次演示/走查后再按 SOP §2 重灌**；本机 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` 与 `python-jose[cryptography]` 包均出现过 requirements 有而环境漏装（B9a 补装 redis、Wave 0 补装 jose，2026-09-07），重装环境后先 `python -c "import jose, redis"` 自检**。
|
||
|
||
------
|
||
|
||
## 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：query_overdue_alerts(C5 追加)/alert_query/customer_context/suitability_check/aml_lookup 【RISK_TOOL_REGISTRY 现 5 个】
|
||
- 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）
|
||
```
|
||
|
||
------
|
||
|
||
## 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` · 说明 `docs/项目框架设计/Core模拟底座/01-表结构与种子说明.md`
|
||
- Redis Key：`docs/项目框架设计/表设计/02-redis-keys.md`
|
||
- Milvus：`kb_product_rules`、`kb_business_ops`；向量 **1024** 维
|
||
- 禁止：Agent 覆盖 L0 正式 C1~C5
|