@linkaicli/linkai-cli 0.0.0-stage → 1.0.18

package/knowledge/report-builder/references/chart-types.md

@@ -0,0 +1,167 @@
+# 图表类型（74 种 · 以 v2 chartRegistry 为准）
+
+以 `linkai kinds` 列出的类型为准。用了清单外的类型 → 卡片保存成功但页面白屏「操作异常」（坑 24）。
+旧版文档里的部分类型（meter/count、others/*、card/*、page/* 等）已不存在，**别照抄**。
+
+```bash
+linkai kinds                                  # 随时列本表
+linkai card-chart --ds <dsId> --name "<名>" --kind <大类/类型> --dim <维度[,维度]> --meas <数值,数值> [--series 系列]
+```
+
+「建议」列来自 registry 的 `fieldTip`：「N个维度」→ 第4参逗号分隔；「N个数值」→ 第5参逗号分隔；
+「1个系列/分组」→ 第6参。
+
+状态列（2026-09-17/18 三轮实测，2026-10-14 补测时间轴）：**69/74 建卡开页渲染验证通过，5 种禁用，无未测**。
+带 ★ 的说明是必配项——`clis/linkai/templates.js` 骨架已带默认值，`card-chart` 直接用即可；
+需要建卡后改 config 的（editor 的 html、multiFlowStep 的字段映射、gallery 的字段映射），
+用 `card-get` → 改 chartSetting → `card-save`。
+
+
+## 报表
+
+| 类型 | 名称 | 说明 | 状态 |
+|---|---|---|---|
+| `table/agtable` | AG表格 | 建议选择多个字段作为列 | ✅ 09-17 实测 |
+| `table/gantt` | 甘特图 | 每行为一条最细粒度任务。状态字段仅支持：待启动、进行中、已完成、超时完成、预警、异常。 | ✅ 09-17 实测 |
+| `table/multiFlowStep` | 流程图 | 流程图（甘特同族）：★style.main 填主任务字段 + dynamic.main=[层级字段…] 两者必填，否则只出「请先配置」提示；状态值仅支持 待启动/进行中/已完成/预警/异常 | ✅ 09-18 实测 |
+| `table/s2table` | 多维报表 | 建议 多个数值，多个维度（仅 定制租户构建可用，勿在本环境用） | ⛔ 禁用 |
+
+## 折线图
+
+| 类型 | 名称 | 说明 | 状态 |
+|---|---|---|---|
+| `line/basic` | 基础折线图 | 建议 1个维度，1个数值 | ✅ 09-17 实测 |
+| `line/multiple` | 多折线图 | 建议 1个维度，多个数值 | ✅ 09-18 实测 |
+| `line/step` | 阶梯折线图 | 建议 1个维度，1个数值，1个分组 | ✅ 09-18 实测 |
+
+## 柱状图
+
+| 类型 | 名称 | 说明 | 状态 |
+|---|---|---|---|
+| `column/Grouped` | 分组柱状图 | 建议 1个维度，1个数值，1个分组 | ✅ 09-18 实测 |
+| `column/basic` | 基础柱状图 | 建议 1个维度，1个数值 | ✅ 09-17 实测 |
+| `column/conversionTag` | 转化率柱状图 | 建议 1个维度，1个数值 | ✅ 09-18 实测 |
+| `column/percent` | 百分比柱状图 | 建议 1个维度，1个数值，1个分组 | ✅ 09-17 实测 |
+| `column/stacked` | 堆叠柱状图 | 建议 1个维度，1个数值，1个分组 | ✅ 09-17 实测 |
+
+## 面积图
+
+| 类型 | 名称 | 说明 | 状态 |
+|---|---|---|---|
+| `area/basic` | 基础面积图 | 建议 1个维度，1个数值 | ✅ 09-18 实测 |
+| `area/percent` | 百分比面积图 | 建议 1个维度，1个数值，1个分组 | ✅ 09-18 实测 |
+| `area/stacked` | 堆积面积图 | 建议 1个维度，1个数值，1个分组 | ✅ 09-17 实测 |
+
+## 条形图
+
+| 类型 | 名称 | 说明 | 状态 |
+|---|---|---|---|
+| `bar/basic` | 基础条形图 | 建议 1个维度，1个数值 | ✅ 09-17 实测 |
+| `bar/divideBar` | 正负条形图 | 建议 1个维度，多个数值。正负条形图：数值应含负值（正右负左），全正数+窄卡会挤成一团；config.theme 用 {colors10:[…]} 对象色板才生效 | ✅ 09-18 实测 |
+| `bar/grouped` | 分组条形图 | 建议 1个维度，1个数值，1个分组 | ✅ 09-18 实测 |
+| `bar/percent` | 百分比条形图 | 建议 1个维度，1个数值，1个分组 | ✅ 09-18 实测 |
+| `bar/stacked` | 堆叠条形图 | 建议 1个维度，1个数值，1个分组 | ✅ 09-17 实测 |
+| `bar/symmetric` | 水平对称图 | 建议 1个维度，2个数值 | ✅ 09-17 实测 |
+| `bar/verticalSymmetric` | 垂直对称图 | 建议 1个维度，2个数值 | ✅ 09-18 实测 |
+
+## 饼图
+
+| 类型 | 名称 | 说明 | 状态 |
+|---|---|---|---|
+| `pie/basic` | 饼图 | 建议： 1个维度，1个数值 | ✅ 09-17 实测 |
+| `pie/donut` | 环图 | 建议： 1个维度，1个数值 | ✅ 09-17 实测 |
+
+## 双轴图
+
+| 类型 | 名称 | 说明 | 状态 |
+|---|---|---|---|
+| `dualAxes/columnLine` | 柱线混合图 | 建议： 1个维度，1个数值主轴，多个数值次轴 | ✅ 09-18 实测 |
+| `dualAxes/dualLine` | 双轴折线图 | 建议： 1个维度，多个数值主轴，多个数值次轴 | ✅ 09-18 实测 |
+| `dualAxes/groupedColumnLine` | 分组柱线图 | 建议： 1个维度，多个数值主轴，多个数值次轴 | ✅ 09-18 实测 |
+| `dualAxes/pareto` | 帕累托图 | 建议： 1个维度，1个数值 | ✅ 09-18 实测 |
+| `dualAxes/stackedColumnLine` | 堆叠柱线图 | 建议： 1个维度，多个数值主轴，多个数值次轴 | ✅ 09-18 实测 |
+| `dualAxes/stackedPercentColumnLine` | 百分比堆叠柱线图 | 建议： 1个维度，多个数值主轴，多个数值次轴 | ✅ 09-18 实测 |
+
+## 散点图
+
+| 类型 | 名称 | 说明 | 状态 |
+|---|---|---|---|
+| `scatter/basic` | 散点图 | 建议：1个维度 + 2个数值（均设为主轴），依次为X轴、Y轴 | ✅ 09-17 实测 |
+| `scatter/bubble` | 气泡图 | 建议：1个维度 + 3个数值（均设为主轴），依次为X轴、Y轴、气泡大小 | ✅ 09-18 实测 |
+| `scatter/singleAxisScatter` | 单轴散点图 | 建议： 1-2个维度，1个数值 | ✅ 09-18 实测 |
+
+## 玫瑰图
+
+| 类型 | 名称 | 说明 | 状态 |
+|---|---|---|---|
+| `rose/basic` | 基础玫瑰图 | 建议 1个维度，1个数值，1个系列 | ✅ 09-17 实测 |
+| `rose/grouped` | 分组玫瑰图 | 建议 1个维度，1个数值，1个系列 | ✅ 09-18 实测 |
+| `rose/stacked` | 堆叠玫瑰图 | 建议 1个维度，1个数值，1个系列 | ✅ 09-18 实测 |
+
+## 进度图
+
+| 类型 | 名称 | 说明 | 状态 |
+|---|---|---|---|
+| `progress/bullet` | 子弹图 | 建议： 1个维度，2个数值 | ✅ 09-18 实测 |
+| `progress/gauge` | 仪表盘 | 建议： 2个数值 | ✅ 09-17 实测 |
+| `progress/liquid` | 水波图 | 建议： 2个数值 | ✅ 09-17 实测 |
+| `progress/progress` | 进度条图 | 建议： 2个数值 ✅ 值=第1数值/第2数值，>1 封顶满条 | ✅ 09-18 实测 |
+| `progress/ringProgress` | 进度环图 | 建议： 2个数值 ✅ 同 progress，>1 显示 100% | ✅ 09-18 实测 |
+
+## 指标卡
+
+| 类型 | 名称 | 说明 | 状态 |
+|---|---|---|---|
+| `meter/antdTable` | 表格图 | 建议 1个图片，多个维度，多个数值 | ⛔ 禁用 |
+| `meter/commonMeter` | 通用指标卡 | registry 标记 disabled，选了会报「当前图表已禁用」 | ⛔ 禁用 |
+| `meter/gallery` | 画廊 | 建议 1个图片，多个维度，多个数值。三个必配：★basicStyle.image/title 填字段名；★horizontalCount 必填（如 3）——缺省时 dataByRow 恒空数组、有数据也白屏零报错；图片字段的 dtos format 需设 "img" 才渲染成图，默认显示 URL 文本 | ✅ 09-18 实测 |
+| `meter/list` | 趋势指标卡 | 建议 分组方式：按数值（1个维度，多个数值） 按维度（0或1个数值，多个维度） | ✅ 09-17 实测 |
+| `meter/meterList` | 列表指标卡 | 类型一至五用专用字段配置；类型六已改为 `cardRender.areas` 自定义渲染网格 | ✅ 09-18 实测 + 10-15 确认 |
+| `meter/meterStep` | 阶段指标卡 |  | ✅ 09-18 实测 |
+| `meter/meterTimeline` | 时间轴指标卡 | 按时间字段分组降序，内容用 `cardRender.areas`；时间轴固定显示 | ✅ 10-14 实测 + 10-15 确认 |
+| `meter/step` | 步骤指标卡 | config 不能为空：group.type='custom' 且 groups[0].list 填字段名（waxis1/yaxis1…），否则只出骨架行 | ✅ 09-18 实测 |
+
+## 更多图表
+
+| 类型 | 名称 | 说明 | 状态 |
+|---|---|---|---|
+| `more/funnel` | 漏斗图 | 建议 多个数值 ✅ 可渲染；正经配法=多个数值各一层 | ✅ 09-18 实测 |
+| `more/heatmap` | 矩形热力图 | 建议2个维度 1个数值 | ⛔ 禁用 |
+| `more/matrixHeatmap` | 相关矩阵 | 建议 2个维度，1个数值 | ✅ 09-18 实测 |
+| `more/radar` | 雷达图 | 建议 多个数值 | ✅ 09-18 实测 |
+| `more/radialBar` | 玉珏图 | 建议 1个数值，1个维度，1个分组 | ✅ 09-18 实测 |
+| `more/radialBarGroup` | 分组玉珏图 | 建议 1个数值，1个维度，1个分组 | ✅ 09-18 实测 |
+| `more/radialBarStack` | 堆叠玉珏图 | 建议 1个数值，1个维度，1个分组 | ✅ 09-18 实测 |
+| `more/rank` | 排行榜 | 建议 2个维度，1个数值 | ✅ 09-17 实测 |
+| `more/sankey` | 桑基图 | 建议 2个维度，1个数值 | ✅ 09-18 实测 |
+| `more/treemap` | 矩形树图 | 建议 多个维度，多个数值 | ⛔ 禁用 |
+| `more/waterfall` | 瀑布图 | 建议 1个数值，1个维度 | ✅ 09-17 实测 |
+| `more/wordCloud` | 词云 | 建议 1维度，1个数值 | ✅ 09-17 实测 |
+
+## 网页组件
+
+| 类型 | 名称 | 说明 | 状态 |
+|---|---|---|---|
+| `web/clock` | 时钟 |  | ✅ 09-18 实测 |
+| `web/countdown` | 倒计时 | ✅ 组件正常，目标时间在 config 里配 | ✅ 09-18 实测 |
+| `web/editor` | 富文本 | 富文本：config.html 直接塞 HTML 字符串即渲染，纯接口可配，无需界面编辑器；数据字段无实际作用 | ✅ 09-18 实测 |
+| `web/iframe` | iframe网页 | 组件正常，需 config.url 配目标地址（非数据图） | ✅ 09-18 实测 |
+| `web/swiper` | 轮播图 | 建议 1个维度（图片） | ✅ 09-18 实测 |
+| `web/timeline` | 时间轴 | 建议 1个维度（时间），1个数值 | ✅ 09-18 实测 |
+
+## 大屏图
+
+| 类型 | 名称 | 说明 | 状态 |
+|---|---|---|---|
+| `widget/counter` | 计数器 |  | ✅ 09-18 实测 |
+| `widget/map` | 地图 | ✅ 可渲染；维度必须是省份名才落色块 | ✅ 09-18 实测 |
+| `widget/podium` | 领奖台 |  | ✅ 09-18 实测 |
+
+## 3D
+
+| 类型 | 名称 | 说明 | 状态 |
+|---|---|---|---|
+| `3d/interval` | 3D柱状图 | 建议 2个维度，1个数值。★config.theme 必须是 {colors10:[…]} 对象（同 3d/scatter 的坑） | ✅ 09-18 实测 |
+| `3d/line` | 3D折线图 | 建议 1个维度，3个数值 | ✅ 09-18 实测 |
+| `3d/render` | 3D渲染器 |  | ✅ 09-18 实测 |
+| `3d/scatter` | 3D散点图 | 建议 1个维度，3-5个数值（依次 X/Y/Z/尺寸/颜色）。★config.theme 必须是 {colors10:[…]} 对象——组件读 theme.colors10，给数组必崩 addColorStop(undefined)（前端图表组件的已知问题） | ✅ 09-18 实测 |

package/knowledge/report-builder/references/dashboard-patterns.md

@@ -0,0 +1,138 @@
+# 看板组件配方（按 demo 还原时先查这里）
+
+2026-10-14 按 demo「商品经营看板」在测试租户实测落地后整理。每条标【实测】或【确认】。
+
+## 0. demo / 运营分析方案默认基线【实测】
+
+按 demo 还原，或新建商品经营、款式画像、订单执行、采购履约、仓储等运营分析方案时，除非用户或 demo 明确给出其它值，
+必须在交付前一次性应用并验收下表，不得仅因为 `query` 成功就认为方案已完成，也不要等截图暴露问题后再逐项补：
+
+| 项目 | 默认项 | 写后检查 |
+|---|---|---|
+| PC 内容区 | 24 格画布居中用 `x:2,width:20`，左右各 2 格；同行子卡全部落在 `[2,22]` | 左右边界对称、卡片无越界/重叠；手机布局不随 PC 留白改动 |
+| 手机布局 | PC 同行多卡在手机端按“从左到右、从上到下”依次纵向堆叠；后续区块的 `mobileY` 按前面卡片累计高度顺延 | 不允许两张卡复用同一组 `mobileX/mobileY/mobileWidth/mobileHeight`；全页矩形无重叠 |
+| 页面与内容层次 | 方案 `dataScreenSetting.pageBackgroundColor:#F4F3EE`；分区标题卡、统计指标卡、时间轴指标卡的**方案卡位**默认透明；其它主要内容组件保留 `#FFFFFF` | 暖色出现在页面及留白区；透明色写在 pageCard 的 `dataScreenSetting.backgroundColor`，不写进图表配置 |
+| 分区标题 | `cardType:5`，编号+主标题+`subtitle` 同行，`description:""`、`showDecorLine:false`、PC/手机高 2 格；卡位透明且 `cardTitle.show:false` | 标题无白底、无第二行辅助说明、无滚动条；下游 PC 卡位按压缩量同步上移 |
+| 数据卡外壳 | 数据卡自己的外层标题栏默认隐藏，避免与分区标题重复；保留组件内部必要标题 | `dataScreenSetting.cardTitle.show:false`，但不能误删图表内字段名/图例 |
+| 头部统计指标卡 | 新建与存量统一用列表指标卡 `meter/meterList` + `stepType:'type6'`，数据集一卡一行，内容由 `cardRender.areas` 排版；方案卡位背景保持 `transparent`、`cardTitle.show:false`；**不得用时间轴指标卡 `meter/meterTimeline`**；分组名作为数据列写进卡片第一行 | 存量 `meter/list`、一行 AG 表格、时间轴卡也迁移，不做兼容保留；检查 `areas` 非空、全部指标在当前分辨率可见且无横纵滚动条 |
+| AG 宽度 | **一律** `fitTableWidth:true`（自适应宽度）；等分列把 `agColumnWidths` 基础宽统一设为 `50`，不写超出卡片宽度的大固定宽 | 无横向滚动；全部可见列铺满容器；用户列宽覆盖已排除 |
+| 类型六尺寸 | `cardWidth:100`（只是最小宽，防止窄屏溢出）、`cardColumns` = 卡数；卡宽约 220px（20 格内容区五等分）时两列「标签 / 值」网格放不下长金额，改成单列「标签 值」行；PC 高度按实测卡高取格数；手机端固定单列堆叠，`mobileHeight` ≈ 卡数 × (卡高 + 12) ÷ 24 | 页面上 `.component_MeterListStep6` 的 `scrollHeight == clientHeight`、`scrollWidth == clientWidth` |
+| 卡片外层标题栏 | 有分区标题时数据卡一律 `cardTitle.show:false`；**例外**：卡片自带筛选器（如指标切换器）显示在标题栏里，这类卡保留标题栏 | 回读 pageCard `dataScreenSetting.cardTitle.show`；带 `filters` 的卡为 `true` |
+| AG 明细高度 | 按常见行数给足高度（表头约 36px + 行数 × rowHeight），避免纵向滚动条；出现纵向滚动条时 `fitTableWidth` 会横向溢出约 8px | `.ag-body-viewport` 无纵向滚动、`.ag-center-cols-viewport` `scrollWidth <= clientWidth + 1` |
+| 单行 AG 高度 | LMBI 没有内容驱动的自动格高；按 `卡片格数 = ceil((rowHeight + 约16) / 24)` 取刚好容纳内容的固定高度 | 无纵向滚动、无底部大块留白；只改 PC 时保留 `mobileHeight` |
+| 饼图 / 环图 | `pie/basic`、`pie/donut` 默认用实际数值字段持久降序：`card-sort --card <cardId> --spec "<数值字段>:desc"`；Top N 之外合并“其他” | `plan-get` 中 `sortField` 为目标 `yaxisN desc`，取数 SQL 外层有 `ORDER BY … DESC`；扇区和图例均从大到小 |
+
+这些是本类看板的默认基线，不是覆盖用户选择的全局强制值。修改存量方案时先备份，只补缺失项；已有明确设计值保留。
+
+## 1. 指标卡：四种组件，能做什么
+
+| 组件（chartType） | 数据形状 | 能做 | 做不了 |
+|---|---|---|---|
+| 趋势指标卡 `meter/list` | 任意行，**所有行的数值列求和**后显示 | 多组指标（`config.group.type:'custom'` + `groups:[[字段…]]`）、同环比箭头（`config.thb.fields` 里的字段按正负自动加红↑/绿↓）、条件样式对比图标覆盖默认箭头、`config.fieldConfig[字段].labelVisible` 隐藏标签 | ★**不画迷你线**（名字叫趋势，渲染层 `MeterItemText` 只画数字）；比率列按行求和会错，数据集必须一行 |
+| 列表指标卡 `meter/meterList` | **一行 = 一张卡** | 类型一至五保留标题/主数据/辅助数据/标签/图片等专用配置；**类型六**改为 `cardRender.areas` 自定义渲染，支持列数、最小卡宽、间距、圆角和边框 | 类型一的 `chartField` 是**单个数值**画成占比进度条，不是趋势线；透明背景在方案卡位配置 |
+| 通用指标卡 `meter/commonMeter` | — | — | 已禁用 |
+| **AG 表格一行多列**（非头部统计卡的特殊需求）`table/agtable` | 一行，每个指标一组列 | 每列 = 一张卡：自定义渲染多行（指标名 / 大数字 / **`chartLine` 迷你线** / 同比 / 环比），对比图标 + 颜色标记，千分位/¥ 由数据集出显示列 | 圆角、卡片间隙做不了（是表格单元格）；头部统计指标卡无论新建或存量都迁移到列表指标卡类型六 |
+
+### 1.1 AG 表格做指标卡（含迷你线）【实测】
+
+本节只用于非头部统计卡的明确特殊需求。已有头部 AG 指标卡不沿用本节做兼容维护，统一迁移到列表指标卡类型六。
+
+- 数据集一行：每个指标出 `xx标签`（常量指标名）、`xx显示`（已格式化文本）、`xx趋势`（迷你线 JSON）、
+  `xx同比显示` / `xx环比显示`（取绝对值的文本）、`xx同比率` / `xx同比pp` 数值列（给箭头判断方向），再加常量 `同比标签` `环比标签`。
+  模板参考领谋提供的 `rpt_gop_overall_kpi`。
+- **迷你线**：自定义渲染项 `{"type":"chartLine","field":"<趋势字段>","xField":"x","yField":"y","chartHeight":36}`，
+  字段值是 JSON 数组字符串 `[{"x":"09-13","y":7637}, …]`（`BaseChartRender` 里 `JSON.parse`）。
+  ★JSON 必须用 `json_object()` 在 SQL 里**运行时**生成，不能拼字符串：取数时 SQL 里的大括号会被全部删掉（坑 44）。
+- **卡片标题**：`config.showHeader:false`，第一行放 `xx标签` 字段——不要改字段标题当表头（agtable 改 title 查询会挂）。
+- 箭头：`conditionStyle.arrow.conditions` 每个显示字段两条，颜色：`conditionStyle.fontColor` 同样两条：
+  ```json
+  {"field":"<xx同比显示>","depField":"<xx同比率>","operator":">","value":"0","arrow":"up","color":"","parentId":"<13位随机数>"}
+  {"field":"<xx同比显示>","depField":"<xx同比率>","operator":"<","value":"0","arrow":"down","color":"","parentId":"…"}
+  ```
+- **卡片间隙：不要做**。试过在卡片列之间插 12px「间隔列」+ 关边框 + `cellMark` 铺灰底，列宽固定后整行超出看板宽度、
+  出现横向滚动条，用户要求回滚（2026-10-14）。保持一行 7 列、默认边框，列宽自适应等前端迭代。
+- 金额前缀 ¥：dto 的 `unit` 只能加**后缀**，前缀只能在 SQL 里拼显示列（`CONCAT('¥', REPLACE(money_format(ROUND(x,0)),'.00',''))`）。
+
+## 2. 明细表：合并单元格 + 值和变化率并排 + 箭头 + 分组表头【实测】
+
+数据集是长表（维度值 × 对比期），每个指标带 `xx对比率`（规模量，%）或 `xx对比pp`（比率，pp）。模板：`rpt_gop_dim_detail`
+（= `rpt_gop_dim_overview` + 合计组 + 排序键）。`chartSetting.config.wd.columns`：
+
+| 列 | 配置 |
+|---|---|
+| 维度值 | 普通列，`spanRows:true`（合并单元格）、`fixed:true` |
+| 对比期 | 普通列，`fixed:true` |
+| 每个指标 | `enableCustomRender:true`，一个 row 两个 `labelValue` 项：`[值字段（黑）, 对比字段（紫 #7C3AED，11px）]`，`field:[值, 对比]` |
+| 分组表头 | `{"id":"group_<uuid>","name":"淘宝数据","children":[指标列…]}` |
+| 排序/辅助字段 | `hidden:true` 普通列 |
+
+- 箭头：`conditionStyle.arrow` 每个对比字段 `>0 up` / `<0 down` 两条（字段和 depField 都是对比字段本身）。
+- 合计行底色：`conditionStyle.rowMark` `{"field":"","depField":"<组序>","operator":"==","value":0,"color":"#F7F8FA"}`。
+- 单位：dto `format:'number'` + `unit`（比率 `%`、pp 变化 `pp`、对比率 `%`），`decimal:-1` 取整、`thousandSeparator:true`。
+- 排序：`card-sort --card <cardId> --spec "组序:asc,本期销售金额:desc,对比期序:asc"`（持久排序，分页前生效）。
+- 合计行别用表格自带的「总计」：那是对每列求和，比率/对比率列加总没意义，且固定在底部。
+
+## 3. 图表区块
+
+| demo 要素 | 做法 | 限制 |
+|---|---|---|
+| 折线按维度分线 | `line/multiple`：维度1=月日（x 轴不套日期格式，数据里直接给 MM-DD）、维度2=日期序（YYYYMMDD 整数，不画），数值=指标值，系列=维度值；`card-sort --spec 日期序:asc`（坑 57）；`limitCount:0` | 图例点击切换由 AntV 默认支持；「全选/全不选」按钮做不了 |
+| 指标切换器 | 卡片自带参数筛选器（`update-new` 的 `filters`，`filterProperty:2`、`isSelfadd:"true"` 手工选项）——**显示在卡片标题栏里**【实测】 | — |
+| 环形占比 | `pie/donut`，模板出前 N + 其他；数值字段 `format:number`、`decimal:-1`、`thousandSeparator:true`；默认 `card-sort --card <cardId> --spec "指标值:desc"`，扇区与图例按占比从大到小 | 中心 TOTAL 不套格式（坑 53）；带占比的分页图例做不了；不要只依赖模板 SQL 内层排序 |
+| 气泡四象限 | `scatter/bubble`，系列=象限（模板 `象限` 列）→ 按象限着色 | 均值虚线、象限计数做不了 |
+| 分区标题 | `cardType:5` 标题卡（见 report.md）；数据卡自己的标题栏隐藏（坑 54）。demo 是单行时，说明放 `subtitle`、清空 `description`、高 2 格；原 4 格压到 2 格后下游卡片 `y -= 2` | `subtitle` 和主标题同行，但样式写死斜体；正体说明只能用下方 `description` |
+| 方案左右留白 | 24 格 PC 布局用居中的 20 格内容区：满宽卡统一 `x:2,width:20`，左右各 2 格；多卡同行也必须落在 `[2,22]` 内（见 report.md） | 用户要求更大留白时对称缩宽（如 `x:3,width:18`）；不要用卡内 padding 假留白，手机布局默认不跟着改 |
+| 暖色页面背景 | 方案顶层 `dataScreenSetting.pageBackgroundColor` 设 `#F4F3EE`；分区标题、统计指标卡（`meter/list`、`meter/meterList`）和时间轴指标卡（`meter/meterTimeline`）的方案卡位默认设 `dataScreenSetting:{useCardConfig:true,backgroundColor:'transparent',…}`；其它主内容组件默认保留 `#FFFFFF` 白色层次（见 report.md） | 页面色与单卡色是两层配置；背景只在方案/pageCard 层设置，不新增或依赖图表内部背景配置 |
+
+## 4. 参数变量的分配【实测】
+
+- 只有 19 个变量 `$1~$9`、`$A~$J`，gop 模板基本占满。**同一个变量可以在不同卡片上取不同值**：前端只把
+  `bindUserPageCards` 里包含该卡片的看板筛选器、以及卡片自己的筛选器发给这张卡（`ChartPageView/utils.js` `transformFromServer`）。
+  例：顶部「日期」绑 `$2/$3` 到总览/日趋势等，每月趋势卡自带「月份」筛选器也绑 `$2/$3`；顶部「对比」绑 `$D` 只给明细，
+  日趋势卡自带「指标」也绑 `$D`。
+- 区间筛选器的标签前端会自动加「(区间)」后缀，标签别再写「区间」。
+
+## 5. 报表 SQL 从哪来（商品经营 / gop）
+
+- 优先复用领谋提供的现成报表 SQL 模板（如商品经营 `rpt_gop_*`），原样使用；指标口径以数据字典知识库为准。
+  写新 SQL 时：禁止 `SELECT *` / `alias.*`、关键字大写、注释写在文件头；模板不够用、需要新指标或新视图时请用户联系领谋数据团队。
+- 数据集 SQL 长度：实测 5.2 万字符可保存，10.6 万字符保存失败（DbUpdateException）。不要把两份模板嵌套拼接。
+
+## 6. 第二个看板（发货监控，2026-10-14）补充的配方【实测/确认】
+
+| 需求 | 做法 |
+|---|---|
+| 堆叠柱（两段之和 = 总量） | `column/stacked`，数值放两列（如 待发未逾期 / 逾期未发货），不要系列字段：前端按数值列名当系列（`AntvChart/config.js` default 处理器）；`config.theme` 给两色 |
+| 横条列表（账龄分布） | AG 表格无表头，自定义渲染 `progress` 项：`{"type":"progress","field":"<0~100 的列>","showPercent":false,"progressWidth":300}`；字段是 `format:'percent'` 时按比率 ×100（`ProgressBar/utils.js`）。进度条单色，不能按行分色 |
+| 表格里的进度列 | 同一单元格一行放 `progress`（条长 0~100）+ `labelValue`（发货进度，`format:'percent'`） |
+| 件数药丸（待发灰 / 逾期红 / 已发青） | 件数列做成**自定义渲染**（一个 `labelValue`），加 `conditionStyle.value` 条件 `{field:X, depField:X, operator:'>', value:0, color:<深色>}` → 渲染成「白字 + 底色小圆角」（`textStyle.js` `getConditionValueMarkStyle`）。★底色要深，浅底白字看不清 |
+| 分组表头下子列只显示「待发货」 | 表头取 `field[0]` 的标题（坑 5）。渠道子列 `field: [<同名合计字段>, <渠道字段>]`，渲染项指向渠道字段：表头借合计字段的名字，不用改 title |
+| 渠道下拉显示中文 | 手工选项 `userPageCardFilterValueRes` **只显示 value**（`name` 是筛选器标签，不是选项文字）。要显示中文就让 SQL 认中文值（如 `$B` 同时认枚举与中文名） |
+| 卡片内文本检索框 | 卡片 `filters`：`filterType:3`（条件控件）+ `filterOperationType:35` + `filterProperty:2` 绑变量，渲染成输入框 |
+| 一页里汇总行 | 放在数据集里（组序 0）+ 持久排序 组序 升序；开分页时只在第一页。顶部已有总览卡时干脆不出 |
+| 区块说明文字 | 需和主标题同行：`contentText.config.subtitle`；需另起一行且保持正体：`description`。存量标题改文字用 `replace-page-card`，改高和下游坐标再用 `update-page-card` |
+| 一行的 AG 指标卡高度 | 卡片格数 = ⌈(rowHeight + 约 16) ÷ 24⌉；rowHeight 118 → 6 格（`实际px = 24 × 格数 − 8`，坑 7），多给会在卡下留白 |
+
+## 7. 第三个看板（款式画像，2026-10-14）补充的配方【实测】
+
+| 需求 | 做法 |
+|---|---|
+| 款头卡（图 + 名称 + 十几个属性） | AG 一行无表头：商品列 = image 区（宽 116）+ 文字区（款号 / 款名 / 颜色尺码 / 构成）；属性两两一列，每列四行「标签 / 值 / 标签 / 值」；标签与值都由数据集出 |
+| 系统标签药丸（不同颜色） | 数据集出 `标签N` + `标签N类型`（good/risk/warn），`conditionStyle.value` 按 `标签N类型 == good` 等着色；空标签不显示 |
+| 一组指标卡带组标题 | 首列「分组」：组标题（粗、主题色）+ 组说明（区间、环比 / 同比区间） |
+| 环比 / 同比红绿反向（退货率升高是坏事） | 每个对比显示列两条 `fontColor`：规模类 >0 青 / <0 红，退货率 >0 红 / <0 青；箭头 `arrow` 不分方向含义 |
+| 同一数据集出指标卡和明细 | 指标卡 `limitCount:1` + 持久排序选中合计行（坑 68）；明细卡正常分页 |
+| 合并单元格（款色） | 普通列 `spanRows:true` + 持久排序把同色排在一起（`行序, 款色, 尺码序`） |
+| 卡片外的切换器只影响部分卡 | 方案筛选器 `bindUserPageCards` 只绑那几张（趋势指标 `$F` 只绑趋势图 + 趋势汇总；发货渠道 `$B` 只绑发货三张） |
+| 横向堆叠条（一天一行） | `bar/stacked`，维度 日期标签 + 日期 + 渠道序，系列 渠道，持久排序 `日期:desc,渠道序:asc` |
+| 采购时间轴 | 做不出横向时间线；改成倒序表格：类型 / 状态药丸、交付文字、入库进度条 + 入库文字，建议翻单行浅青底 |
+| 改分区说明 | `replace-page-card`（坑 64） |
+| 商品档案卡（图 + 名称 + 属性网格 + 标签） | **列表指标卡类型一**（`meter/meterList`，`stepType:'type1'`，`horizontal:true`、`cardWidth` 约 1360）：`imageField` 款图、`imageTagFields` 图上角标、`mainField` 款名、`assistantField` 款号、`tagFields` 小标签、`listFields` 属性网格（标签 = 字段 title，`listColumns` 列数）、`footerTagFields` 尾部标签（一格按英文逗号拆，条件样式按单个标签文字匹配）。`title/subTitle` 是写死的文字 |
+| 一张卡一个指标（大数字 + 多行标签/值） | **列表指标卡类型六**：一行数据一张卡，内容改用 `cardRender.areas`（同 AG 自定义渲染）；横向用 `cardColumns` 等分列，`cardWidth` 是最小宽，再配 `cardGap` / `cardRadius` / `showBorder`。需要透出方案暖色底时，把该卡的**方案卡位** `dataScreenSetting.backgroundColor` 设为 `transparent`，不要写入 `stepTypeConfig.type6`。手机或 `listDirection:'vertical'` 固定单列通宽。`areas` 空时会把全部字段按「标签：值」全量兜底渲染，所以正式卡必须明确配 `areas`。旧 `titleField` / `mainField` / `assistantFields` / `assistantColumns` / `mainText` / `cardMinWidth` 已不生效，存量卡需迁移 |
+| 建列表指标卡 | `card-table` 建骨架（全部列注册成维度）→ `card-get` → `chartParentType:'meter'`、`chartType:'meterList'`、`chartSetting:{id:'meterList',parentId:'meter',config:{stepType,stepTypeConfig:{typeN:{…}}}}` → `card-save`；已有卡片可原地改类型，id 不变 |
+| 统计卡与明细区分 | AG 一行卡整行底色：`rowMark` 条件 `{field:'', depField:<任一字段>, operator:'!=', value:'§', color:'#EEF4F2'}`（恒真） |
+| 长说明文字的参数 | 不要横铺成一行十列；数据集拆成「一个参数一行」，AG 三列（参数 / 取值 / 说明，说明用普通列自动换行）+ 隔行底色 |
+| 真正的时间轴（每个时间点一组卡） | **时间轴指标卡** `meter/meterTimeline`：一行数据一张卡，卡内用 `config.cardRender.areas`；按 `timeField` 分组，组间**固定按时间降序**，同组保持原数据顺序；`cardWidth` 180~800px，`cardGap` 同时作用于组间和组内，`cardRadius` 设圆角。方案卡位背景默认 `transparent`。现在时间节点/轴线固定显示，`showTimeline:false` 和 `conditionStyle.rowMark` 都已移除；不需要轴线的普通卡片网格改用列表指标卡类型六 |
+| demo 风格指标卡（标题 + 大数字 + 两列小标签 / 值） | 默认用**列表指标卡类型六**：数据集一卡一行，`cardRender.areas` 每行用 `fieldWidth` 定宽对齐，值可用等宽字体（`fontFamily:'IBM Plex Mono', monospace`）；横向设 `cardColumns` + `cardWidth`，间距/圆角设 `cardGap` / `cardRadius`，需要顶部色条和边框开 `showBorder`。用卡位高度容纳实际换行结果，上线前检查无纵向滚动条。|
+| 统计格子（标签 / 值 / 说明） | 同上，数据集「一格一行」（序 / 排序键 / 标签 / 值 / 说明 / 色），值按「色」列 `fontColor` 着色；说明 `showEmpty:false` |
+| 表格列铺满卡片 | AG `config.fitTableWidth: true`（前端 2026-10-14 新增「自适应表格宽度」）：列总宽 < 卡片宽时等比拉伸，列多时不压缩；行号列、勾选列不参与 |

package/knowledge/report-builder/references/dataset.md

@@ -0,0 +1,152 @@
+# 数据集
+
+## ⚠ 租户隔离：动手前必读
+
+**领谋的租户隔离靠视图，不靠平台。** 每次查询服务端会先注入一句
+`SET @tenant_code = '<当前空间的租户码>'`，但这只是个会话变量 ——
+**只有视图的定义里写了 `WHERE tenant_code = (@tenant_code)` 才会生效**。
+
+数据集「高代码」SQL 能直接查任意底表，于是很容易写出一条**跨租户**的查询：
+
+```sql
+-- ❌ 危险：把别的租户的数据一起查出来了，界面上完全看不出异常
+SELECT ... FROM dwd_shein_goods_d
+
+-- ✅ 两种正确写法
+SELECT ... FROM dwd_shein_goods_d_view              -- 视图自带过滤（如果有配套视图）
+SELECT ... FROM dwd_shein_goods_d WHERE tenant_code = @tenant_code
+```
+
+实测（2026-09-17，scm_warehouse）：
+
+| 项 | 数 |
+|---|---|
+| 库里视图总数 | 165 |
+| 其中带 `@tenant_code` 过滤的 | **93** |
+| `dwd_shein_*` 五张表 | **全是 BASE TABLE，一个配套视图都没有** |
+| 某张底表不带过滤查出来 | 1937 行，**其中 1843 行不属于当前租户** |
+
+**adapter 的防线是硬的、无逃生舱、以领谋接口为权威**：
+`POST /index-block/get-data-source-table-field/<dataSourceId>` 是界面建数据集时的选表清单，
+返回的全部是租户视图——**SQL 里的每张表必须在这份白名单里**，否则直接拒绝。
+
+```bash
+linkai ds-tables [--search 关键字]     # 查白名单（含 0 张就是没暴露）
+```
+
+表不在白名单 = 这件事现在做不了。**本 CLI 不具备操作数据库的能力**（不能建视图、不能查系统库、不能改数据），
+请用户联系领谋数据团队：为所需数据建租户视图，并加进该空间数据源的选表清单。清单是领谋侧配置的，只建视图不一定可用。
+
+演示/占位数据可以用 `UNION ALL` 常量造行，不碰表、天然过防线。
+
+```bash
+linkai sql-check --file detail.sql        # 本地校验（单条只读查询 + 选表清单 + 禁止系统库）→ 服务端推断字段
+```
+
+数据集 SQL 的本地防线：
+
+- 只能是**单条只读查询**：以 `SELECT` 或 `WITH` 开头；多语句、`INSERT/UPDATE/DELETE/DDL/SET`、`INTO OUTFILE` 一律拒绝；
+- 每张表（含逗号连接、JOIN、CTE 内）都必须在 `ds-tables` 清单里；`information_schema`/`mysql`/`performance_schema`/`sys` 一律拒绝；
+- 校验先在本地完成，通过后才提交给服务端。
+
+如果查出来的数据和预期不一致（例如租户归属、重复数据），记录现象（数据集、筛选条件、行数）交给领谋数据团队排查，不要尝试自行修数。
+
+## 建与改
+
+界面上「低代码」那条路只能选白名单表；`linkai` 建的是「高代码」SQL 数据集，同样只能查 `ds-tables` 清单里的视图。
+
+数据集的列**别名就是后面所有配置的映射键**（卡片里叫 `comment`）。一旦卡片建好，**改别名 = 断映射 = 卡片取不到数**；只改值的算法/格式是安全的。
+
+**建和改都走接口**：
+
+```bash
+linkai ds-create --name "数据集名" --file q.sql        # 新建（存前自动把 SQL 格式化成人能读的多行）
+linkai ds-update --ds <dsId> --name "数据集名" --file q.sql  # ★ 原地更新，id 不变、字段映射不断、卡片不用动
+linkai ds-sql --ds <dsId> [--output out.sql]           # ★ 读回库里实际存的 SQL —— 人工审查/复核格式就靠它
+linkai fmt --file in.sql              # 单独格式化（幂等：已是像样多行的不动）
+```
+
+⚠ 实测（2026-09-18）：`add-or-update` 存储**不丢换行**——三个空间抽查的数据集 SQL
+全部是多行原样。「界面里看着一行」多半是编辑器不折行的横向滚动观感。
+不管观感如何，`ds-create/update` 现在都会先过 `formatSql`（`LM_NO_FMT=1` 跳过），
+读回验证用 `ds-sql`。底层读取接口：`GET /index-block-data-argument/data-set-detail/<dsId>`。
+
+底层是 `POST /index-block-data-argument/add-or-update`，三个参数决定它是新建还是更新：
+
+| `indexBlockDataId` | `isNewDataSet` | 结果 |
+|---|---|---|
+| 全 0 | `true` | 新建 ✅ |
+| **已有 id** | **`true`** | **原地更新，返回同一个 id** ✅ ← 就是这个组合 |
+| 已有 id | `false` | **建出一个坏数据集**：id 是新的、`tableCnName` 是空串，<br>拿去建卡片直接 403「数据集Id有误」，而且它不出现在列表里、删都删不掉 ❌ |
+| 全 0 | `true` + 同名 | 400「该数据集名称已存在！」（名称全空间唯一） |
+
+`isNewDataSet` 这个名字骗人 —— **更新时也要传 `true`**。
+
+要判断一个数据集是不是坏的：`linkai ds-fields --ds <id>`，
+正常的第一个字段 `tableCnName` 形如 `sql_comment_<13位时间戳>`，坏的是空串。
+
+**数据集列表与删除**（文档别处没写）：
+
+```bash
+POST /index-block/get-index-block-data-folder-bussiness-info  {"page":{"pageIndex":1,"pageSize":50}}
+POST /index-block/delete-folder-bussiness                     ["<列表返回的 id，不是 objId>"]
+```
+
+被卡片引用的数据集删不掉（403「该数据集已被指标[xxx]使用」），得先把卡片切到新数据集。
+
+
+SQL 里值得预先算好的列：排序用的**数字优先级**列、给人看的**处理建议**文本列、格式化好的**日期**列（`DATE_FORMAT(x,'%Y-%m-%d')`，别把 `23:59:59` 带到界面上）。条件样式判断用数字列比用中文文本稳。
+
+## 数据集保存
+
+`POST /index-block-data-argument/add-or-update`，返回数据集 id：
+
+```jsonc
+{
+  "indexBlockDataId": "<已有数据集的 id；新建时留空>",
+  "isNewDataSet": true,
+  "mode": 2,                                  // 2 = 高代码 SQL
+  "dataSourceId": "<数据源id>",
+  "sql": "SELECT ...",
+  "name": "数据集名", "parentId": "<分组id>", "tag": "", "remark": "", "isPrivate": false,
+  "joinOns": [],
+  "tables": [{
+    "id": "<随便一个 guid>",
+    "tableName": "sql_name_<13位时间戳>",       // 命名是前端凑的，服务端不校验格式
+    "tableComment": "sql_comment_<同上>",
+    "sortNum": 0,
+    "fieldColumns": [{
+      "id": "<guid>",
+      "tableFieldName": "机会ID",              // = SQL 里的列别名
+      "aliasCnName": "机会ID",                 // 同上
+      "fieldComment": "",
+      "argumentType": 0,                      // 数值列（int/decimal）0；其余（文本、日期、布尔）2
+      "calculationMode": 2,                   // 数值 2 / 文本 99
+      "tableFieldType": "decimal",            // decimal | string | datetime
+      "tableFieldTypeName": "bigint",         // 数据库原始类型
+      "sortNum": 0, "sqlType": 0, "isCustomize": false
+    }]
+  }]
+}
+```
+
+`fieldColumns` 照抄 `POST /index-block/get-field-info-by-data-set-sql` 的返回加工即可。
+
+### SQL 模式保存三步（与界面一致，CLI 已内置）【前端 2026-10-21「数据集保存之前校验数据」】
+
+界面上 SQL 数据集点保存时依次做三步，CLI 的 `ds-create` / `ds-update` / `build` 也照此执行，任何一步失败都不保存：
+
+1. **运行**：`POST /index-block/get-field-info-by-data-set-sql {dataSourceId, sql}` → 产生字段，按下表生成映射字段 `fieldColumns`。
+2. **取数验证**：`POST /index-block/get-data-set`，body 为 `{tables(含上一步的 fieldColumns), joinOns:[], mode:2, dataSourceId, isNewDataSet:true, filters:[], sortFields:[], sql}`；返回预览数据（实测约 50 行）。取数失败报 `SQL_INVALID`。
+3. **保存**：`POST /index-block-data-argument/add-or-update`，`tables` 用第 1 步生成的同一份。
+
+映射字段规则（与界面「运行」后生成的一致）：
+
+| `field_type` | `argumentType` | `calculationMode` | `tableFieldType` |
+|---|---|---|---|
+| `int` / `decimal` | `0` | `2`（求和） | `decimal` |
+| 其它（`string`、`datetime`、`bool`…） | `2` | `99`（参与分组） | 原类型 |
+
+`aliasCnName` = `tableFieldName` = 列别名，`fieldComment` 为空串。【实测 2026-11-02】界面建的数据集即此结构；`data-set-fields` 回读时数值列 `argumentType` 显示为 `1`，属服务端转换。CLI 1.0.16 之前把 `datetime` 等非字符串列当成数值、`calculationMode` 记 0，与界面不一致，已修正。
+改已有数据集最省事的办法：**抓一份现成的 body 下来，只换 `sql` 和 `fieldColumns`**——
+里面那些 guid 每次保存前端都重新生成，服务端不在意。

package/knowledge/report-builder/references/fill-import.md

@@ -0,0 +1,95 @@
+# 填报源数据导入、新增与更新
+
+版本：1.0。适用：已有领谋填报方案的文件转换与写入。具体字段、业务键、接口参数与覆盖策略来自当前客户契约和实时接口，本文不是所有填报表通用的写入请求。
+
+## 写前定位
+
+确认用户授权导入的环境、租户、方案、文件和范围；用户已明确要求导入时，无须额外让其选择CLI。`status`确认租户，检索并完整读取客户文档，回读目标卡片、填报块、字段、报表页卡与权限。不能凭同名对象选ID。没有适用契约时先做来源分析，不能把任意Excel塞进已有表。
+
+检查来源表头、页签、类型、单位、期间、版本、维度及映射。允许模板明确支持的差异，例如只有一个业务页签；不要求客户补空的其他页签。未知项目和结构变化记录差异，不丢行、猜映射或当0。
+
+## 新增与更新的判断
+
+转换后先按契约业务键去重，再在目标范围内分页回读已有记录（填报记录身份不是字段审计事件条数）。不能只读第一页就判定不存在。映射业务键到真实持久行ID，同时比较规范化后业务字段的内容摘要。文件哈希用于识别文件，不代替业务键。
+
+| 情况 | 处理 |
+|---|---|
+| 业务键不存在 | 新增；行ID算法按客户契约 |
+| 业务键存在且内容相同 | 跳过，或在已验证的幂等协议下重传；不制造新行 |
+| 业务键存在且内容不同 | 使用既有行ID和已验证的更新协议；不是仅重发新增请求 |
+| 新预算版本 | 若版本属于业务键，新增该版本，保留旧版；展示选择按客户规则 |
+| 一文件内相同键不同值 | 标明冲突来源，不能随意保留最后一条 |
+| 同一业务键已经有多个持久行ID | 报告重复存量，先定位；不擅自删除或只用SQL去重掩盖 |
+| 文件比旧文件少行 | 不能推定删除；确认是全量快照还是增量，按既定删除/作废协议处理 |
+| 编码、科目名或标准化规则改变 | 评估键是否变化，按已确认迁移规则处理；否则仅该部分暂停 |
+
+区分空白不改、空白清空、数值0三种语义，依契约执行。导入批次、文件名变化不自动代表业务值变更。
+
+## 更新能力闸门
+
+稳定UUID只提供确定身份，不证明接口具备upsert。不能仅因HTTP200、返回true、`isInsert=true`或行ID相同就声称覆盖成功。先查询已验证协议；必要时在获授权的隔离测试对象中验证“新增→同键重传→同键改值→分页回读”，证明行数不增、值正确、其他范围不变。生产导入请求不等于授权创建测试对象或在真实数据上试错。
+
+未验证更新协议时，可以处理可确认的新记录；更新部分按实际支持边界暂停并报告，不能改用随机ID追加，也不能声称所有能力已实现。目标键已存在但无法读取其持久行ID或无法验证更新语义时，不执行该键写入。
+
+## 新建填报卡片（硬性规则）
+
+【2026-10-29 实测记录；本次按页面源码复核】接口能保存、能导入、能查询，不等于创建正确。曾经自拼报文建出的填报卡片，字段落在左侧“维度”里，字符类型写成了 `string`，客户在页面上一看就是错的。
+
+**页面流程（唯一正确来源）**：创建卡片 → 在“填报报表”中开启 → 弹窗里填写“填报的字段及类型” → 数据集随便选一个已有的（不建关联，**不要为填报表专门新建数据集**）→ 按需求选择“填报内容依据的字段” → 保存后字段出现在左侧**“填报”**分类下。
+
+**类型只能用弹窗现有选项，禁止自行命名**（`fillFieldType` 取值 → 底层 `tableFieldType`）：
+
+| 选项 | fillFieldType | tableFieldType |
+|---|---|---|
+| 字符 | `varchar` | string |
+| 整数 | `int` | int |
+| 小数 | `decimal` | decimal |
+| 时间 | `datetime` | datetime |
+| 日期 | `date` | date |
+| 布尔 | `bool` | bool |
+| 图片 / 文件 / 按钮 | `img` / `file` / `btn` | string |
+
+- **`fillFieldType` 绝不能写 `string`**。`string` 只是底层 `tableFieldType`，两者不能混用。
+- 顶层 `fillFields` 与 `chartSetting.config.report` 中非空的 `fillFields`（及 `fillField`）镜像配置，字段名称与类型要一致。页面保存时允许 `report.fillFields` 为空，不能因此漏掉顶层 `fillFields`。
+
+**通过 CLI/接口创建或修改时，必须复现页面保存结构**（`/index-block/new`、`/index-block/update-new`）：
+
+- 左侧定义 `indexBlockShowOrderFields` 中每个填报字段：`argumentType: 4`、`isFill: true`、`isCustomize: true`、`fieldExpression` 与 `fieldExpressionDesc` 都写成 `{字段名}`（带花括号）、`uniqueId` 与 `fillFieldProperties[].uniqueId` 相同。
+- 右侧绘制 `indexBlockDataSettingDtos` 引用填报字段时仍是 `argumentType: 2`（维度）、`isFill: true`，这是正常的，不要把绘制区改成 4。
+- 不要只补一个 `isFill` 标记，也不要把 `argumentType` 一律改成 4。`card-save` 和通用 `api` 发送上述两个接口前会做本地校验。
+- 不确定结构时，先在租户里找一张页面创建的填报卡片（或请用户手工建一张测试卡片），用 `get-new-index-block-detail` 回读后逐字段对照，再动正式对象；无法确认就停下来，按页面流程操作。
+
+**验收（缺一不可）**：重新打开卡片，字段出现在左侧“填报”下；填报弹窗里每个字段的类型显示为现有选项（如“字符”）；填报数据行数和下游分析结果与修改前一致。
+
+修正已有错误卡片时保留卡片 ID、字段 `uniqueId`、绘制绑定（`waxisN`）和数据集，只改字段角色、表达式和类型，并先备份卡片和数据基线。
+
+## 填报写入报文格式（硬性规则）
+
+【实测 2026-10-30】写自由填报用 `/index-block/new-fill-field`：
+
+- `fillValues` 里**一条业务记录对应一个元素**，`fillFieldValue` 一次带齐该表全部填报字段（中文字段名→字符串值）。
+- `key` 固定传字符串 `"fillfieldid"`，它的作用是选择填报块（第二个块是 `fillfieldid1`），**不是字段ID或字段uniqueId**。
+- **禁止拆字段写**（一条记录拆成多个元素、每个只带一个字段）：首次写入时后端按记录ID覆盖保存，最后只剩一个字段，填报表页面出现空行；看板如果读变更历史可能仍显示正确，所以不能只看看板验收。
+- 卡片配置了依据字段（`freeFillUniqueFields`）时，可以不传 `value`，后端按依据字段匹配：不存在则新增，存在则更新原记录并保留ID。传 `value` 时必须是已有记录ID，不能自己生成新ID。同一请求内依据字段重复、或已有记录缺依据字段/重复，都会整批报错。
+- 写完必须回读填报表本身（行数、依据字段无空值无重复、抽查整行字段完整），再核对看板。
+- **禁止通过修改分析数据集SQL（按导入批次等过滤）来“去重”或隐藏数据**；导入批次名里的“样本”不代表测试数据。疑似重复先按依据字段核查并报告用户，删除记录必须用户明确同意。
+
+推荐用 `linkai fill-write --card <cardId> --file <records.json>`：按上述格式组包（一条记录一个元素、字段一次带齐），写前校验租户归属和字段名，写后回读填报表行数。
+
+删除填报记录（`/index-block/del-new-fill-field-value`，body `[{"ids":[记录ID…],"isFreeFill":true,"indexBlockDataId":"<卡片所用数据集ID>"}]`，POST）属于需要用户额外明确授权的动作：先备份并列出将删除的记录，用户确认后再调用，删除后回读。
+
+## 写入与恢复
+
+未封装操作通过当前CLI允许的 `api` 调用；先读接口文档、帮助及真实契约。只操作用户授权的填报目标，不把写填报与改数据库、SQL执行或外发推送混同。新建填报对象时须使用完整已验证的创建流程，已有对象导入不重建。
+
+形成批次清单，按接口限制分批。每批记录请求范围、预期动作和回读结果；数量从实际比较得出。既有导入器的`imported`进度不能跨不同文件/任务复用，恢复应绑定文件指纹、转换版本和目标范围。
+
+报错、超时、进程中断时先按键回读：已成功部分记账，确未成功部分再传，未知部分继续核实。保留失败明细便于重试；不盲目重复整批。
+
+## 验收和运行记录
+
+检查业务键唯一性、持久行身份、值、单位、来源范围及控制数。以目标范围的业务记录核对新增/更新/跳过数量，不以审计事件数量或请求条数代替。缺少证据的计数标为未确认。
+
+回读分析结果及筛选选项，使用相同店铺/月份/版本口径对账，不拿全年预算与单月实际直接比较。异常给出具体依据，不自动重算客户源文件。
+
+报告实际处理的文件与范围、新增/更新/跳过/失败/未知数、关键对账结果及未完成原因。保存运行记录，普通补数不修改模型知识；映射、来源契约或业务口径变化后更新方案档案版本。模板见技能assets或 `templates/solution-knowledge/import-run-template.json`。