group_fqcd_jr/docs/21-投顾Agent迁移TODO.md

投顾 Agent 迁移 TODO

目标：以 qyqy_develop 为新底座，在不直接合并 lzl 的前提下，重新接入现有投顾 Agent 能力。

使用规则：每完成一项，将 [ ] 改为 [x]，并在任务后补充提交号、测试结果或问题记录。

迁移进度记录

阶段一：迁移准备

已完成本地冻结和质量基线：提交 5dcaf7c，标签 advisor-before-base-migration。数据库备份保存于 .migration-backups/jr_agent-before-base-migration.sql，接口快照保存于 .migration-backups/current-openapi.json。

阶段一测试结果：单元/契约测试 259 passed，集成测试 21 passed，Ruff 通过，MyPy 通过，数据库结构审计通过，Alembic 当前版本为 20260911_adv_profile_tags。

当前阻塞：远程仓库 47.106.207.27:3000 暂时无法连接；lzl_develop 尚未确认存在。当前新底座已包含 tools/audit_constraints.py，旧库版本不兼容问题待切换独立测试库处理。

阶段二：建立新开发分支

已基于本地缓存的 origin/qyqy_develop@6516ccb 创建 lzl_develop。新底座单元/契约测试 447 passed，Ruff 通过，MyPy（103 个源文件）通过。

注意：当前 MySQL 测试库仍记录旧投顾迁移版本 20260911_adv_profile_tags，新底座无法解析该版本；后续必须使用新底座基线重新初始化或准备独立迁移数据库，不能直接在该旧库上继续升级。

阶段三：公共底座适配

已新增最小投顾 Agent advisor，通过新底座的 BaseAgent、AgentFactory、ToolExecutor、意图声明和场内行情只读工具运行。当前只接入行情查询，产品、问卷、投资目标、持仓和推荐能力留待后续阶段逐项接入。

阶段三测试结果：专项测试 9 passed，全量单元/契约测试 448 passed，Ruff 通过，MyPy（104 个源文件）通过。适配提交：5e8eecc。

阶段四：数据库和迁移

已将旧投顾迁移按 qyqy_develop 的 20260910_drop_review_separation head 重新接入为一条连续链，新增产品治理、合同证据、行业/资产分类、历史行情、行情源健康、 数据质量、动态配置回测、投资目标、会话目标抽取和画像标签治理表。未修改基线迁移， 未删除、重命名或改变基线表和字段；迁移契约测试对此有静态校验。

阶段四测试结果：迁移契约 2 passed，全量单元测试 442 passed，Ruff 通过，MyPy （104 个源文件）通过；独立 MySQL 库 jr_agent_qyqy_migration 在线执行 alembic upgrade head 成功，结构审计显示 72 张业务表无缺失或多余，约束/ORM 审计通过。 原 jr_agent 库仍记录旧投顾迁移版本 20260911_adv_profile_tags，不能直接用新底座升级， 已保留不动，待数据库负责人按迁移方案另行切换。

一、迁移准备

• 确认远程仓库可访问。（当前失败：连接 47.106.207.27:3000 被拒绝）
• 确认 origin/qyqy_develop 的最新提交。（已确认本地缓存引用为 6516ccb，待远程恢复后重新 fetch）
• 确认是否存在远程 lzl_develop。（远程暂不可访问）
• 确认当前 lzl 工作区没有未解释的代码改动。（已提交 5dcaf7c；.idea 和 .migration-backups 已加入忽略）
• 提交 lzl 当前所有投顾开发成果。（5dcaf7c）
• 创建迁移前标签 advisor-before-base-migration。
• 备份当前测试库。（.migration-backups/jr_agent-before-base-migration.sql）
• 导出当前数据库结构和迁移版本。（数据库迁移 head：20260911_adv_profile_tags）
• 导出当前产品、适当性、合同和行情数据。
• 保存当前接口清单和 Swagger 截图。（OpenAPI JSON：.migration-backups/current-openapi.json）
• 保存当前单元、契约和集成测试结果。（259 个单元/契约测试，21 个集成测试）
• 保存当前投顾 Agent 端到端验收记录。

二、建立新开发分支

• 基于 origin/qyqy_develop 创建 lzl_develop。（基于本地缓存 6516ccb，远程恢复后需重新 fetch）
• 确认新分支工作区干净。（619a5e6 后无业务代码改动，迁移备份已忽略）
• 建立迁移模块分支或提交规范。（按本 TODO 的模块提交名执行）
• 确认 qyqy_develop 的 Python、数据库和中间件版本要求。（已核对 pyproject.toml、.env.example 和底座文档）
• 确认新底座的启动命令和环境变量。（已核对 uvicorn app.main:app、Worker 入口和环境配置）
• 确认新底座的数据库迁移 head。（代码 head：20260910_drop_review_separation；旧测试库版本不兼容）
• 确认新底座的公共测试可以通过。（单元/契约 447 passed）

