@finebi/finebi-cli 1.5.0 → 1.6.1

package/templates/web-app/docs/acceptance.md

@@ -0,0 +1,67 @@
+# 开发与验收
+
+本文件用于生成项目的独立验收，无需 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、凭证和抓取样本 |
+
+修复后重新执行受影响检查。既有项目不会随模板自动升级；记录采用的模板版本和本次应用的修复，保留业务绑定与本地凭证。

package/templates/web-app/docs/auth-and-deploy.md

@@ -0,0 +1,17 @@
+# 认证与部署
+
+## 本地开发
+
+Vite开发插件读取服务端环境 `FINEBI_DEV_BASE_URL`、`FINEBI_DEV_USERNAME/FINEBI_DEV_PASSWORD`，或已有短期 `FINEBI_DEV_TOKEN`。BASE_URL必须是目标完整decision地址。支持由本地.env.local提供，禁止提交文件；不要使用VITE_前缀。
+
+代理在内存保存开发会话，只接受本机同源、带XMLHttpRequest标记的POST；白名单限制为配置看板及组件查询，不代理登录管理或任意接口。浏览器无需持有开发账号凭证。失效返回AUTH_REQUIRED；密码方式下一次显式重试重新登录，token方式需更新token并重启开发服务。不要向他人开放开发服务端口。
+
+代理使用共享筛选校验器校验配置与 refer，类型、编码、候选值和默认语义统一见[筛选契约](filters.md)，不维护独立编码规则。
+
+## 生产
+
+`npm run build` 输出dist，开发代理不会进入产物。将静态资源托管在与FineBI相同源的应用子路径，basePath配置为实际decision路径。用户先通过FineBI登录，查询携带当前Cookie，服务端按当前身份判断资源、数据和字段权限。
+
+登录失效、HTTP403、查询失败分别显示状态，用户登录后点击重试。生产包不保存开发token、不调用CLI、不自动以开发者账号重登。`npm run preview`不注入身份，只用于产物展示；本版不提供部署上传/发布命令、跨域认证或生产嵌入式SSO接入。目录发布来源配置 directoryEntryId，需目标平台原生 HTTP 接口支持对应目录权限；身份仍是访问者 Cookie，详情见[数据契约](data-contract.md)。
+
+交付应检查dist无凭证，核对真实查询网络与页面；开发身份验证通过不能证明所有生产用户有权访问，发布目录权限需另行验证。

package/templates/web-app/docs/data-contract.md

