深色模式
给 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(动手前必须确认,缺了就问人,不要编)
| 名称 | 例子 | 没有会怎样 |
|---|---|---|
报表服务地址 ORIGIN | https://report.example.com | 写不出 src |
报表 id ID | r260922123456 | 写不出 src |
| 筛选条件 id 及取值来源 | month ← 页面上的月份选择器;dept ← 登录用户的科室 | 条件传不进去或拼错名字 |
| 哪些条件不让使用者改 | dept | 界面口径不对 |
| 要不要报表自带页头 | 宿主已有标题栏 → 不要 | 页面上出现两条标题栏 |
报表 id 从报表服务的报表列表页(每行的「嵌入」按钮)或 GET /api/reports 取。
HARD RULES
- 先定形态:A 还是 B。下面的 URL CONTRACT / POSTMESSAGE CONTRACT 只管 A,CUSTOM ELEMENT CONTRACT 只管 B。别把两套混着写。
- 只嵌查看态(形态 A):
view=1必须有。少了它嵌进去的是设计器(带对话和属性面板),是错的。形态 B 的元素本来就只有查看态,没有这个坑。 - 报表必须已发布。没发布的报表打开只显示一句「还没有发布」;发布由做报表的人在报表服务里点,宿主侧做不了。
- 不要在链接里放 token、密码、签名、SQL。链接会进历史记录和 Referer。报表服务也不接受从客户端传 SQL。
lock不是权限。它只把控件设成只读,改链接就能绕开。按身份限制数据必须走登录凭证(宿主后端换票,见 AUTH CONTRACT),不能靠lock或链接参数交差;写代码时如果用户以为lock能限权,要明确告诉他不能。- 条件变化走
postMessage,不要重新拼src。换src会让 iframe 整页重载、图表重画一遍。首次挂载用 URL,之后用setParams。 postMessage的targetOrigin写具体域名,不要'*';接收侧校验e.origin和msg.source。- 不要替用户猜条件 id。猜错的表现是「页面上多一条提示、筛选没生效」,比报错更难被发现。
- 报表服务开了鉴权(
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 | 必填 |
view | 1 | 必填,查看态 |
version | v3 / draft / 省略 | 省略=当前发布版;draft 仅供发布前自查,不要给客户 |
lock | a,b 或 all | 这些条件只读 |
chrome | 0 | 去掉报表页头(标题、版本、刷新、导出) |
theme | primary:%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=b | store=S001,S002 |
| 不限(清掉报表默认值) | id=(空串) | month= |
链接上不写的条件 = 用报表自己的默认值。写了但报表里没有的 key 会被忽略,页面顶上列出来提示。
POSTMESSAGE CONTRACT(形态 A)
报表 → 宿主,{ source: 'conch-report', type, … }:
| type | 附带字段 | 用途 |
|---|---|---|
ready | id, title, version | 渲染完成;此前发给报表的消息会被丢掉 |
height | height(px) | 内容高度变化;宿主据此调 iframe 高度,避免第二条滚动条 |
params | params(全部条件的当前值) | 使用者或宿主改了条件 |
authRequired | — | 报表要登录凭证;在 ready 之前就会来,收到立即回 auth,不要排队等 ready |
error | message, code, status | 报表打不开(没发布、没权限、服务不通);code 以 auth_ 开头或是 scope_missing 说明是凭证的问题 |
宿主 → 报表,{ source: 'conch-report-host', type, … }:
| type | 附带字段 | 用途 |
|---|---|---|
setParams | params:条件 id → 值(只写要改的) | 改条件并重新取数 |
refresh | — | 按当前条件重新取数 |
setTheme | tokens:令牌名 → 值 | 换配色 |
auth | token:宿主后端换来的凭证 | 交登录凭证;可主动推,也在收到 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 | 必填 |
version | v3 / draft / 省略 | 同 version |
lock | a,b 或 all | 同 lock |
chrome | 0 | 同 chrome=0 |
params | JSON 对象 | 条件值用原生 JSON 类型,不拼字符串:区间 ["2026-01-01","2026-03-31"]、多选 ["S001","S002"]、不限 null |
theme | JSON 对象或 名:值,名:值 | 同 theme |
方法(拿到元素就能调,早于渲染完成也不丢):setParams(obj)、refresh()、setTheme(obj);读当前条件用 el.params。
凭证(报表服务开了鉴权时):el.tokenProvider = async () => token,token 由宿主后端换票得到;是 JS 属性,不要写成 HTML 属性。
事件(从元素冒泡,内容在 event.detail):
| 事件 | detail | 对应形态 A 的 |
|---|---|---|
conch-ready | id, title, version | ready |
conch-params | params | params |
conch-error | message, code, status | error |
没有 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 变量,主题只换值不改样式源码。
