@finebi/finebi-cli 1.6.1 → 1.6.3

package/templates/web-app/src/finebi/normalize.ts

@@ -1,4 +1,4 @@
-import type {Cell, Column, Dataset, QueryResult} from './types';
+import type {AxisLabel, Cell, Column, Dataset, QueryResult, RowKind} from './types';
 
 // Native preview JSON is deliberately confined to this boundary.
 type Native = Record<string, any>;
@@ -46,6 +46,28 @@ export function normalize(source: Native): QueryResult {
     r.datasets.push(dataset);
     if (p.hasNext) warn(r, 'NEXT_PAGE_UNSUPPORTED');
     if (r.range.total.value !== null && dataset.rows.length < r.range.total.value) warn(r, 'RESULT_TRUNCATED');
+  } else if (p?.resultType === 'BIGROUP') {
+    r.resultType = 'GROUP_TABLE';
+    if (!Array.isArray(p.header) || !Array.isArray(p.items)) {
+      r.normalization = 'UNSUPPORTED'; warn(r, 'INVALID_GROUP_TABLE'); return r;
+    }
+    const style = source.widgetBean?.settings?.tableStyle;
+    if (style?.showRowHeaderIcon === true) r.range.mode = 'INITIAL_VIEW';
+    else r.range = {mode: 'PAGE', page: 1, pageSize: Number.isSafeInteger(style?.rowCounts) && style.rowCounts > 0 ? style.rowCounts : null, pageUnit: 'GROUP', hasNext: typeof p.hasNext === 'boolean' ? p.hasNext : null, hasPrevious: typeof p.hasPrev === 'boolean' ? p.hasPrev : null, total: {value: null, unit: 'GROUP'}};
+    r.datasets.push(groupDataset(p, source.widgetBean, r));
+    if (p.hasNext) warn(r, 'NEXT_PAGE_UNSUPPORTED');
+  } else if (p?.resultType === 'BICROSS') {
+    r.resultType = 'CROSS_TABLE'; r.range.mode = 'INITIAL_VIEW';
+    const flag = (v: unknown) => typeof v === 'boolean' ? v : null;
+    const either = (a: boolean | null, b: boolean | null) => a === true || b === true ? true : a === false && b === false ? false : null;
+    const horizontal = {hasNext: flag(p.hasXNext), hasPrevious: flag(p.hasXPrev)};
+    const vertical = {hasNext: flag(p.hasYNext), hasPrevious: flag(p.hasYPrev)};
+    r.range.axes = {horizontal, vertical};
+    r.range.hasNext = either(horizontal.hasNext, vertical.hasNext);
+    r.range.hasPrevious = either(horizontal.hasPrevious, vertical.hasPrevious);
+    if (r.range.hasNext) warn(r, 'NEXT_PAGE_UNSUPPORTED');
+    const dataset = crossDataset(p, r);
+    if (dataset) r.datasets.push(dataset);
   } else if (p?.resultType === 'CHART') {
     r.resultType = 'CHART'; r.range.mode = 'UNPAGED';
     const models: Native[] = [];
@@ -75,3 +97,139 @@ export function normalize(source: Native): QueryResult {
 function detailType(type: number): Column['type'] {
   return type === 1 ? 'STRING' : type === 2 ? 'DECIMAL' : [3,13,15,20].includes(type) ? 'DATE' : 'UNKNOWN';
 }
+
+function rowKind(values: Native[], axis = 'rowSumInfo'): RowKind {
+  const kinds = values.map(metric => {
+    const info = metric?.[axis];
+    if (typeof info?.totalSum !== 'boolean' || typeof info?.innerSum !== 'boolean' || info.totalSum && info.innerSum) return 'UNKNOWN';
+    return info.totalSum ? 'GRAND_TOTAL' : info.innerSum ? 'SUBTOTAL' : 'DATA';
+  });
+  return kinds.length && kinds.every(kind => kind === kinds[0]) ? kinds[0] : 'UNKNOWN';
+}
+
+// Native top leaves and left value arrays share the converter's slot order.
+// Field IDs repeat across cross columns and must never be used to join cells.
+function crossDataset(preview: Native, result: QueryResult): Dataset | null {
+  const reject = (reason: string) => {result.normalization = 'UNSUPPORTED'; warn(result, reason); return null;};
+  const record = (v: unknown): v is Native => !!v && typeof v === 'object' && !Array.isArray(v);
+  if (![preview.top, preview.left].every(axis => record(axis) && Array.isArray(axis.header) && Array.isArray(axis.items))) return reject('INVALID_CROSS_TABLE');
+  type Leaf = {path: AxisLabel[]; values: Native[]; restricted: boolean; unknownAuthority: boolean};
+  let invalid = false;
+  const leaves = (items: Native[]): Leaf[] => {
+    const output: Leaf[] = [];
+    const visit = (item: Native, parents: AxisLabel[], restricted: boolean, unknownAuthority: boolean) => {
+      if (!record(item) || item.children != null && !Array.isArray(item.children) || item.values != null && !Array.isArray(item.values)) {invalid = true; return;}
+      const children: Native[] = item.children ?? [], values: Native[] = item.values ?? [];
+      if (children.length && values.length || values.some(v => !record(v))) {invalid = true; return;}
+      restricted ||= item.authority === false;
+      const label = text(item.formatText) ?? text(item.text);
+      unknownAuthority ||= label !== null && item.authority !== true && item.authority !== false;
+      const path = [...parents];
+      if (label !== null) path.push({fieldId: text(item.dId), label: restricted ? '受限' : unknownAuthority ? '不可用' : label, state: restricted ? 'RESTRICTED' : unknownAuthority ? 'UNAVAILABLE' : 'AVAILABLE'});
+      if (children.length) for (const child of children) visit(child, path, restricted, unknownAuthority);
+      else if (values.length || item.dId != null) output.push({path, values, restricted, unknownAuthority});
+    };
+    for (const item of items) visit(item, [], false, false);
+    return output;
+  };
+  const top = leaves(preview.top.items), left = leaves(preview.left.items);
+  if (invalid) return reject('CROSS_TABLE_TOPOLOGY_UNSUPPORTED');
+  const slots = top.flatMap(leaf => (leaf.values.length ? leaf.values : [{}]).map(metric => {
+    const path = [...leaf.path], label = text(metric.formatText) ?? text(metric.text);
+    const restricted = leaf.restricted || metric.authority === false;
+    const unknownAuthority = leaf.unknownAuthority || label !== null && metric.authority !== true && metric.authority !== false;
+    if (label !== null && (path.at(-1)?.label !== label || path.at(-1)?.fieldId !== metric.dId)) path.push({fieldId: text(metric.dId), label: restricted ? '受限' : unknownAuthority ? '不可用' : label, state: restricted ? 'RESTRICTED' : unknownAuthority ? 'UNAVAILABLE' : 'AVAILABLE'});
+    const titleParts = path.map(p => p.label);
+    if (path.length > leaf.path.length && titleParts.at(-1) === titleParts.at(-2)) titleParts.pop();
+    return {path, title: titleParts.join(' / '), restricted, unknownAuthority, sourceFieldId: text(metric.dId)};
+  }));
+  // With no column dimensions the platform emits an empty top axis;
+  // each left values array still contains the ordered metric slots.
+  if (!slots.length && !preview.top.header.length && !preview.top.items.length) {
+    const width = Math.max(0, ...left.map(leaf => leaf.values.length));
+    for (let index = 0; index < width; index++) slots.push({path: [], title: '', restricted: false, unknownAuthority: false, sourceFieldId: null});
+  }
+  if (left.some(leaf => leaf.values.length > slots.length)) return reject('CROSS_TABLE_WIDTH_MISMATCH');
+  if (!slots.length && left.some(leaf => leaf.values.length)) return reject('CROSS_TABLE_WITHOUT_COLUMNS');
+  const dataset: Dataset = {id: 'main', columns: [column('cross:row', '行分组', 0, 'STRING'), ...slots.map((slot, index) => {
+    const metrics = left.map(leaf => leaf.values[index]).filter(metric => metric?.dId != null);
+    const kind = rowKind(metrics, 'colSumInfo');
+    const suffix = kind === 'GRAND_TOTAL' ? '（总计）' : kind === 'SUBTOTAL' ? '（小计）' : '';
+    return {...column(`cross:${index}`, (slot.title || `列 ${index + 1}`) + suffix, index + 1, 'DECIMAL'), path: slot.path, kind};
+  })], rows: [], returnedRowCount: left.length};
+  for (const leaf of left) {
+    if (leaf.values.length !== slots.length) partial(result, 'CROSS_TABLE_WIDTH_MISMATCH');
+    const kind = rowKind(leaf.values.filter(metric => metric.dId != null));
+    const titlePath = leaf.path.filter(p => kind !== 'DATA' || p.fieldId !== '__summary_dim_id__');
+    const metricIds = leaf.values.map(metric => text(metric.dId)).filter(id => id !== null);
+    const last = titlePath.at(-1);
+    if (last?.fieldId && last.label === titlePath.at(-2)?.label
+        && metricIds.length && metricIds.every(id => id === last.fieldId)) titlePath.pop();
+    const label = titlePath.map(p => p.label).join(' / ') || '—';
+    const rowCell: Cell = leaf.restricted ? value(null, '受限', false, 'STRING') : leaf.unknownAuthority ? unavailable('AUTHORITY_UNAVAILABLE') : value(label, label, true, 'STRING');
+    const cells = slots.map((slot, index): Cell => {
+      const metric = leaf.values[index];
+      const meta = {sourceFieldId: text(metric?.dId), columnKind: rowKind(metric ? [metric] : [], 'colSumInfo')};
+      if (leaf.restricted || slot.restricted || metric?.authority === false) return {...value(null, '受限', false, 'DECIMAL'), ...meta};
+      if (leaf.unknownAuthority || slot.unknownAuthority) return {...unavailable('AUTHORITY_UNAVAILABLE'), ...meta};
+      if (!metric) return {...unavailable('MISSING_CELL'), ...meta};
+      if (typeof metric.dId !== 'string' || !metric.dId.trim()) return {...unavailable('MISSING_FIELD_ID'), ...meta, sourceFieldId: null};
+      if (slot.sourceFieldId && metric.dId && slot.sourceFieldId !== metric.dId) {
+        partial(result, 'CROSS_TABLE_METRIC_MISMATCH'); return {...unavailable('AMBIGUOUS_FIELD'), ...meta};
+      }
+      const raw = metric.value ?? metric.text, display = text(metric.formatText) ?? text(metric.text);
+      if (typeof metric.dId === 'string' && metric.dId.trim() && metric.authority === true
+          && metric.value === null && metric.text === null && metric.formatText === null) {
+        return {...value(null, null, true, 'DECIMAL'), ...meta};
+      }
+      // Empty metric placeholders have no proven business-null semantics.
+      return {...(raw == null ? unavailable('DISPLAY_ONLY', display) : value(raw, display, metric.authority, 'DECIMAL')), ...meta};
+    });
+    dataset.rows.push({kind, path: leaf.path, cells: [rowCell, ...cells]});
+  }
+  return dataset;
+}
+
+function groupDataset(preview: Native, widget: Native, result: QueryResult): Dataset {
+  const list = (items: unknown): Native[] => Array.isArray(items) ? items : [];
+  const metrics = new Set<string>();
+  const collect = (items: Native[]) => {
+    for (const item of items) {
+      for (const metric of list(item?.values)) if (typeof metric?.dId === 'string') metrics.add(metric.dId);
+      collect(list(item?.children));
+    }
+  };
+  collect(preview.items);
+  const dataset: Dataset = {id: 'main', columns: preview.header.map((header: Native, index: number) => {
+    const type = widget?.dimensions?.[header?.dId]?.type;
+    return column(header?.dId, header?.text, index, metrics.has(header?.dId) ? 'DECIMAL' : type === 1 ? 'STRING' : type === 2 ? 'DECIMAL' : 'UNKNOWN');
+  }), rows: [], returnedRowCount: 0};
+  const ids = new Set(dataset.columns.map(c => c.fieldId));
+  const visit = (item: Native, parents: Map<string, Native>) => {
+    if (!item || typeof item !== 'object') {partial(result, 'MISSING_GROUP_NODE'); return;}
+    const path = new Map(parents);
+    if (item.dId != null) path.set(item.dId, item);
+    const values = list(item.values), children = list(item.children);
+    if (item.values != null && !Array.isArray(item.values) || item.children != null && !Array.isArray(item.children)) partial(result, 'INVALID_GROUP_NODE');
+    if (item.dId != null && !ids.has(item.dId) || values.some(metric => !ids.has(metric?.dId))) partial(result, 'UNMAPPED_GROUP_FIELD');
+    if (values.length || !children.length) dataset.rows.push({kind: rowKind(values), cells: dataset.columns.map(c => {
+      const matching = values.filter(metric => metric?.dId === c.fieldId), dimension = path.get(c.fieldId);
+      if (matching.length === 1 && !dimension) {
+        const metric = matching[0], display = text(metric.formatText) ?? text(metric.text), raw = metric.value ?? metric.text;
+        if (raw == null && metric.authority === true) return unavailable('DISPLAY_ONLY', display);
+        return value(raw, display, metric.authority, c.type);
+      }
+      if (!matching.length && dimension) {
+        const display = text(dimension.formatText) ?? text(dimension.text);
+        if (dimension.authority === false) return value(null, display, false, c.type);
+        return c.type === 'STRING' ? value(dimension.text, display, dimension.authority, c.type) : unavailable('GROUP_KEY_SEMANTICS_UNKNOWN', display);
+      }
+      if (matching.length) partial(result, 'AMBIGUOUS_FIELD');
+      return unavailable(matching.length ? 'AMBIGUOUS_FIELD' : 'MISSING_CELL');
+    })});
+    for (const child of children) visit(child, path);
+  };
+  for (const item of preview.items) visit(item, new Map());
+  dataset.returnedRowCount = dataset.rows.length;
+  return dataset;
+}

package/templates/web-app/src/finebi/types.ts

@@ -1,12 +1,14 @@
-export type Cell = {value: string | null; display: string | null; state: 'AVAILABLE' | 'NULL' | 'UNAVAILABLE' | 'RESTRICTED'; reason: string | null};
-export type Column = {key: string; fieldId: string; name: string; type: 'STRING' | 'DECIMAL' | 'DATE' | 'UNKNOWN'; encoding: string | null};
-export type Dataset = {id: string; columns: Column[]; rows: {kind: 'DATA' | 'UNKNOWN'; cells: Cell[]}[]; returnedRowCount: number};
+export type Cell = {value: string | null; display: string | null; state: 'AVAILABLE' | 'NULL' | 'UNAVAILABLE' | 'RESTRICTED'; reason: string | null; sourceFieldId?: string | null; columnKind?: RowKind};
+export type AxisLabel = {fieldId: string | null; label: string; state: Cell['state']};
+export type Column = {key: string; fieldId: string; name: string; type: 'STRING' | 'DECIMAL' | 'DATE' | 'UNKNOWN'; encoding: string | null; path?: AxisLabel[]; kind?: RowKind};
+export type RowKind = 'DATA' | 'SUBTOTAL' | 'GRAND_TOTAL' | 'UNKNOWN';
+export type Dataset = {id: string; columns: Column[]; rows: {kind: RowKind; cells: Cell[]; path?: AxisLabel[]}[]; returnedRowCount: number};
 export type QueryResult = {
-  schemaVersion: '1'; resultType: 'DETAIL_TABLE' | 'CHART' | 'UNKNOWN';
+  schemaVersion: '1'; resultType: 'DETAIL_TABLE' | 'GROUP_TABLE' | 'CROSS_TABLE' | 'CHART' | 'UNKNOWN';
   normalization: 'COMPLETE' | 'PARTIAL' | 'UNSUPPORTED'; datasets: Dataset[]; warnings: string[];
-  range: {mode: 'PAGE' | 'UNPAGED' | 'UNKNOWN'; page: number | null; pageSize: number | null; pageUnit: string | null; hasNext: boolean | null; hasPrevious: boolean | null; total: {value: number | null; unit: string | null}};
+  range: {mode: 'PAGE' | 'INITIAL_VIEW' | 'UNPAGED' | 'UNKNOWN'; page: number | null; pageSize: number | null; pageUnit: string | null; hasNext: boolean | null; hasPrevious: boolean | null; total: {value: number | null; unit: string | null}; axes?: {horizontal: {hasNext: boolean | null; hasPrevious: boolean | null}; vertical: {hasNext: boolean | null; hasPrevious: boolean | null}}};
 };
-export type WidgetBinding = {entryId: string; name: string; type: 'table' | 'bar' | 'line' | 'pie' | 'kpi'; datasetId?: string; categoryFieldId?: string; valueFieldId?: string; series?: {fieldId:string;label:string}[]; description?:string; filterNames?:string[]; tableFieldIds?:string[]; localFilterFieldIds?:string[]; valueFormat?:'number'|'percent'; categoryFormat?:'epoch-month'; categoryTimeZone?:string};
+export type WidgetBinding = {entryId: string; dimensionIds?: string[]; name: string; type: 'table' | 'bar' | 'line' | 'pie' | 'kpi'; datasetId?: string; categoryFieldId?: string; valueFieldId?: string; series?: {fieldId:string;label:string}[]; description?:string; filterNames?:string[]; tableFieldIds?:string[]; localFilterFieldIds?:string[]; valueFormat?:'number'|'percent'; categoryFormat?:'epoch-month'; categoryTimeZone?:string};
 export type FilterBinding = {name: string; label: string} & (
   {type: 'date' | 'date-range' | 'year' | 'month' | 'month-range' | 'quarter'; options?: never; allowNull?: never}
   | {type: 'text' | 'number'; options?: never; allowNull?: boolean}

package/templates/web-app/src/retail.css

@@ -1,7 +1,7 @@
 .retail{--chart-1:#3158d5;--chart-2:#e18047;--chart-3:#82a7a0;--chart-4:#9b8fc6;--chart-5:#d2b977;background:#f5f3ee;color:#24272d;min-height:100vh;font-family:"Segoe UI","Microsoft YaHei",sans-serif}
 .retail main{max-width:1480px;padding:48px 48px 24px}.retail a{color:#3158d5}.retail button,.retail select,.retail input{border-radius:5px}.retail :focus-visible{outline:3px solid #e18047;outline-offset:3px}
 .retail-nav{position:sticky;top:0;z-index:30}.retail :is(#dashboard,#components,#data-notes){scroll-margin-top:100px}
-.retail-nav{height:78px;padding:0 48px;border-bottom:1px solid #dcd9d1;display:flex;align-items:center;justify-content:space-between;gap:30px;background:#faf9f6}.retail-nav a{text-decoration:none;color:#40434b}.retail-brand{display:flex;align-items:center;gap:12px;font-weight:700;font-size:17px;white-space:nowrap}.retail-brand b{display:grid;place-items:center;background:#24272d;color:#faf9f6;font-family:Georgia,serif;font-size:30px;width:39px;height:39px;border-radius:4px}.retail-brand small{font-size:12px;font-weight:400;border-left:1px solid #bbb7ad;margin-left:10px;padding-left:12px}.retail-nav>div{display:flex;gap:36px;font-size:13px}.retail-nav>div a:first-child{color:#3158d5;font-weight:650}.retail-live{font-size:12px;white-space:nowrap}.retail-live:before{content:"";display:inline-block;width:6px;height:6px;background:#3158d5;border-radius:50%;margin-right:8px}
+.retail-nav{height:78px;padding:0 48px;border-bottom:1px solid #dcd9d1;display:flex;align-items:center;justify-content:space-between;gap:30px;background:#faf9f6}.retail-nav a{text-decoration:none;color:#40434b}.retail-brand{display:flex;align-items:center;gap:12px;font-weight:700;font-size:17px;white-space:nowrap}.retail-brand b{display:grid;place-items:center;background:#24272d;color:#faf9f6;font-family:Georgia,serif;font-size:30px;width:39px;height:39px;border-radius:4px}.retail-brand small{font-size:12px;font-weight:400;border-left:1px solid #bbb7ad;margin-left:10px;padding-left:12px}.retail-nav>div{display:flex;gap:36px;font-size:13px}.retail-nav>div a[aria-current="location"]{color:#3158d5;font-weight:650}.retail-live{font-size:12px;white-space:nowrap}.retail-live:before{content:"";display:inline-block;width:6px;height:6px;background:#3158d5;border-radius:50%;margin-right:8px}
 .retail header{align-items:flex-end;margin-bottom:30px;gap:30px}.retail .eyebrow{font-size:10px;letter-spacing:2.5px;color:#6d706e}.retail h1{font-size:36px;letter-spacing:-1.2px;font-weight:650;margin:12px 0}.retail header .muted{font-size:13px;max-width:750px;line-height:1.9}.retail .muted{color:#75776f}.retail .header-actions{display:flex;align-items:center;gap:20px;white-space:nowrap;font-size:12px}.retail .header-actions button{background:#24272d;color:#fff;border-color:#24272d;padding:11px 18px}.retail .header-actions a{color:#656863;text-decoration:none}
 .retail .filter-card{border-radius:8px;border-color:#dedbd3;background:#faf9f6;box-shadow:none;padding:20px 24px;margin-bottom:8px}.retail .filter-heading{margin-bottom:14px}.retail .filter-heading p{display:none}.retail .filter-symbol{height:28px;width:28px;background:#eaeefa;border-radius:5px;color:#3158d5}.retail .filter-heading h2{font-size:13px;color:#424740}.retail .filter-fields{gap:14px}.retail .filter-fields:has(>.filter-field:only-child){max-width:760px}.retail .filter-label-row{margin-bottom:5px}.retail .filter-label-row label{color:#575d65}.retail .filter-bottom{margin-top:9px;padding-top:12px;border-color:#e3e0d8}.retail .filter-scope{font-size:11px;color:#797d7e;line-height:1.8;margin:4px 0}.retail .field-hint{min-height:0;margin-top:6px}.retail .filter-status{background:#e9edf9;color:#3158d5}.retail .filter-status.pending{background:#fff0db;color:#855316}.retail .query-status{font-size:11px;color:#75776f;text-align:right;margin:12px 0 28px}
 .retail .section-heading{display:flex;align-items:baseline;gap:16px;margin:35px 0 18px}.retail .section-heading>span{font:10px "Segoe UI",sans-serif;letter-spacing:1.5px;color:#85877d}.retail .section-heading h2{font-size:18px;letter-spacing:-.3px;margin:0}.retail .section-heading p{font-size:11px;color:#85877d;margin:0 0 0 auto}

package/templates/web-app/tests/field-selection.test.mjs

@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict';
+import {after,test} from 'node:test';
+import {createServer as createHttpServer} from 'node:http';
+import {createServer} from 'vite';
+import {configErrors} from '../src/finebi/config.js';
+import {createDevMiddleware} from '../scripts/dev-proxy.mjs';
+const server=await createServer({configFile:false,cacheDir:'temp/vite-field-selection-tests',server:{middlewareMode:true,hmr:false}});
+after(()=>server.close());
+const {queryWidget,queryWidgets}=await server.ssrLoadModule('/src/finebi/client.ts');
+const binding={entryId:'w',name:'Table',type:'table'};
+const config={schemaVersion:'1',title:'Test',basePath:'/bi',layout:'overview',dashboardId:'r',maxRows:10,pageSize:5,widgets:[binding],filters:[]};
+const response=()=>new Response(JSON.stringify({success:true,data:{w:{previewResult:{resultType:'DETAIL',header:[],items:[],row:0}}}}));
+
+test('optional dimensionIds validates lists without confusing omission and empty selection',()=>{
+  for(const ids of [undefined,[],['city'],['sales'],['city','sales']]) {
+    const widget=ids===undefined?binding:{...binding,dimensionIds:ids};
+    assert.deepEqual(configErrors({...config,widgets:[widget]}),[]);
+  }
+  for(const ids of [null,'sales',[1],[''],[' '],[null],['sales','sales']]) {
+    assert.ok(configErrors({...config,widgets:[{...binding,dimensionIds:ids}]}).some(e=>e.includes('dimensionIds')));
+  }
+});
+
+test('binding selection reaches ordinary and published queries unchanged, including omission',async()=>{
+  for(const directoryEntryId of [undefined,'directory']) {
+    const widgets=[binding,...[[],['city'],['sales'],['city','sales']].map(dimensionIds=>({...binding,dimensionIds}))];
+    const app={...config,...(directoryEntryId?{directoryEntryId}:{}),widgets};
+    for(const widget of widgets) {
+      await queryWidget(app,widget,{},undefined,async(_url,init)=>{
+        const body=JSON.parse(init.body);
+        assert.deepEqual(body.dimensionSelections,widget.dimensionIds===undefined?undefined:{w:widget.dimensionIds});
+        assert.equal(Object.hasOwn(body,'dimensionSelections'),widget.dimensionIds!==undefined);
+        assert.equal(body.reportEntryId,directoryEntryId);
+        return response();
+      });
+    }
+    await assert.rejects(queryWidgets(app,{},undefined,()=>assert.fail('conflicting bindings must not fetch')),/selection|选择/);
+  }
+});
+
+test('invalid selection fails before browser HTTP and matching batch selections can share an instance',async()=>{
+  await assert.rejects(queryWidgets({...config,widgets:[{...binding,dimensionIds:null}]},{},undefined,()=>assert.fail('invalid config must not fetch')),/dimensionIds/);
+  const widgets=[{...binding,dimensionIds:['city','sales']},{...binding,dimensionIds:['sales','city']}];
+  await queryWidgets({...config,widgets},{},undefined,async(_url,init)=>{
+    const body=JSON.parse(init.body);assert.deepEqual(body.widgetIds,['w']);
+    assert.deepEqual(body.dimensionSelections,{w:['city','sales']});return response();
+  });
+});
+
+test('proxy preserves configured choices and rejects malformed or unconfigured selections before upstream',async()=>{
+  const sent=[];
+  const widgets=[binding,...[[],['sales'],['city','sales']].map(dimensionIds=>({...binding,dimensionIds}))];
+  const middleware=createDevMiddleware({...config,directoryEntryId:'directory',widgets},
+    {FINEBI_DEV_BASE_URL:'http://bi.example/bi',FINEBI_DEV_TOKEN:'secret'},async(_url,init)=>{sent.push(JSON.parse(init.body));return response();});
+  const http=createHttpServer((req,res)=>middleware(req,res,()=>{}));
+  await new Promise(resolve=>http.listen(0,'127.0.0.1',resolve));
+  const send=extra=>fetch(`http://127.0.0.1:${http.address().port}/bi/v5/api/dashboard/report/r/widgets/query`,{
+    method:'POST',headers:{'X-Requested-With':'XMLHttpRequest'},body:JSON.stringify({widgetIds:['w'],pageLimit:10,reportEntryId:'directory',...extra})});
+  try {
+    for(const selections of [null,[],{other:['sales']},{w:null},{w:['']},{w:['sales','sales']},{w:['unknown']},{w:['city']}]) {
+      assert.equal((await send({dimensionSelections:selections})).status,400);
+    }
+    assert.equal(sent.length,0);
+    for(const selections of [undefined,{w:[]},{w:['sales']},{w:['city','sales']}]) {
+      assert.equal((await send(selections===undefined?{}:{dimensionSelections:selections})).status,200);
+      assert.deepEqual(sent.at(-1).dimensionSelections,selections);
+      assert.equal(sent.at(-1).reportEntryId,'directory');
+    }
+  } finally {middleware.dispose?.();await new Promise(resolve=>http.close(resolve));}
+});

package/templates/web-app/tests/proxy.test.mjs

@@ -12,7 +12,7 @@ test('directory proxy pins the published entry and never forwards another source
   try {
     for(const body of [{},{reportEntryId:'other'},{directoryEntryId:'entry'}])assert.equal((await send(body)).status,400);
     assert.equal(sent.length,0);assert.equal((await send({reportEntryId:'entry'})).status,200);assert.equal(sent[0].reportEntryId,'entry');
-  }finally{await new Promise(r=>server.close(r));}
+  }finally{middleware.dispose();await new Promise(r=>server.close(r));}
 });
 
 test('development identity stays on server and cross-site or out-of-scope requests are rejected', async () => {
@@ -20,7 +20,7 @@ test('development identity stays on server and cross-site or out-of-scope reques
   const middleware = createDevMiddleware({basePath:'/webroot/decision',dashboardId:'r',widgets:[{entryId:'w'}],maxRows:1000}, {FINEBI_DEV_BASE_URL:'http://bi.example/webroot/decision',FINEBI_DEV_USERNAME:'tester',FINEBI_DEV_PASSWORD:'dev-secret'}, async (url,init) => {
     upstream.push({url,init});
     return new Response(JSON.stringify(url.endsWith('/login') ? {data:{accessToken:'session-secret'}} : {success:true,data:{w:{previewResult:{resultType:'DETAIL'}}}}));
-  });
+  }, {save:async()=>{},notify:()=>{}});
   const server=createServer((req,res)=>middleware(req,res,()=>{res.writeHead(404);res.end();}));
   await new Promise(r=>server.listen(0,'127.0.0.1',r));
   const base=`http://127.0.0.1:${server.address().port}`;
@@ -44,16 +44,31 @@ test('development identity stays on server and cross-site or out-of-scope reques
     assert.equal(upstream.length,3,'reuse only the in-memory development session');
   } finally {await new Promise(r=>server.close(r));}
 });
-test('HTML login response clears expired development session and explicit retry logs in again', async()=>{
+test('HTML login response renews the session and retries native query once', async()=>{
   let logins=0, queries=0;
   const middleware=createDevMiddleware({basePath:'/webroot/decision',dashboardId:'r',widgets:[{entryId:'w'}],filters:[],maxRows:1000},{FINEBI_DEV_BASE_URL:'http://bi.example/webroot/decision',FINEBI_DEV_USERNAME:'tester',FINEBI_DEV_PASSWORD:'secret'},async url=>{
     if(url.endsWith('/login')){logins++;return new Response(JSON.stringify({data:{accessToken:'token-'+logins}}));}
     if(++queries===1)return new Response('<html>登录</html>',{headers:{'content-type':'text/html'}});
     return new Response(JSON.stringify({success:true,data:{w:{previewResult:{resultType:'DETAIL'}}}}));
-  });
+  }, {save:async()=>{},notify:()=>{}});
   const server=createServer((req,res)=>middleware(req,res,()=>{}));await new Promise(r=>server.listen(0,'127.0.0.1',r));
   const send=()=>fetch(`http://127.0.0.1:${server.address().port}/webroot/decision/v5/api/dashboard/report/r/widgets/query`,{method:'POST',headers:{'X-Requested-With':'XMLHttpRequest'},body:JSON.stringify({widgetIds:['w'],pageLimit:10})});
-  try{const expired=await send();assert.equal(expired.status,401);assert.equal((await expired.json()).errorCode,'AUTH_REQUIRED');assert.equal((await send()).status,200);assert.equal(logins,2);}finally{await new Promise(r=>server.close(r));}
+  try{assert.equal((await send()).status,200);assert.equal(logins,2);assert.equal(queries,2);}finally{await new Promise(r=>server.close(r));}
+});
+
+test('permission errors never renew and repeated expiry stops after one retry',async()=>{
+  for(const status of [403,401]) {
+    let queries=0,logins=0;
+    const middleware=createDevMiddleware({basePath:'/bi',dashboardId:'r',widgets:[{entryId:'w'}],maxRows:1000},
+      {FINEBI_DEV_BASE_URL:'http://localhost/bi',FINEBI_DEV_TOKEN:'cached',FINEBI_DEV_USERNAME:'alice',FINEBI_DEV_PASSWORD:'secret'},
+      async url=>{if(url.endsWith('/login')){logins++;return new Response(JSON.stringify({data:{accessToken:'new'}}));}
+        queries++;return new Response('{}',{status});},{save:async()=>{},notify:()=>{}});
+    const server=createServer((req,res)=>middleware(req,res,()=>{}));await new Promise(r=>server.listen(0,'127.0.0.1',r));
+    try {
+      const response=await fetch(`http://127.0.0.1:${server.address().port}/bi/v5/api/dashboard/report/r/widgets/query`,{method:'POST',headers:{'X-Requested-With':'XMLHttpRequest'},body:JSON.stringify({widgetIds:['w'],pageLimit:10})});
+      assert.equal(response.status,status);assert.equal(queries,status===403?1:2);assert.equal(logins,status===403?0:1);
+    } finally {middleware.dispose?.();await new Promise(r=>server.close(r));}
+  }
 });
 test('missing credentials gives an explicit auth error without upstream access',async()=>{
   const middleware=createDevMiddleware({basePath:'/webroot/decision',dashboardId:'r',widgets:[{entryId:'w'}],maxRows:1000},{},()=>{throw Error('must not fetch');});

package/templates/web-app/tests/runtime.test.mjs

@@ -73,6 +73,13 @@ test('auth expiry, permission denial, login HTML and missing widget stay distinc
     await assert.rejects(queryWidgets(config,{},undefined,async()=>response), e=>e instanceof FineBIError && e.code===code);
   }
 });
+
+test('development authorization failures explain the next action without revealing credentials',async()=>{
+  for(const code of ['AUTH_PLUGIN_REQUIRED','AUTH_HTTPS_REQUIRED','AUTH_PROTOCOL_ERROR','AUTH_UNAVAILABLE','AUTH_STORAGE_FAILED']) {
+    await assert.rejects(queryWidgets(config,{},undefined,async()=>new Response(JSON.stringify({success:false,errorCode:code}),{status:502})),
+      error=>error.code===code && /开发终端/.test(error.message));
+  }
+});
 test('view binding requires exact fields and an explicit model for multi-model results', () => {
   const source = {previewResult:{resultType:'CHART',geoms:[{dataModel:{fields:[{id:'x',name:'地区',fieldType:'DIMENSION'},{id:'y',name:'金额',fieldType:'MEASURE'}],colData:[['East','West'],[12,5]],rowCount:2}}]}};
   const r=normalize(source);

package/templates/web-app/tests/session.test.mjs

@@ -0,0 +1,91 @@
+import assert from 'node:assert/strict';
+import {test} from 'node:test';
+import {mkdtemp, mkdir, readFile, writeFile, stat, symlink} from 'node:fs/promises';
+import {resolve} from 'node:path';
+import {createDevSession} from '../scripts/dev-session.mjs';
+import {saveSession} from '../scripts/session-file.mjs';
+import {browserSession} from '../scripts/browser-session.mjs';
+
+const baseUrl='https://bi.example/decision';
+const env={FINEBI_DEV_BASE_URL:baseUrl,FINEBI_DEV_USERNAME:'alice',FINEBI_DEV_PASSWORD:'password'};
+const json=(body,status=200)=>new Response(JSON.stringify(body),{status,headers:{'content-type':'application/json'}});
+const no=()=>{throw Error('unexpected call');};
+
+test('query arriving during invalidation waits for file clearing then acquires a session',async()=>{
+  let release;
+  const blocked=new Promise(r=>{release=r;});
+  const session=createDevSession({...env,FINEBI_DEV_TOKEN:'old'}, {fetchImpl:async()=>json({data:{accessToken:'new'}}),
+    browser:no,save:async(_url,token)=>{if(!token)await blocked;}});
+  const clearing=session.invalidate('old');const next=session.get();release();await clearing;
+  assert.equal(await next,'new');
+});
+
+test('valid cached session wins; concurrent acquisition prefers password and persists once',async()=>{
+  const cached=createDevSession({...env,FINEBI_DEV_TOKEN:'cached'},{fetchImpl:no,browser:no,save:no});
+  assert.equal(await cached.get(),'cached');
+  const saves=[];
+  const session=createDevSession(env,{fetchImpl:async(url,init)=>{
+    assert.equal(url,baseUrl+'/login');assert.equal(JSON.parse(init.body).username,'alice');
+    return json({data:{accessToken:'password-session'}});
+  },browser:no,save:async(...args)=>saves.push(args)});
+  assert.deepEqual(await Promise.all([session.get(),session.get()]),['password-session','password-session']);
+  assert.equal(saves.length,1);assert.equal(saves[0][1],'password-session');
+});
+
+test('password rejection uses browser once, persists identity and does not retry rejected password',async()=>{
+  let passwords=0,browsers=0;
+  const saves=[];
+  const session=createDevSession(env,{fetchImpl:async()=>{passwords++;return json({errorCode:'PASSWORD_ERROR'},401);},
+    browser:async()=>({token:'sso-'+(++browsers),username:'Bob'}),save:async(...args)=>saves.push(args)});
+  assert.equal(await session.get(),'sso-1');await session.invalidate('sso-1');
+  assert.equal(await session.get(),'sso-2');assert.equal(passwords,1);assert.equal(browsers,2);
+  assert.equal(saves.at(-1)[2],'Bob');
+});
+
+test('network and upstream server errors never trigger browser authorization',async()=>{
+  for(const fetchImpl of [async()=>{throw Error('socket');},async()=>json({},503)]) {
+    const s=createDevSession(env,{fetchImpl,browser:no,save:no});
+    await assert.rejects(s.get(),/UPSTREAM_UNAVAILABLE/);
+  }
+});
+
+test('stale failures do not clear fresh token; persisted token is bound to server',async()=>{
+  const saves=[];
+  const s=createDevSession({...env,FINEBI_DEV_TOKEN:'old'},{fetchImpl:async()=>json({data:{accessToken:'new'}}),browser:no,save:async(...v)=>saves.push(v)});
+  await s.invalidate('old');assert.equal(await s.get(),'new');await s.invalidate('old');assert.equal(await s.get(),'new');
+  const changed=createDevSession({...env,FINEBI_DEV_TOKEN:'wrong-server',FINEBI_DEV_TOKEN_BASE_URL:'https://other.example/decision'},
+    {fetchImpl:async()=>json({data:{accessToken:'right-server'}}),browser:no,save:async()=>{}});
+  assert.equal(await changed.get(),'right-server');
+});
+
+test('session file preserves other configuration, replaces duplicate tokens and restricts access',async()=>{
+  const root=resolve('temp');await mkdir(root,{recursive:true});const dir=await mkdtemp(resolve(root,'auth-file-'));
+  const path=resolve(dir,'.env.local');
+  await writeFile(path,'# own config\nCUSTOM="keep"\nFINEBI_DEV_PASSWORD="keep-password"\nFINEBI_DEV_TOKEN=old\nexport FINEBI_DEV_TOKEN=duplicate\n');
+  await saveSession(path,baseUrl,'new-session','Alice');
+  const content=await readFile(path,'utf8');
+  assert.match(content,/CUSTOM="keep"/);assert.match(content,/PASSWORD="keep-password"/);
+  assert.equal((content.match(/^FINEBI_DEV_TOKEN=/gm)||[]).length,1);assert.doesNotMatch(content,/duplicate|=old/);
+  assert.match(content,/FINEBI_DEV_TOKEN_BASE_URL="https:\/\/bi.example\/decision"/);
+  if(process.platform!=='win32')assert.equal((await stat(path)).mode & 0o777,0o600);
+  await saveSession(path,baseUrl,'','');assert.match(await readFile(path,'utf8'),/FINEBI_DEV_TOKEN=""/);
+});
+
+test('session persistence refuses symlinks', {skip:process.platform==='win32'}, async()=>{
+  await mkdir('temp',{recursive:true});const dir=await mkdtemp(resolve('temp','auth-link-'));
+  const target=resolve(dir,'other');await writeFile(target,'unchanged');await symlink(target,resolve(dir,'.env.local'));
+  await assert.rejects(saveSession(resolve(dir,'.env.local'),baseUrl,'secret','Alice'));
+  assert.equal(await readFile(target,'utf8'),'unchanged');
+});
+
+test('browser handoff pins verification URL and keeps retrieval secret out of notices',async()=>{
+  const notices=[],opened=[],calls=[];
+  const result=await browserSession(baseUrl,{notify:text=>notices.push(text),openBrowser:url=>opened.push(url),sleep:async()=>{},
+    fetchImpl:async(url,init)=>{calls.push({url,init});return url.endsWith('/start')
+      ?json({data:{deviceCode:'d'.repeat(43),userCode:'ABCD-EFGH',verificationPath:'/api/bi-cli/dev-session-auth/authorize?code=ABCD-EFGH',expiresIn:600,interval:5}})
+      :json({data:{status:'approved',token:'session-secret',username:'Alice'}});}});
+  assert.equal(result.token,'session-secret');assert.equal(opened[0],baseUrl+'/api/bi-cli/dev-session-auth/authorize?code=ABCD-EFGH');
+  assert.doesNotMatch(notices.join(' '),/session-secret|dddddddd/);
+  assert.equal(JSON.parse(calls[1].init.body).deviceCode,'d'.repeat(43));
+  await assert.rejects(browserSession(baseUrl,{notify:no,openBrowser:no,fetchImpl:async()=>json({data:{deviceCode:'d'.repeat(43),userCode:'ABCD-EFGH',verificationPath:'https://evil.example/',expiresIn:600,interval:5}})}),/AUTH_PROTOCOL_ERROR/);
+});