@finebi/finebi-cli 1.6.0 → 1.6.2

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

@@ -0,0 +1,80 @@
+# 开发与验收
+
+本文件用于生成项目的独立验收，无需 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/templates/web-app/docs/auth-and-deploy.md

@@ -2,16 +2,31 @@
 
 ## 本地开发
 
-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
+```
 
-筛选仅允许配置中的控件名和单值数组：下拉值必须属于 options，date 值必须是有效的 YYYY-MM-DD 日历日期，不使用固定日期白名单。空日期通过省略参数恢复保存条件，代理拒绝空字符串和多值日期数组。
+首次查询按以下顺序认证：复用有效 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)，不维护独立编码规则。
 
 ## 生产
 
 `npm run build` 输出dist，开发代理不会进入产物。将静态资源托管在与FineBI相同源的应用子路径，basePath配置为实际decision路径。用户先通过FineBI登录，查询携带当前Cookie，服务端按当前身份判断资源、数据和字段权限。
 
-登录失效、HTTP403、查询失败分别显示状态，用户登录后点击重试。生产包不保存开发token、不调用CLI、不自动以开发者账号重登。`npm run preview`不注入身份，只用于产物展示；本版不提供部署上传/发布命令、跨域认证、嵌入SSO或目录发布来源查询。
+登录失效、HTTP403、查询失败分别显示状态，用户登录后点击重试。生产包不保存开发token、不调用CLI、不自动以开发者账号重登。`npm run preview`不注入身份，只用于产物展示；本版不提供部署上传/发布命令、跨域认证或生产嵌入式SSO接入。目录发布来源配置 directoryEntryId，需目标平台原生 HTTP 接口支持对应目录权限；身份仍是访问者 Cookie，详情见[数据契约](data-contract.md)。
 
 交付应检查dist无凭证，核对真实查询网络与页面；开发身份验证通过不能证明所有生产用户有权访问，发布目录权限需另行验证。

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

@@ -2,7 +2,30 @@
 
 ## 输入与版本
 
-浏览器调用 `/v5/api/dashboard/report/{dashboardId}/widgets/query`，传板内实例 widgetIds、includeWidgetBean=true、pageLimit、refer。原生结果仅在 src/finebi/normalize.ts 解析。输出 schemaVersion=1，与 CLI 标准化结果采用相同的字段、值状态与范围语义；v1 浏览器只覆盖 DETAIL 和 CHART，不等于 Java 适配器的全部覆盖。
+浏览器调用 `/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 支持。未选字段上的过滤继续生效；展示绑定必须与所选输出相符，缺列不能补零。模板不提供运行时字段选择器。
 
 ## 消费顺序
 
@@ -12,10 +35,32 @@ columns 含 key、fieldId、name、type、encoding。key 仅在本次dataset内
 
 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 和缺列都会保留警告。
+浏览器适配器不能获知服务端 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；即使返回数等于总数，也不覆盖这一状态。当前仅提供已加载结果的搜索、排序和分页，页面显示该范围。图表UNPAGED也不等于底层明细全量，可能存在Top N或聚合。
+明细表 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/templates/web-app/docs/design.md

@@ -1,13 +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提供可搜索单选/多选、日期及年月区间日历、输入框、空值勾选、重置和应用按钮；其他日期类输入保留对应格式。日历与选择器采用中文界面，筛选卡片展示待应用状态，小屏幕自动换行，区间日历可滚动。主题在FilterBar的ConfigProvider中配置，布局在src/styles.css中调整。搜索仅过滤配置的候选项，不触发远端候选查询。
+默认FilterBar提供可搜索单选/多选、日期及年月区间日历、年月面板、输入框、空值勾选、重置和应用按钮；其他日期类输入保留对应格式。年月面板提供十二个月、年份网格、前后翻年、本月、默认条件与单项清除，方向键/Enter/Esc 操作且关闭回到触发按钮。选择只改草稿，完整状态为 YYYY-MM；清除沿用源默认。日历与选择器采用中文界面，小屏幕自动换行，区间日历可滚动。主题在FilterBar的ConfigProvider中配置，布局在src/styles.css中调整。搜索仅过滤配置的候选项，不触发远端候选查询。
 
 `layout=overview` 使用顶部标题/刷新、筛选栏、双列图表和通栏表格，适合单页分析。
 
 `layout=workbench` 增加侧栏应用导航，适合后续扩展多页面。两者共用src/styles.css的颜色、间距和面板规则；小屏幕收为单列。通过修改应用页面与业务组件扩展，不复制请求/认证/解析代码。
 
