Skip to content

给 AI 的接入说明 ​

这一页是写给代码助手的:把整页贴进上下文,或让它抓 https://report.doc.yijiangsoft.com/md/ai.md,它就能在宿主代码里把接入写对。内容自包含,不用再翻别的页面。

人也能读——只是密度高、没有铺垫。

纯文本索引:/llms.txt 全站正文:/llms-full.txt 本页原文:/md/ai.md


TASK ​

把 conch-report 的查看态嵌进宿主系统的页面。两种形态,能力完全一样,参数名一一对应:

形态怎么嵌输入运行期交互选它的场合
A. iframe写一个 <iframe>,不引包不改构建URL 查询串postMessage宿主是老系统 / 小程序 web-view / 不想加脚本依赖;拿不准就选这个
B. 自定义元素<script type="module" src="{ORIGIN}/embed.js"> + <conch-report> 标签元素属性DOM 事件 + 元素方法宿主是现代前端项目、一页要摆多张报表、希望报表跟页面一起滚动

形态 B 渲染在 Shadow DOM 里:宿主的全局 CSS 渗不进去,报表样式也漏不出来;高度自己跟着内容走,宿主不用管。要求浏览器支持 Shadow DOM 与 ES 模块(IE 不行)。

INPUTS(动手前必须确认,缺了就问人,不要编) ​

名称例子没有会怎样
报表服务地址 ORIGINhttps://report.example.com写不出 src
报表 id IDr260922123456写不出 src
筛选条件 id 及取值来源month ← 页面上的月份选择器;dept ← 登录用户的科室条件传不进去或拼错名字
哪些条件不让使用者改dept界面口径不对
要不要报表自带页头宿主已有标题栏 → 不要页面上出现两条标题栏

报表 id 从报表服务的报表列表页(每行的「嵌入」按钮)或 GET /api/reports 取。

HARD RULES ​

  1. 先定形态:A 还是 B。下面的 URL CONTRACT / POSTMESSAGE CONTRACT 只管 A,CUSTOM ELEMENT CONTRACT 只管 B。别把两套混着写。
  2. 只嵌查看态(形态 A):view=1 必须有。少了它嵌进去的是设计器(带对话和属性面板),是错的。形态 B 的元素本来就只有查看态,没有这个坑。
  3. 报表必须已发布。没发布的报表打开只显示一句「还没有发布」;发布由做报表的人在报表服务里点,宿主侧做不了。
  4. 不要在链接里放 token、密码、签名、SQL。链接会进历史记录和 Referer。报表服务也不接受从客户端传 SQL。
  5. lock 不是权限。它只把控件设成只读,改链接就能绕开。按身份限制数据必须走登录凭证(宿主后端换票,见 AUTH CONTRACT),不能靠 lock 或链接参数交差;写代码时如果用户以为 lock 能限权,要明确告诉他不能。
  6. 条件变化走 postMessage,不要重新拼 src。换 src 会让 iframe 整页重载、图表重画一遍。首次挂载用 URL,之后用 setParams。
  7. postMessage 的 targetOrigin 写具体域名,不要 '*';接收侧校验 e.origin 和 msg.source。
  8. 不要替用户猜条件 id。猜错的表现是「页面上多一条提示、筛选没生效」,比报错更难被发现。
  9. 报表服务开了鉴权(auth.mode: "jwt")时必须接凭证:换票只在宿主后端做(客户端密钥不进浏览器);形态 A 回应 authRequired,形态 B 设 tokenProvider。租户 id、机构 id 一律不从前端传。

URL CONTRACT(形态 A) ​

{ORIGIN}/?id={ID}&view=1[&<条件id>=<值>][&lock=…][&chrome=0][&version=…][&theme=…]

保留字段(其余 key 一律按报表筛选条件解析):

