@finebi/finebi-cli 1.6.1 → 1.6.2

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/docs/acceptance.md

@@ -1,67 +1,80 @@
-# 开发与验收
-
-本文件用于生成项目的独立验收，无需 CLI 源仓库。测试夹具、真实开发身份和生产访问者身份分别记录，不能互相代替。协议以[数据契约](data-contract.md)、[筛选](filters.md)和[认证部署](auth-and-deploy.md)为准。
-
-## 1. 绑定与设计准备
-
-先记录以下最小清单，证据与临时文件放项目 `temp/`；不记录密码、token 或 Cookie。
-
-| 项目 | 核实内容 |
-|---|---|
-| 来源 | CLI profile、目标地址、dashboardId、目录入口或分析主题；板内实例 entryId |
-| 字段与指标 | queryFields.dId、选定 datasetId、维度/指标、公式或聚合、单位；记录数不能自动解释为去重对象数 |
-| 时间 | 时间粒度、原值编码、显示时区；日期条件与时间戳轴标签分开核实 |
-| 筛选 | 真实控件名、类型、默认行为、候选项来源、组件作用范围；无源控件时不添加服务端筛选 |
-| 范围 | 返回行数、hasNext、normalization、warnings；不根据首页推算全量 |
-| 设计 | 使用者和主要决策、首屏重点、导航/分组/密度，与既有布局的区别 |
-
-先完成一个指标、一张图，以及存在时的一个真实筛选：源结果 → 页面值 → 应用条件 → 恢复保存默认。证据不足时说明未知项，继续不依赖该项的工作。
-
-## 2. 本地自动检查
-
-1. 首次安装使用 `npm ci`。
-2. `npm test` 验证已覆盖的数据、配置、认证、交互逻辑和分包行为。
-3. `npm run build` 完成类型检查与生产构建。
-4. `npm run test:browser` 启动独立浏览器验收页，打开终端给出的本机地址。选择布局后运行检查；按第 3 节调整浏览器视口并重复运行。页面必须显示 PASS，FAIL 或未完成不能视为通过。
-
-浏览器验收页只使用 `tests/browser/` 中的合成响应，复用实际 App、查询编码、适配器和图表组件；不读取 `.env.local`、不使用开发代理、不访问 FineBI。它检查图形实际绘制、运行错误、筛选草稿/应用/恢复、目录入口与组件作用范围、空/部分/失败状态、单项重试和组件边界。截图判断、真实权限、生产部署和未覆盖控件仍需人工或对应专项验证。
-
-测试页和夹具不得复制到 public/ 或生产配置。`npm run build` 只构建正式入口；浏览器测试服务仅在回环地址使用，完成后停止。
-
-## 3. 浏览器视觉与交互
-
-检查实际应用整页，包括首屏、图表中段、最后一行和明细。推荐 1440、1024、390px 视口；记录实际宽度，不把桌面缩放当成小屏验证。共享组件改变时至少覆盖 overview、workbench、cockpit、retail；只改某布局样式时重点验证该布局及相邻断点。
-
-- 正常/空结果、部分适配、截断、受限值、失败与重试有清楚状态，失败不保留旧值充当最新结果。
-- 图表画布有实际内容，控制台没有新增运行错误或图表模块缺失告警；图例、轴标签、大数值和长标题不裁切。
-- 检查实际组件数量，同时用奇数/偶数组合观察排列；无异常空洞、重叠和页面横向溢出。表格内部滚动允许存在。
-- 逐个点击页内导航并滚动到页面底部，确认导航仍可操作、目标标题不被遮挡；retail 同时检查桌面单行与窄屏两行导航，以及返回经营概览。
-- 草稿不触发查询，应用后核对请求及页面值；恢复默认按源保存条件重新查询。检查键盘焦点、窄屏控件、单组件失败与重试；有年月/区间等控件时验证其实际操作。
-- 展开范围和适配说明，确认技术详情可读，影响业务判断的限制没有被隐藏。
-
-自动边界检查不能判断所有视觉问题。保存有上下文的截图，并人工检查留白、密度、文字和绘图质量。
-
-## 4. 真实取数与身份
-
-| 验证层 | 必须记录的证据 | 不证明什么 |
-|---|---|---|
-| CLI | 同一 profile 的资源、字段与查询结果 | 浏览器身份或原生查询接口可用 |
-| 开发页面 | 脱敏请求参数、真实返回、页面值；应用/恢复条件的前后对照 | 所有生产用户均有权限 |
-| 生产 Cookie | 部署后的同源静态页面，目标访问者身份及目录入口下的取数、失效和无权限表现 | 其他账号、SSO 环境或部署拓扑也可用 |
-
-目录来源检查每次查询保留 reportEntryId。存在过滤作用范围差异时同时检查受影响和不受影响组件。不要仅用 HTTP 200、组件数量或 CLI 返回证明页面值正确。生产环境未提供时明确写“未验证”，不为完成验收新增部署或扩大权限。
-
-## 5. 交付记录
-
-记录应用路径/启动命令、CLI 与模板版本、绑定来源和口径、改动范围，以及下表。结果使用“通过 / 失败 / 未验证 / 不适用”，附原因和证据路径。
-
-| 项目 | 结果 | 证据或限制 |
-|---|---|---|
-| 本地测试 / 类型检查 / 构建 | 待记录 | 命令、退出码与日志 |
-| 浏览器夹具 | 待记录 | 布局、实际视口、PASS/FAIL 与截图 |
-| 真实开发取数 / 筛选 / 恢复 | 待记录 | 请求和显示值对照，未覆盖控件 |
-| 生产 Cookie / 权限 | 待记录 | 环境、身份范围；未部署注明未验证 |
-| 整页视觉 / 键盘 | 待记录 | 桌面与小屏截图、人工检查结果 |
-| 交付包 | 待记录 | 包含同一次构建的 dist；排除 .env*、temp、node_modules、凭证和抓取样本 |
-
-修复后重新执行受影响检查。既有项目不会随模板自动升级；记录采用的模板版本和本次应用的修复，保留业务绑定与本地凭证。
+# 开发与验收
+
+本文件用于生成项目的独立验收，无需 CLI 源仓库。测试夹具、真实开发身份和生产访问者身份分别记录，不能互相代替。协议以[数据契约](data-contract.md)、[筛选](filters.md)和[认证部署](auth-and-deploy.md)为准。
+
+## 1. 绑定与设计准备
+
+先记录以下最小清单，证据与临时文件放项目 `temp/`；不记录密码、token 或 Cookie。
+
+| 项目 | 核实内容 |
+|---|---|
+| 来源 | CLI profile、目标地址、dashboardId、目录入口或分析主题；板内实例 entryId |
+| 字段与指标 | queryFields.dId、选定 datasetId、维度/指标、公式或聚合、单位；记录数不能自动解释为去重对象数 |
+| 字段选择 | 常规绑定省略 dimensionIds；配置时核对完整白名单与输出列，分别验证省略、维度加指标、仅指标和空列表；同实例不同展示绑定分别核对请求 |
+| 时间 | 时间粒度、原值编码、显示时区；日期条件与时间戳轴标签分开核实 |
+| 筛选 | 真实控件名、类型、默认行为、候选项来源、组件作用范围；无源控件时不添加服务端筛选 |
+| 范围 | 返回行数、hasNext、normalization、warnings；不根据首页推算全量 |
+| 设计 | 使用者和主要决策、首屏重点、导航/分组/密度，与既有布局的区别 |
+
+清单先覆盖最小绑定，扩展组件时逐项补齐；不必先完成整板配置。证据不足时说明未知项，继续不依赖该项的工作。
+
+### 1.1 最小真实查询
+
+在配置整页组件之前，先验证开发页面的真实取数链路：
+
+1. 用同一来源的 CLI info/data 选择一个模板支持且有可核对数据的组件，例如单行 KPI；检查 resultType、normalization、warnings、range 和结果字段，不按标题或 chartType 判断可用性。CLI 查询成功仅用于准备绑定，不能证明浏览器适配和开发身份可用。
+2. 在 public/app-config.json 中只填写该组件的真实绑定及必要配置；目录来源保留 directoryEntryId，需要字段选择时保留相同 dimensionIds。不要先复制整页占位组件，也不为测试凭空创建源指标或控件。
+3. 按 [README 开始](../README.md#开始)安装依赖、配置开发身份并运行 npm run dev。打开实际应用，通过开发代理触发原生查询；优先复用已有会话，需要登录时遵循[本地开发认证](auth-and-deploy.md#本地开发)，不要把 CLI Access Key 当作会话 token，也不要在已有会话可用时重复索要密码。
+4. 核对请求来源和参数、业务响应、适配状态与页面显示值。单凭 HTTP 200、CLI 成功或合成验收页 PASS 不算通过；空结果只能证明当前空态，需另选有可核对数据的组件或条件验证值的消费。脱敏证据放项目 temp/，不得记录凭证。
+5. 该组件通过后，按本页需求补齐一个指标和一张图的代表性绑定；源中不存在或本页不需要的类型注明不适用。有真实筛选时验证“源结果 → 页面值 → 应用条件 → 恢复保存默认”，确认请求及显示与条件一致。完成这些适用检查后再扩展整页，并继续验证新增绑定。
+
+身份、权限、接口或适配失败时，记录失败层与原因，先解决当前链路再扩大绑定；缺少访问条件时可继续不依赖真实数据的设计工作，但真实查询须标记未验证。开发身份通过不代表生产 Cookie 验证通过，身份边界见第 4 节。
+
+## 2. 本地自动检查
+
+1. 首次安装使用 `npm ci`。
+2. `npm test` 验证已覆盖的数据、配置、认证、交互逻辑和分包行为。
+3. `npm run build` 完成类型检查与生产构建。
+4. `npm run test:browser` 启动独立浏览器验收页，打开终端给出的本机地址。选择布局后运行检查；按第 3 节调整浏览器视口并重复运行。页面必须显示 PASS，FAIL 或未完成不能视为通过。
+
+浏览器验收页只使用 `tests/browser/` 中的合成响应，复用实际 App、查询编码、适配器和图表组件；不读取 `.env.local`、不使用开发代理、不访问 FineBI。它检查图形实际绘制、运行错误、筛选草稿/应用/恢复、目录入口与组件作用范围、空/部分/失败状态、单项重试和组件边界。截图判断、真实权限、生产部署和未覆盖控件仍需人工或对应专项验证。
+
+测试页和夹具不得复制到 public/ 或生产配置。`npm run build` 只构建正式入口；浏览器测试服务仅在回环地址使用，完成后停止。
+
+## 3. 浏览器视觉与交互
+
+检查实际应用整页，包括首屏、图表中段、最后一行和明细。推荐 1440、1024、390px 视口；记录实际宽度，不把桌面缩放当成小屏验证。共享组件改变时至少覆盖 overview、workbench、cockpit、retail；只改某布局样式时重点验证该布局及相邻断点。
+
+- 正常/空结果、部分适配、截断、受限值、失败与重试有清楚状态，失败不保留旧值充当最新结果。
+- 图表画布有实际内容，控制台没有新增运行错误或图表模块缺失告警；图例、轴标签、大数值和长标题不裁切。
+- 检查实际组件数量，同时用奇数/偶数组合观察排列；无异常空洞、重叠和页面横向溢出。表格内部滚动允许存在。
+- 逐个点击页内导航并滚动到页面底部，确认导航仍可操作、目标标题不被遮挡；retail 同时检查桌面单行与窄屏两行导航，以及返回经营概览。
+- 草稿不触发查询，应用后核对请求及页面值；恢复默认按源保存条件重新查询。检查键盘焦点、窄屏控件、单组件失败与重试；有年月/区间等控件时验证其实际操作。
+- 展开范围和适配说明，确认技术详情可读，影响业务判断的限制没有被隐藏。
+
+自动边界检查不能判断所有视觉问题。保存有上下文的截图，并人工检查留白、密度、文字和绘图质量。
+
+## 4. 真实取数与身份
+
+| 验证层 | 必须记录的证据 | 不证明什么 |
+|---|---|---|
+| CLI | 同一 profile 的资源、字段与查询结果 | 浏览器身份或原生查询接口可用 |
+| 开发页面 | 脱敏请求参数、真实返回、页面值；应用/恢复条件的前后对照 | 所有生产用户均有权限 |
+| 生产 Cookie | 部署后的同源静态页面，目标访问者身份及目录入口下的取数、失效和无权限表现 | 其他账号、SSO 环境或部署拓扑也可用 |
+
+目录来源检查每次查询保留 reportEntryId。存在过滤作用范围差异时同时检查受影响和不受影响组件。不要仅用 HTTP 200、组件数量或 CLI 返回证明页面值正确。生产环境未提供时明确写“未验证”，不为完成验收新增部署或扩大权限。
+
+## 5. 交付记录
+
+记录应用路径/启动命令、CLI 与模板版本、绑定来源和口径、改动范围，以及下表。结果使用“通过 / 失败 / 未验证 / 不适用”，附原因和证据路径。
+
+| 项目 | 结果 | 证据或限制 |
+|---|---|---|
+| 本地测试 / 类型检查 / 构建 | 待记录 | 命令、退出码与日志 |
+| 浏览器夹具 | 待记录 | 布局、实际视口、PASS/FAIL 与截图 |
+| 真实开发取数 / 筛选 / 恢复 | 待记录 | 请求和显示值对照，未覆盖控件 |
+| 生产 Cookie / 权限 | 待记录 | 环境、身份范围；未部署注明未验证 |
+| 整页视觉 / 键盘 | 待记录 | 桌面与小屏截图、人工检查结果 |
+| 交付包 | 待记录 | 包含同一次构建的 dist；排除 .env*、temp、node_modules、凭证和抓取样本 |
+
+修复后重新执行受影响检查。既有项目不会随模板自动升级；记录采用的模板版本和本次应用的修复，保留业务绑定与本地凭证。

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/docs/auth-and-deploy.md

@@ -2,9 +2,24 @@
 
 ## 本地开发
 
-Vite开发插件读取服务端环境 `FINEBI_DEV_BASE_URL`、`FINEBI_DEV_USERNAME/FINEBI_DEV_PASSWORD`，或已有短期 `FINEBI_DEV_TOKEN`。BASE_URL必须是目标完整decision地址。支持由本地.env.local提供，禁止提交文件；不要使用VITE_前缀。
+Vite开发插件读取项目 `.env.local` 或进程环境中的 `FINEBI_DEV_BASE_URL`（完整 decision 地址），可选 `FINEBI_DEV_USERNAME/FINEBI_DEV_PASSWORD` 和已有 FineBI 会话 `FINEBI_DEV_TOKEN`。进程环境优先；不要使用 `VITE_` 前缀，不要把 CLI Access Key 填入 TOKEN。
 
-代理在内存保存开发会话，只接受本机同源、带XMLHttpRequest标记的POST；白名单限制为配置看板及组件查询，不代理登录管理或任意接口。浏览器无需持有开发账号凭证。失效返回AUTH_REQUIRED；密码方式下一次显式重试重新登录，token方式需更新token并重启开发服务。不要向他人开放开发服务端口。
+```dotenv
+FINEBI_DEV_BASE_URL=https://bi.example/webroot/decision
+# 有用户名密码时填写；只有 SSO 时省略这两项。
+FINEBI_DEV_USERNAME=your-user
+FINEBI_DEV_PASSWORD=your-password
+```
+
+首次查询按以下顺序认证：复用有效 token；需要登录时先尝试配置的用户名密码；没有完整账密或密码明确被拒绝时，终端显示浏览器授权链接和确认码，并尝试打开浏览器。先通过客户原 FineBI/SSO 入口登录，再打开授权链接核对账号与确认码。开发进程主动轮询领取会话，不要求 FineBI 服务器连接本机，也不改变 SSO 回跳地址。
+
+浏览器授权要求服务端插件提供 `/api/bi-cli/dev-session-auth/*`，使用 HTTPS（仅回环允许 HTTP）。旧插件返回 `AUTH_PLUGIN_REQUIRED`，应更新插件；密码路径不依赖新增端点。客户端终端只显示授权地址、确认码、账号与状态，不显示密码或 token。
+
+新会话写入 `.env.local` 的 `FINEBI_DEV_TOKEN`、`FINEBI_DEV_TOKEN_BASE_URL`、`FINEBI_DEV_TOKEN_USERNAME`；保留其他配置，缺少 BASE_URL 时补入本次地址。保存的 token 与目标地址绑定，切换地址不复用旧 token。文件写入先限制权限（POSIX 0600；Windows 当前用户、SYSTEM、Administrators），失败返回 `AUTH_STORAGE_FAILED`。文件禁止提交或随包发布。token 只由 Node 读取；授权交出的是真实会话权限，并非仅限本应用看板。
+
+明确过期时清除保存的旧 token，按上述顺序恢复，再重试原查询一次。并发请求共享认证；旧请求不能清除新会话。再次失效、授权拒绝或超时后返回 `AUTH_REQUIRED`，用户处理后点击重试。密码明确拒绝后本次运行不重复尝试；网络故障、上游 5xx、查询 403 不触发浏览器授权。认证文件保存会更新内存，不需要重启；手动修改地址或账密配置后需重启开发服务。若进程环境还设置了旧 TOKEN，它会覆盖文件，重新启动前应移除该覆盖。
+
+代理只接受本机同源、带 XMLHttpRequest 标记的 POST；白名单限制为配置看板及组件查询，不向浏览器开放登录管理或任意接口。不要向他人开放开发服务端口。Vite 禁止访问 `.env*` 和 `temp/`，关闭服务会取消待完成的授权。会话有效期由 FineBI 决定；SSO 的 IP/终端/附加 Cookie 约束、退出登录行为及多节点部署需在客户环境验证，自动化测试不等于所有 SSO 已兼容。
 
 代理使用共享筛选校验器校验配置与 refer，类型、编码、候选值和默认语义统一见[筛选契约](filters.md)，不维护独立编码规则。
 

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/docs/data-contract.md

@@ -1,38 +1,66 @@
-# 数据契约与适配范围
-
-## 输入与版本
-
-浏览器调用 `/v5/api/dashboard/report/{dashboardId}/widgets/query`，传板内实例 widgetIds、includeWidgetBean=true、pageLimit、refer。原生结果仅在 src/finebi/normalize.ts 解析。输出 schemaVersion=1，与 CLI 标准化结果采用相同的字段、值状态与范围语义；v1 浏览器只覆盖 DETAIL 和 CHART，不等于 Java 适配器的全部覆盖。
-
-配置 directoryEntryId 时请求增加 reportEntryId，开发代理校验来源与配置严格相等后透传。目标平台 HTTP 查询服务需同时支持目录权限预检与 MOUNT 模式；仅升级 CLI Provider 不代表该 HTTP 入口已支持。权限/版本错误直接呈现，不移除入口后重试。各展示组件独立请求，批量加载限制三路并发，单个组件失败不遮蔽其他结果；同一原生实例可有不同展示和筛选绑定。
-
-### 字段选择
-
-当前模板没有字段选择配置，浏览器请求不传 `dimensionSelections`，因此沿用组件保存的维度和指标配置。页面展示字段的绑定不等于服务端字段选择；用 CLI 验证自定义选择得到的结果，也不代表模板会自动使用同一选择。
-
-支持完整白名单语义的平台接口通过 `dimensionSelections` 按组件指定维度和指标的 `dId` 列表；CLI 对应参数为 `dashboard data --dimension-ids`。ID 从同一来源的 `dashboard info` 中目标实例的 `queryFields` 取得，只选 `selectable=true` 的字段，包括已关闭但仍可选择的字段；不能用字段名或底层数据集字段 ID 代替。
-
-- 不传选择项时沿用保存配置。
-- 显式列表是维度和指标的完整白名单，未列出的可选字段全部关闭；需要维度和指标同时输出时必须一起列出。
-- 只传维度会关闭未选指标，只传指标会关闭全部可选维度；`[]` 关闭全部可选维度和指标，不保证各组件都有有效输出，明细表不返回列及数据行。
-- 选择只影响本次查询，不保存配置、不清除过滤、不按列表顺序重排字段，也不能添加组件未配置的字段。
-
-这套语义要求目标平台 Provider/HTTP 查询接口支持维度和指标完整白名单；只升级 CLI 不会为模板增加字段选择能力。
-
-## 消费顺序
-
-检查 normalization（COMPLETE/PARTIAL/UNSUPPORTED）→ warnings → 选唯一 dataset → 按 columns 解释 rows[].cells → 按 range 说明范围。COMPLETE 只表示本次结构转换完整，不表示全集。多模型需指定 datasetId；UNKNOWN 行不得自动求和。
-
-columns 含 key、fieldId、name、type、encoding。key 仅在本次dataset内唯一；fieldId 是结果字段ID，不能当底层数据集字段ID。绑定使用fieldId，不使用可能重复的name。
-
-cells 含 value、display、state、reason：AVAILABLE 可用，NULL 确认空值，UNAVAILABLE 无法可靠解释，RESTRICTED 权限受限。表格优先显示 display，受限单元格统一显示“受限”。计算不能从 display 反解析数字；DECIMAL_STRING 保留上游值，JS Number 仅用于图形坐标且不能用于高精度金额计算。DATE 的 EPOCH_MILLIS_STRING 保留毫秒字符串，不擅自改变时区。日期元数据支持原生类型3、13、15、20；未知类型保守返回不可用。
-
-浏览器适配器不能获知服务端 cellCharLimit，字符串不能据此承诺未经截断的数据库原文。图表可见数值不代表底层明细；数值型字符串不会被猜成图表指标。交叉表/分组表及缺少内联模型的图形明确为不支持；多模型、computedState 和缺列都会保留警告。
-
-## 范围
-
-明细表 range.total 采用有效原生row；PAGE是本次首页，pageLimit不提供续页。hasNext=true 原样保留并产生 NEXT_PAGE_UNSUPPORTED；即使返回数等于总数，也不覆盖这一状态。当前仅提供已加载结果的搜索、排序和分页，页面显示该范围。图表UNPAGED也不等于底层明细全量，可能存在Top N或聚合。
-
-服务端返回空数组与缺失组件不同：前者可显示空数据，后者是 INVALID_RESPONSE。受限/失败/不支持结果不回退静态样本。
-
-表格排序使用 AVAILABLE 的 value，DECIMAL_STRING 按十进制字符串比较，支持合法指数而不转换为浮点金额；缺值排在可用值之后。搜索、展示筛选和 CSV 使用 displayCell 的统一值状态呈现；CSV 导出当前匹配集合而非仅当前页，含 UNKNOWN 行标识并转义公式前缀。图表坐标允许 Number 近似，展开数据表保留原始显示值。经营观察仅消费当前结果的状态、行数和单值 KPI，不自动累加 UNKNOWN 行或推断业务比率。
+# 数据契约与适配范围
+
+## 输入与版本
+
+浏览器调用 `/v5/api/dashboard/report/{dashboardId}/widgets/query`，传板内实例 widgetIds、includeWidgetBean=true、pageLimit、refer。原生结果仅在 src/finebi/normalize.ts 解析。输出 schemaVersion=1，与 CLI 标准化结果采用相同的字段、值状态与范围语义；浏览器覆盖 DETAIL、BIGROUP、BICROSS 和 CHART。交叉表采用下述浏览器矩阵契约；CLI Java 标准化器的交叉表支持范围独立，不由浏览器能力推断。
+
+配置 directoryEntryId 时请求增加 reportEntryId，开发代理校验来源与配置严格相等后透传。目标平台 HTTP 查询服务需同时支持目录权限预检与 MOUNT 模式；仅升级 CLI Provider 不代表该 HTTP 入口已支持。权限/版本错误直接呈现，不移除入口后重试。各展示组件独立请求，批量加载限制三路并发，单个组件失败不遮蔽其他结果；同一原生实例可有不同展示和筛选绑定。
+
+### 字段选择
+
+`widgets[].dimensionIds?: string[]` 是可选的服务端字段选择配置。常规绑定省略该字段，浏览器不为该实例发送选择项，沿用组件保存的维度和指标启用状态；不会强制启用保存态隐藏字段。显式配置时，请求发送 `dimensionSelections: { [entryId]: dimensionIds }`。页面展示字段的绑定不等于服务端字段选择；CLI 查询使用的列表需要显式写入对应展示绑定才会在模板中生效。
+
+支持完整白名单语义的平台接口通过 `dimensionSelections` 按组件指定维度和指标的 `dId` 列表；CLI 对应参数为 `dashboard data --dimension-ids`。ID 从同一来源的 `dashboard info` 中目标实例的 `queryFields` 取得，只选 `selectable=true` 的字段，包括已关闭但仍可选择的字段；不能用字段名或底层数据集字段 ID 代替。
+
+- 不传选择项时沿用保存配置。
+- 显式列表是维度和指标的完整白名单，未列出的可选字段全部关闭；需要维度和指标同时输出时必须一起列出。
+- 只传维度会关闭未选指标，只传指标会关闭全部可选维度；`[]` 关闭全部可选维度和指标，不保证各组件都有有效输出，明细表不返回列及数据行。
+- 选择只影响本次查询，不保存配置、不清除过滤、不按列表顺序重排字段，也不能添加组件未配置的字段。
+
+配置只接受无重复、无空白项的字符串数组，`null` 非法；不能用 `[]` 代替省略。需要同时输出城市和销售额时，可在目标 `widgets[]` 条目添加以下属性（占位 ID 需替换）：
+
+```json
+"dimensionIds": ["<城市dId>", "<销售额dId>"]
+```
+
+各展示绑定独立查询；同一 `entryId` 可以配置不同的字段选择。直接调用批量 `queryWidgets` 时，同一实例必须使用相同选择集合，否则拒绝请求；列表顺序不影响集合比较，省略与 `[]` 不等价。开发代理校验选择属于请求实例，且匹配该实例至少一个配置绑定，再原样转发；不会丢弃选择或补回指标。
+
+这套语义要求目标平台 HTTP 查询接口支持维度和指标完整白名单，CLI 验证还需对应 Provider 支持。未选字段上的过滤继续生效；展示绑定必须与所选输出相符，缺列不能补零。模板不提供运行时字段选择器。
+
+## 消费顺序
+
+检查 normalization（COMPLETE/PARTIAL/UNSUPPORTED）→ warnings → 选唯一 dataset → 按 columns 解释 rows[].cells → 按 range 说明范围。COMPLETE 只表示本次结构转换完整，不表示全集。多模型需指定 datasetId；UNKNOWN 行不得自动求和。
+
+columns 含 key、fieldId、name、type、encoding。key 仅在本次dataset内唯一；fieldId 是结果字段ID，不能当底层数据集字段ID。绑定使用fieldId，不使用可能重复的name。
+
+cells 含 value、display、state、reason：AVAILABLE 可用，NULL 确认空值，UNAVAILABLE 无法可靠解释，RESTRICTED 权限受限。表格优先显示 display，受限单元格统一显示“受限”。计算不能从 display 反解析数字；DECIMAL_STRING 保留上游值，JS Number 仅用于图形坐标且不能用于高精度金额计算。DATE 的 EPOCH_MILLIS_STRING 保留毫秒字符串，不擅自改变时区。日期元数据支持原生类型3、13、15、20；未知类型保守返回不可用。
+
+浏览器适配器不能获知服务端 cellCharLimit，字符串不能据此承诺未经截断的数据库原文。图表可见数值不代表底层明细；数值型字符串不会被猜成图表指标。缺少内联模型的图形明确为不支持；多模型、computedState 和缺列都会保留警告。
+
+### 分组表
+
+原生 BIGROUP 转为 GROUP_TABLE，提供 main 数据集。按 header 的 dId 对齐列，递归保留父级分组键；节点有指标或为叶子时输出行，不丢弃父级汇总。指标采用原生 value，缺失时只接受 text 中的规范十进制数值，不反解析 formatText、单位或百分号。分组键只有明确的字符串类型可作为 value，数值/日期分组保留展示文本并标记 GROUP_KEY_SEMANTICS_UNKNOWN，不冒充原始字段值。
+
+行类型依据指标的 rowSumInfo：DATA、SUBTOTAL、GRAND_TOTAL；标记缺失、冲突或同一行指标分类不一致时为 UNKNOWN，不根据“合计”等标题猜测。表格显示数据／小计／总计，CSV 保留行类型。父级键、指标权限及字段歧义分别保留；重复指标不取第一个充数，不把缺值补零。含小计、总计或 UNKNOWN 的数据集不能直接累加所有行。
+
+### 交叉表
+
+原生 BICROSS 转为 CROSS_TABLE/main，以当前返回视图的矩阵展示。按 top 树叶子及其 values 的顺序建立列槽位，再按同一位置读取 left 叶子 values；保留多级分组、指标横排/竖排及原生合计位置，不按重复的指标 dId 合并交叉列。top/left 都必须存在。没有列维度时，平台返回空 top 轴，使用 left 有序指标槽位；空视图与缺失轴结构分开处理。
+
+首列 fieldId 为 `cross:row`，展示行分组完整路径；后续列为 `cross:0`、`cross:1` 等本次查询的槽位 ID，标题拼接列分组路径。这些 ID 不是 FineBI 的 dId，不能用于 dimensionIds 或跨查询固定字段绑定。通常只配置 `type: "table"`，省略 tableFieldIds/localFilterFieldIds 以展示全部返回列；按原生指标 dId 配置图形或 KPI 不适用于这个矩阵。模板展示路径标题，不复刻原生合并单元格、树展开和布局样式。
+
+`columns[].path` 和 `rows[].path` 保留有序 `{fieldId,label,state}`，值单元格的 `sourceFieldId` 保留原生指标 dId。展示标题中，追加的指标名称与末级列分组名称相同时只显示一次，指标放在行维度时，仅当末级路径的 fieldId 与该行非空指标 dId 一致，且名称与前一级相同时，隐藏末级重复标题。两种去重均不折叠真实分组层级的同名标签，不修改 path 或单元格映射。DATA 行展示时省略内部 `__summary_dim_id__` 承载节点的“合计”，保留真实业务分组名称及完整 path。
+
+行 kind 来自 rowSumInfo；列 kind 及单元格 columnKind 来自 colSumInfo，未知或冲突保持 UNKNOWN。列小计/总计明确标注，CSV 保留展示路径标题与行类型；不能混加各级汇总。受限轴标签显示“受限”，关联单元格也保持受限。具有非空指标 dId、authority=true 且 value/text/formatText 均显式为 null 的单元格为 NULL，表格和 CSV 显示“—”；无指标的结构占位、缺失值载荷或权限未知仍为 UNAVAILABLE，不补零。
+
+返回值少于列槽位时标记 PARTIAL，缺格保留 MISSING_CELL；原生列指标 ID 与对应数值 ID 冲突时标记 PARTIAL/AMBIGUOUS_FIELD。数值多于列槽位、轴缺失或节点同时携带子树与非空 values 的未覆盖结构标记 UNSUPPORTED，不能截掉多余值或按猜测顺序对齐。
+
+## 范围
+
+明细表 range.total 采用有效原生row；PAGE是本次首页，pageLimit不提供续页。hasNext=true 原样保留并产生 NEXT_PAGE_UNSUPPORTED；即使返回数等于总数，也不覆盖这一状态。普通分组表的分页单位为 GROUP，总组数未知；展开后的 returnedRowCount 可以超过首页组数。开启 showRowHeaderIcon 的表头展开模式标记 INITIAL_VIEW，不给出普通页码或续页状态；原生 hasNext 仍产生续页警告。当前仅提供已加载结果的搜索、排序和分页，页面显示该范围。图表UNPAGED也不等于底层明细全量，可能存在Top N或聚合。
+
+交叉表 range.mode 为 INITIAL_VIEW，page/pageSize/pageUnit/total 均不声明普通表格分页或总数。`range.axes.horizontal/vertical` 分别保留原生 X/Y 的 hasNext/hasPrevious；任一方向还有数据即给出 NEXT_PAGE_UNSUPPORTED。合并 hasNext/hasPrevious 只有两轴均明确为 false 才为 false，否则保留 true 或未知。页面分别显示横向、纵向还有数据的状态；本地分页、搜索、排序和 CSV 只覆盖当前返回矩阵，不请求服务端续页或展开节点。
+
+服务端返回空数组与缺失组件不同：前者可显示空数据，后者是 INVALID_RESPONSE。受限/失败/不支持结果不回退静态样本。
+
+表格排序使用 AVAILABLE 的 value，DECIMAL_STRING 按十进制字符串比较，支持合法指数而不转换为浮点金额；缺值排在可用值之后。搜索、展示筛选和 CSV 使用 displayCell 的统一值状态呈现；CSV 导出当前匹配集合而非仅当前页，保留数据、小计、总计及 UNKNOWN 行标识并转义公式前缀。图表坐标允许 Number 近似，展开数据表保留原始显示值。经营观察仅消费当前结果的状态、行数和单值 KPI，不自动累加 UNKNOWN 行或推断业务比率。

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/docs/filters.md

@@ -8,7 +8,7 @@
 
 开发时从同一看板的 `dashboard info` 获取真实控件 `filterName` 和实例信息，必要时读取 `dashboard bean` 确认控件类型、绑定字段、保存默认值和作用范围。`name` 必须使用解码后的真实控件名；`label` 仅用于显示。重名控件需先在源看板消除歧义，不能用 label 或组件 ID 替代请求键。没有控件时 `filters` 保持空数组，不把任意字段伪造成服务端筛选。
 
-`app inspect` 和浏览器只检查本地配置，不访问远端，也不能证明控件类型或作用范围正确。交付前必须用真实接口证明条件生效。配置不复制源看板默认值，恢复默认后由服务端读取当前保存条件。
+`app inspect` 默认只展示配置摘要，`--strict` 才按 CLI 内置模板规则检查。浏览器加载配置时使用项目内的校验规则；本地配置校验不能证明远端控件类型或作用范围正确。交付前必须用真实接口证明条件生效。配置不复制源看板默认值，恢复默认后由服务端读取当前保存条件。
 
 ### 1.2 条件组合与刷新
 
@@ -87,7 +87,7 @@
 更换同语义 UI 组件时，沿用表中的状态类型和统一编码器。新增能力按以下链路扩展：
 
 1. 确认源控件的类型、名称、字段、默认值、作用范围及真实请求编码，区分浏览器内部控件状态与 HTTP refer 协议；检查目标部署版本确实支持覆盖。
-2. 扩展 `src/finebi/types.ts` 和 `filters.js` 中的配置、状态校验、编码和反向请求校验。CLI 的 `app inspect`、客户端和开发代理共用该模块，不另建一套允许列表。
+2. 扩展 `src/finebi/types.ts` 和 `filters.js` 中的配置、状态校验、编码和反向请求校验。客户端和开发代理共用项目内该模块，不另建一套允许列表。CLI 的 `app inspect --strict` 使用随 CLI 分发的模板模块，不能用它约束定制项目的扩展。
 3. 在 `FilterBar` 或业务页面接入控件。动态候选项必须有经过验证的接口、访问者权限、搜索/分页语义、加载失败状态、依赖条件和请求取消策略；级联还须定义上游变化后下游选择的保留或清除方式。不从样本推断完整候选项。
 4. 测试合法值、非法值、保留字、名称冲突、空值、恢复默认、开放区间和组合提交；再用真实看板核对请求、数据范围与组件展示。源码或单测通过不能代替部署与浏览器验收。
 5. 同步本契约、模板支持摘要并重新生成分发物。图表库和 UI 组件库选型见[页面骨架](design.md)。

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/examples/cockpit.config.json

@@ -1,22 +1,22 @@
-{
-  "schemaVersion": "1",
-  "title": "经营概览",
-  "description": "资源绑定示例：替换所有 REPLACE_*，不包含业务数据",
-  "basePath": "/webroot/decision",
-  "layout": "cockpit",
-  "dashboardId": "REPLACE_DASHBOARD_ID",
-  "maxRows": 1000,
-  "pageSize": 8,
-  "insights": true,
-  "dataNotes": ["请填写经过核实的数据单位、组件口径与筛选作用范围。"],
-  "widgets": [
-    {"entryId":"REPLACE_KPI_1", "name":"指标一", "type":"kpi", "valueFieldId":"REPLACE_VALUE_1", "filterNames":["REPLACE_MONTH_CONTROL"]},
-    {"entryId":"REPLACE_KPI_2", "name":"指标二", "type":"kpi", "valueFieldId":"REPLACE_VALUE_2", "filterNames":[]},
-    {"entryId":"REPLACE_KPI_3", "name":"指标三", "type":"kpi", "valueFieldId":"REPLACE_VALUE_3", "filterNames":[]},
-    {"entryId":"REPLACE_KPI_4", "name":"指标四", "type":"kpi", "valueFieldId":"REPLACE_VALUE_4", "filterNames":[]},
-    {"entryId":"REPLACE_TREND", "name":"年度趋势", "type":"line", "categoryFieldId":"REPLACE_TIME_FIELD", "series":[{"fieldId":"REPLACE_MEASURE_A", "label":"指标 A"},{"fieldId":"REPLACE_MEASURE_B", "label":"指标 B"}], "filterNames":[]},
-    {"entryId":"REPLACE_COMPARISON", "name":"分类对比", "type":"bar", "categoryFieldId":"REPLACE_CATEGORY_FIELD", "valueFieldId":"REPLACE_MEASURE", "filterNames":[]},
-    {"entryId":"REPLACE_TABLE", "name":"分组明细", "type":"table", "tableFieldIds":["REPLACE_GROUP_FIELD","REPLACE_MEASURE"], "localFilterFieldIds":["REPLACE_GROUP_FIELD"], "filterNames":["REPLACE_MONTH_CONTROL"]}
-  ],
-  "filters": [{"name":"REPLACE_MONTH_CONTROL", "label":"年月", "type":"month"}]
-}
+{
+  "schemaVersion": "1",
+  "title": "经营概览",
+  "description": "资源绑定示例：替换所有 REPLACE_*，不包含业务数据",
+  "basePath": "/webroot/decision",
+  "layout": "cockpit",
+  "dashboardId": "REPLACE_DASHBOARD_ID",
+  "maxRows": 1000,
+  "pageSize": 8,
+  "insights": true,
+  "dataNotes": ["请填写经过核实的数据单位、组件口径与筛选作用范围。"],
+  "widgets": [
+    {"entryId":"REPLACE_KPI_1", "name":"指标一", "type":"kpi", "valueFieldId":"REPLACE_VALUE_1", "filterNames":["REPLACE_MONTH_CONTROL"]},
+    {"entryId":"REPLACE_KPI_2", "name":"指标二", "type":"kpi", "valueFieldId":"REPLACE_VALUE_2", "filterNames":[]},
+    {"entryId":"REPLACE_KPI_3", "name":"指标三", "type":"kpi", "valueFieldId":"REPLACE_VALUE_3", "filterNames":[]},
+    {"entryId":"REPLACE_KPI_4", "name":"指标四", "type":"kpi", "valueFieldId":"REPLACE_VALUE_4", "filterNames":[]},
+    {"entryId":"REPLACE_TREND", "name":"年度趋势", "type":"line", "categoryFieldId":"REPLACE_TIME_FIELD", "series":[{"fieldId":"REPLACE_MEASURE_A", "label":"指标 A"},{"fieldId":"REPLACE_MEASURE_B", "label":"指标 B"}], "filterNames":[]},
+    {"entryId":"REPLACE_COMPARISON", "name":"分类对比", "type":"bar", "categoryFieldId":"REPLACE_CATEGORY_FIELD", "valueFieldId":"REPLACE_MEASURE", "filterNames":[]},
+    {"entryId":"REPLACE_TABLE", "name":"分组明细", "type":"table", "tableFieldIds":["REPLACE_GROUP_FIELD","REPLACE_MEASURE"], "localFilterFieldIds":["REPLACE_GROUP_FIELD"], "filterNames":["REPLACE_MONTH_CONTROL"]}
+  ],
+  "filters": [{"name":"REPLACE_MONTH_CONTROL", "label":"年月", "type":"month"}]
+}