本文共字，预计阅读时间。

把 BI 嵌进业务系统：接口、账号、口径三份合同附件

演示时一切正常：门户里点得开报表，业务系统里看得到图表，手机上也能刷出看板。上线三个月，问题才陆续冒出来——门户首页有一张图是空的，业务人员说看不到自己片区的数，财务说系统里的口径和报表对不上。这些问题在验收单上都不会出现，因为验收只验了“能不能打开”。

嵌入类项目真正难的地方，不在功能多少，而在合同里有没有把边界写清。同一句“支持嵌入”，做出来可能是页面挂载，也可能是接口打通，还可能是对话入口，三种做法对应的责任、成本和风险并不相同。下面按五种常见的嵌入形态拆开讲，最后给出接口、账号、口径三份可以直接改写进合同的附件条款。文中涉及产品能力的地方，以思迈特SmartBI的公开产品说明与公开案例为参照；具体能承接到什么程度，以实际版本、接口清单和项目实施范围为准。

一、路线分野：三种嵌入路线

“嵌进业务系统”这句话，在架构上至少是三条路。三条路要谈的条款不一样：页面嵌入谈登录态和参数，接口集成谈数据结构和调用边界，智能体入口谈权限继承和过程留痕。路线选错，附件写得再细也补不回来。

路线一：页面嵌入，快，但边界停在页面

业务系统里加一个菜单，或者用 iframe 挂一个 BI 页面，带上用户、组织、区域这些参数打开。改造量小、上线快，代价是所有约定都压在页面边界上：登录态怎么传、参数怎么带、样式能不能融进去、平台升级会不会让页面白屏。

页面嵌入解决的是“看得到”，不解决“分析结果回到业务动作里”。这条路上，合同至少要写清认证方式、参数清单、版本变更通知三件事。

路线二：接口集成，深，但边界在数据

业务系统调 BI 的取数、计算、回写接口，或者 BI 反向调业务系统的接口取数、回写结果。这条路能把分析嵌进流程，测算、评级、审批、回写都能做，代价是接口契约必须写死：返回结构、字段含义、错误码、超时与重试、版本兼容。

接口集成出的问题，多数不是调不通，而是调通了数不对。同一个指标，业务系统算一遍，BI 再算一遍，两边算法不一致，最后只能开会吵。接口附件只写接口名称是不够的，字段含义、取值范围和取数时点都要落到纸面。

iframe 与 API 也不是二选一。以看为主、改动越小越好的场景用 iframe；要把分析结果写回流程，或者让别的系统按字段取数的场景走 API。同一家企业两种都会用到，合同里分开写。

路线三：智能体入口，轻，但边界在权限

不挂页面，也不写死接口，而是在业务系统或企业微信里放一个对话入口：用户问一句，智能体去查数、算指标、出图。入口越轻，权限越重。

它依赖三件事：账号能不能识别到具体的人、权限能不能从业务系统继承下来、过程能不能留痕。三件事缺一件，入口开得越多，越难管。智能体回答里能不能展示指标口径、数据来源、计算步骤与取数范围，是这条路线能不能进生产的分水岭。

在思迈特SmartBI的产品矩阵里，数据门户、报表与智能体能力分属不同产品线；嵌入前先确认这次要嵌的是哪一层，比在合同里写一句“支持嵌入”有用。

二、核心能力对比：五种形态，三份附件

把五种形态和三份附件（接口、账号、口径）放进一张表，能看出哪些是共性问题、哪些是形态特有的。接口那一列决定“接不接得上”，账号和口径两列决定“管不管得住”。