key值含义
id报表 id必填
view1必填,查看态
versionv3 / draft / 省略省略=当前发布版;draft 仅供发布前自查,不要给客户
locka,b 或 all这些条件只读
chrome0去掉报表页头(标题、版本、刷新、导出)
themeprimary:%232c6ecb,bg:%23ffffff覆盖设计令牌;名字省略 --cr- 前缀;值里不能有逗号

条件值的写法(先 encodeURIComponent,用 URLSearchParams 就自动做了):

条件类型写法例
文本 / 数字 / 日期 / 月份 / 单选 / 树id=值month=2026-08、day=2026-08-31、store=S001
日期区间id=起,止 或 id_from=/id_to=range=2026-01-01,2026-03-31
数字区间id=小,大 或 id_min=/id_max=amount=100,500
多选id=a,b 或重复 id=a&id=bstore=S001,S002
不限(清掉报表默认值)id=(空串)month=

链接上不写的条件 = 用报表自己的默认值。写了但报表里没有的 key 会被忽略,页面顶上列出来提示。

POSTMESSAGE CONTRACT(形态 A) ​

报表 → 宿主,{ source: 'conch-report', type, … }:

type附带字段用途
readyid, title, version渲染完成;此前发给报表的消息会被丢掉
heightheight(px)内容高度变化;宿主据此调 iframe 高度,避免第二条滚动条
paramsparams(全部条件的当前值)使用者或宿主改了条件
authRequired—报表要登录凭证;在 ready 之前就会来,收到立即回 auth,不要排队等 ready
errormessage, code, status报表打不开(没发布、没权限、服务不通);code 以 auth_ 开头或是 scope_missing 说明是凭证的问题

宿主 → 报表,{ source: 'conch-report-host', type, … }:

type附带字段用途
setParamsparams:条件 id → 值(只写要改的)改条件并重新取数
refresh—按当前条件重新取数
setThemetokens:令牌名 → 值换配色
authtoken:宿主后端换来的凭证交登录凭证;可主动推,也在收到 authRequired 时回

setParams 的值用 JS 原生类型:区间 ['2026-01-01','2026-03-31']、多选 ['S001','S002']、不限 null。

CUSTOM ELEMENT CONTRACT(形态 B) ​

html
<script type="module" src="{ORIGIN}/embed.js"></script>
<conch-report report-id="{ID}" params='{"month":"2026-08"}' lock="month" chrome="0"></conch-report>

embed.js 自己知道报表服务在哪(取脚本来源),不要另外配地址。

属性(与 URL CONTRACT 的保留字段一一对应):

属性值说明
report-id报表 id必填
versionv3 / draft / 省略同 version
locka,b 或 all同 lock
chrome0同 chrome=0
paramsJSON 对象条件值用原生 JSON 类型,不拼字符串:区间 ["2026-01-01","2026-03-31"]、多选 ["S001","S002"]、不限 null
themeJSON 对象或 名:值,名:值同 theme

方法(拿到元素就能调,早于渲染完成也不丢):setParams(obj)、refresh()、setTheme(obj);读当前条件用 el.params。

凭证(报表服务开了鉴权时):el.tokenProvider = async () => token,token 由宿主后端换票得到;是 JS 属性,不要写成 HTML 属性。

事件(从元素冒泡,内容在 event.detail):

事件detail对应形态 A 的
conch-readyid, title, versionready
conch-paramsparamsparams
conch-errormessage, code, statuserror

没有 height 事件——元素高度由布局自己撑开,宿主不需要配合。

改 params / theme 是热更新;改 report-id / version / lock / chrome 会重新打开报表。

js
const el = document.createElement('conch-report')
el.setAttribute('report-id', ID)
container.appendChild(el)
el.addEventListener('conch-ready', (e) => console.log(e.detail.title))
el.setParams({ month: '2026-08' })      // 条件变化一律走这个,别改属性字符串
// 卸载:el.remove(),没有全局监听要清

Vue 3 要在编译器里声明 isCustomElement: (tag) => tag === 'conch-report',否则报 "Failed to resolve component"。React 18 及更早不会把对象属性传给自定义元素,条件一律用 setParams(),不要写在 JSX 属性上。

