65 lines
4.0 KiB
Markdown
65 lines
4.0 KiB
Markdown
# 新底座无损迁移设计
|
||
|
||
## 目标
|
||
|
||
将 `qyqy_develop` 作为新的 Agent 平台底座，同时完整保留现有项目的场外基金、NL2SQL、访客 token、客服 Agent/RAG、人工转接、联调页面与现有 API 能力。
|
||
|
||
迁移过程不得修改以下对象：
|
||
|
||
- `develop` 分支；
|
||
- `feature/customer-service-rag` 工作区及其未提交内容；
|
||
- `qyqy_develop` 工作区；
|
||
- 当前正在使用的 MySQL 数据库、Redis、Milvus 和已运行服务。
|
||
|
||
所有变更仅发生在 `feature/foundation-safe-migration` 工作区；数据库验证只允许使用独立副本库。
|
||
|
||
## 基线与保留范围
|
||
|
||
新底座保留其已修复的公共能力：统一错误信封、限流、追踪标识、模型 embedding、记忆召回、Worker 租约、Outbox、配置发布、知识引用签名和数据库约束纠偏。
|
||
|
||
现有项目必须迁入并保持行为：
|
||
|
||
- 场外基金 API、规则、邮件处理与 Worker；
|
||
- 金融 NL2SQL 工具与相关 Agent；
|
||
- 访客 token 与访客客服对话；
|
||
- 已登录用户客服对话；
|
||
- 客服的 FAQ、产品、政策知识检索；
|
||
- 客服人工转接、安全风险与合规降级；
|
||
- 现有测试页和既有接口的业务可用性。
|
||
|
||
客服仍严格不返回任何用户个人持仓、收益、订单、银行卡或投诉进度；个人查询继续由前端独立接口承担。
|
||
|
||
## 迁移策略
|
||
|
||
1. 先从客服工作区提取不可变补丁备份，包含已跟踪修改和未跟踪文件，但不改变原工作区。
|
||
2. 在本分支合并现有功能分支，保留全部历史业务文件；公共冲突文件由人工语义合并，不使用“全选 ours/theirs”。
|
||
3. 对客服未提交改动按模块迁移：知识契约、Milvus 适配器、检索服务、客服路由、客服 Agent、访客运行上下文、联调页和测试。
|
||
4. 以新底座的 Factory、BaseAgent、ToolExecutor、PlatformGovernance、WorkerRuntime 为唯一公共执行链；业务模块不得绕过这些边界。
|
||
5. 合并 Alembic 图：新底座 head `20260910_drop_review_separation` 与场外基金 head `20260910_offsite_worker` 通过新的 merge revision 收敛为一个 head。该 revision 不承载业务 DDL。
|
||
|
||
## 高风险合并规则
|
||
|
||
| 区域 | 迁移规则 |
|
||
| --- | --- |
|
||
| 认证与访客 | 保留 JWT/RBAC 失败关闭；访客只恢复最小 `visitor` 上下文，不查询正式用户 RBAC，不写客户专属记忆。 |
|
||
| 配置与密钥 | 合并非敏感配置键；真实密钥只保留在本地 `.env`，不得写入代码、示例配置或日志。 |
|
||
| 模型网关 | 以新底座的单文本 embedding 受控路由为基准，扩展客服批量 embedding 时复用相同密钥解析、端点选择和失败关闭逻辑。 |
|
||
| 工具与治理 | 保留工具白名单、权限、超时、审计与脱敏；客服电话是受控公开配置，其他手机号码保持脱敏。 |
|
||
| Worker | 保留新底座租约、Outbox、记忆与 episode 链路；仅在身份恢复点加入访客分支。 |
|
||
| 数据库 | 不修改历史迁移已表达的字段定义；不在现有库直接执行 `upgrade`；先验证迁移图，再在副本库审计。 |
|
||
|
||
## 验收门禁
|
||
|
||
每一阶段失败即停止，不触碰现有工作区或数据库。
|
||
|
||
1. Git 门禁：整合前后原有三个工作区均保持原分支、原状态。
|
||
2. 迁移图门禁：`alembic heads` 只返回一个 head，迁移历史完整，副本库审计通过。
|
||
3. 底座门禁：新底座的单元、契约及可用集成测试通过。
|
||
4. 业务门禁：场外基金、NL2SQL、访客 token、客服 RAG、人工转接、登录客户账户问题拦截均有回归测试。
|
||
5. 安全门禁：访客不能获取客户数据；客服不能返回个人账户数据；未发布或过期知识不可检索；检索失败安全转人工。
|
||
6. 回退门禁：不合并该分支即完全回退；迁移期间不发布数据库结构或服务进程变更。
|
||
|
||
## 完成定义
|
||
|
||
仅当整合工作区测试、结构审计和独立数据库副本验证全部通过，并且原工作区状态未改变时，迁移分支才可以提交给用户审阅和决定是否合并。
|