@guandata/guanvis 0.1.30 → 0.1.32

package/skills/guanvis/references/builder-reference.md

@@ -17,7 +17,7 @@
 | `.addDynamicMetricAdditional(name, fields, options?)` | 添加动态数值组，候选字段写入副轴 |
 | `.addColorBy(field)` | 按指标值渐变着色（接受度量字段，不是维度）|
 | `.addTooltip(field)` / `.addFilter(field)` | 提示/筛选 |
-| `.addSort(field)` / `.addSplit(field)` / `.addSize(field)` | 排序/拆分/大小 |
+| `.addSort(field)` / `.addSplit(field)` / `.addSize(field)` | 排序/拆分/大小；排序字段的排序方向用 `sortType: SortOrder.ASC/DESC` |
 | `.addLocation(field)` / `.addTarget(field)` / `.addCompare(field)` | 位置/目标/对比 |
 | `.setSplitSetting({ rows, columns })` | 拆分行列数（默认各 3），需配合 `.addSplit(field)` |
 | `.setColorByColors(preset_or_config)` | colorBy 渐变色。传 `ColorByPreset.RedGreen` 等预设名称，或 `{ startColor, endColor, middleColor?, steps? }` 自定义 hex 颜色 |
@@ -66,7 +66,7 @@
 | `.addMetric(metric)` | 添加指标平台指标；至少一个 |
 | `.addDynamicRow(name, fields, options?)` / `.addDynamicColumn(name, fields, options?)` | 添加指标平台动态维度组 |
 | `.addDynamicMetric(name, fields, options?)` / `.addDynamicMetricAdditional(name, fields, options?)` | 添加指标平台动态指标组 |
-| `.addFilter(field, filterType, filterValue)` / `.addSort(field)` | 添加筛选/排序 |
+| `.addFilter(field, filterType, filterValue)` / `.addSort(field)` | 添加筛选/排序；排序字段的排序方向用 `sortType: SortOrder.ASC/DESC` |
 | `.setShowTitle()` / `.setShowLegend()` / `.setDataLabel()` / `.setAxis()` / `.setTableSetting()` / `.setRawSettings()` | 常用图表设置，和普通 CardBuilder 一致 |
 | `.setProps(obj)` / `.setRawProps(key, value)` | 设置指标卡片 `meta.chartMain.props` |
 | `.setConfig(obj)` / `.setRawConfig(key, value)` | 设置指标卡片 `meta.chartMain.config` |
@@ -355,6 +355,7 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 | `.removeLayoutItem(cardRef)` | 从当前 Page 根布局移除已放置的 card/selector/layout component；主要给动作级移动 API 使用 |
 | `.addFilterSelectorGroup(group)` | 添加一个筛选栏筛选器组 |
 | `.addFilterSelector(selectorId)` | 显式添加一个未分组的筛选栏 selector，并控制其与筛选器组的顺序 |
+| `.setFilterPanelLayout(config)` | 配置筛选栏的布局相关属性；见下方“筛选栏布局” |
 | `.setFilterLayout(items)` | 整体设置快捷筛选区的 selector / filter selectorGroup ID 列表；checkout 场景会覆盖 base `filterLayout` |
 | `.clearFilterLayout()` | 清空快捷筛选区；常用于把已有快捷筛选器改成画布内普通筛选器卡片 |
 | `.addFilterLayoutItem(items)` | 向快捷筛选区追加 selector / filter selectorGroup ID，已存在则跳过 |
@@ -369,9 +370,61 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 | `.setCardMargin(margin)` | 卡片间距 |
 | `.setFineMode(enabled)` | 开启/关闭精细模式 |
 | `.setDashboardTitle(enabled, options?: { title?: string })` | 开启/关闭仪表板标题；未传 `title` 时默认使用 Page 名称 |
+| `.setExportView(enabled, config?)` | 开启/关闭导出视图；`config.mode` 决定使用分页方向还是单页宽度 |
+| `.setWidthAdaptive(enabled, width?)` | 开启/关闭宽度自适应；默认宽度 1280 |
 | `.setLayoutSetting(config)` | 原始 layout 配置 |
 | `.build()` | 构建 |
 
