# 旧版系统集成实施总结

> **日期：** 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 已完全覆盖）