建议命令：

git fetch origin qyqy_develop
git switch -c lzl_develop origin/qyqy_develop
python -m pytest tests/unit tests/contract -q
python -m ruff check app tests tools alembic
python -m mypy app

三、公共底座适配

• 阅读并记录 app/core/contracts.py 的请求和响应契约。
• 阅读并记录 app/core/errors.py 的错误码和错误信封。
• 确认 JWT 鉴权和 RBAC 解析流程。
• 确认 BaseAgent 的标准执行流程。
• 确认 AgentFactory 的 Agent 注册方式。
• 确认 ToolExecutor 的工具鉴权和角色限制。
• 确认模型路由、模型降级和超时处理方式。
• 确认 Redis、Milvus、Neo4j 的接入方式。
• 确认记忆抽取、召回、生命周期和 Episode 聚合流程。
• 确认 Worker 注册和事件消费方式。
• 适配投顾 Agent 的公共请求和响应结构。（复用 BaseAgent 和 AgentRequest/CoreResult）
• 适配投顾工具注册。（复用 query_fund_quote 只读工具）
• 适配投顾 Agent 的 AgentDefinition。（新增 advisor，版本 0.1.0）
• 适配 app/main.py 的路由注册。（复用已注册 Agent Run 入口，无新增旁路）
• 确认所有写接口使用 Idempotency-Key。（底座契约测试通过）
• 确认所有管理操作写入审计。（底座契约测试通过）
• 确认所有跨存储同步使用 Outbox。（底座 Worker/事件测试通过）
• 完成底座适配提交 advisor/base-adaptation。（5e8eecc）

验收：

• 公共底座单元测试通过。（已包含于 447 passed）
• 公共底座契约测试通过。（已包含于 447 passed）
• AgentFactory 测试通过。（已包含于 447 passed）
• ToolExecutor 测试通过。（已包含于 447 passed）
• 鉴权和权限边界测试通过。（已包含于 447 passed）
• Ruff 检查通过。
• MyPy 检查通过。（103 个源文件）

四、数据库和迁移

• 对比 qyqy_develop 数据库基线和 docs/00-新数据库基线设计.md。（迁移契约测试 + 在线结构审计）
• 确认没有删除或重命名基线表。（14 个投顾迁移仅 CREATE TABLE）
• 确认没有删除、重命名或复用基线字段。（迁移契约测试通过）
• 确认没有改变基线字段类型和可空性。（未修改基线迁移）
• 确认迁移链只有一个 head。（20260911_adv_profile_tags）
• 迁移产品参考数据表。
• 迁移产品治理和适当性表。
• 迁移产品合同证据表。
• 迁移产品行业和资产类别表。
• 迁移历史行情表。
• 迁移产品指标快照表。
• 迁移行情源监控和失败记录表。
• 迁移行情质量表。
• 迁移资产配置回测表。
• 迁移投资组合图谱投影检查点表。
• 迁移投资目标表。
• 迁移会话目标抽取表。
• 迁移画像标签表 advisor_profile_tag。
• 迁移画像漂移复核表 advisor_profile_drift_review。
• 为历史当前画像回填标签证据。（迁移包含回填逻辑；独立空库无历史画像）
• 在空库执行迁移。（jr_agent_qyqy_migration）
• 在已有测试库执行迁移。
• 执行数据库结构审计。（72 张业务表，无缺失或多余）
• 执行数据库约束审计。（唯一键与 ORM 映射通过）
• 完成数据库迁移提交 advisor/database-migrations。（待提交）

验收命令：

python -m alembic upgrade head
python tools/audit_schema.py
python tools/audit_constraints.py

五、产品数据和适当性

• 迁移场内基金产品模型。
• 迁移产品查询 Repository。
• 导入南方场内基金产品。
• 导入 R1-R5 产品适当性等级。
• 导入基金合同字段和权威来源。
• 导入销售机构披露信息。
• 导入产品状态和交易状态。
• 接入产品治理变更监控。
• 接入产品资产规模指标。
• 接入产品历史行情指标。
• 接入产品流动性指标。
• 实现场内基金过滤。
• 实现适当性硬过滤。
• 实现合同证据过滤。
• 实现来源缺失时的失败关闭。
• 完成产品数据提交 advisor/product-data。

验收：

• R1、R2、R3、R4、R5 均有可查询产品。
• 每个风险等级至少有四个测试产品。
• 各基金类型分类正确。
• 场外基金不会进入场内交易表。
• 不适配产品会被排除并说明原因。
• 产品来源和合同证据可追溯。