+#### 导出视图与宽度自适应
+
+```javascript
+// 多页导出：orientation 默认 ExportOrientation.VERTICAL
+page.setExportView(true, {
+    mode: ExportViewMode.MULTI_PAGE,
+    orientation: ExportOrientation.HORIZONTAL
+});
+
+// 单页导出：width 默认 827，可选范围 300 ~ 3000
+page.setExportView(true, {
+    mode: ExportViewMode.SINGLE_PAGE,
+    width: 1440
+});
+
+// 宽度自适应：默认 1280，可选范围 800 ~ 4096
+page.setWidthAdaptive(true);
+page.setWidthAdaptive(true, 1600);
+```
+
+`setExportView()` 以 `mode` 为唯一判断依据。未传 `mode` 时默认 `ExportViewMode.MULTI_PAGE`；多页模式只读取 `orientation`，缺失或非法时使用 `ExportOrientation.VERTICAL`；单页模式只读取 `width`，缺失或非法时使用 827。传入与当前模式不匹配的 `width` / `orientation` 会被忽略并产生 warning。
+
+`setWidthAdaptive(true, width)` 的 `width` 会先静默四舍五入，再校验是否位于 `800 ~ 4096`；缺失或非法时使用 1280。宽度自适应不能与 `layoutType: "responsive"` 同时开启，但可以与导出视图同时开启。
+
+#### 筛选栏布局
+
+```javascript
+page.setFilterPanelLayout({
+    type: FilterPanelLayoutType.GRID,
+    spacing: FilterPanelSpacing.MIDDLE,
+    padding: { top: 8, right: 12, bottom: 8, left: 12 },
+    labelPosition: "top",
+    actionOrder: "right"
+});
+```
+
+所有字段均可选，多次调用按字段增量合并。
+
+`padding` 支持 `top/right/bottom/left` 和`0 ~ 32`内的整数；非数字、`NaN`、`Infinity` 等非法值会产生 warning 并丢弃。
+
+| 字段 | 可选值 | 写入 `page.meta.filterLayoutSettings` |
+|------|--------|----------------------------------------|
+| `type` | `FilterPanelLayoutType.GRID` / `PARAGRAPH` | `layoutType` |
+| `spacing` | `FilterPanelSpacing.SMALL` / `MIDDLE` / `LARGE` | `selPadding` |
+| `padding` | `{ top?, right?, bottom?, left? }` | `paddingValue` |
+| `labelPosition` | `"top"` / `"left"` | `selName.position` |
+| `actionOrder` | `"left"` / `"right"` | `opStyle.order` |
+
+该方法只覆盖上述布局字段。checkout 会在 `.guanvis/base/page.json` 保留完整线上配置，pack/publish 时在此基础上合并布局补丁，因此颜色、字体和背景不会丢失；新页面的视觉字段由主题补齐。
+
 ### AreaTitleBuilder
 
 `areaTitle` 是 Page 根布局里的区域小标题，不是 Card，不绑定数据集，也不会生成 page-card relation。ID 必须以 `areaTitle_` 开头，建议用 `guanvis gen-layout-id areaTitle` 生成。
@@ -569,10 +622,11 @@ registerPage(page.build());
 |------|------|
 | `createSelector(name)` | 创建筛选器 |
 | `.setId(cardId)` | 设置固定资源 ID（同 CardBuilder） |
-| `.setSelectorType(type)` | 筛选器类型：`SelectorType.DS_ELEMENTS`（列表选择，默认）、`DS_INTERVAL`（数值范围）、`CALENDAR`（日期）、`TIME_MACRO`（快捷日期区间） |
+| `.setSelectorType(type)` | 筛选器类型：`SelectorType.DS_ELEMENTS`（列表选择，默认）、`DS_INTERVAL`（数值范围）、`CALENDAR`（日期）、`TIME_MACRO`（快捷日期区间）、`PARAMETER`（全局参数，由 `bindParameter` 自动设置） |
 | `.setFilterType(type)` | 筛选条件：`DS_INTERVAL` 默认 `"BT"`（区间），`DS_ELEMENTS` 默认 `"IN"`。可用值参见 `FilterType` 枚举 |
 | `.bindDataset(dsId)` | 绑定数据集（可选，单数据集场景自动绑定） |
 | `.bindField(field)` | 绑定筛选字段（`DS_ELEMENTS`/`DS_INTERVAL`/`CALENDAR` 必填，`TIME_MACRO` 不需要），使用 `f("字段名")` 引用 |
+| `.bindParameter(paramRef, options?)` | 绑定 `param(dpId)`；参数筛选器不绑定数据集、字段，也不调用 `linkTo*`。覆盖本地默认值时传 `{ inheritParent: false, defaultValue: ... }` |
 | `.setGranularity(granularity)` | 设置 `CALENDAR` 日期筛选器粒度，等价于只允许一个粒度。可用值：`Granularity.YEAR`、`QUARTER`、`MONTH`、`WEEK`、`DAY` |
 | `.setGranularityOptions(options, defaultGranularity?)` | 设置 `CALENDAR` 可选日期粒度列表和默认粒度，例如 `[Granularity.MONTH, Granularity.QUARTER]`。未显式设置时会从目标卡片日期字段粒度自动推断 |
 | `.setTimeMacroOptions(options, defaultMacroName?)` | 设置快捷日期选项（自动设置 `selectorType` 为 `TIME_MACRO`）。`options`: `[{ name, expr }]`，`expr` 使用内置宏名（见示例）。`defaultMacroName` 默认选中的宏名，传 `null` 则不选（页面打开时无默认值），不传则取第一项。不需要 `bindField` 和 `bindDataset` |
@@ -950,6 +1004,216 @@ var logoBase64 = __asset_base64("./logo.png")__;
 - 路径不允许向上跳出内容目录（安全限制）
 - 占位符仅在 `pack`/`publish` 构建时处理，不影响 AI 脚本的可读性
 
