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

概述

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

对接方式

1. 嵌入方式（推荐）

使用 iframe 嵌入打标确认页面，通过 postMessage 进行跨窗口通信。

通信协议

消息类型定义

1. 页面加载完成消息（由打标系统发送）

{
  type: 'externalPageLoaded',
  loadedAt: 1672531200000, // 时间戳
  status: 'ready'
}

2. 用户数据消息（由第三方系统发送）

{
  type: 'externalParams',
  business_attr: 'LOAN2024001',     // 贷款申请编号（必填）
  user_id: 'user001',              // 用户ID（必填）
  user_nm: '张三',                 // 用户姓名（必填）
  user_org: '福建农信',            // 所属机构（必填）
  user_endpoint: '福州分行',       // 所属行社（必填）
  contract_no: 'CONTRACT001',      // 合同编号（必填）
  timestamp: 1672531200000,        // 时间戳
  source: 'thirdPartySystem'       // 来源标识
}

3. 数据接收确认消息（由打标系统发送）

{
  type: 'externalParamsReceived',
  originalData: {
    // 原始用户数据
  },
  receivedAt: 1672531200000,      // 接收时间戳
  status: 'success'                // 接收状态
}

对接流程

步骤1：加载打标页面

// 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：监听页面加载完成消息

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

步骤3：发送用户数据

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：监听数据接收确认

// 监听智能打标系统的确认消息
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. 消息来源验证

在生产环境中，建议验证消息来源：

window.addEventListener('message', (event) => {
  // 验证消息来源域名
  if (event.origin !== 'https://your-tagging-system.com') {
    return;
  }
  
  // 处理消息
});

2. 数据验证

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

3. 错误处理

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

调试指南

1. 浏览器开发者工具

打开控制台查看错误信息
使用 Network 面板检查请求状态
查看 Console 面板的通信日志

2. 消息跟踪

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

3. 网络监控

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

性能优化建议

1. 页面加载优化

压缩静态资源
使用 CDN 加速
实现懒加载机制

2. 通信优化

减少不必要的消息传输
使用消息批处理
实现消息缓存机制

3. 用户体验优化

提供清晰的加载状态
实现自动重试机制
添加操作超时提示

常见问题及解决方案

问题1：postMessage 通信失败

症状：数据发送后无响应原因：

消息格式不正确
目标窗口未正确引用
跨域限制 解决方案：
检查消息格式是否符合规范
确保使用正确的窗口引用（contentWindow 或 opener）
在生产环境配置正确的域名白名单

问题2：页面加载缓慢导致通信超时

症状：长时间等待无响应原因：网络延迟或页面资源加载慢 解决方案：

系统已实现渐进式超时机制（5s/10s/15s）
添加加载状态提示
优化第三方系统网络环境

问题3：iframe 内容无法滚动

症状：内容超出显示区域无法查看原因：iframe 样式限制 解决方案：

添加 scrolling="auto" 属性：

<iframe src="http://your-domain.com/#/externalPage" 
       frameborder="0" 
       width="100%" 
       height="100%" 
       scrolling="auto"></iframe>

设置合适的 height 和 width

使用响应式 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;
}

技术支持

如遇技术问题，请提供以下信息：

浏览器版本和操作系统
错误截图或日志
复现步骤
网络环境信息

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

智能打标确认页面前端对接说明.md 6.2 KB History Raw