AIclinicalresearch/docs/09-架构实施/旧版系统集成/03-集成实施总结.md

旧版系统集成实施总结

日期： 2026-02-27
耗时： 1 天（含 ECS 侦察 + 代码开发 + Bridge 架构升级 + E2E 验证）
状态： ✅ 本地 E2E 验证通过，待部署生产环境

---

1. 目标

将老系统（循证医学平台 www.xunzhengyixue.com）的两个核心模块——研究管理和统计分析工具——无缝嵌入新系统（AI 临床研究平台），实现：

• 用户在新系统内一键访问老系统功能，无需重复登录
• 老系统导航栏/页脚隐藏，视觉融入新系统
• 用户数据隔离（AAA 用户看不到 BBB 的项目）

2. 最终架构

新系统页面（iit.xunzhengyixue.com）
  │
  ├─ 顶部导航栏：研究管理 | 统计分析工具
  │
  └─ 点击后 ─► POST /api/v1/legacy/auth
                  │
                  ▼
              新系统后端：
                - JWT 解出用户手机号
                - 连老系统 MySQL，查找/创建用户
                - 生成 MD5 Token 写入 u_user_token
                - 返回 { token, nickname, id, userRole }
                  │
                  ▼
              前端构建 Bridge URL ─► iframe 加载
                  │
                  ▼
              token-bridge.html（www.xunzhengyixue.com）
                - Storage Access API 检查（同站自动授权）
                - 设置 Cookie（SameSite=None; Secure）
                - 内嵌 iframe 加载目标页面
                - 注入自定义 CSS（隐藏导航栏/页脚/清除间距）
                  │
                  ▼
              老系统页面正常渲染，用户看到自己的数据

3. 代码改动清单

新系统后端（3 个文件）

文件	类型	说明
backend/src/modules/legacy-bridge/legacy-auth.service.ts	新增	连接老系统 MySQL，Token 生成与注入
backend/src/modules/legacy-bridge/routes.ts	新增	POST /api/v1/legacy/auth
backend/src/modules/legacy-bridge/mysql-pool.ts	新增	MySQL 连接池（懒加载）
backend/src/index.ts	改动	注册 legacy 路由
backend/.env	改动	LEGACY_MYSQL_* 配置

新系统前端（5 个文件）

文件	类型	说明
frontend-v2/src/modules/legacy/LegacySystemPage.tsx	新增	Bridge iframe 容器
frontend-v2/src/modules/legacy/ResearchManagement.tsx	新增	研究管理入口
frontend-v2/src/modules/legacy/StatisticalTools.tsx	新增	统计分析工具入口
frontend-v2/src/framework/modules/types.ts	改动	新增 legacyUrl 字段
frontend-v2/src/framework/modules/moduleRegistry.ts	改动	模块注册改为 iframe 模式
frontend-v2/src/App.tsx	改动	legacy 路由注册

ECS 服务器（3 个文件）

文件	类型	说明
/home/work/www/xunzhengyixue/token-bridge.html	新增	Wrapper Bridge（核心）
/home/work/www/xunzhengyixue/static/js/common.js	改动	iframe 检测（已被 bridge CSS 覆盖，保留为双重保障）
/home/work/www/xunzhengyixue/tool/js/appajax.js	改动	iframe 检测（已被 bridge CSS 覆盖，保留为双重保障）

4. 关键技术决策

决策	方案	原因
认证方式	Token 注入（直写 MySQL）	不依赖老系统 API、不需要用户密码
嵌入方式	Wrapper Bridge + 内嵌 iframe	同源 DOM 访问，可注入 CSS
Cookie 跨域	Storage Access API + SameSite=None	解决 localhost 开发环境第三方 Cookie 限制
用户关联	手机号匹配	两套系统唯一可靠的关联键
样式定制	Bridge 页面 CSS 注入	集中管理，无需改老系统文件

5. 踩坑与修复

#	问题	修复
1	gen_time 用 MySQL NOW() 导致登录失败	改为 Date.now()（毫秒时间戳）
2	隐藏 #nav-col 导致研究管理无左侧导航	只隐藏 header + footer，不隐藏侧边栏
3	工具详情页有独立 JS 不受 common.js 控制	在 appajax.js 也加 iframe 检测
4	localhost 无法为 .xunzhengyixue.com 设 Cookie	升级为 Wrapper Bridge（同域内设 Cookie）
5	SameSite=None 在 Chrome 中仍被拒绝	添加 Storage Access API 双重保障
6	隐藏导航栏后顶部留白	CSS 清除 body/page-wrapper 的 padding-top

6. 验证结果

测试项	结果
Token 注入 + 自动登录	✅
研究管理 — 左侧导航 + 内容	✅
统计分析工具 — 126 个工具列表	✅
工具详情页 — 统计分析 + 出报告 + 下载	✅
导航栏/页脚隐藏 + 无顶部间距	✅
普通模式自动授权	✅
无痕模式	❌ 浏览器限制，预期行为

7. 后续

1. 部署新系统到 SAE 生产环境
2. 生产端到端验证（同站环境，预期无需 Storage Access API）
3. 可选：回退 ECS common.js / appajax.js 的 iframe 检测改动（bridge CSS 已完全覆盖）