六、开户风险问卷

• 迁移问卷查询接口。
• 迁移问卷提交接口。
• 迁移服务端评分规则。
• 迁移 C1-C5 风险等级生成。
• 迁移开户画像快照生成。
• 迁移问卷有效期控制。
• 迁移每日和年度提交次数限制。
• 迁移首次登录拦截。
• 迁移画像同步 Outbox 事件。
• 确认客户响应不返回答案、总分、风险等级和画像。
• 确认问卷重复提交具有幂等性。
• 完成风险问卷提交 advisor/risk-questionnaire。

验收：

• 新客户访问投顾业务会被拦截。
• 新客户可以查询问卷。
• 新客户可以成功提交问卷。
• 问卷结果正确写入后台表。
• 客户响应不包含内部评分信息。
• 投顾工具可以读取必要的内部画像投影。

七、投资目标和目标书

• 迁移投资目标创建接口。
• 迁移收益目标下限和上限。
• 迁移最大回撤字段。
• 迁移流动性要求字段。
• 迁移投资期限字段。
• 迁移业绩比较基准字段。
• 迁移目标备注字段。
• 迁移目标书生成。
• 迁移客户确认流程。
• 迁移投顾审核流程。
• 迁移当前目标查询工具。
• 迁移目标缺口状态。
• 确认目标创建后为 pending_confirmation。
• 确认未确认目标不能用于推荐和配置。
• 确认目标书未审核不能对客发布。
• 确认收益目标不被表述为收益承诺。
• 完成投资目标提交 advisor/investment-goal。

八、持仓分析

• 迁移持仓查询。
• 迁移持仓市值计算。
• 迁移单产品集中度计算。
• 迁移行业集中度计算。
• 迁移 HHI 指标计算。
• 迁移行业穿透计算。
• 迁移行情和行业数据覆盖率计算。
• 迁移 Neo4j 图谱增强。
• 确认 MySQL 是数值分析权威来源。
• 确认 Neo4j 只做关系增强。
• 实现图谱不可用时的降级。
• 实现关键数据不足时的降级。
• 确认分析结果不生成交易指令。
• 完成持仓分析提交 advisor/portfolio-analysis。

验收：

• 无持仓时返回明确状态。
• 缺少市值时不计算集中度。
• 行业覆盖不足时不输出确定性行业结论。
• 图谱不可用时仍可返回可靠的数值分析。
• 客户看不到内部数据库查询细节。

九、动态资产配置

• 迁移 C1-C5 基础配置。
• 迁移投资期限约束。
• 迁移流动性约束。
• 迁移最大回撤约束。
• 迁移收益目标约束。
• 迁移历史行情指标读取。
• 迁移动态权重优化器。
• 迁移流动性覆盖率。
• 迁移动态配置回测。
• 保存配置回测证据。
• 实现数据覆盖不足时的降级状态。
• 确认输出配置比例而不是买卖指令。
• 完成资产配置提交 advisor/asset-allocation。

验收：

• 收益目标参与优化。
• 最大回撤参与优化。
• 流动性要求参与优化。
• 投资期限参与优化。
• 动态配置与静态配置可以对比。
• 回测结果包含限制条件和数据覆盖率。

十、产品推荐和审核发布

• 迁移产品推荐 Agent。
• 迁移客户画像读取。
• 迁移投资目标读取。
• 迁移适当性硬过滤。
• 迁移合同证据过滤。
• 迁移行情和流动性校验。
• 迁移图谱增强。
• 迁移多因子排序。
• 迁移个性化推荐理由。
• 迁移推荐证据卡片。
• 迁移排除原因。
• 迁移推荐方案生成。
• 迁移 pending_review 状态。
• 迁移管理员审核接口。
• 迁移审核拒绝原因。
• 迁移审核通过后发布。
• 确认审核前不可对客发布。
• 确认推荐不生成交易委托。
• 完成产品推荐提交 advisor/recommendation。

验收：

• 画像未完成时不能推荐。
• 投资目标未确认时不能推荐。
• 不适配产品不会进入候选列表。
• 每个推荐产品都有证据。
• 每个排除产品都有原因。
• 推荐方案默认进入待审核。
• 审核通过后客户才能查看发布内容。

十一、会话闭环