完整说明见自定义元素(原文 /md/guide/web-component.md)。

REFERENCE IMPLEMENTATION(形态 A,框架无关,照这个结构写) ​

js
function mountReport(container, { origin, id, params = {}, lock, chrome = true, version, getToken }) {
  const q = new URLSearchParams({ id, view: '1' })
  for (const [k, v] of Object.entries(params)) {
    if (v !== null && v !== undefined) q.set(k, Array.isArray(v) ? v.join(',') : String(v))
  }
  if (lock) q.set('lock', Array.isArray(lock) ? lock.join(',') : lock)
  if (chrome === false) q.set('chrome', '0')
  if (version) q.set('version', version)

  const frame = document.createElement('iframe')
  frame.src = `${origin}/?${q}`
  frame.style.cssText = 'width:100%;height:480px;border:0'
  container.appendChild(frame)

  let ready = false
  const queue = []
  const post = (msg) => {
    if (!ready) { queue.push(msg); return }            // ready 之前排队,别丢
    frame.contentWindow.postMessage({ source: 'conch-report-host', ...msg }, origin)
  }
  const onMessage = (e) => {
    if (e.origin !== origin || e.source !== frame.contentWindow) return
    const msg = e.data
    if (!msg || msg.source !== 'conch-report') return
    if (msg.type === 'height') frame.style.height = msg.height + 'px'
    if (msg.type === 'ready') { ready = true; queue.splice(0).forEach(post) }
    // 开了鉴权时:凭证由宿主后端换票给出(getToken 调自己的后端),不排队,收到就回
    if (msg.type === 'authRequired' && getToken)
      getToken().then((token) => frame.contentWindow.postMessage({ source: 'conch-report-host', type: 'auth', token }, origin))
  }
  window.addEventListener('message', onMessage)

  return {
    setParams: (p) => post({ type: 'setParams', params: p }),
    refresh: () => post({ type: 'refresh' }),
    setTheme: (t) => post({ type: 'setTheme', tokens: t }),
    destroy: () => { window.removeEventListener('message', onMessage); frame.remove() },
  }
}

Vue 3 / React 的成品组件见宿主代码示例(原文 /md/guide/examples.md),结构与上面一致:src 只在挂载时算一次,条件变化 watch/useEffect 里发 setParams,height 存进组件状态。

AUTH CONTRACT(报表服务开了鉴权时) ​

宿主后端换票(只在后端调,密钥不进浏览器):

http
POST {ORIGIN}/api/auth/exchange
Authorization: Basic base64(<客户端 id>:<密钥>)
Content-Type: application/json

{ "sub": "<宿主用户 id>", "role": "viewer", "scope": ["<这个人能看的机构 id>"] }
→ { "token": "…", "expiresAt": "…" }
  • role:viewer(默认,只看已发布)/ designer / admin。
  • scope:数组;多个维度时写对象 { "org_ids": [...] }。不限范围要显式 "scopeAll": true,不写 scope 等于什么都看不到。
  • space:各机构自己设计、自己用报表时传机构 id(通常与 scope 同值),报表只在本空间可见;所有机构共用同一批报表时不传。
  • 凭证 10 分钟左右过期,报表会自己再要,宿主给一个「随时能再换一张」的后端接口即可。

完整说明见登录身份与数据范围(原文 /md/guide/auth.md)。

HTTP API(只有在不嵌 iframe、要自己画的时候才用) ​

方法路径请求体回什么
GET/api/reports—报表列表,publishedVersion 为 null 表示没发布
GET/api/reports/{id}/view?version=—规格(不含 SQL)+ 初始条件 +(快照版的)数据;409 = 没发布
POST/api/reports/{id}/data{version, params}{queries:{<查询名>:{columns,columnTypes,rows,truncated,elapsedMs}}},单条失败带 error
POST/api/reports/{id}/drill{version, drill, args, params}穿透明细
POST/api/reports/{id}/export/xlsx|docx{version, params[, drill, args]}文件流
GET/api/reports/{id}/versions—版本列表

