From 619a5e661fe6ed5f1d7c225a6048e428a4ffd306 Mon Sep 17 00:00:00 2001 From: Windows Date: Fri, 11 Sep 2026 11:31:50 +0800 Subject: [PATCH] docs: record advisor migration preparation --- .gitignore | 1 + docs/21-投顾Agent迁移TODO.md | 417 +++++++++++++++++++++++++++++++++++ 2 files changed, 418 insertions(+) create mode 100644 docs/21-投顾Agent迁移TODO.md diff --git a/.gitignore b/.gitignore index d1ef047..797f2b8 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,4 @@ dist/ *.log .idea/ .vscode/ +.migration-backups/ diff --git a/docs/21-投顾Agent迁移TODO.md b/docs/21-投顾Agent迁移TODO.md new file mode 100644 index 0000000..864024a --- /dev/null +++ b/docs/21-投顾Agent迁移TODO.md @@ -0,0 +1,417 @@ +# 投顾 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`，约束审计待迁移到新底座后补齐。 + +## 一、迁移准备 + +- [ ] 确认远程仓库可访问。（当前失败：连接 `47.106.207.27:3000` 被拒绝） +- [x] 确认 `origin/qyqy_develop` 的最新提交。（已确认本地缓存引用为 `6516ccb`，待远程恢复后重新 fetch） +- [ ] 确认是否存在远程 `lzl_develop`。（远程暂不可访问） +- [x] 确认当前 `lzl` 工作区没有未解释的代码改动。（已提交 `5dcaf7c`；`.idea` 和 `.migration-backups` 已加入忽略） +- [x] 提交 `lzl` 当前所有投顾开发成果。（`5dcaf7c`） +- [x] 创建迁移前标签 `advisor-before-base-migration`。 +- [x] 备份当前测试库。（`.migration-backups/jr_agent-before-base-migration.sql`） +- [x] 导出当前数据库结构和迁移版本。（数据库迁移 head：`20260911_adv_profile_tags`） +- [ ] 导出当前产品、适当性、合同和行情数据。 +- [x] 保存当前接口清单和 Swagger 截图。（OpenAPI JSON：`.migration-backups/current-openapi.json`） +- [x] 保存当前单元、契约和集成测试结果。（259 个单元/契约测试，21 个集成测试） +- [ ] 保存当前投顾 Agent 端到端验收记录。 + +## 二、建立新开发分支 + +- [ ] 基于 `origin/qyqy_develop` 创建 `lzl_develop`。 +- [ ] 确认新分支工作区干净。 +- [ ] 建立迁移模块分支或提交规范。 +- [ ] 确认 `qyqy_develop` 的 Python、数据库和中间件版本要求。 +- [ ] 确认新底座的启动命令和环境变量。 +- [ ] 确认新底座的数据库迁移 head。 +- [ ] 确认新底座的公共测试可以通过。 + +建议命令： + +```powershell +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 的公共请求和响应结构。 +- [ ] 适配投顾工具注册。 +- [ ] 适配投顾 Agent 的 `AgentDefinition`。 +- [ ] 适配 `app/main.py` 的路由注册。 +- [ ] 确认所有写接口使用 `Idempotency-Key`。 +- [ ] 确认所有管理操作写入审计。 +- [ ] 确认所有跨存储同步使用 Outbox。 +- [ ] 完成底座适配提交 `advisor/base-adaptation`。 + +验收： + +- [ ] 公共底座单元测试通过。 +- [ ] 公共底座契约测试通过。 +- [ ] AgentFactory 测试通过。 +- [ ] ToolExecutor 测试通过。 +- [ ] 鉴权和权限边界测试通过。 +- [ ] Ruff 检查通过。 +- [ ] MyPy 检查通过。 + +## 四、数据库和迁移 + +- [ ] 对比 `qyqy_develop` 数据库基线和 `docs/00-新数据库基线设计.md`。 +- [ ] 确认没有删除或重命名基线表。 +- [ ] 确认没有删除、重命名或复用基线字段。 +- [ ] 确认没有改变基线字段类型和可空性。 +- [ ] 确认迁移链只有一个 head。 +- [ ] 迁移产品参考数据表。 +- [ ] 迁移产品治理和适当性表。 +- [ ] 迁移产品合同证据表。 +- [ ] 迁移产品行业和资产类别表。 +- [ ] 迁移历史行情表。 +- [ ] 迁移产品指标快照表。 +- [ ] 迁移行情源监控和失败记录表。 +- [ ] 迁移行情质量表。 +- [ ] 迁移资产配置回测表。 +- [ ] 迁移投资组合图谱投影检查点表。 +- [ ] 迁移投资目标表。 +- [ ] 迁移会话目标抽取表。 +- [ ] 迁移画像标签表 `advisor_profile_tag`。 +- [ ] 迁移画像漂移复核表 `advisor_profile_drift_review`。 +- [ ] 为历史当前画像回填标签证据。 +- [ ] 在空库执行迁移。 +- [ ] 在已有测试库执行迁移。 +- [ ] 执行数据库结构审计。 +- [ ] 执行数据库约束审计。 +- [ ] 完成数据库迁移提交 `advisor/database-migrations`。 + +验收命令： + +```powershell +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 事件。 + +统一命令： + +```powershell +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 和模型故障具备降级行为。 +- [ ] 所有关键写操作具备幂等和审计记录。 +- [ ] 每个迁移模块都有独立提交、测试结果和回滚点。 +- [ ] 完成迁移验收记录和交接文档。