@finebi/finebi-cli 1.5.0 → 1.6.0

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

@@ -0,0 +1,89 @@
+# 控件筛选与页面联动
+
+## 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 表达式，不自动继承原生点击联动，不根据返回数据猜测控件作用范围。联动开发必须先建立真实控件映射。
+
+### 1.3 空值、默认与清除
+
+| 页面状态 | 请求及含义 |
+|---|---|
+| 未设置、`undefined`、空字符串；多选 `[]`；区间两端为空 | 省略请求键，使用源看板保存条件 |
+| 恢复单项默认 | 将该项草稿设为空；应用后省略该项 |
+| 恢复全部默认 | 立即提交空 `refer`，重新查询保存条件 |
+| `null`，且配置 `allowNull:true` | 文本/数值选择发送 `["null"]`，只筛选空值 |
+| 日期或年月区间只填写一端 | 只发送该端；服务端将另一端设为空，不继承保存端点 |
+| 清除所有服务端筛选、不限制任何数据 | 当前协议没有统一清除操作，模板不提供这一承诺 |
+
+“恢复默认”和“筛选空值”是不同操作。文本值 `"null"` 是原生保留字，不能作为普通文本值传递；多选不支持空值与普通值混选。日期类不支持 `allowNull`。
+
+## 2. 模板当前内置支持
+
+默认筛选栏使用 Ant Design：单选/多选可搜索本地配置的候选项，`date-range` 和 `month-range` 使用日历区间选择器，支持只填写一端、清空和重置。其余类型保留下面的字符串或选项状态；组件库不改变请求语义。样式与组件替换见[页面骨架](design.md)。
+
+### 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/skills/finebi-cli-agent/scripts/finebi-cli/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>