错误统一 {"error":"…"}。多租户部署时租户来自请求头 X-Conch-Tenant,由反向代理注入,前端传不了。

CHECKLIST(交付前逐条核对) ​

两种形态都要核对:

  • [ ] 条件 id 是从报表里确认过的,不是猜的
  • [ ] 条件变化走 setParams,没有重新挂载报表
  • [ ] 宿主是 https 时报表地址也是 https
  • [ ] 跟用户确认过:lock 不等于数据权限

形态 A(iframe)另加:

  • [ ] src 里有 id 和 view=1
  • [ ] 条件值用 URLSearchParams 拼,没有手工字符串拼接
  • [ ] 监听了 height 并调整 iframe 高度
  • [ ] 校验了 e.origin 与 msg.source;postMessage 的 targetOrigin 不是 '*'
  • [ ] ready 之前发的消息有排队补发
  • [ ] 组件卸载时移除了 message 监听

形态 B(自定义元素)另加:

  • [ ] embed.js 用 <script type="module"> 引,没有另外配服务地址
  • [ ] params 是合法 JSON 对象,值用原生类型而不是拼出来的字符串
  • [ ] Vue 项目配了 isCustomElement;React 18 及更早没把对象写进 JSX 属性
  • [ ] 卸载走 el.remove(),没有手工去动 Shadow DOM 里的东西

FAILURE MODES ​

现象原因处理
页面写「还没有发布」报表只有草稿让做报表的人发布;自查可用 version=draft
iframe 空白混合内容 / frame-ancestors 不含宿主域名 / 代理加了 X-Frame-Options / sandbox 太紧看浏览器控制台的拒绝原因,对号处理;sandbox 至少要 allow-scripts allow-same-origin,导出还要 allow-downloads
条件没生效,顶上有提示条件 id 拼错核对报表筛选栏里的 id
条件没生效,没有提示值的写法不对(区间、多选、编码)按上面的写法表改
出现第二条滚动条没监听 height加上高度同步
setParams 无反应发早了 / source 写错 / targetOrigin 不匹配 / 该条件被 lock 或快照锁了按顺序排查
报表改了页面没变只改了草稿没发布,或链接钉了 version重新发布;去掉 version
<conch-report> 标签在但一片空白embed.js 没加载成功(没写 type="module"、地址不通、被 CSP 挡了)看控制台网络请求与 CSP 拒绝原因
元素里说「还没有指定报表」report-id 没写或为空补上
元素的 params 没生效属性不是合法 JSON,控制台有一句提示改成合法 JSON,或改用 setParams()
Vue 报 "Failed to resolve component: conch-report"没配 isCustomElement按 CUSTOM ELEMENT CONTRACT 配
报表打不开,error.code 是 auth_required报表服务开了鉴权,宿主没回 auth / 没设 tokenProvider按 AUTH CONTRACT 接凭证
error.code 是 scope_missing换票时没带 scope带上这个人的范围值,或显式 scopeAll: true
请求 400「由系统按登录身份决定」链接或请求里带了范围参数去掉;范围只经凭证传

GLOSSARY ​

  • 查看态:只有筛选栏和画布的只读页面,view=1,宿主嵌的就是它。
  • 设计器:做报表的界面,带对话面板和属性面板,不要嵌给最终用户。
  • 发布版 / 草稿:嵌出去的链接跟发布版走;草稿是设计者正在改的那份。
  • 数据快照:发布时固化了数据的版本,打开不查库,条件只读。
  • 穿透明细:点图表或指标卡弹出的明细层,查看态里点了就有,宿主不用管。
  • 设计令牌:--cr-* 开头的 CSS 变量,主题只换值不改样式源码。

给 AI 用的纯文本索引在 /llms.txt,每篇原文在 /md/ 下。