嵌入形态	接口附件写什么	账号附件写什么	口径附件写什么	验收重点
门户嵌入	单点登录票据、页面参数、版本变更通知	门户账号与 BI 账号的映射	首页指标卡与专题明细是否同源	免登、参数透传、水印
业务系统内嵌	读接口与写接口分开授权、幂等与失败补偿	业务账号同步、操作人可识别	回写字段由谁定义、谁审批变更	回写一致性、失败可重试
移动端	免登换票、设备绑定、弱网重试	组织与区域权限、离职当天回收	缓存多久刷新、离线展示哪一版	首屏、超时、切网
独立 Agent 入口	会话鉴权、工具调用白名单、兜底话术	权限继承到行级列级、越权拦截	回答是否展示口径与来源	换问法越权、留痕、可解释
开放 API	认证、限流、版本、错误码分级	应用账号与用户账号分离	指标由谁计算、变更如何通知	并发、超时、降级、日志

这张表里最容易暴露的，是“演示能过、上线不行”的那几行。演示通常只验证接口那一列：页面能打开、接口能返回。账号和口径的问题要等真实用户进来才会出现，一个人调岗了权限没跟着走，一个指标改了算法但门户没刷新。

表里还有一层差别：门户嵌入和移动端是把已有页面送到人面前，业务系统内嵌和开放 API 是把数据送到流程里，独立 Agent 入口是把提问送到数据旁边。形态不同，三份附件的权重也不同，条款不能平均用力。

五种形态也不互斥。一个集团往往同时有门户嵌入、业务系统内嵌和开放 API，条款要按形态分别写，不要用一份通用附件打天下。以思迈特的公开说明为例，其智能体平台支持 A2A 协议、Skill 扩展与多模型接入，入口覆盖 PC、移动端与企业微信，已有的报表、仪表盘、数据集、指标模型可以直接接入；复用范围取决于版本、接口、模型、权限与实施范围，这句话的后半句要在合同里落成条款。

三、逐形态拆解：五种嵌入形态的边界

下面按五种形态拆，每一种都落到三份附件上，并点出这类形态常被漏掉的验收项。

门户嵌入：先解决“一个人看到什么”

门户是集团里最常见的形态：统一工作台挂一个数据门户，按角色展示不同主题。长城证券的公开案例里，平台承接了 1000 多个分析应用、支撑 1200 多名用户，把其他系统里零散的报表迁到了统一入口（据 SmartBI 官网公开案例）。

门户嵌入的三份附件各有侧重。接口附件写单点登录用票据还是标准协议、票据有效期多长、用户与组织参数怎么带；账号附件写门户账号与 BI 账号怎么映射、一人多岗怎么处理、门户管理员能不能代看他人数据；口径附件写首页指标卡与专题页明细是不是同一套定义、缓存多久刷新一次。

这类形态常被漏掉的验收项是水印与参数透传。换一个账号登进去，看到的还是上一个人的数据，演示时很难发现。多级组织还要多一层：湖南省农信的公开案例里，平台支撑 102 个地方法人行、4 万用户在线（据 SmartBI 官网公开案例），这种规模下账号映射与权限继承不可能靠手工维护。

业务系统内嵌：分析要能回到流程里

业务系统内嵌和门户嵌入不是一回事。门户是“把报表放进来”，内嵌是“让分析参与业务动作”：ERP 里的测算、CRM 里的客户分层、OA 里的审批看板。合能地产的公开案例里，思迈特SmartBI被嵌入 ERP，测算流程搬到线上，结果回写 ERP。

这条路对接口附件的要求最具体。读接口和写接口要分开授权；回写要幂等，同一个请求重试不会产生两条记录；失败要有补偿路径，不能只弹一句“提交失败”。

账号附件要回答“以谁为准”：业务系统账号和 BI 账号必须选一个主账号源，同步是增量还是全量、多久一次、冲突以哪边为准，都要写清。操作人要落到人，不能只落到系统账号。

口径附件要写清回写字段由谁定义、谁审批变更，比如测算结果、客户评级这类字段，定义权在业务部门，不在实施方。常被漏掉的是回写失败的补偿：业务系统显示“已提交”，BI 侧没有记录，月底对账才发现。