• 迁移意图分类。
• 迁移产品推荐意图。
• 迁移持仓分析意图。
• 迁移资产配置意图。
• 迁移对比分析意图。
• 迁移投资目标意图。
• 迁移会话实体抽取。
• 迁移投资目标缺口识别。
• 迁移缺口追问状态。
• 迁移会话状态持久化。
• 迁移记忆召回。
• 迁移 Episode 聚合。
• 迁移 Agent Run 持久化。
• 迁移 Outbox 事件。
• 迁移会话审计。
• 确认用户消息可以形成完整闭环。
• 确认缺少字段时只追问必要信息。
• 确认工具失败时返回可理解的降级结果。
• 完成会话闭环提交 advisor/conversation。

十二、画像标签和漂移复核

• 迁移画像标签模型。
• 迁移标签值保存。
• 迁移标签置信度保存。
• 迁移来源类型保存。
• 迁移来源引用保存。
• 迁移来源置信度保存。
• 迁移画像版本保存。
• 迁移标签生效状态。
• 迁移标签值变化检测。
• 迁移来源变化检测。
• 迁移置信度下降检测。
• 迁移候选画像保存。
• 迁移漂移复核队列。
• 迁移管理员查看标签证据接口。
• 迁移管理员审核通过接口。
• 迁移管理员审核拒绝接口。
• 审核通过后切换当前画像。
• 审核通过后创建 Milvus 同步事件。
• 审核通过后创建 Neo4j 同步事件。
• 审核期间暂停产品推荐。
• 审核期间暂停资产配置。
• 审核期间暂停持仓分析。
• 审核期间暂停调仓模拟。
• 确认客户不能读取内部标签、置信度和审核信息。
• 完成画像治理提交 advisor/profile-governance。

十三、全端测试

• 执行全部单元测试。
• 执行全部契约测试。
• 执行全部集成测试。
• 执行 Ruff 检查。
• 执行 MyPy 检查。
• 执行数据库结构审计。
• 执行数据库约束审计。
• 验证空库迁移。
• 验证已有测试库迁移。
• 验证首次登录问卷流程。
• 验证投资目标创建和确认流程。
• 验证产品推荐流程。
• 验证持仓分析流程。
• 验证动态资产配置流程。
• 验证推荐审核发布流程。
• 验证画像漂移复核流程。
• 验证行情主源失败切换备用源。
• 验证 Redis 不可用时的降级。
• 验证 Neo4j 不可用时的降级。
• 验证 Milvus 不可用时的降级。
• 验证模型端点失败时的降级。
• 验证幂等键重复请求。
• 验证权限越权请求。
• 验证客户数据隔离。
• 验证审计记录和 Outbox 事件。

统一命令：

python -m pytest tests/unit -q
python -m pytest tests/contract -q
python -m pytest tests/integration -q
python -m ruff check app tests tools alembic
python -m mypy app
python -m alembic upgrade head
python tools/audit_schema.py
python tools/audit_constraints.py

十四、灰度发布

• 在本地测试库完成迁移。
• 在联调库完成迁移。
• 仅开放测试客户和管理员账号。
• 灰度产品查询和适当性过滤。
• 灰度风险问卷。
• 灰度投资目标。
• 灰度持仓分析。
• 灰度资产配置。
• 灰度产品推荐。
• 灰度推荐审核发布。
• 灰度画像漂移复核。
• 记录灰度期间错误、延迟和降级次数。
• 确认客户数据未越权暴露。
• 确认没有产生真实交易委托。

十五、回滚准备

• 保存迁移前数据库备份。
• 保存迁移前 Git 标签。
• 保存每个模块的提交号。
• 保存每个模块的测试结果。
• 保存迁移后的结构审计结果。
• 准备关闭新投顾入口的配置开关。
• 准备应用代码按提交回滚方案。
• 确认数据库不执行破坏性 downgrade。
• 确认新增表保留，不自动删除。
• 确认失败 Outbox 可以重试或人工处理。
• 确认原画像和原推荐结果可以保留。
• 完成灰度回滚演练。

十六、最终完成标准

• qyqy_develop 底座测试全部通过。
• 投顾业务测试全部通过。
• 数据库基线审计通过。
• 空库迁移成功。
• 已有测试库迁移成功。
• 鉴权和首次登录拦截有效。
• 风险问卷后台评分有效且客户不可见。
• 投资目标采集、确认和审核有效。
• 持仓分析数值来源可靠。
• 收益、回撤、流动性参与动态配置。
• 产品推荐具备适当性过滤、证据卡片和排除原因。
• 推荐方案审核发布闭环有效。
• 会话实体抽取和目标缺口追问有效。
• 画像标签具备置信度和来源。
• 画像漂移复核闭环有效。
• 行情双源和失败告警有效。
• Redis、Neo4j、Milvus 和模型故障具备降级行为。
• 所有关键写操作具备幂等和审计记录。
• 每个迁移模块都有独立提交、测试结果和回滚点。
• 完成迁移验收记录和交接文档。