-默认Chart组件基于ECharts提供柱状、折线和饼图的基本映射、resize和dispose；Widget提供KPI和错误边界，DataTable提供范围明确的本地搜索/分页。Agent按业务绑定categoryFieldId/valueFieldId，不以返回形状猜图表类型。复杂图形需新增明确的适配与测试。
+`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

@@ -8,7 +8,7 @@
 
 开发时从同一看板的 `dashboard info` 获取真实控件 `filterName` 和实例信息，必要时读取 `dashboard bean` 确认控件类型、绑定字段、保存默认值和作用范围。`name` 必须使用解码后的真实控件名；`label` 仅用于显示。重名控件需先在源看板消除歧义，不能用 label 或组件 ID 替代请求键。没有控件时 `filters` 保持空数组，不把任意字段伪造成服务端筛选。
 
-`app inspect` 和浏览器只检查本地配置，不访问远端，也不能证明控件类型或作用范围正确。交付前必须用真实接口证明条件生效。配置不复制源看板默认值，恢复默认后由服务端读取当前保存条件。
+`app inspect` 默认只展示配置摘要，`--strict` 才按 CLI 内置模板规则检查。浏览器加载配置时使用项目内的校验规则；本地配置校验不能证明远端控件类型或作用范围正确。交付前必须用真实接口证明条件生效。配置不复制源看板默认值，恢复默认后由服务端读取当前保存条件。
 
 ### 1.2 条件组合与刷新
 
@@ -16,6 +16,8 @@
 
 同一文本多选表示选中值集合；不同控件的组合、与组件自身过滤的叠加以及作用组件，遵循源看板配置。页面不提供任意 AND/OR 表达式，不自动继承原生点击联动，不根据返回数据猜测控件作用范围。联动开发必须先建立真实控件映射。
 
+`widgets[].filterNames` 可记录已核实的作用控件名，查询该展示组件时仅传这些控件的覆盖；`[]` 不传覆盖，省略则继续由源看板决定。只能引用 filters 中的真实名称，不得根据本次结果猜测。筛选栏展示已配置的作用组件和未映射情况，不能把未知作用范围显示成全局联动。同一实例不同展示的映射分别生效。
+
 ### 1.3 空值、默认与清除
 
 | 页面状态 | 请求及含义 |
@@ -33,6 +35,8 @@
 
 默认筛选栏使用 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 是源控件接受的字符串，不能为空或重复。
@@ -83,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/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

@@ -1,2 +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>
+<!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>

package/templates/web-app/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "finebi-web-app",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "finebi-web-app",
-      "version": "0.2.0",
+      "version": "0.3.0",
       "dependencies": {
         "@rc-component/picker": "1.12.2",
         "antd": "6.6.7",

package/templates/web-app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "finebi-web-app",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "type": "module",
   "engines": {"node": ">=18.17"},
@@ -8,7 +8,8 @@
     "dev": "vite --host 127.0.0.1",
     "build": "tsc --noEmit && vite build",
     "preview": "vite preview --host 127.0.0.1",
-    "test": "node --test tests/*.test.mjs"
+    "test": "node --test tests/*.test.mjs",
+    "test:browser": "vite --config tests/browser/vite.config.mjs"
   },
   "dependencies": {"@rc-component/picker": "1.12.2", "antd": "6.6.7", "date-fns": "4.1.0", "echarts": "5.6.0", "react": "18.3.1", "react-dom": "18.3.1"},
   "devDependencies": {"@types/node": "22.13.10", "@types/react": "18.3.18", "@types/react-dom": "18.3.5", "typescript": "5.8.3", "vite": "5.4.21"}

package/templates/web-app/public/app-config.json

@@ -1,11 +1,11 @@
-{
-  "schemaVersion": "1",
-  "title": "FineBI 数据应用",
-  "basePath": "/webroot/decision",
-  "layout": "overview",
-  "dashboardId": "",
-  "maxRows": 1000,
-  "pageSize": 8,
-  "widgets": [],
-  "filters": []
-}
+{
+  "schemaVersion": "1",
+  "title": "FineBI 数据应用",
+  "basePath": "/webroot/decision",
+  "layout": "overview",
+  "dashboardId": "",
+  "maxRows": 1000,
+  "pageSize": 8,
+  "widgets": [],
+  "filters": []
+}