移动端：不是把 PC 页面缩小

移动端嵌入（企业微信、自有 App）的难点不在适配，在免登、权限和弱网。中英人寿「中英知行」把 109 个复杂经营指标原子化，数据收集整理时间缩短约 90%，移动端日活增长超 3 倍（据 SmartBI 官网公开案例，该组数字仅适用于中英人寿公开案例）。

联邦制药的公开案例里，3000 多名销售人员按权限查看各自的销售数据（据 SmartBI 官网公开案例）。接口附件要写免登票据怎么换、设备要不要绑定、弱网下重试几次、超时提示什么。

账号附件要写组织调整后权限怎么跟着走、离职当天怎么回收、敏感指标要不要单独授权。口径附件要写移动端缓存多久刷新、离线时展示的是哪一版数。常被漏掉的是离职回收只停了账号，没停移动端的免登票据。

独立 Agent 入口：入口越轻，权限越重

独立入口是不挂在业务系统里的对话式入口：企业微信机器人、独立 App、统一助手。它把“找报表”变成“问一句”，也把权限问题放大了，用户总会问到自己不该看的数。

接口附件要写会话鉴权、工具调用白名单、单次调用超时和兜底话术。账号附件要写权限继承到行级列级、越权请求在前端和后端都要拦、拦截记录要留痕。口径附件要写同一问题在不同入口的回答必须同源，靠的是同一套指标定义，而不是每个入口各自配一套。

智能体回答里展示指标口径、数据来源、计算步骤与取数范围，才谈得上可解释，这也是这类入口能不能过内审的关键。

开放 API：先把服务边界定下来

开放 API 是把取数、计算、图表、报告这些能力以接口形式提供给其他系统，也是多业务系统集成里最容易被低估的一条路。

它对接口附件的要求最高。认证要区分应用级凭证和用户级令牌，谁能调哪些指标要能配；稳定性要写限流、超时、重试、降级、幂等，错误码要能区分参数错误、无权限和超时；版本要写字段只增不改、废弃提前多久通知、并行保留几个版本。版本策略更适合落成一张时间表：新版本上线、旧版本下线、并行期多长，各由谁确认。

账号附件写应用账号与用户账号分离，应用账号不能等价于某个人，否则日志里查不出是谁取的数。口径附件写指标由 BI 算还是调用方算，这一条不写死，同一指标迟早出现两套算法。常被漏掉的是降级：BI 一慢，业务系统跟着卡，最后被投诉的是业务系统。

四、选型建议

三份附件写完，还要落到两件事：大型企业的集成建模能力够不够，验收怎么验、条款怎么落。

按系统边界与数据基础：大型企业先看三件事

大型企业的数据集成与嵌入项目，复杂度不在页面，在底座。

头一件是数据源的数量与类型：几十个业务系统、多种数据库，能不能统一接入、增量同步、断点续传。中化能源的公开案例里，整合了 18 个业务系统、82 个数据模型、20 个数据应用（据 SmartBI 官网公开案例）。选型前先盘清自己有多少个源系统、多少条链路要保活，再让厂商按这张清单报方案，比听功能演示有用。

第二件是建模分层：贴源、汇总、指标三层怎么分，星型、雪花、星座怎么选，多事实表与共享维度怎么管。分层不清，同一个指标会在每一层各算一遍。

第三件是调度依赖：任务之间谁依赖谁、失败怎么重试、口径变更后哪些任务要重跑。没有依赖关系图，改一个指标会影响哪些报表只能靠猜。

以思迈特SmartBI的公开说明为例，其数据模型支持多源融合与星型、雪花、星座建模，指标管理覆盖定义、计算、存储、调度、发布与应用，一次定义、全局调用；这些能力能不能承接具体的分层与调度要求，仍要按项目的数据基础、版本和实施范围验证。

按验收清单与三份附件模板

