@finebi/finebi-cli 1.6.1 → 1.6.3

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/src/App.tsx

@@ -10,6 +10,13 @@ const FilterBar=lazy(()=>import('./components/FilterBar').then(module=>({default
 function Dashboard({config}: {config: AppConfig}) {
   const [filters,setFilters]=useState<FilterState>({}),[refresh,setRefresh]=useState(0);
   const [states,setStates]=useState<Record<string,WidgetState>>({});
+  const [activeHash,setActiveHash]=useState(()=>window.location.hash||'#dashboard');
+  useEffect(()=>{
+    const syncHash=()=>setActiveHash(window.location.hash||'#dashboard');
+    window.addEventListener('hashchange',syncHash);
+    syncHash();
+    return ()=>window.removeEventListener('hashchange',syncHash);
+  },[]);
   const generation=useRef(0),retries=useRef(new Map<string,AbortController>());
   useEffect(()=>{
     const controller=new AbortController();generation.current++;setStates({});
@@ -34,7 +41,7 @@ function Dashboard({config}: {config: AppConfig}) {
   const cockpit=config.layout==='cockpit';
   const separateKpis=cockpit||retail;
   return <div className={`app ${config.layout}`}>
-    {retail&&<nav className="retail-nav" aria-label="页面导航"><a className="retail-brand" href="#dashboard"><b>F.</b><span>FineBI <small>经营简报</small></span></a><div><a href="#dashboard">经营概览</a><a href="#components">销售分析</a><a href="#data-notes">口径说明</a></div><span className="retail-live">动态数据</span></nav>}
+    {retail&&<nav className="retail-nav" aria-label="页面导航"><a className="retail-brand" href="#dashboard"><b>F.</b><span>FineBI <small>经营简报</small></span></a><div><a href="#dashboard" aria-current={activeHash==='#dashboard'?'location':undefined}>经营概览</a><a href="#components" aria-current={activeHash==='#components'?'location':undefined}>销售分析</a><a href="#data-notes" aria-current={activeHash==='#data-notes'?'location':undefined}>口径说明</a></div><span className="retail-live">动态数据</span></nav>}
     {config.layout!=='overview'&&!retail&&<aside><strong>FineBI<span>数据应用</span></strong><nav><a href="#dashboard">数据概览</a><a href="#components">分析组件</a>{config.insights&&<a href="#observations">经营观察</a>}<a href="#data-notes">数据口径</a></nav><p className="source-label">{config.directoryEntryId?'目录发布来源':'分析主题来源'}<br/>访问者权限由 FineBI 控制</p></aside>}
     <main id="dashboard"><header><div><span className="eyebrow">FINEBI · LIVE DATA</span><h1>{config.title}</h1><p className="muted">{config.description??'基于源看板的实时数据，按当前访问权限呈现'}</p></div><div className="header-actions"><a href={retail?'#data-notes':config.basePath} target={retail?undefined:'_blank'} rel="noreferrer">{retail?'口径说明':'打开 FineBI'}</a><button onClick={()=>setRefresh(n=>n+1)}>刷新数据</button></div></header>
     {config.filters.length>0&&<Boundary><Suspense fallback={<p role="status">正在加载筛选控件…</p>}><FilterBar bindings={config.filters} onApply={setFilters} cockpit={cockpit} scope={scope} compact={retail}/></Suspense></Boundary>}

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/src/components/DataTable.tsx

@@ -15,7 +15,7 @@ export function DataTable({dataset, pageSize,binding}: {dataset: Dataset; pageSi
   const download=()=>{const url=URL.createObjectURL(new Blob([tableCsv(visible,shown)],{type:'text/csv;charset=utf-8'}));const link=document.createElement('a');link.href=url;link.download='loaded-results.csv';link.click();setTimeout(()=>URL.revokeObjectURL(url),1000);};
   return <><div className="table-tools"><label>搜索已加载数据 <input placeholder="搜索已加载数据" value={search} onChange={e => {setSearch(e.target.value);setPage(0);}}/></label><span>已加载 {dataset.returnedRowCount} 行 · 匹配 {rows.length} 行</span><button onClick={download}>导出匹配结果 CSV</button></div>
     {(binding.localFilterFieldIds?.length??0)>0&&<div className="local-filters">{binding.localFilterFieldIds!.map(id=>{const index=fieldIndex(dataset,id);return <label key={id}>{dataset.columns[index].name}（已加载值）<select value={filters[id]??''} onChange={e=>{setFilters(old=>({...old,[id]:e.target.value}));setPage(0);}}><option value="">全部已加载值</option>{[...new Set(dataset.rows.map(row=>displayCell(row.cells[index])))].filter(Boolean).map(value=><option key={value}>{value}</option>)}</select></label>;})}</div>}
-    <div className="table-scroll"><table><thead><tr><th>序号</th>{visible.columns.map(c => <th key={c.key} aria-sort={sort?.fieldId===c.fieldId?(sort.direction==='asc'?'ascending':'descending'):'none'}><button className="sort-column" onClick={()=>{setSort({fieldId:c.fieldId,direction:sort?.fieldId===c.fieldId&&sort.direction==='asc'?'desc':'asc'});setPage(0);}}>{c.name} {sort?.fieldId===c.fieldId?(sort.direction==='asc'?'↑':'↓'):'↕'}</button></th>)}<th>行类型</th></tr></thead><tbody>{shown.slice(current * pageSize, (current + 1) * pageSize).map((row,i) => <tr key={current * pageSize + i}><td>{current * pageSize + i + 1}</td>{row.cells.map((c,j) => <td key={visible.columns[j].key}>{displayCell(c)}</td>)}<td>{row.kind==='DATA'?'数据':'UNKNOWN'}</td></tr>)}</tbody></table></div>
+    <div className="table-scroll"><table><thead><tr><th>序号</th>{visible.columns.map(c => <th key={c.key} aria-sort={sort?.fieldId===c.fieldId?(sort.direction==='asc'?'ascending':'descending'):'none'}><button className="sort-column" onClick={()=>{setSort({fieldId:c.fieldId,direction:sort?.fieldId===c.fieldId&&sort.direction==='asc'?'desc':'asc'});setPage(0);}}>{c.name} {sort?.fieldId===c.fieldId?(sort.direction==='asc'?'↑':'↓'):'↕'}</button></th>)}<th>行类型</th></tr></thead><tbody>{shown.slice(current * pageSize, (current + 1) * pageSize).map((row,i) => <tr key={current * pageSize + i}><td>{current * pageSize + i + 1}</td>{row.cells.map((c,j) => <td key={visible.columns[j].key}>{displayCell(c)}</td>)}<td>{{DATA:'数据',SUBTOTAL:'小计',GRAND_TOTAL:'总计',UNKNOWN:'UNKNOWN'}[row.kind]}</td></tr>)}</tbody></table></div>
     {!rows.length && <p className="empty">没有匹配的数据</p>}
     <nav className="pager" aria-label="已加载数据分页"><button disabled={current===0} onClick={()=>setPage(current-1)}>上一页</button><span>{current+1} / {pages}</span><button disabled={current===pages-1} onClick={()=>setPage(current+1)}>下一页</button></nav></>;
 }

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/src/components/Widget.tsx

@@ -32,6 +32,7 @@ export function Widget({state,binding,pageSize,onRetry,compact=false}: {state:Wi
     {state.error&&<div className="component-error" role="alert"><p>{'code' in state.error?String(state.error.code)+' · ':''}{state.error.message}</p><button onClick={onRetry}>重试组件</button></div>}
     {result&&<>
     {compact?<details className="query-details"><summary>查询范围{selected?` · ${selected.returnedRowCount} 行`:''}</summary><p>{result.range.mode} · {result.normalization} · 后续数据：{String(result.range.hasNext)}</p><p>筛选作用：{binding.filterNames?.join('、')||'沿用源组件条件'}</p></details>:<p className="result-range">{result.range.mode} · 本次{selected?` ${selected.returnedRowCount} 行`:'多个模型，需显式选择'}{result.range.total.value!==null?` · 查询总行数 ${result.range.total.value}`:''} · hasNext={String(result.range.hasNext)} · {result.normalization}</p>}
+    {result.range.axes&&<p className="result-range">交叉表当前视图 · 横向还有数据：{result.range.axes.horizontal.hasNext===null?'未知':result.range.axes.horizontal.hasNext?'是':'否'} · 纵向还有数据：{result.range.axes.vertical.hasNext===null?'未知':result.range.axes.vertical.hasNext?'是':'否'}</p>}
     {(result.warnings.length>0||result.normalization!=='COMPLETE'||result.range.hasNext===true)&&<div className="notice" role="status">{result.range.hasNext||result.warnings.includes('NEXT_PAGE_UNSUPPORTED')?'当前仅展示首屏返回结果，本地分页不代表服务端续页。':'部分源图形未转换，当前展示已返回的数据模型。'}{compact?<details><summary>查看适配说明</summary><small>{result.normalization} · {result.warnings.join(' · ')}</small></details>:<small>{result.normalization} · {result.warnings.join(' · ')}</small>}</div>}
     <Boundary key={state.at} onRetry={onRetry}><Content result={result} binding={binding} pageSize={pageSize}/></Boundary>
     </>}

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/src/finebi/client.ts

@@ -1,6 +1,6 @@
 import {normalize} from './normalize';
 import {encodeFilters} from './filters.js';
-import {configErrors} from './config.js';
+import {configErrors, sameDimensionIds} from './config.js';
 import type {AppConfig, QueryResult, FilterState, WidgetBinding} from './types';
 export class FineBIError extends Error {
   constructor(public code: string, message: string) {super(message); this.name = 'FineBIError';}
@@ -14,10 +14,16 @@ export async function queryWidgets(config: AppConfig, filters: FilterState = {},
   const refer = encodeFilters(config.filters,filters);
   const ids = [...new Set(widgetIds ?? config.widgets.map(w => w.entryId))];
   if(!ids.length||ids.some(id=>!config.widgets.some(w=>w.entryId===id)))throw new Error('组件不在配置范围内');
+  const dimensionSelections:Record<string,string[]> = Object.create(null);
+  for(const id of ids) {
+    const bindings=config.widgets.filter(w=>w.entryId===id);
+    if(bindings.some(w=>!sameDimensionIds(w.dimensionIds,bindings[0].dimensionIds)))throw new Error('同一组件有不同字段选择，请按展示绑定分别查询');
+    if(bindings[0].dimensionIds!==undefined)dimensionSelections[id]=bindings[0].dimensionIds;
+  }
   const response = await fetchImpl(`${config.basePath.replace(/\/$/, '')}/v5/api/dashboard/report/${encodeURIComponent(config.dashboardId)}/widgets/query`, {
     method: 'POST', credentials: 'include', signal, redirect: 'manual',
     headers: {'Content-Type': 'application/json', 'X-Requested-With': 'XMLHttpRequest'},
-    body: JSON.stringify({widgetIds: ids, includeWidgetBean: true, pageLimit: config.maxRows, refer,...(config.directoryEntryId?{reportEntryId:config.directoryEntryId}:{})}),
+    body: JSON.stringify({widgetIds: ids, includeWidgetBean: true, pageLimit: config.maxRows, refer,...(config.directoryEntryId?{reportEntryId:config.directoryEntryId}:{}),...(Object.keys(dimensionSelections).length?{dimensionSelections}:{})}),
   });
   if (response.status === 401 || response.type === 'opaqueredirect' || response.status >= 300 && response.status < 400) throw new FineBIError('AUTH_REQUIRED', '登录已失效，请登录 FineBI 后重试');
   if (response.status === 403) throw new FineBIError('PERMISSION_DENIED', '当前用户没有访问权限');
@@ -26,7 +32,15 @@ export async function queryWidgets(config: AppConfig, filters: FilterState = {},
   const code = body.errorCode ?? body.code;
   if (['TIME_OUT','JWT_EXPIRED','LOGIN_INFO_NOT_AVAILABLE','CANNOT_GET_TOKEN','AUTH_REQUIRED'].includes(code)) throw new FineBIError('AUTH_REQUIRED', '登录已失效，请登录 FineBI 后重试');
   if (code === 'PERMISSION_DENIED') throw new FineBIError('PERMISSION_DENIED', '当前用户没有数据或字段权限');
-  if (!response.ok || body.success !== true) throw new FineBIError('QUERY_FAILED', 'FineBI 查询失败，请检查组件、控件绑定及访问权限');
+  const developmentAuthErrors: Record<string,string> = {
+    AUTH_PLUGIN_REQUIRED:'请更新 FineBI 服务端插件以启用浏览器授权',
+    AUTH_HTTPS_REQUIRED:'浏览器授权需要 HTTPS FineBI 地址',
+    AUTH_PROTOCOL_ERROR:'认证响应不符合预期，请检查 FineBI 地址和版本',
+    AUTH_UNAVAILABLE:'授权服务暂不可用，请稍后重试',
+    AUTH_STORAGE_FAILED:'无法保存本地会话，请检查 .env.local 文件权限',
+  };
+  if (developmentAuthErrors[code]) throw new FineBIError(code, `${developmentAuthErrors[code]}；详情见开发终端`);
+  if (!response.ok || body.success !== true) throw new FineBIError(typeof code==='string'?code:'QUERY_FAILED', 'FineBI 查询失败，请检查组件、控件绑定、平台版本及访问权限');
   const results: Record<string, QueryResult> = {};
   for (const id of ids) {
     if (!body.data?.[id]?.previewResult) throw new FineBIError('INVALID_RESPONSE', `接口未返回组件 ${id}，不能视为空数据`);
@@ -35,8 +49,10 @@ export async function queryWidgets(config: AppConfig, filters: FilterState = {},
   return results;
 }
 export async function queryWidget(config:AppConfig,binding:WidgetBinding,filters:FilterState={},signal?:AbortSignal,fetchImpl:typeof fetch=fetch):Promise<QueryResult> {
+  validateConfig(config);
+  if(!config.widgets.includes(binding))throw new Error('展示绑定不在配置范围内');
   // Validate all draft names before projecting the verified component scope.
   encodeFilters(config.filters,filters);
   const scoped=binding.filterNames ? Object.fromEntries(Object.entries(filters).filter(([name])=>binding.filterNames!.includes(name))) : filters;
-  return (await queryWidgets(config,scoped,signal,fetchImpl,[binding.entryId]))[binding.entryId];
+  return (await queryWidgets({...config,widgets:[binding]},scoped,signal,fetchImpl,[binding.entryId]))[binding.entryId];
 }

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/src/finebi/config.d.ts

@@ -1 +1,3 @@
 export function configErrors(config: unknown): string[];
+export function sameDimensionIds(left: string[] | undefined, right: string[] | undefined): boolean;
+export function validateDimensionSelections(widgets: {entryId: string; dimensionIds?: string[]}[], widgetIds: string[], selections: unknown): void;

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/src/finebi/config.js

@@ -1,6 +1,19 @@
 import {validateFilterBindings} from './filters.js';
 const nonempty=value=>typeof value==='string'&&value.trim().length>0;
 const record=value=>value!==null&&typeof value==='object'&&!Array.isArray(value);
+const validDimensionIds=value=>Array.isArray(value)&&value.every(nonempty)&&new Set(value).size===value.length;
+export function sameDimensionIds(left,right) {
+  if(left===undefined||right===undefined)return left===right;
+  return validDimensionIds(left)&&validDimensionIds(right)&&left.length===right.length&&left.every(id=>right.includes(id));
+}
+export function validateDimensionSelections(widgets,widgetIds,selections) {
+  if(selections!==undefined&&(!record(selections)||Object.keys(selections).some(id=>!widgetIds.includes(id))))throw new Error('Invalid dimension selections');
+  for(const id of widgetIds) {
+    const selected=selections&&Object.hasOwn(selections,id)?selections[id]:undefined;
+    if(selected!==undefined&&!validDimensionIds(selected))throw new Error('Invalid dimensionIds');
+    if(!widgets.some(w=>w.entryId===id&&sameDimensionIds(w.dimensionIds,selected)))throw new Error('Unconfigured dimension selection');
+  }
+}
 export function configErrors(config) {
   if(!record(config))return ['configuration must be a JSON object.'];
   const errors=[];
@@ -21,9 +34,10 @@ export function configErrors(config) {
   if(!Array.isArray(config.widgets)||!config.widgets.length)return [...errors,'widgets must be a non-empty array.'];
   for(const [i,w] of config.widgets.entries()) {
     if(!record(w)){errors.push(`widgets[${i}] must be an object.`);continue;}
-    const fields=['entryId','name','type','datasetId','categoryFieldId','valueFieldId','series','description','filterNames','tableFieldIds','localFilterFieldIds','valueFormat','categoryFormat','categoryTimeZone'];
+    const fields=['entryId','name','type','datasetId','categoryFieldId','valueFieldId','series','description','filterNames','tableFieldIds','localFilterFieldIds','valueFormat','categoryFormat','categoryTimeZone','dimensionIds'];
     for(const field of Object.keys(w))if(!fields.includes(field))errors.push(`widgets[${i}].${field} is unsupported.`);
     for(const field of ['entryId','name'])if(!nonempty(w[field]))errors.push(`widgets[${i}].${field} is required.`);
+    if('dimensionIds' in w&&!validDimensionIds(w.dimensionIds))errors.push(`widgets[${i}].dimensionIds must be unique non-empty strings.`);
     if(!['table','kpi','bar','line','pie'].includes(w.type))errors.push(`widgets[${i}].type is unsupported.`);
     if('valueFormat' in w&&(w.type!=='kpi'||!['number','percent'].includes(w.valueFormat)))errors.push(`widgets[${i}].valueFormat requires a KPI and number or percent.`);
     if('categoryFormat' in w||'categoryTimeZone' in w) {

package/skills/finebi-cli-agent/scripts/finebi-cli/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/skills/finebi-cli-agent/scripts/finebi-cli/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/skills/finebi-cli-agent/scripts/finebi-cli/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/skills/finebi-cli-agent/scripts/finebi-cli/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/skills/finebi-cli-agent/scripts/finebi-cli/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/skills/finebi-cli-agent/scripts/finebi-cli/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/skills/finebi-cli-agent/scripts/finebi-cli/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/);
+});