@@ -0,0 +1,38 @@
+# 数据契约与适配范围
+
+## 输入与版本
+
+浏览器调用 `/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 行或推断业务比率。

package/templates/web-app/docs/design.md

@@ -0,0 +1,54 @@
+# 页面骨架
+
+## 设计选择与信息组织
+
+开始改页面前，用几句话记录使用者、主要决策、首屏指标、分析顺序、导航和信息密度；已有用户偏好直接沿用。需要新风格时，说明与已有页面在导航、指标组织、图表布局、字体层级和配色上的具体差异。
+
+| 布局 | 适用起点 | 信息组织 |
+|---|---|---|
+| overview | 聚焦一个主题的单页分析 | 顶部标题与筛选，组件顺序呈现，通栏明细 |
+| workbench | 需要常驻导航的分析工作台 | 侧栏与内容区，组件结构沿用基础版 |
+| cockpit | 高频经营监测、多指标对比 | 深绿侧栏、独立 KPI 区、经营观察和分析图 |
+| retail | 零售经营简报 | 横向导航、米白底色、连续 KPI 带和编号分析区 |
+
+布局名称是开发起点。图表按分析问题分组，例如趋势、对比、构成、明细；根据真实组件数量决定双列、通栏或分组，不能假设固定数量、首图类型或标题长度。检查奇数和偶数组件、长名称、大数值、多系列、警告与空状态；留白应服务阅读，避免固定跨列造成孤立卡片或大块空位。
+
+首屏给出当前指标与筛选条件，查询范围和影响理解的限制保持可见，适配代码等技术细节可展开。图表轴单位、时间标签、颜色与图例应一致；仅在已核实的口径上调整显示。小屏按阅读顺序收为单列，表格在自身容器滚动，控件与提示不能遮挡内容。浏览器检查范围见[验收文档](acceptance.md#3-浏览器视觉与交互)。
+
+## 展示实现与扩展
+
+图表库和UI组件库不限定，按页面的展示、交互和设计需求选择。模板默认使用ECharts绘图，筛选栏默认使用Ant Design和date-fns；开发时可替换为D3等图表实现，或选用合适的UI组件库，也可使用原生控件。更换库需要调整对应展示组件、依赖和样式，不是app-config中的自动切换选项。
+
+替换展示实现时继续复用src/finebi的取数与认证逻辑，遵循[数据契约](data-contract.md)和[筛选契约](filters.md)，保留值状态、数据范围提示、空/错误状态及请求取消处理；按所选库的生命周期释放图表、监听器和其他资源。
+
+默认FilterBar提供可搜索单选/多选、日期及年月区间日历、年月面板、输入框、空值勾选、重置和应用按钮；其他日期类输入保留对应格式。年月面板提供十二个月、年份网格、前后翻年、本月、默认条件与单项清除，方向键/Enter/Esc 操作且关闭回到触发按钮。选择只改草稿，完整状态为 YYYY-MM；清除沿用源默认。日历与选择器采用中文界面，小屏幕自动换行，区间日历可滚动。主题在FilterBar的ConfigProvider中配置，布局在src/styles.css中调整。搜索仅过滤配置的候选项，不触发远端候选查询。
+
+`layout=overview` 使用顶部标题/刷新、筛选栏、双列图表和通栏表格，适合单页分析。
+
+`layout=workbench` 增加侧栏应用导航，适合后续扩展多页面。两者共用src/styles.css的颜色、间距和面板规则；小屏幕收为单列。通过修改应用页面与业务组件扩展，不复制请求/认证/解析代码。
+
+`layout=cockpit` 使用深绿侧栏、标题动作区、筛选卡片、四列 KPI、可选经营观察、双列图表、通栏明细和口径折叠区；少于四个或更多 KPI 按配置自然排列，窄屏收为两列 KPI 和单列图表。绿色样式集中在 src/cockpit.css。组件独立加载/失败/重试，批量加载最多三路并发；筛选或刷新取消旧请求，单项重试另发当前组件的请求。所有布局复用同一协议。
+
+`layout=retail` 使用米白背景、墨色标题、横向导航、蓝橙图表和编号分析区，样式集中在 `src/retail.css`。导航在滚动时固定于顶部；页内链接定位到对应区域，销售分析定位到“销售表现”标题。锚点预留导航高度，窄屏两行导航也不能遮住目标。KPI 使用连续指标带；分析图按双列连续排列，明细表通栏，窄屏为两列 KPI 和单列图表。筛选作用与查询范围可以展开，数据缺失和部分适配警告保持可见。绑定骨架为 [examples/retail.config.json](../examples/retail.config.json)，不包含真实资源或数据；可按业务删减组件，沿用同一查询、认证与取消机制。
+
+布局与绑定配置：
+
+| 配置 | 用途 |
+|---|---|
+| `description` / `dataNotes` | 页头说明 / 已核实的数据口径文本 |
+| `insights:true` | 根据当前结果显示单行 KPI 原始显示值、返回行数、失败和适配状态；不包含销售业务公式，不推断全量经营结论 |
+| `widgets[].description` | 组件说明、单位或已核实的口径 |
+| `widgets[].series:[{fieldId,label}]` | line 多系列开关、bar 指标切换；与 categoryFieldId 同属选定 dataset，不跨模型拼接；单指标继续用 valueFieldId |
+| `widgets[].tableFieldIds` | table 按 fieldId 指定展示列及顺序；不配置时显示全部结果列 |
+| `widgets[].localFilterFieldIds` | table 对指定结果字段提供已加载值筛选；不触发远端查询 |
+| `widgets[].filterNames` | 已核实的真实控件作用映射；省略时由源看板决定，空数组表示该组件不传控件覆盖，详见[筛选契约](filters.md) |
+| `widgets[].valueFormat` | KPI 可选 `number`（精确十进制分组并省略尾零）或 `percent`（比例乘 100，四舍五入保留两位）；只处理 AVAILABLE 的 value，不从 display 解析数值。原值保留在指标 title；未配置沿用源显示值 |
+| `widgets[].categoryFormat` / `categoryTimeZone` | line/bar 可选 `epoch-month`，并显式指定 IANA 时区（如 Asia/Shanghai），把已核实为毫秒时间戳的分类值显示为 YYYY-MM。仅改变轴标签，展开表保留原值；不能按数值外观猜日期 |
+
+示例骨架为 [examples/cockpit.config.json](../examples/cockpit.config.json)。默认 public/app-config.json 不绑定业务资源，不含静态数据；示例也只包含资源/字段占位符。组件和观察都可按需删减，不复制参考应用的 CLI 子进程后端。
+
+默认Chart组件基于ECharts提供柱状、折线和饼图的字段映射、空值断线、resize和dispose；可展开原始显示值表。Widget提供KPI和错误边界，DataTable提供范围明确的本地搜索、精确十进制排序、已加载值筛选、分页和 CSV 匹配结果导出。CSV 保留值状态/UNKNOWN 行标识并转义公式前缀。Agent按业务绑定categoryFieldId/valueFieldId，不以返回形状猜图表类型。复杂图形需新增明确的适配与测试。
+
+图表按配置类型从`src/components/charts/`加载，只有实际渲染非空图表时才加载对应ECharts模块；表格和KPI不依赖图表运行库。筛选栏按需加载，选择框和日期区间控件各有独立加载入口。加载期间显示状态，加载失败由错误边界展示；图表继续在卸载时dispose。新增图表时添加对应注册入口并复用Chart，避免在页面入口引入整套图表库。
+
+日期适配器使用`calendar-locales.ts`中的中文和默认英文语言。Vite将`date-fns/locale`精确映射到该文件，避免动态语言查找引入所有语言包；扩展界面语言时同步添加对应导出和验证，不修改日期解析规则。构建回归测试检查入口依赖、图表独立入口和语言包范围。部署时完整上传同一次构建的`dist`目录，保留相对路径与所有按需加载资源。

package/templates/web-app/docs/filters.md

@@ -0,0 +1,93 @@
+# 控件筛选与页面联动
+
+## 1. 通用交互约定
+
+模板把页面筛选状态统一转换为 FineBI `widgets/query` 的 `refer`。`src/finebi/filters.js` 是配置校验、值编码和代理校验的共同入口；UI 库可以替换，不能绕过这个入口拼装条件。
+
+### 1.1 绑定与能力发现
+
+开发时从同一看板的 `dashboard info` 获取真实控件 `filterName` 和实例信息，必要时读取 `dashboard bean` 确认控件类型、绑定字段、保存默认值和作用范围。`name` 必须使用解码后的真实控件名；`label` 仅用于显示。重名控件需先在源看板消除歧义，不能用 label 或组件 ID 替代请求键。没有控件时 `filters` 保持空数组，不把任意字段伪造成服务端筛选。
+
+`app inspect` 和浏览器只检查本地配置，不访问远端，也不能证明控件类型或作用范围正确。交付前必须用真实接口证明条件生效。配置不复制源看板默认值，恢复默认后由服务端读取当前保存条件。
+
+### 1.2 条件组合与刷新
+
+页面编辑的是草稿，点击“应用筛选”后统一提交；未应用时明确提示页面仍显示上次查询结果。应用和刷新均重查全部绑定组件，取消旧请求，并阻止旧响应覆盖新结果。请求失败显示错误，不以过期结果冒充最新数据。
+
+同一文本多选表示选中值集合；不同控件的组合、与组件自身过滤的叠加以及作用组件，遵循源看板配置。页面不提供任意 AND/OR 表达式，不自动继承原生点击联动，不根据返回数据猜测控件作用范围。联动开发必须先建立真实控件映射。
+
+`widgets[].filterNames` 可记录已核实的作用控件名，查询该展示组件时仅传这些控件的覆盖；`[]` 不传覆盖，省略则继续由源看板决定。只能引用 filters 中的真实名称，不得根据本次结果猜测。筛选栏展示已配置的作用组件和未映射情况，不能把未知作用范围显示成全局联动。同一实例不同展示的映射分别生效。
+
+### 1.3 空值、默认与清除
+
+| 页面状态 | 请求及含义 |
+|---|---|
+| 未设置、`undefined`、空字符串；多选 `[]`；区间两端为空 | 省略请求键，使用源看板保存条件 |
+| 恢复单项默认 | 将该项草稿设为空；应用后省略该项 |
+| 恢复全部默认 | 立即提交空 `refer`，重新查询保存条件 |
+| `null`，且配置 `allowNull:true` | 文本/数值选择发送 `["null"]`，只筛选空值 |
+| 日期或年月区间只填写一端 | 只发送该端；服务端将另一端设为空，不继承保存端点 |
+| 清除所有服务端筛选、不限制任何数据 | 当前协议没有统一清除操作，模板不提供这一承诺 |
+
+“恢复默认”和“筛选空值”是不同操作。文本值 `"null"` 是原生保留字，不能作为普通文本值传递；多选不支持空值与普通值混选。日期类不支持 `allowNull`。
+
+## 2. 模板当前内置支持
+
+默认筛选栏使用 Ant Design：单选/多选可搜索本地配置的候选项，`date-range` 和 `month-range` 使用日历区间选择器，支持只填写一端、清空和重置。其余类型保留下面的字符串或选项状态；组件库不改变请求语义。样式与组件替换见[页面骨架](design.md)。
+
+单 `month` 使用自定义年月面板，默认显示“源看板默认”。支持十二个月点选、点击年份进入年份网格、前后翻年、本月、默认条件和清除；方向键、Home/End、PageUp/PageDown、Enter 和 Esc 可操作。关闭后回到触发按钮，切换网格保留焦点，窄屏限制面板宽度。选择只修改 YYYY-MM 草稿；默认/清除省略请求覆盖，点击应用才取数，不承诺清除源看板保存条件。
+
+### 2.1 配置与状态
+
+每个配置包含 `{name,label,type}`，`type` 省略时为 `select`。未知类型、重复名称、区间后缀与其他控件名冲突均提前报错。`options` 只用于选择类，每项为 `{label,value}`，value 是源控件接受的字符串，不能为空或重复。
+
+| type | 页面状态（应用前） | 原生 refer 示例 | 对应源控件 |
+|---|---|---|---|
+| `text` | 字符串，精确值选择 | `{"地区":["上海"]}` | 文本选择控件；不是包含/模糊匹配 |
+| `select` | 一个 options.value | `{"地区":["上海"]}` | 文本或数值选择 |
+| `multi-select` | options.value 字符串数组 | `{"地区":["上海,北京"]}` | 文本或数值选择 |
+| `number` | 十进制字符串 | `{"金额":["-12.50"]}` | NumberControl 数值选择；不是数值范围/滑块 |
+| `date` | `YYYY-MM-DD` | `{"日期":["2024-02-29"]}` | 单日期或日期面板 |
+| `date-range` | `{start,end}`，日期字符串 | `{"日期范围_s":["2024-02-01"],"日期范围_e":["2024-02-29"]}` | 日期区间 |
+| `year` | `YYYY` | `{"年份":["2024"]}` | 年份 |
+| `month` | `YYYY-MM` | `{"年月":["2024-02"]}` | 年月 |
+| `month-range` | `{start,end}`，年月字符串 | `{"年月范围_s":["2024-01"],"年月范围_e":["2024-03"]}` | 年月区间 |
+| `quarter` | `YYYY-Q`，Q 为 1–4 | `{"季度":["2024-3"]}` | 年季度 |
+| `time-label` | 配置中的标签名称 | `{"时间标签":["本月"]}` | 源看板已配置的时间标签 |
+
+日期选择器可以使用原生 HTML 或 UI 库，状态始终是日历字符串，不转时间戳或时区。年份限 0001–9999，校验真实日历和起止顺序；区间端点必须显式给出字符串，空字符串表示该端留空。服务端决定日期边界的计算口径，页面不自行追加 23:59:59 或把结束日期加一天。
+
+数值保留十进制字符串精度，不先转 JavaScript Number；接受负号和小数，不接受指数、千分位、单位、NaN 或 Infinity。多选的外层请求数组始终只有一个字符串；不能直接发送 `["上海","北京"]`，服务端只读取首项。原生逗号协议没有转义，普通文本输入及选择项中的逗号和字面值 `"null"` 被拒绝。时间标签按完整名称匹配，不使用逗号拆分规则。
+
+### 2.2 配置示例
+
+以下名称为示例，必须替换为同一看板中类型相符的真实 filterName。
+
+```json
+"filters": [
+  {"name":"地区", "label":"销售地区", "type":"multi-select", "allowNull":true,
+   "options":[{"label":"上海", "value":"上海"},{"label":"北京", "value":"北京"}]},
+  {"name":"订单日期范围", "label":"订单日期", "type":"date-range"},
+  {"name":"金额选择", "label":"金额", "type":"number"}
+]
+```
+
+上述区间配置用真实控件名，不手动添加 `_s/_e`；编码器统一生成后缀并检查冲突。单日期控件不能按区间协议绑定。已有两个单独 `date` 配置绑定 `_s/_e` 的项目可以继续运行，但只有 `date-range` 把两端作为一个整体校验。
+
+### 2.3 候选项与支持边界
+
+选择类当前使用配置中的静态 `options`，不自动查询完整候选项、不提供远端搜索、分页或级联。静态选项应来自经过核实的源控件值或业务明确允许的子集；不能把本次已加载结果中的唯一值宣称为全部候选项。`time-label.options` 必须来自源控件已有标签名称，不能自行发明动态日期表达式。
+
+数值范围、滑块、树控件、级联控件、任意比较运算、日期时间精度输入、混选空值与普通值均不在当前适配范围。配置未知类型会报错；不要换成 `text` 绕过检查。原生 refer 没有覆盖能力的类型，需要先增加并验证服务端协议，不能只添加 UI。
+
+本地搜索、排序、分页仅作用于已加载结果；`maxRows` 限制单次返回量，当前不提供服务端续页和全局排序。
+
+## 3. 后续扩展方式
+
+更换同语义 UI 组件时，沿用表中的状态类型和统一编码器。新增能力按以下链路扩展：
+
+1. 确认源控件的类型、名称、字段、默认值、作用范围及真实请求编码，区分浏览器内部控件状态与 HTTP refer 协议；检查目标部署版本确实支持覆盖。
+2. 扩展 `src/finebi/types.ts` 和 `filters.js` 中的配置、状态校验、编码和反向请求校验。CLI 的 `app inspect`、客户端和开发代理共用该模块，不另建一套允许列表。
+3. 在 `FilterBar` 或业务页面接入控件。动态候选项必须有经过验证的接口、访问者权限、搜索/分页语义、加载失败状态、依赖条件和请求取消策略；级联还须定义上游变化后下游选择的保留或清除方式。不从样本推断完整候选项。
+4. 测试合法值、非法值、保留字、名称冲突、空值、恢复默认、开放区间和组合提交；再用真实看板核对请求、数据范围与组件展示。源码或单测通过不能代替部署与浏览器验收。
+5. 同步本契约、模板支持摘要并重新生成分发物。图表库和 UI 组件库选型见[页面骨架](design.md)。

package/templates/web-app/examples/cockpit.config.json

@@ -0,0 +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"}]
+}

package/templates/web-app/examples/retail.config.json

@@ -0,0 +1,185 @@
+{
+  "schemaVersion": "1",
+  "templateVersion": "0.3.0",
+  "title": "零售经营简报",
+  "description": "请根据同一来源的真实指标、字段和控件替换绑定。",
+  "basePath": "/webroot/decision",
+  "layout": "retail",
+  "dashboardId": "REPLACE_DASHBOARD_ID",
+  "directoryEntryId": "REPLACE_DIRECTORY_ENTRY_ID",
+  "maxRows": 1000,
+  "pageSize": 8,
+  "insights": false,
+  "widgets": [
+    {
+      "entryId": "REPLACE_ENTRY_1",
+      "name": "销售额",
+      "type": "kpi",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "valueFieldId": "REPLACE_VALUE_1",
+      "valueFormat": "number"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_2",
+      "name": "毛利",
+      "type": "kpi",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "valueFieldId": "REPLACE_VALUE_2",
+      "valueFormat": "number"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_3",
+      "name": "比率指标",
+      "type": "kpi",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "valueFieldId": "REPLACE_VALUE_3",
+      "valueFormat": "percent"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_4",
+      "name": "计数指标",
+      "type": "kpi",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "valueFieldId": "REPLACE_VALUE_4",
+      "valueFormat": "number"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_5",
+      "name": "销售与毛利趋势",
+      "type": "line",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_5",
+      "valueFieldId": "REPLACE_VALUE_5",
+      "categoryFormat": "epoch-month",
+      "categoryTimeZone": "Asia/Shanghai",
+      "series": [
+        {
+          "fieldId": "REPLACE_SERIES_5_1",
+          "label": "销售额"
+        },
+        {
+          "fieldId": "REPLACE_SERIES_5_2",
+          "label": "毛利"
+        }
+      ]
+    },
+    {
+      "entryId": "REPLACE_ENTRY_6",
+      "name": "销售额 TOP10 门店",
+      "type": "bar",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_6",
+      "valueFieldId": "REPLACE_VALUE_6"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_7",
+      "name": "区域销售构成",
+      "type": "pie",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_7",
+      "valueFieldId": "REPLACE_VALUE_7"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_8",
+      "name": "品类销售额",
+      "type": "bar",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_8",
+      "valueFieldId": "REPLACE_VALUE_8"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_9",
+      "name": "自有店 / 管理店销售趋势",
+      "type": "line",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_9",
+      "valueFieldId": "REPLACE_VALUE_9",
+      "categoryFormat": "epoch-month",
+      "categoryTimeZone": "Asia/Shanghai",
+      "series": [
+        {
+          "fieldId": "REPLACE_SERIES_9_1",
+          "label": "自有店"
+        },
+        {
+          "fieldId": "REPLACE_SERIES_9_2",
+          "label": "管理店"
+        }
+      ]
+    },
+    {
+      "entryId": "REPLACE_ENTRY_10",
+      "name": "生活馆 / 时尚馆销售趋势",
+      "type": "line",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_10",
+      "valueFieldId": "REPLACE_VALUE_10",
+      "categoryFormat": "epoch-month",
+      "categoryTimeZone": "Asia/Shanghai",
+      "series": [
+        {
+          "fieldId": "REPLACE_SERIES_10_1",
+          "label": "生活馆"
+        },
+        {
+          "fieldId": "REPLACE_SERIES_10_2",
+          "label": "时尚馆"
+        }
+      ]
+    },
+    {
+      "entryId": "REPLACE_ENTRY_11",
+      "name": "门店风格构成",
+      "type": "pie",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_11",
+      "valueFieldId": "REPLACE_VALUE_11"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_12",
+      "name": "门店性质构成",
+      "type": "pie",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_12",
+      "valueFieldId": "REPLACE_VALUE_12"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_13",
+      "name": "门店经营明细",
+      "type": "table",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "tableFieldIds": [
+        "REPLACE_TABLE_FIELD_1",
+        "REPLACE_TABLE_FIELD_2",
+        "REPLACE_TABLE_FIELD_3",
+        "REPLACE_TABLE_FIELD_4"
+      ],
+      "localFilterFieldIds": [
+        "REPLACE_TABLE_FIELD_1"
+      ]
+    }
+  ],
+  "filters": [
+    {
+      "name": "REPLACE_STORE_CONTROL",
+      "label": "店名（精确匹配）",
+      "type": "text"
+    }
+  ],
+  "dataNotes": [
+    "请填写已核实的来源、单位、期间、门店计数口径与控件作用范围。未确认公式时保留源指标名称。"
+  ]
+}

package/templates/web-app/index.html

@@ -0,0 +1,2 @@
+<!doctype html>
+<html lang="zh-CN"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>FineBI 数据应用</title></head><body><div id="root"></div><script type="module" src="/src/main.tsx"></script></body></html>