group_xinghuo_jinrong/docs/项目框架设计/理财顾问Agent-合并说明.md

投资顾问 Agent · 从 advisor-agent 合并说明

日期：2026-09-12
源分支：xinghuo/advisor-agent @ 68df13c（Sprint0~3 后端 MVP · 101 pytest）
目标分支：merger（AL-09 宿主 + 客服 / 风控 / 问数已接线）
状态：已合入 merger（2026-09-12 · fast-forward） — OpenAPI 62 路径 · Sprint0 冒烟绿 · test_sprint* 约 65 红（缺本机迁移/模板 seed/Milvus 等）· 后续以本文 + plan 为准。

---

0. 已拍板决策（2026-09-12）

#	决策	结论
D1	API 前缀与契约	以 merger / 代销平台 API v0.1 为准；不保留 /api/v1/* 对外形态
D2	冲突文件	只增不盖；与 merger 同路径冲突时 保留 merger（同客服 / 问数合并说明）
D3	顾问侧命名	迁入代码 按 merger 习惯重命名（见 §2）；禁止覆盖问数 template_service、平台 compliance
D4	集成方式	新增投资顾问 Agent + 接缝；不接顾问独立 main.py / 第二套 JWT
D5	验证顺序	先接线 → 再跑全量 pytest；Neo4j 以本机 Docker 已就绪为前提
D6	图库	复用 merger 已有 scripts/sync/sync_neo4j.py / sync_advisor_rel.py，不迁入顾问分支重复同步实现
D7	HTTP 前缀	已定稿： /api/advisor-agent/*（2026-09-12 确认）
D8	演示 UI	不迁入 源分支 demo_ui/ · 不挂载 /demo StaticFiles（2026-09-12 确认）
D9	管理/审计 API	第一批不迁入 源分支 admin/audit-logs（2026-09-12：风控侧页面已覆盖合规查看诉求；见 §2.1）

---

1. 一句话定位

投资顾问 Agent = 顾问工作台后端线（合规文案检测 · 复制门闸 · 话术模板 · 市场异动 · KYC 采集），与：

• 平台 API（/api/advisors/* 归属 · /api/compliance/suitability-check 适当性）
• 通用对话线（POST /api/chat + X-Agent-Type）
• 问数线（/api/analyst/*）

并行存在。合并时 不替换 main.py 骨架、不覆盖 auth_service.py、不把 KYC 硬塞进 chat.py（与问数 §3.1 双轨理由相同：响应形态与审计字段不同）。

---

2. 重命名与路径对照（advisor → merger）

2.1 HTTP：废弃 /api/v1，统一业务域前缀

推荐对外前缀： /api/advisor-agent（单数 advisor + agent，与平台复数 /api/advisors 区分，避免路由与文档歧义）。

中文职责	源分支挂载（勿保留）	合并后 canonical 路径（kebab-case）
顾问文案合规检测与规则库	/api/v1/compliance/*	/api/advisor-agent/compliance/content-check · .../compliance/rules · .../compliance/rules/{rule_id}
复制追踪门闸	/api/v1/copy/track	POST /api/advisor-agent/copy/track
话术模板 CRUD / 检索 / 引用	/api/v1/templates/*	/api/advisor-agent/script-templates/*
市场异动扫描 / 解读 / 反馈	/api/v1/market-alerts/* · /api/v1/market/*	/api/advisor-agent/market-alerts/* · /api/advisor-agent/market/*
KYC 会话与采集对话	/api/v1/kyc/*	/api/advisor-agent/kyc/sessions · .../chat · .../complete
输入防护探测	/api/v1/guard/*	/api/advisor-agent/guard/check
顾问看板（个人/全局）	/api/v1/dashboard/*	/api/advisor-agent/dashboard/*
资产配置（当前 stub）	/api/v1/allocation/*	/api/advisor-agent/allocation/*
审计日志只读列表	/api/v1/admin/audit-logs	不迁入（D9）

D9 说明（与风控页面的关系）：

• merger 风控菜单已给合规/风控可看、可操作的 业务留痕面：例如 预警台账（RiskAlertsPage · compliance 角色看 AML 单并处置）、适当性检查 / AML 扫描（操作结果写 audit_log / 业务表，页面上体现为「留痕」说明）。
• 源分支 GET /admin/audit-logs 是 整张 audit_log 的通用翻页列表，merger 前端目前没有对应页；与上述风控台账 用途重叠（合规日常看单），不是 MVP 合并必带。
• 投资顾问线 仍须写 共用 audit_log（合规检测 · KYC · 复制门闸等），与风控/问数 同表；日后若要做「全事件审计检索」，应在 风控/运维统一入口 扩展 API + 页面，不要再挂一条顾问专用 admin/audit-logs。

平台层禁止占用 / 混淆：

中文职责	merger 已有路径	顾问迁入时
G-01 适当性判定	POST /api/compliance/suitability-check（app/api/compliance.py）	不得把文案检测挂到 /api/compliance/check
理财师客户归属	GET /api/advisors/{advisor_id}/customers	不得用 /api/advisors 挂 KYC/合规

契约附录：合并落地后补 接口契约-代销平台API-v0.1.md § 路由树 一段「投资顾问 Agent 扩展」（与 v0.2 行情草案同级，标注 已实现 / MVP）。

2.2 路由文件（merger 习惯：按域拆分 + main.py 挂载）

中文职责	建议路径	说明
顾问线路由聚合（可选）	app/api/advisor_agent/__init__.py	APIRouter(prefix="/api/advisor-agent") + include_router
文案合规 API	app/api/advisor_compliance.py	自源 compliance.py 改写 prefix/response
话术模板 API	app/api/advisor_script_templates.py	自源 templates.py
KYC API	app/api/advisor_kyc.py	自源 kyc.py
市场异动 API	app/api/advisor_market.py	自源 market.py
复制门闸 API	app/api/advisor_copy.py	自源 copy.py
输入防护 API	app/api/advisor_guard.py	自源 guard.py
看板 / 配置 stub	app/api/advisor_dashboard.py · advisor_allocation.py	源分支同名改写

不迁入（含 D9）：

| app/api/admin.py（audit-logs 列表） | 风控侧已有合规查看链路；通用审计查询留待平台统一 |

不迁入（宿主/冲突）：

路径	原因
app/api/__init__.py（v1 聚合）	由 merger main.py 挂载
app/api/deps.py	merger 完整 JWT + 归属矩阵
app/api/auth.py	统一 app/api/auth.py + auth_service 签发
app/api/chat.py	宿主对话线；顾问 KYC 独立 REST，不走 Chat 四件套
app/main.py	AL-09 宿主入口

2.3 Service / Repository 重命名（消除与问数撞名）

源分支	合并后	原因
app/service/template_service.py	app/service/script_template_service.py	merger 已有问数 template_service.py（NL2SQL 模板）
app/service/template_vector_service.py	app/service/script_template_vector_service.py	话术 Milvus 专用
app/repository/template_repository.py	app/repository/script_template_repository.py	与上配套
app/service/auth_service.py	不迁入	merger Auth SDK 唯一验签
app/service/llm_client.py	app/service/advisor_llm_client.py	与问数 llm.py、宿主 embedding 区分（可选，merge 时二选一）
app/middleware/trace.py	不迁入	宿主 TraceMiddleware + utils.trace
app/utils/response.py · success_response	不迁入	统一 app/utils/response.py 的 ok / fail / error_body
app/utils/exceptions.py · AuthenticationError	不迁入	统一 ApiError / PermissionDenied + register_error_handlers

2.4 模型层

策略	说明
请求/响应 Pydantic	app/model/advisor_schemas.py（对齐 analyst_schemas.py；不扩写 merger 巨型 schemas.py 覆盖）
ORM 实体	app/model/entities/advisor.py 或追加 entities.py 仅新增类（禁止覆盖已有 risk/analytics 映射）
内部 Auth 视图	由 advisor_auth_adapter.py 从 deps.AuthContext 映射（见 §3.2）

2.5 测试文件

源分支	合并后建议
tests/test_sprint*.py · tests/test_step*.py	保留文件名或统一 tests/test_advisor_sprint*.py
断言中的 /api/v1	全部改为 §2.1 canonical 路径
断言 success_response 形	改为 merger 统一响应 envelope（与 test_wave6_analyst 一致）

---

3. S4 接缝设计（对齐问数 S3 · 客服 S2）

3.1 宿主挂载（唯一 main.py 改动面）

# 示例：按域 router 逐个 include，或单一 advisor_agent 聚合 router
from app.api.advisor_compliance import router as advisor_compliance_router
# ...
app.include_router(advisor_compliance_router)
# 各 router 内部 prefix 已含 /api/advisor-agent/...

不挂载 /demo StaticFiles · 不复制 demo_ui/（D8）；MVP 以 pytest + 既有 web/ 为准。

3.2 鉴权接缝

1. 路由层：Depends(get_platform_auth_context)（与问数 / 平台 API 一致）。

2. 新增 app/api/advisor_auth_adapter.py（或扩展 auth_adapter.py）：

   • deps.AuthContext → 顾问服务内使用的视图（actor_id / roles / permissions / trace_id）。
   • 源分支 require_permission("compliance:check") → merger has_permission / 矩阵；权限字符串 原样保留 或映射到现有 staff 角色（advisor / compliance / admin）。

3. dev 测试账号：在 merger auth.py / 种子 JWT 中补齐源分支文档中的 advisor_test · compliance_test · admin_test 权限集（仅 development）。

4. 禁止顾问代码 import 宿主 gateway/*；禁止宿主 import 顾问私有 repo 绕过 deps。

3.3 归属与客户访问

• KYC / 合规检测带 customer_id 的写读：必须走 merger 已有 assert_platform_customer_access / core_customer_advisor 口径（与问数 advisor 域一致）。
• 源分支 ownership_service.py 若与 deps 重复，合并后 删私有版，逻辑收敛到 deps + core_ro。

3.4 响应与异常

• 所有新 router 返回 ok(request, data) 或 fail(...) / 抛出 ApiError。
• 源分支 ApiResponse 包装层：仅在 adapter 测试期保留 thin wrapper，不对外暴露第二套 JSON 形。

3.5 共用底座表（agent_session / agent_message / audit_log）

merger 01-mysql-共用底座.sql 已建 11 张底座表；源分支 Alembic 20260911_0001 不得在已灌库环境重复 CREATE。

动作	说明
跳过	Sprint0 foundation 中与底座重复的 CREATE TABLE
增量	仅执行顾问 专用表 + agent_message 唯一约束（源 20260912_0007）等 ALTER
写入	KYC 会话写 agent_session.agent_type='advisor' · 消息写 agent_message · 审计写 audit_log.agent_type='advisor'

3.6 Milvus / Embedding（与客服 fin_* · 问数并存）

集合 / 用途	策略
kb_script_templates	顾问话术向量；仅扩展 milvus_tool.py / embedding_tool.py，不改 fin_* collection 名
降级	与源分支一致：Milvus/Ollama 不可用时 关键词检索降级
灌库	scripts/sync/sync_template_vectors.py（迁入并重命名路径到 scripts/sync/sync_script_template_vectors.py 可选）

3.7 Neo4j（Docker 已就绪）

• 不把 Neo4j 查询接进 KYC HTTP 主链路（一期）。
• 合并后验证：python scripts/sync/sync_neo4j.py · sync_advisor_rel.py（或 prepare_all.ps1 已有步骤）与顾问归属校验 数据一致。
• 源分支文档中的「28 客户 · 3 顾问 · 2 产品」验收，改为 merger Core 种子 + 同步脚本 复测一遍并记入 TEST-LOG。

3.8 memory_service

• merger memory_service.py 已含客服/游客逻辑；源分支扩展 仅追加 顾问/KYC 所需方法（或 AdvisorSessionMessageRepository 独立模块）。
• 禁止用顾问版本覆盖整个 memory_service.py。

---

4. 数据库：Alembic → SQL 迁移（merger 习惯）

不把 alembic/ 作为 merger 唯一迁移入口（与问数 / 客服一致），改为：

scripts/agent/migrate-advisor-agent-sprint1-3.sql
  → compliance_rule · compliance_check_log
  → copy_track_log
  → script_template · template_use_log（及源 0004 全部对象）
  → market_alert（及关联索引）
  → kyc_session（及关联字段）
  → agent_message 上 uk_agent_message_session_seq（若本机尚无）

步骤	说明
前置	jinrong_agent 已执行 01 共用底座 + 02 agent 专用（风控/问数/客服已有表）
种子	scripts/seed/import_compliance_rules.py · import_script_templates.py（迁入 scripts/agent/ 或 scripts/seed/）
重置	不改 scripts/core/reset.ps1 破坏 core；可选 scripts/agent/reset-advisor-agent.sql 仅清顾问专用表

---

5. 合并什么 / 不合并什么

5.1 整包迁入（新增或重命名后迁入）

类别	源路径（示意）	作用
合规引擎	compliance_*_service.py · compliance_*_repository.py	硬规则 + 语义兜底 + 日志
复制门闸	copy_track_*	WARN/BLOCK 与审计
话术	script_template_*（重命名后）	CRUD · 混合检索 · 引用留痕
市场	market_*_service.py · market_alert_*	扫描 · 解读 · 反馈闭环
KYC	kyc_*	会话状态机 · 字段解析 · 消息序号
编排（未完成）	agent_graph.py · agent_tools.py	可选迁入；LangGraph 未落地前 不挂 chat
评测脚本	scripts/eval/evaluate_compliance.py · evaluate_agent.py	开发回归资产
演示	scripts/demo/run_demo_smoke.ps1	改为调 canonical 路径后保留
测试	tests/test_sprint*.py 等	改路径/响应/import 后解禁
文档	docs/开发文档/35~39 · docs/演示文档/*	迁入 docs/项目框架设计/ 或 docs/需求拆解/ 子目录，不覆盖 docs/memory/*

5.2 禁止覆盖（冲突时保留 merger）

文件	原因
app/main.py	AL-09 宿主
app/api/deps.py · app/service/auth_service.py	唯一 JWT
app/api/compliance.py	平台适当性
app/service/template_service.py	问数 D-06
app/repository/core_ro.py	含 check_suitability 等
app/config/settings.py	仅追加 advisor_* / kyc_* / compliance_content_* 字段
app/tool/milvus_tool.py · embedding_tool.py	手工合并 增量，禁止整文件覆盖
docs/memory/* · web/ · 风控/问数/客服模块	全部保留 merger
docs/项目框架设计/表设计/01-mysql-共用底座.sql	仅 新 SQL 脚本 追加顾问表，不改 canonical 01 历史

---

6. 测试与验收

6.1 顺序（与 D5 一致）

1. worktree / 集成分支完成 §2 重命名 + §3 接缝（不推 main）
2. 执行 migrate-advisor-agent-sprint1-3.sql + 规则/模板种子
3. （可选）sync_script_template_vectors · Neo4j 同步
4. python -m pytest          # 目标：merger 基线 + 顾问新增全绿
5. ruff check app tests scripts
6. Scope B 冒烟（§6.3）
7. 更新 FRAMEWORK 实现状态表 · TODO · MEMORY（§7）

6.2 基线期望

指标	合并前 merger	合并后目标
pytest	833 passed（见 MEMORY §0）	833 + M passed（M ≈ 源分支 101，去重后略少）
顾问子集	—	pytest tests/test_advisor_sprint*.py（或原 sprint 名）

6.3 Scope B 冒烟（canonical 路径）

1. POST /api/advisor-agent/compliance/content-check + advisor JWT → 200 + 风险等级
2. POST /api/advisor-agent/copy/track · WARN 需 confirm · BLOCK 拒绝
3. GET /api/advisor-agent/script-templates/search?q=… → 200（Milvus 不可用时关键词降级）
4. POST /api/advisor-agent/kyc/sessions → chat 一轮 → complete
5. POST /api/compliance/suitability-check 仍 200（平台路由未回归）
6. POST /api/analyst/chat 仍 200（问数 template_service 未回归）

---

7. Merge 操作顺序（SOP · 步骤 1–5 已在 integrate/advisor-agent 推进）

1. git worktree add ../JinRong-advisor-merge -b integrate/advisor-agent merger
2. git merge xinghuo/advisor-agent --no-commit   # 或 git read-tree + 按 §5.1 只 checkout 新增路径
3. 冲突：按 §5.2 一律保留 merger，顾问逻辑拷贝到新文件名（§2）
4. 接缝：advisor_auth_adapter · main.py include_router · settings 追加 · requirements 追加
5. 删除误迁入：advisor deps/auth/main/alembic（迁移已转 SQL）
6. 改测试路径与响应形 · pytest 全绿
7. 文档：契约附录 · FRAMEWORK · 本说明状态改为「已接线」

---

8. 风险与开放项（合并不解决）

项	说明
KYC Profile / 资产配置	源分支自述未闭环；合并 不包含 S3-03~S3-08
前端工作台	不纳入本次 merge；web/ 后续单独立项
/api/v1 兼容	不做；若演示客户端依赖，单独加 shim router（deprecated）
101 vs 833 测试重叠	conftest · DB fixture 以 merger 为准，顾问测试禁止 drop 宿主表
双 llm_client	merge 时统一配置项命名，避免 .env 键冲突

---

9. 修订记录

日期	说明
2026-09-12	首版：merge 优先 · /api/advisor-agent · 重命名表 · S4 接缝 · 不测前不 claim 完成
2026-09-12	实施中：main 挂载 · 测试改 canonical 路径 · 926 pytest / 65 sprint 待收敛 · 文档 memory 同步