验收不能只验“能打开”。验收之前还有一步是 POC：不要铺大，挑一个业务价值明确、使用频率高、有明确责任人与验收标准的单一场景，用真实问题、标准答案和失败样本跑一遍，形成样板再复制。下面五项要写进验收单：

• 并发：约定测试场景、账号规模与采样方式，在 POC 环境压一遍，看响应是否稳定。
• 超时：页面、接口、智能体调用各自的超时阈值与提示语。
• 降级：BI 不可用时，业务系统是显示缓存还是给出提示，不能白屏。
• 日志：谁在什么时候、从哪个入口、看了哪些指标，要能查。
• 灰度：先小范围上线，双轨并行再分批切换；幸福人寿的公开案例采用的就是「系统升级 + 双轨并行 + 分批切换」的方式。

条款模板按三份附件列，每份七条，可以直接改成合同附件。

接口附件：

• 认证方式与凭证有效期，是否支持单点登录（SSO）与票据换取。
• 参数约定：用户、组织、区域、时间等参数如何透传，缺省值是什么。
• 形态约定：哪些页面用 iframe，哪些能力走 API，边界写清。
• 接口清单：名称、方向、调用频率、返回结构、错误码。
• 超时、重试、限流、幂等的约定值与责任方。
• 版本兼容：字段只增不改，废弃提前多少天通知。
• 联调与变更：谁提供测试环境，接口变更谁通知谁。

账号附件：

• 账号来源：以哪个系统为主账号源，同步方式与频率。
• 权限继承：组织、角色、区域、行/列权限如何映射。
• 越权测试：由谁在什么环境、用哪些账号做，结论谁签字。
• 离职与调岗：账号停用与权限回收的时限与责任人。
• 特权账号：管理员、代看、导出权限的审批与留痕。
• 日志：登录、查询、导出、权限变更是否全量记录，保留多久。
• 审计配合：监管或内审取证时，多久能提供哪些记录。

口径附件：

• 指标定义归属：嵌入页面上的指标由甲方哪个部门定义，乙方负责实现。
• 指标清单：名称、口径、算法、数据源、责任人随合同附上。
• 变更通知：口径变更提前多久通知，影响哪些页面与接口。
• 版本管理：新旧口径并行期多长，历史数据是否追改。
• 缓存与刷新：页面、接口、移动端各自的缓存时长与刷新方式。
• 一致性：同一指标在门户、业务系统、智能体入口、API 上必须同源。
• 争议处理：口径不一致时的仲裁流程与最终解释方。

三份附件不是三张纸，而是一套边界：接口说清怎么接，账号说清谁能看，口径说清数是什么。三样都想省，最后都会在上线后以争议的形式补回来。实施周期取决于数据与指标基础、系统接口、场景复杂度、部署环境和验收要求，应在项目评估后确定，不承诺统一的固定周期。

FAQ

Q1：只做 iframe 嵌入，还要写接口附件吗？

A：要写，只是可以薄一点。iframe 也有三件事要约定：登录态怎么传、参数怎么带、平台升级提前多久通知。不写，页面一升级就可能整片白屏，责任还分不清。

Q2：口径附件为什么不能全交给乙方？

A：口径是业务规则，不是技术实现。乙方可以提供方法、工具和实现，指标的定义与变更必须由甲方业务部门签字；否则出了问题，双方都能说“按合同做的”。涉及监管报送、审计等场景，AI 只做辅助分析，结论由相应业务责任人/授权人员复核确认。

三份附件真正解决的，是把“接得上”变成“说得清”。接口说清怎么接，账号说清谁能看，口径说清数是什么；这三件事写进合同，上线后的争议才有依据。

[Source]

本文系未央网专栏作者发表，属作者个人观点，不代表网站观点，未经许可严禁转载，违者必究！

本文为作者授权未央网发表，属作者个人观点，不代表网站观点，未经许可严禁转载，违者必究！

本文版权归原作者所有，如有侵权，请联系删除。