+### ComplexReportProBuilder（复杂报表 Pro）
+
+复杂报表 Pro 是 `cdType=10 + subType=COMPLEX_REPORT + version=COMPLEX_REPORT_PRO` 的原生报表卡片。**Pro 是需要单独授权的非默认功能**：仅当用户明确点名"复杂报表 / 复杂报表 Pro"、或修改的卡片本身已是 Pro 时使用（选型门槛见 `complex-report-pro-patterns.md` §0）。旧版复杂报表不支持创建、attach 或 checkout/edit；Pro 父卡也不能使用泛化 `attachCard()`，因为它还需要版本化 xlsx 附件和子数据视图协议。
+
+| 方法 | 说明 |
+|---|---|
+| `createComplexReportPro(name)` | 创建 Pro 父卡 |
+| `.setId(cardId)` | **必填**，24 位父卡 ID |
+| `.setDescription(desc)` | 描述 |
+| `.setTemplate(path)` | 使用已有 `.xlsx`；与 `.setWorkbook()` 二选一 |
+| `.setWorkbook(workbook)` | 使用 `createReportWorkbook()` 结构化生成 xlsx |
+| `.addDataView(alias, cardBuilder)` | 添加子数据视图；新建用普通 CardBuilder，checkout 可传 attachCard Builder |
+| `.setTemplateVersion(n)` | 非负整数。新建通常为 0；checkout 默认生成下一版本 |
+| `.setPagination(bool)` | 写入 Pro 分页配置 |
+| `.setColumnWidthStretch(bool)` | 写入列宽拉伸配置 |
+| `.setGCVersion("new" \| "old")` | GcExcel 版本，默认 `new` |
+| `.setReserveFormulaAndHiddenRCS(bool)` | 是否保留公式与隐藏行列，默认 true |
+| `.setDataSourceRelations(relations)` | 多数据源关联；pack 阶段做结构校验并把视图别名/字段名翻译成子卡 ID/zone key，详见下文 |
+| `.setSpecialValue(values)` | 特殊值配置 |
+| `.setRawSettings(key, value)` | 父卡 settings |
+| `.build()` | 构建并校验 |
+
+Workbook API：
+
+| 方法 | 说明 |
+|---|---|
+| `createReportWorkbook().addSheet(name, fn)` | 新建工作簿和 Sheet |
+| `sheet.setValue(cell, value, style?)` | 常量单元格 |
+| `sheet.setFormula(cell, formula, style?)` | Excel 公式 |
+| `sheet.setDynamicFormula(cell, formula, options?, style?)` | 随扩展区域复制的 GcExcel 模板公式 |
+| `sheet.setContextText(cell, text, { context }, style?)` | 随指定维度父格重复的静态文本，主要用于“小计”标签 |
+| `sheet.bindDimension(cell, reportField(view, field), options?)` | Pro 维度绑定 |
+| `sheet.bindMetric(cell, reportField(view, field), options?)` | Pro 度量绑定 |
+| `sheet.bindImage(cell, reportField(view, urlField), options?)` | 将 URL 字段编译为 Pro 图片单元格 |
+| `sheet.bindSubtotal(cell, reportField(view, metric), options)` | 分组小计；`context` 必须指向同一行左侧的 `setContextText` |
+| `sheet.bindGrandTotal(cell, reportField(view, metric), options?)` | 全表总计；自动使用 `E=N,C=None`，禁止传 `context` |
+| `sheet.merge(range)` | 合并，如 `A1:C1` |
+| `sheet.setColumnWidth(column, width)` | 列宽 |
+| `sheet.setRowHeight(row, height)` | 行高 |
+| `sheet.setRowHidden(row)` / `sheet.setColumnHidden(column)` | 隐藏辅助行/列（数据保留但不显示；column 支持 `"B"` 或 `"B:D"`） |
+| `sheet.setRowStyle(row, style)` / `sheet.setColumnStyle(column, style)` | 整行/整列默认样式（覆盖空白格与未来扩展格，区别于逐格样式）。会覆盖行/列内已有单元格样式，应在单元格写入**之前**声明 |
+| `sheet.beginBlock(anchorCell, reportField(view, key), options?)` | 段落明细块：锚点纵向扩展，块内成员整块随记录重复 |
+
+`beginBlock` 返回块构造器，成员单元格自动挂 `context=锚点`（允许位于锚点下方行，这是普通 `context` 校验禁止的形态）：
+
+| 块方法 | 说明 |
+|---|---|
+| `.text(cell, "标签", style?)` | 随块重复的静态标签 |
+| `.dimension(cell, reportField(...), options?)` | 块内维度值 |
+| `.metric(cell, reportField(...), options?)` | 块内度量值 |
+| `.image(cell, reportField(...), options?)` | 块内 URL 图片 |
+| `.formula(cell, "B2*2", style?)` | 块内动态公式（只能引用单元格） |
+| `.spacer(cell)` | 空隙行（空 contextText，随块重复留白） |
+| `.end()` | 返回 sheet 继续链式调用 |
+
+块校验规则：锚点必须位于块矩形的左上角并纵向扩展；成员只能以锚点为唯一父格；小计/总计绑定不允许放进块内；其他模板单元格不得落入块矩形（GcExcel 会整块重复该区域）。锚点通常是记录 ID，metaType=METRIC 的字段可以直接作锚点（跳过维度类型检查）。语义与 dev29 已验证的手写外部模板版完全一致。
+
+绑定 `options` 支持 `expansion`、`fillMode`、`context`、`countPerPage`、`filter`、`filterBy`、`numberFormat` 和 `style`；维度额外支持 `group`、`sort`，度量额外支持 `aggregate`。未知 option 会直接校验失败，不再静默忽略。
+
+`context` 可写单父格 `A3`，也可写横纵双父格 `A4*B3`。父格必须是维度绑定：左父格与当前格同一行且纵向扩展，上父格与当前格同一列且横向扩展，最多各一个。相同数据视图的层级和交叉表只用 `context`；同时生成同源 `filterBy` 会形成嵌套 `LP(...)`，现在会在 pack 阶段拒绝。`filterBy` 仅用于跨数据视图映射，字段的 view 必须是当前绑定 view，引用的 cell 必须同时列在 `context` 中。`filter` 与 `filterBy` 不能并用。
+
+聚合可用 `SUM/COUNT/AVERAGE/MAX/MIN/PRODUCT/STDDEV/STDDEVP/VAR/VARP`。`AVG` 是输入别名，会编译为 `AVERAGE`；`COUNTA` 不是 Pro 聚合函数，会在本地拒绝。`countPerPage` 只接受正整数或 `*`。分页模式最多设置一个 `countPerPage`，且只能放在没有 `context` 的顶层 `bindDimension` 上；放在嵌套子维度上会导致 Pro 分页器只合并部分祖先单元格，因此 `pack` 会直接拒绝。
+
+小计不要手写老复杂报表的 `G_SUBTOTAL/G_GRANDTOTAL`。Pro 的分组汇总由“维度父格 → `setContextText` 小计标签 → `bindSubtotal` 聚合值”组成；全表汇总使用 `bindGrandTotal`。图片 URL 使用 `bindImage`，编译结果是 Pro 后端识别的 `&=IMAGE(G_TEXT({{view.field(...)}}))`，导出时最多处理 1000 个图片单元格，下载失败时会回退显示 URL。图片表格的模板总宽度小于卡片时，优先对父卡调用 `.setColumnWidthStretch(true)` 横向自动铺满，并通过图片列宽与图片行高控制展示比例。Pro 后端会把图片 shape 设置为整个单元格区域，不提供 `contain/crop` 参数；原图画布自带的白边只能在图片源侧裁切。
+
+动态扩展行/列中的占比、同比、差值等公式应使用 `setDynamicFormula()`；普通 `setFormula()` 只适合不需要随模板扩展复制的 Excel 公式。动态公式只能引用单元格，options 只支持 `context`；数据字段引用、内部 `LP/LPF`、未配对括号和其他被忽略的 option 会校验失败。
+
+动态公式的 `context` 还可以指向同行左侧的 `setContextText` 小计标签，实现"分组级公式聚合"：`setDynamicFormula("D3", "SUM(D2)", { context: "B3" })` 会随每个分组复制，GcExcel 把引用改写为整组区域（多明细组变成 `SUM(D2,D4,...)`），对数据绑定列和动态公式列都有效（dev29 已实测，独立求和核对一致）。AVERAGE 等其他聚合同样可用。注意小计公式格的数字格式来自它自己的 style，不继承明细列。
+
+纵向父格允许跨行：父格只需位于子格的左上方位（同行左、同列上、或左上区域均可），不必与子格同行。这覆盖阶梯布局——组标题独占一行（锚点），明细行在下方其他列挂该锚点，小计标签行也跨行挂锚点；GcExcel 会按组正确重复并把跨行小计公式改写为组区域（如 `SUM(C3:C103)`，dev29 已实测）。横向父格仍要求同列上方；`bindSubtotal`/小计行公式的标签仍要求同行左侧。
+
+`sheet.setFreeze(rows, cols, { topLeftCell? })` 冻结顶部行/左侧列（可选 `topLeftCell` 记录可滚动区的视口锚点格，须位于冻结区之外，默认冻结区后的第一格）；`sheet.setConditionalFormat(range, rules)` 写条件格式，rule 支持单元格比较 `{ op: ">", value: "1000", backgroundColor: "#FFC7CE", fontColor: "#9C0006" }`（op 限 `> < >= <= == !=`）或公式条件 `{ formula: "MOD(ROW(),2)=0", backgroundColor: "#EAF3FB" }`（斑马纹）；rule 可加 `stopIfTrue: true` 命中后阻止后续规则求值（多档配色）。规则求值顺序 = rules 数组顺序；多个 `setConditionalFormat` 之间按操作声明顺序求值（重叠区域配合 stopIfTrue 时顺序有语义，反编译也按此全局顺序还原）。注意 `value` 是**公式片段**：数字直接写（`"1000"`），文本常量必须带引号（`value: "\"缺货\""`），裸文本会被 Excel 解释为名称引用。dev29 已实测：GcExcel 完整保留模板的冻结窗格与条件格式，且把条件格式区域自动裁剪到扩展后的数据区（写 `B2:B10000` 即可覆盖整列扩展区）。超链接分两种形态（均 dev29 实证）：**静态格**用 `setHyperlink(cell, url, { tooltip? })`（GcExcel 渲染保留，适合标题/说明/返回目录格）；**扩展区行级链接**用 `setDynamicFormula` + `HYPERLINK("url","文本")`（展开为 shared formula 每行可点）——worksheet 超链条目按固定 ref 定位，不随模板行复制，所以不要给扩展区模板格挂 setHyperlink。颜色必须 `#RRGGBB`。
+
+打印/静态资产扩展（dev29 已实测 GcExcel 全部保留）：`sheet.setImage(cell, path, { scaleX?, scaleY? })` 把**本地** png/jpg/jpeg/gif 嵌入单元格（logo/印章/装饰图；路径相对工程目录且不得逃逸；行级图片列仍用 `bindImage` URL 字段）；style 支持 `diagonalDown: true`（斜线表头，`diagonalColor` 可自定义颜色）；`sheet.setPrintTitleRows(from, to?)` 让表头行在打印/导出每页重复（xlsx Print_Titles）；`sheet.setHeaderFooter({ header?, footer? })` 设置页眉页脚（支持 `&P`/`&N` 页码代码）。序号列用 `setDynamicFormula("ROW()-N", { context: 同行右侧维度格 })`——校验器专门放行"动态公式挂同行右侧父格"的最左序号列形态，GcExcel 逐行展开为 1,2,3…。
+
+启用 `.setPagination(true)` 时只能包含一个 Sheet，且不能使用 `filter`/`filterBy`；同源层级继续使用 `context`，但分页锚点自身必须是无 `context` 的顶层维度。这些约束对 `.setWorkbook()` 结构化模板和 `.setTemplate()` 外部 xlsx 一视同仁：外部模板会在 pack 阶段扫描 `{{...}}` 块的 `CP/C/F` 属性做同样的拒绝。需要保留更高层标签时，应把分页粒度提升为第一层，或把更高层标签改为固定标题/重复列。新建 Pro 必须和引用它的 Page 一起打包，否则后端虽可能报告导入成功，但卡片查询不可用。
+
+多数据源用 `.setDataSourceRelations([group, ...])`，每个 group 定义一个 JOIN 出来的虚拟视图：
+
+```javascript
+report.setDataSourceRelations([{
+    tableName: "产品供应商",               // 模板中通过 产品供应商.字段 引用
+    relations: [
+        { leftId: "products", rightId: "suppliers",
+          leftColumnKey: "供应商ID", rightColumnKey: "供应商ID", joinType: "INNER" },
+        { leftId: "products", rightId: "categories",
+          leftColumnKey: "类别ID", rightColumnKey: "类别ID", joinType: "INNER" }
+    ],
+    selectedCols: [
+        { viewId: "suppliers", key: "公司名称", name: "" },   // name 为空输出显示名
+        { viewId: "categories", key: "类别名称", name: "" },
+        { viewId: "products", key: "订购量", name: "" }
+    ]
+}]);
+```
+
+`leftId/rightId/viewId` 写数据视图别名（也接受 checkout 回读时的子卡 ID），`leftColumnKey/rightColumnKey/key` 写字段显示名（也接受已有 zone key），pack 时统一翻译为后端需要的子卡 ID 和 zone key。`joinType` 仅支持 `INNER/LEFT_OUTER/RIGHT_OUTER/OUTER`（省略默认 `LEFT_OUTER`）；同组 relations 必须把所有视图连成一张连通图，断图会在本地直接拒绝（后端同样拒绝）。JOIN 键如果是 metaType=METRIC 的 ID 字段，在子视图里用 `AggrType.MAX` 带出即可。模板引用虚拟视图时字段名必须出现在该组 `selectedCols` 输出中；`tableName` 会自动补进 `viewNames`。虚拟视图输出是行级明细，`bindSubtotal`/`bindGrandTotal` 聚合它们照常可用。dev29 已验证三源 JOIN + 两级小计 + 总计 + 动态公式。
+
+页面筛选器可以联动 Pro 的数据视图：`createSelector(...).linkTo(index, "字段名")` 的可联动目标序列包含 Pro 子视图（按 `addDataView` 顺序），运行时走与自定义图表相同的 `childFilters` 机制，小计/总计随筛选重算。发布后可用 `guancli card preview <proId> --filter "字段 EQ 值"` 无头验证同一机制。
+
+“每条记录一个多行块”的段落明细形态优先用 `sheet.beginBlock()` 结构化表达（见上表）。手工维护的外部 xlsx 模板也可以实现同样语义：把纵向锚点 `{{view.主键(S=None)}}` 放在块左上角，块内其余标签写 `文本{{(C=锚点)}}`、值写 `{{view.字段(S=None,C=锚点)}}`（含锚点下方行），空隙行用 `{{(C=锚点)}}`。注意值单元格必须显式写 `C=`：省略时 GcExcel 会按默认父格推断挂到左侧模板格，若左侧标签又显式挂回值单元格会形成父格循环依赖——`pack` 现在会在本地按同样的推断规则做环检测直接拒绝（`guanvis report inspect <xlsx>` 可单独查看模板格、父格链与环检测结果）。数据视图的 `.setLimit(n)` 不会限制 Pro 导出行数。
+
+checkout 得到的 `templates/<cdId>.xlsx` 可用 `guanvis report decompile <xlsx> [-o workbook.js]` 反编译为等价的 `createReportWorkbook()` JS 源码（段落块还原为 `beginBlock`，小计/总计还原为 `bindSubtotal`/`bindGrandTotal`，冻结窗格还原为 `setFreeze`，单元格比较/公式类条件格式还原为 `setConditionalFormat`，序号列/阶梯布局等所有 pack 校验放行的父格形态都不会被误判成块，`F=` 过滤原样保留为 `filter` option）；把 card JS 的 `.setTemplate(...)` 换成 `.setWorkbook(workbook)` 后模板即文本化，可由 AI 直接编辑。反编译结果在替换前务必 `preview`/`pack` 校验一遍。
+
+**创建与编辑共用一套 Workbook DSL**，`createReportWorkbook(templatePath?)` 的可选参数决定基底：
+
+| 方法 | 说明 |
+|---|---|
+| `createReportWorkbook()` | 空白基底，从零构建（每个 Sheet 都是新建） |
+| `createReportWorkbook(templatePath)` | 以工程内已有 xlsx 为基底做增量编辑（路径相对工程目录，不得逃逸）；未被操作触及的部件（条件格式、图片、冻结、数据验证、样式）原样保留 |
+| `.addSheet(name, fn)` | 新建 Sheet；基底模式下同名 Sheet 已存在则 pack 失败并提示改用 editSheet |
+| `.editSheet(name, fn)` | 编辑基底中已存在的 Sheet；仅基底模式可用，Sheet 不存在则 pack 失败并提示改用 addSheet |
+| `fn(sheet)` 内 | 两种模式方法完全同名（setValue/bind*/setDynamicFormula/setContextText/merge/setColumnWidth/setRowHeight/setFreeze/setConditionalFormat/setImage/...） |
+| `sheet.clearCell(cell)` | 仅 editSheet 可用：清除单元格内容（样式保留） |
+| `sheet.unmerge(range)` | 仅 editSheet 可用：拆开合并区（配合重新 `merge`） |
+| `sheet.insertRows(startRow, count?)` / `removeRows(startRow, count?)` | 仅 editSheet 可用：插入/删除整行。合并区、真实公式等 xlsx 部件由引擎自动调整，**Pro 模板表达式**（动态公式单元格引用、`C=`/`F=` 父格）同步自动重写；删除仍被其他模板格引用的行会以 dangling-reference 报错拒绝 |
+| `sheet.insertCols(startCol, count?)` / `removeCols(startCol, count?)` | 仅 editSheet 可用：插入/删除整列（列可写字母 `"B"` 或数字），引用重写与行操作相同 |
+| `sheet.setCellStyle(cellOrRange, style)` | 仅 editSheet 可用：**合并语义**改样式——只覆盖 style 对象里给出的属性，未给的属性（如原有 bold/字号）保留；与各操作自带 style 参数的整体替换语义不同 |
+| `{ overwrite: true }` | editSheet 中操作落点已有 `{{...}}`/`&=` 模板表达式时必须显式声明，否则 pack 拒绝（防止静默丢绑定）。绑定类/`setDynamicFormula`/`setContextText` 写在 options 里；`setValue`/`setFormula`/`setRow`/`setColumn` 通过第 4 个参数传：`setValue(cell, value, style, { overwrite: true })`。从零 addSheet 中传 overwrite 会被校验拒绝 |
+
+结构编辑的书写约定：`insertRows`/`insertCols` 之后的操作坐标一律按**移位后的最终位置**书写（操作按链式顺序真实执行）。dev29 实证：财务固定科目表插"口径"列 + 插科目行后，右侧三列 `bindGrandTotal`、下方 `B3-B4` 派生公式与 `IF` 费用率公式全部自动重写且数值正确；标题合并区随插列自动扩展。
+
+**多轮编辑必须累积操作**：`createReportWorkbook(templatePath)` 的基底是本地 `templates/` 快照，每次发布应用的是「基底 + 当前 editSheet 全部操作」。对同一工程做第二轮修改时，要在原操作序列后**追加**新操作（坐标按前序操作移位后书写），不能只保留新一轮操作——否则上一轮修改会从线上消失（dev29 实测踩过）。想从头写增量时，先重新 `checkout` 刷新本地基底。
+
+批量写入与页面级设置（对齐 sheet_engine 指令集，addSheet/editSheet 通用）：
+
+| 方法 | 说明 |
+|---|---|
+| `sheet.setRow(startCell, values, style?)` | 从 startCell 起横向批量写标量值，数组元素 `null` 跳过该格；style 应用到每个写入格。表头行一行写完 |
+| `sheet.setColumn(startCell, values, style?)` | 纵向批量写（固定科目列一次写完） |
+| `sheet.setColumnWidth(col, width)` | col 支持 `"B"` 或范围 `"B:D"`（整段同宽） |
+| `sheet.setSheetDefaults({ defaultColumnWidth?, defaultRowHeight?, defaultRowHidden? })` | 未显式设置宽高的行列默认值（编译时自动先于其他操作应用，脚本内位置不影响结果）；`defaultRowHidden: true` 使未显式声明的行默认隐藏（OOXML zeroHeight） |
+| `sheet.setHyperlink(cell, url, { tooltip?, display? })` | **静态格**超链接（标题/返回目录等固定格；dev29 实证 GcExcel 渲染保留）；`display` 为链接可见文本（格无自身值时用户看到的就是它）。超链不随模板扩展复制——扩展区行级链接用 `setDynamicFormula` + `HYPERLINK("url","文本")`（dev29 实证展开为 shared formula 每行可点） |
+
+样式对象在原有 `bold/italic/fontSize/fontColor/backgroundColor/horizontalAlignment/verticalAlignment/wrapText/numberFormat/borderColor/diagonalDown` 基础上新增（compile/decompile/setCellStyle 合并三端一致，roundtrip 有测试锁定）：
+
+| 属性 | 说明 |
+|---|---|
+| `underline: true \| "single" \| "double"` | 下划线（会计合计线常用 double） |
+| `strikeout: true` | 删除线 |
+| `fontFamily: "宋体"` | 指定字体 |
+| `indent: 1` | 缩进级别（利润表"减：营业成本"科目层级） |
+| `border: { style, color? }` | 四边统一边框；style 取 `thin/medium/thick/double/dashed/dotted/hair`，color 缺省黑 |
+| `borderTop/borderRight/borderBottom/borderLeft: { style, color? }` | 按边框（合计行"下双线"用 `borderBottom: { style: "double" }`） |
+
+`borderColor: "#RRGGBB"` 仍是"四边 thin"的简写。
+
+挂载入口统一为 `report.setWorkbook(workbook)`，与 `.setTemplate(path)`（引用现成 xlsx 不做任何修改）二选一。基底模式 pack 时先把操作叠加到基底编译出临时 xlsx，再执行与外部模板完全相同的校验（引用进查询区、父格图环检测、分页约束）；从零模式则直接做 AST 级校验（错误信息带单元格）。`guanvis diff` 会把基底编辑的每条指令以 `card.template["Sheet"].op[i]` 逐条列出作为模板级变更描述。发布成功后 CLI 自动把工程 JS 的 `.setTemplateVersion(N)` 改写为 N+1，避免下一轮模板编辑命中服务端同版本缓存静默不生效。
+
+主标题、表头和明细行必须形成明确的高度层级。Excel 默认行高约 15pt，不适合 16px 以上的合并标题；推荐主标题 32–36pt、列头 22–26pt、普通明细 18–22pt，并给标题设置 `verticalAlignment: "center"`：
+
+```javascript
+sheet.merge("A1:F1")
+    .setValue("A1", "销售经营月报", {
+        fontSize: 16,
+        bold: true,
+        horizontalAlignment: "center",
+        verticalAlignment: "center"
+    })
+    .setRowHeight(1, 34)
+    .setRowHeight(2, 25);
+```
+
+如果标题合并了两行，应按合并后的总高度判断，例如两行各 30pt；不要再额外叠加单行 36pt。
+
+```javascript
+var view = createCard(ChartType.DATA_GRID, "sales")
+    .setId("bbbbbbbbbbbbbbbbbbbbbbbb")
+    .bindDataset(DS)
+    .addRow(f("区域"))
+    .addMetric(f("销售额", { aggrType: AggrType.SUM }));
+
+var workbook = createReportWorkbook().addSheet("月报", function (sheet) {
+    sheet.merge("A1:B1")
+        .setValue("A1", "销售月报", {
+            fontSize: 16, bold: true,
+            horizontalAlignment: "center", verticalAlignment: "center"
+        })
+        .setRowHeight(1, 34);
+    sheet.bindDimension("A3", reportField("sales", "区域"));
+    sheet.bindMetric("B3", reportField("sales", "销售额"), {
+        aggregate: "SUM", context: "A3", numberFormat: "#,##0.00"
+    });
+});
+
+registerComplexReportPro(createComplexReportPro("销售月报")
+    .setId("aaaaaaaaaaaaaaaaaaaaaaaa")
+    .setWorkbook(workbook)
+    .addDataView("sales", view)
+    .build());
+```
+
+分页与两级小计、总计组合的核心模板结构如下：
+
+```javascript
+sheet.bindDimension("A3", reportField("orders", "城市"), {
+    countPerPage: 20
+});
+sheet.bindDimension("B3", reportField("orders", "客户"), { context: "A3" });
+sheet.setContextText("A4", "城市小计", { context: "A3" }, subtotalStyle);
+sheet.bindSubtotal("D4", reportField("orders", "金额"), {
+    aggregate: "SUM", context: "A4", numberFormat: "#,##0.00"
+});
+sheet.bindGrandTotal("D5", reportField("orders", "金额"), {
+    aggregate: "SUM", numberFormat: "#,##0.00"
+});
+```
+
+发布后必须执行 `guancli card preview <proCardId> -o result.xlsx`，并打开结果确认数据已展开、没有残留 `{{...}}` 模板表达式；因为只有 GcExcel 能验证最终模板语义。完整协议、checkout 和线上能力矩阵见 `designs/complex-report-pro.md`。
+
 ### DuPontBuilder（杜邦分析图）
 
 杜邦分析图不是普通 `ChartType`，而是 BI 的 `LAYOUT` 卡片（`cdType=9`），meta 结构为 `{ layoutType: "DU_PONT", layout: ... }`。guanvis 用 `createDuPontChart()` 创建父卡片，用普通 `CardBuilder` 创建每个节点中的指标卡。
