# 智能打标确认页面前端对接说明

## 概述

本文档详细说明第三方系统如何通过 `/externalPage` 接口与 智能打标 系统进行集成。对接采用安全的跨窗口通信机制，确保数据传输的安全性和可靠性。

## 对接方式

### 1. 嵌入方式（推荐）
使用 iframe 嵌入打标确认页面，通过 postMessage 进行跨窗口通信。

## 通信协议

### 消息类型定义

#### 1. 页面加载完成消息（由打标系统发送）
```javascript
{
  type: 'externalPageLoaded',
  loadedAt: 1672531200000, // 时间戳
  status: 'ready'
}
```

#### 2. 用户数据消息（由第三方系统发送）
```javascript
{
  type: 'externalParams',
  business_attr: 'LOAN2024001',     // 贷款申请编号（必填）
  user_id: 'user001',              // 用户ID（必填）
  user_nm: '张三',                 // 用户姓名（必填）
  user_org: '福建农信',            // 所属机构（必填）
  user_endpoint: '福州分行',       // 所属行社（必填）
  contract_no: 'CONTRACT001',      // 合同编号（必填）
  timestamp: 1672531200000,        // 时间戳
  source: 'thirdPartySystem'       // 来源标识
}
```

#### 3. 数据接收确认消息（由打标系统发送）
```javascript
{
  type: 'externalParamsReceived',
  originalData: {
    // 原始用户数据
  },
  receivedAt: 1672531200000,      // 接收时间戳
  status: 'success'                // 接收状态
}
```

## 对接流程

### 步骤1：加载打标页面
```javascript
// iframe嵌入方式
const iframeUrl = 'http://your-domain.com/#/externalPage';
const iframe = document.createElement('iframe');
iframe.src = iframeUrl;
iframe.style.width = '100%';
iframe.style.height = '600px';
document.body.appendChild(iframe);
```

### 步骤2：监听页面加载完成消息
```javascript
// 监听智能打标页面发送的加载完成消息
window.addEventListener('message', (event) => {
  if (event.data && event.data.type === 'externalPageLoaded') {
    console.log('智能打标页面已加载完成，可以发送用户数据');
    
    // 发送用户数据
    sendUserData();
  }
});
```

### 步骤3：发送用户数据
```javascript
function sendUserData() {
  const userData = {
    type: 'externalParams',
    business_attr: 'LOAN2024001',
    user_id: 'user001',
    user_nm: '张三',
    user_org: '福建农信',
    user_endpoint: '福州分行',
    contract_no: 'CONTRACT001',
    timestamp: Date.now(),
    source: 'yourSystemName'
  };

  // 发送给iframe
  if (iframe && iframe.contentWindow) {
    iframe.contentWindow.postMessage(userData, '*');
  }
}
```

### 步骤4：监听数据接收确认
```javascript
// 监听智能打标系统的确认消息
window.addEventListener('message', (event) => {
  if (event.data && event.data.type === 'externalParamsReceived') {
    console.log('智能打标系统已成功接收数据');
    
    // 更新UI状态
    updateIntegrationStatus('数据接收成功');
  }
});
```

## 必填字段验证

智能打标系统会对以下字段进行必填验证：
- `business_attr` - 贷款申请编号
- `user_id` - 用户ID  
- `user_nm` - 用户姓名
- `user_org` - 所属机构
- `user_endpoint` - 所属行社
- `contract_no` - 合同编号

如果缺少任一必填字段，系统将拒绝处理并显示警告信息。

## 安全注意事项

### 1. 消息来源验证
在生产环境中，建议验证消息来源：
```javascript
window.addEventListener('message', (event) => {
  // 验证消息来源域名
  if (event.origin !== 'https://your-tagging-system.com') {
    return;
  }
  
  // 处理消息
});
```

### 2. 数据验证
- 验证必填字段完整性
- 对用户输入进行合法性检查
- 防止 XSS 攻击

### 3. 错误处理
- 实现完善的错误捕获机制
- 提供用户友好的错误提示
- 记录通信日志便于排查

## 调试指南

### 1. 浏览器开发者工具
1. 打开控制台查看错误信息
2. 使用 Network 面板检查请求状态
3. 查看 Console 面板的通信日志

### 2. 消息跟踪
```javascript
// 添加详细的日志记录
console.log('发送消息:', message);
console.log('接收消息:', event.data);
console.log('消息来源:', event.origin);
```

### 3. 网络监控
- 监控页面加载时间
- 检查跨域请求是否被阻止
- 验证 SSL 证书有效性

## 性能优化建议

### 1. 页面加载优化
- 压缩静态资源
- 使用 CDN 加速
- 实现懒加载机制

### 2. 通信优化
- 减少不必要的消息传输
- 使用消息批处理
- 实现消息缓存机制

### 3. 用户体验优化
- 提供清晰的加载状态
- 实现自动重试机制
- 添加操作超时提示

## 常见问题及解决方案

### 问题1：postMessage 通信失败
**症状**：数据发送后无响应
**原因**：
1. 消息格式不正确
2. 目标窗口未正确引用
3. 跨域限制
**解决方案**：
1. 检查消息格式是否符合规范
2. 确保使用正确的窗口引用（contentWindow 或 opener）
3. 在生产环境配置正确的域名白名单

### 问题2：页面加载缓慢导致通信超时
**症状**：长时间等待无响应
**原因**：网络延迟或页面资源加载慢
**解决方案**：
1. 系统已实现渐进式超时机制（5s/10s/15s）
2. 添加加载状态提示
3. 优化第三方系统网络环境

### 问题3：iframe 内容无法滚动
**症状**：内容超出显示区域无法查看
**原因**：iframe 样式限制
**解决方案**：
1. 添加 scrolling="auto" 属性：
   ```html
   <iframe src="http://your-domain.com/#/externalPage" 
           frameborder="0" 
           width="100%" 
           height="100%" 
           scrolling="auto"></iframe>
   ```
2. 设置合适的 height 和 width
3. 使用响应式 CSS 样式：
   ```css
   .iframe-container {
     flex: 1;
     min-height: 0;
     overflow: hidden;
     border: 1px solid #e4e7ed;
     border-radius: 4px;
     background-color: #fff;
     display: flex;
     flex-direction: column;
   }
   
   .iframe-container iframe {
     flex: 1;
     width: 100%;
     height: 100%;
     border: none;
     background-color: #fff;
   }
   ```

## 技术支持

如遇技术问题，请提供以下信息：
1. 浏览器版本和操作系统
2. 错误截图或日志
3. 复现步骤
4. 网络环境信息

---

*本文档最后更新：2026年3月17日*