@@ -1183,11 +1447,42 @@ option = {
 
 > **适用场景**：ECHARTS_LITE 自定义地图仅适用于不需要其他 JS 库的简单场景。Tableau 迁移场景应使用 **SDK 模式**（支持 Vega-Lite 等更灵活的库）。中国地图优先使用 `BASIC_MAP` 内置图表。
 
+#### 编辑已有自定义图表（checkout 反编译 + attachCard 内容编辑）
+
+`guanvis checkout` 遇到普通自定义图表（cdType=CUSTOM，subType 为 `SDK` 或 `ECHARTS_LITE`，对照后端 CustomCardType 真实枚举）时，会把线上内容**反编译成可编辑源文件**（pack 内联流程的精确逆变换）：
+
+```
+project/
+├── card_02_<cdId>.js               ← attachCard(...).loadContent("charts/<cdId>")
+└── charts/
+    ├── <cdId>.js                   ← 图表脚本（必生成；可直接编辑）
+    ├── <cdId>.html / <cdId>.css    ← 仅线上内容非空时生成
+    └── <cdId>_assets/              ← 从脚本/HTML 抽取的内嵌资源
+        ├── asset_01.json           ← 原 __asset_text 内联的大 JSON/文本
+        └── asset_02.png            ← 原 __asset_base64 内联的图片
+```
+
+- **内嵌资源抽取**：脚本中 ≥2KB 的内联字符串字面量（GeoJSON、base64 图片等）会被抽取回独立文件，脚本恢复为 `__asset_text("./<cdId>_assets/asset_01.json")__` / `__asset_base64("./…/asset_02.png")__` 占位符形式。每个抽取都经过「重新内联后与原文逐字节相等」验证，验证不过就放弃抽取仅还原原文——未编辑的 checkout 工程 `guanvis diff` 恒为空。
+- **编辑方式**：直接改 `charts/<cdId>.js`（或 .html/.css、替换 assets 里的资源文件），pack/publish 时经 `loadContent` 自动回填进 `card.meta`，diff 会显示 `card.meta.script` 的路径级变更。占位符引用的资源文件缺失、越界或不可读时 pack/publish **直接报错**，不会把 `__asset_text(...)__` 残留发布上线。
+- `.html`/`.css` 文件**不存在时保留线上原值**；要清空内容需写入空文件。重跑 checkout 会重建 `charts/<cdId>.*` 与 `<cdId>_assets/`（本地未发布的脚本修改会被线上版本覆盖；`--refresh-base` 则不触碰 charts/）。
+- **不做反编译的 CUSTOM 子类型**（checkout 保持普通 attachCard，内容编辑 API 一律报错）：`COMPLEX_REPORT` 走 Pro 专属流程；`PLUGIN`/`PLUGIN_LITE` 的内容事实源是 `pluginId` 引用的插件市场资源，本地改副本会与插件脱钩并可能破坏按插件渲染的逻辑，应更新插件本体；`REPORT_FORM` 是表格填报模板配置，不是渲染脚本。
+
+`AttachedCardBuilder` 的内容编辑 API（仅对 subType 为 `SDK`/`ECHARTS_LITE` 的自定义图表卡有效，其余 cdType/subType 一律报错）：
+
+| 方法 | 说明 |
+|------|------|
+| `.loadContent(baseName)` | 从 `<baseName>.js/.html/.css` 加载内容（`.js` 必须存在，`.html`/`.css` 缺失时保留 base 值）；checkout 反编译工程默认使用这条链路 |
+| `.setScript(script)` / `.setHtml(html)` / `.setCss(css)` | 内联覆盖单项内容；与 `loadContent` 同时使用时内联值优先（会有 warning） |
+| `.setContent(html, css, script)` | 一次性内联设置三项 |
+| `.setLibs([url, ...])` / `.addLib(url)` | 替换 / 追加外部 JS 库列表 |
+
+所有通过 `loadContent`/`setScript`/`setHtml`/`setCss` 写入的内容都会走 `__asset_text`/`__asset_base64` 占位符替换（相对内容文件所在目录解析），与 `createCustomChart` 的行为一致。
+
 ### 枚举常量
 
 | 枚举 | 常用值 | 说明 |
 |------|--------|------|
-| `ChartType` | `BASIC_COLUMN`, `BASIC_BAR`, `BASIC_LINE`, `PIE`, `PIVOT_TABLE`, `DETAIL_TABLE`, `KPI_CARD`, `BASIC_MAP`, `WORLD_MAP`, `POINT_MAP`, `BUBBLE_MAP` 等 74 种 | 图表类型（与后端 ChartType.scala 一一对应）。地图类型使用 `addRow()` 放地理维度 |
+| `ChartType` | `BASIC_COLUMN`, `BASIC_BAR`, `BASIC_LINE`, `PIE`, `PIVOT_TABLE`, `DETAIL_TABLE`, `KPI_CARD`, `BASIC_MAP`, `WORLD_MAP`, `POINT_MAP`, `BUBBLE_MAP` 等 74 种 | 图表类型（与后端 ChartType.java 对应）。地图类型使用 `addRow()` 放地理维度。后端 `GANTT(74)` 未提供：guandata-web 前端尚无甘特图渲染实现，创建会产出前端不能渲染的卡片；attach 回写已支持透传 GANTT 卡 |
 | `AggrType` | `SUM`, `AVG`, `COUNT`(=CNT), `COUNT_DISTINCT`(=CNT_DISTINCT), `MIN`, `MAX` | 聚合类型 |
 | `FieldType` | `STRING`, `INT`, `LONG`, `DOUBLE`, `FLOAT`, `DATE`, `BOOL`, `DECIMAL` | 字段数据类型 |
 | `SortOrder` | `ASC`, `DESC` | 排序方向 |