@finebi/finebi-cli 1.5.0 → 1.6.1

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

@@ -0,0 +1,19 @@
+import assert from 'node:assert/strict';
+import {test} from 'node:test';
+import {build} from 'vite';
+
+test('production entry defers charts and optional controls and only bundles supported date locales',async()=>{
+  const result=await build({logLevel:'silent',build:{write:false}});
+  const chunks=result.output.filter(item=>item.type==='chunk');
+  const initial=new Set();
+  const visit=chunk=>{if(initial.has(chunk))return;initial.add(chunk);for(const name of chunk.imports){const imported=chunks.find(c=>c.fileName===name);if(imported)visit(imported);}};
+  chunks.filter(c=>c.isEntry).forEach(visit);
+  const initialModules=[...initial].flatMap(c=>Object.keys(c.modules));
+  assert.ok(!initialModules.some(id=>/node_modules\/(echarts|zrender)\//.test(id)),'ECharts must not be an entry dependency');
+  assert.ok(!initialModules.some(id=>/node_modules\/(antd|@rc-component\/picker)\//.test(id)),'optional filter UI must not be an entry dependency');
+  const modules=chunks.flatMap(c=>Object.keys(c.modules));
+  assert.ok(!modules.some(id=>id.includes('/tests/browser/')),'browser fixtures and their fetch replacement must not enter production');
+  const locales=new Set(modules.flatMap(id=>{const match=id.match(/date-fns\/locale\/([^/]+)/);return match?[match[1]]:[];}));
+  assert.deepEqual([...locales].filter(name=>!['en-US','zh-CN','_lib','en-US.js','zh-CN.js'].includes(name)),[],'do not bundle unused calendar languages');
+  for(const type of ['Bar','Line','Pie'])assert.ok(chunks.some(c=>c.isDynamicEntry&&Object.keys(c.modules).some(id=>id.endsWith(`/charts/${type}.tsx`))),`${type} has an independent lazy entry`);
+});

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

@@ -0,0 +1,25 @@
+import assert from 'node:assert/strict';
+import {test} from 'node:test';
+import {createServer} from 'vite';
+
+test('picker input and month arithmetic preserve the full calendar contract',async()=>{
+  const server=await createServer({configFile:false,cacheDir:'temp/calendar-tests',server:{middlewareMode:true,hmr:false}});
+  try {
+    const {calendarValue,calendarConfig:config}=await server.ssrLoadModule('/src/components/calendar.ts');
+    for(const value of ['0001-01-01','0099-02-28','0100-03-01','2000-02-29','2024-02-29','9999-12-31']) {
+      const parsed=config.locale.parse('zh_CN',value,['YYYY-MM-DD']);
+      assert.ok(parsed,value);
+      assert.equal(config.locale.format('zh_CN',parsed,'YYYY-MM-DD'),value);
+      assert.equal(config.locale.format('zh_CN',calendarValue(value),'YYYY-MM-DD'),value);
+    }
+    for(const value of ['0001-02','0099-12','2024-02','9999-12']) {
+      const parsed=config.locale.parse('zh_CN',value,['YYYY-MM']);
+      assert.equal(config.locale.format('zh_CN',parsed,'YYYY-MM'),value);
+      assert.equal(config.locale.format('zh_CN',calendarValue(value),'YYYY-MM'),value);
+    }
+    for(const value of ['0000-01-01','1900-02-29','2023-02-29','2024-13-01','2024-02-30','']) assert.equal(calendarValue(value),null,value);
+    assert.equal(config.locale.parse('zh_CN','2023-02-29',['YYYY-MM-DD']),null);
+    assert.equal(config.locale.format('zh_CN',config.getEndDate(calendarValue('0001-02')),'YYYY-MM-DD'),'0001-02-28');
+    assert.equal(config.locale.format('zh_CN',config.addMonth(calendarValue('0099-12'),1),'YYYY-MM'),'0100-01');
+  } finally {await server.close();}
+});

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

@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict';
+import {after,test} from 'node:test';
+import {createServer} from 'vite';
+import {createElement} from 'react';
+import {renderToStaticMarkup} from 'react-dom/server';
+const server=await createServer({configFile:false,cacheDir:'temp/vite-cockpit-tests',server:{middlewareMode:true,hmr:false}});
+after(()=>server.close());
+const client=await server.ssrLoadModule('/src/finebi/client.ts');
+const data=await server.ssrLoadModule('/src/services/table-data.ts');
+const queries=await server.ssrLoadModule('/src/services/widget-queries.ts');
+const {Widget}=await server.ssrLoadModule('/src/components/Widget.tsx');
+const config={schemaVersion:'1',title:'Test',basePath:'/bi',layout:'cockpit',dashboardId:'r',directoryEntryId:'directory',maxRows:1000,pageSize:8,
+  widgets:[{entryId:'a',name:'A',type:'table',filterNames:['month']},{entryId:'b',name:'B',type:'table',filterNames:[]}],filters:[{name:'month',label:'月份',type:'month'}]};
+const native={previewResult:{resultType:'DETAIL',header:[],items:[],size:10,row:0,hasNext:false}};
+test('retry is only exposed after a settled failure, never while an initial request is pending',()=>{
+  const props={binding:config.widgets[0],pageSize:8,onRetry:()=>{}};
+  assert.doesNotMatch(renderToStaticMarkup(createElement(Widget,{...props,state:{loading:true}})),/重试组件/);
+  assert.match(renderToStaticMarkup(createElement(Widget,{...props,state:{loading:false,error:new Error('fixture')}})),/重试组件/);
+});
+test('directory source and verified per-widget scope survive individual queries, never falling back',async()=>{
+  const sent=[];
+  const fetcher=async(url,init)=>{sent.push({url,...JSON.parse(init.body)});return new Response(JSON.stringify({success:true,data:{a:native,b:native}}));};
+  await client.queryWidget(config,config.widgets[0],{month:'2024-02'},undefined,fetcher);
+  await client.queryWidget(config,config.widgets[1],{month:'2024-02'},undefined,fetcher);
+  assert.deepEqual(sent.map(s=>s.reportEntryId),['directory','directory']);
+  assert.deepEqual(sent.map(s=>s.widgetIds),[['a'],['b']]);
+  assert.deepEqual(sent.map(s=>s.refer),[{month:['2024-02']},{}]);
+  let calls=0;
+  await assert.rejects(client.queryWidget(config,config.widgets[0],{},undefined,async()=>{calls++;return new Response('{}',{status:403});}),e=>e.code==='PERMISSION_DENIED');
+  assert.equal(calls,1);
+});
+test('component loader limits concurrency, publishes independent failures and respects cancellation',async()=>{
+  const updates=[];let active=0,peak=0;
+  const many={...config,widgets:[...config.widgets,...Array.from({length:6},(_,i)=>({entryId:'extra-'+i,name:'Extra',type:'table'}))]};
+  await queries.loadWidgets(many,{},new AbortController().signal,(id,state)=>updates.push([id,state]),async(_url,init)=>{
+    active++;peak=Math.max(peak,active);await new Promise(r=>setTimeout(r,5));active--;
+    const id=JSON.parse(init.body).widgetIds[0];return id==='a'?new Response('{}',{status:500}):new Response(JSON.stringify({success:true,data:{[id]:native}}));
+  });
+  assert.equal(peak,3);assert.ok(updates.find(([id,s])=>id==='0:a'&&s.error));assert.ok(updates.find(([id,s])=>id==='1:b'&&s.result));
+  const controller=new AbortController();controller.abort();let calls=0;
+  await queries.loadWidgets(config,{},controller.signal,()=>assert.fail('no stale update'),async()=>{calls++;});assert.equal(calls,0);
+});
+test('same native widget can have separate display scopes; aborted old responses publish nothing',async()=>{
+  const duplicate={...config,widgets:[config.widgets[0],{...config.widgets[0],filterNames:[]}]};
+  const complete=[];
+  await queries.loadWidgets(duplicate,{month:'2024-02'},new AbortController().signal,(key,state)=>{if(state.result)complete.push(key);},async()=>new Response(JSON.stringify({success:true,data:{a:native}})));
+  assert.deepEqual(complete.sort(),['0:a','1:a']);
+  const controller=new AbortController(),updates=[];
+  await queries.loadWidgets(config,{},controller.signal,(_key,state)=>updates.push(state),async()=>{controller.abort();return new Response(JSON.stringify({success:true,data:{a:native,b:native}}));});
+  assert.ok(updates.every(s=>s.loading));
+});
+const cell=(value,state='AVAILABLE',display=value)=>({value,display,state,reason:null});
+const dataset={id:'main',returnedRowCount:4,columns:[{fieldId:'x',key:'c0',name:'名字',type:'STRING'},{fieldId:'v',key:'c1',name:'金额',type:'DECIMAL'}],rows:[
+  {kind:'DATA',cells:[cell('=HYPERLINK("x")'),cell('9007199254740993.01')]},
+  {kind:'DATA',cells:[cell('B'),cell('9007199254740993.02','AVAILABLE','9,007,199,254,740,993.02元')]},
+  {kind:'UNKNOWN',cells:[cell('C'),cell(null,'RESTRICTED','***')]},
+  {kind:'DATA',cells:[cell('D'),cell(null,'NULL',null)]},
+]};
+test('loaded table sorts decimals exactly, filters and exports matching rows with safe CSV and explicit states',()=>{
+  assert.equal(data.compareDecimal('9007199254740993.01','9007199254740993.02'),-1);
+  assert.equal(data.compareDecimal('-1.001e3','-1001'),0);
+  assert.equal(data.compareDecimal('1e-10','0.00000000009'),1);
+  assert.equal(data.compareDecimal('1.20','1.2'),0);
+  assert.equal(data.compareDecimal('1200','1.2e3'),0);
+  assert.equal(data.compareDecimal('-0.001200','-1.2e-3'),0);
+  const rows=data.tableRows(dataset,{search:'',sort:{fieldId:'v',direction:'desc'},filters:{}});
+  assert.equal(rows[0].cells[0].value,'B');assert.equal(rows[1].cells[0].value,'=HYPERLINK("x")');
+  const filtered=data.tableRows(dataset,{search:'',filters:{x:'B'}});assert.equal(filtered.length,1);
+  const csv=data.tableCsv(dataset,rows);
+  assert.match(csv,/'=HYPERLINK/);assert.match(csv,/受限/);assert.doesNotMatch(csv,/\*\*\*/);assert.match(csv,/UNKNOWN/);
+  assert.match(data.tableCsv(dataset,filtered),/9,007,199/);
+  assert.throws(()=>data.tableRows(dataset,{search:'',filters:{missing:'x'}}),/字段/);
+});

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

@@ -0,0 +1,96 @@
+import assert from 'node:assert/strict';
+import {test} from 'node:test';
+import {createServer} from 'node:http';
+import {createDevMiddleware} from '../scripts/dev-proxy.mjs';
+
+test('directory proxy pins the published entry and never forwards another source',async()=>{
+  const sent=[];
+  const middleware=createDevMiddleware({basePath:'/bi',dashboardId:'r',directoryEntryId:'entry',widgets:[{entryId:'w'}],filters:[],maxRows:10},
+    {FINEBI_DEV_BASE_URL:'http://bi.example/bi',FINEBI_DEV_TOKEN:'secret'},async(_url,init)=>{sent.push(JSON.parse(init.body));return new Response(JSON.stringify({success:true,data:{}}));});
+  const server=createServer((req,res)=>middleware(req,res,()=>{}));await new Promise(r=>server.listen(0,'127.0.0.1',r));
+  const send=body=>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,...body})});
+  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));}
+});
+
+test('development identity stays on server and cross-site or out-of-scope requests are rejected', async () => {
+  const upstream = [];
+  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'}}}}));
+  });
+  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}`;
+  const path='/webroot/decision/v5/api/dashboard/report/r/widgets/query';
+  const request=(body,headers={})=>fetch(base+path,{method:'POST',headers:{'Content-Type':'application/json','X-Requested-With':'XMLHttpRequest',...headers},body:JSON.stringify(body)});
+  try {
+    const valid={widgetIds:['w'],pageLimit:1000};
+    assert.equal((await request(valid,{Origin:'https://evil.example'})).status,403);
+    assert.equal((await request({...valid,widgetIds:['other']})).status,400);
+    assert.equal((await request({...valid,pageLimit:10001})).status,400);
+    assert.equal((await request({...valid,refer:{'未配置的控件':['x']}})).status,400);
+    assert.equal(upstream.length,0);
+    const result=await request(valid,{Origin:base});
+    assert.equal(result.status,200);
+    assert.doesNotMatch(await result.text(),/secret/);
+    assert.equal(upstream.length,2);
+    assert.equal(upstream[1].init.headers.Cookie,'fine_auth_token=session-secret');
+    assert.equal(upstream[1].init.redirect,'manual');
+    assert.equal((await fetch(base+'/webroot/decision/login',{method:'POST'})).status,403);
+    assert.equal((await request(valid)).status,200);
+    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()=>{
+  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'}}}}));
+  });
+  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));}
+});
+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');});
+  const server=createServer((req,res)=>middleware(req,res,()=>{}));
+  await new Promise(r=>server.listen(0,'127.0.0.1',r));
+  try {
+    const r=await 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})});
+    assert.equal(r.status,401);assert.equal((await r.json()).errorCode,'AUTH_REQUIRED');
+  }finally{await new Promise(r=>server.close(r));}
+});
+test('date proxy accepts real dates without an option allowlist and rejects malformed overrides',async()=>{
+  const calls=[];
+  const middleware=createDevMiddleware({basePath:'/bi',dashboardId:'r',widgets:[{entryId:'w'}],maxRows:1000,filters:[{name:'日期',label:'日期',type:'date'},{name:'产品',label:'产品',options:[{label:'橡皮',value:'橡皮'}]}]},
+    {FINEBI_DEV_BASE_URL:'http://bi.example/bi',FINEBI_DEV_TOKEN:'secret'},async (_url,init)=>{calls.push(JSON.parse(init.body));return new Response(JSON.stringify({success:true,data:{}}));});
+  const server=createServer((req,res)=>middleware(req,res,()=>{}));await new Promise(r=>server.listen(0,'127.0.0.1',r));
+  const send=refer=>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:1000,refer})});
+  try {
+    for(const refer of [{'日期':['2023-02-29']},{'日期':['2024-02-30']},{'日期':['0000-01-01']},{'日期':['2024-2-01']},{'日期':['']},{'日期':['2024-01-01','2024-02-01']},{'日期':[42]},{'未知':['2024-01-01']},{'产品':['未知']}]) assert.equal((await send(refer)).status,400);
+    assert.equal(calls.length,0);
+    const refer={'日期':['2024-02-29'],'产品':['橡皮']};assert.equal((await send(refer)).status,200);assert.deepEqual(calls[0].refer,refer);
+    assert.equal((await send({})).status,200);assert.deepEqual(calls[1].refer,{});
+  }finally{await new Promise(r=>server.close(r));}
+});
+
+test('proxy applies the same typed contract to ranges, multi-select, null and unsupported raw values',async()=>{
+  const calls=[];
+  const middleware=createDevMiddleware({basePath:'/bi',dashboardId:'r',widgets:[{entryId:'w'}],maxRows:1000,filters:[
+    {name:'产品',label:'产品',type:'multi-select',allowNull:true,options:[{label:'A',value:'A'},{label:'B',value:'B'}]},
+    {name:'日期',label:'日期',type:'date-range'}, {name:'金额',label:'金额',type:'number'},
+  ]},{FINEBI_DEV_BASE_URL:'http://bi.example/bi',FINEBI_DEV_TOKEN:'secret'},async (_url,init)=>{calls.push(JSON.parse(init.body));return new Response(JSON.stringify({success:true,data:{}}));});
+  const server=createServer((req,res)=>middleware(req,res,()=>{}));await new Promise(r=>server.listen(0,'127.0.0.1',r));
+  const send=refer=>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,refer})});
+  try {
+    for(const refer of [{'产品':['A','B']},{'产品':['A,C']},{'产品':['A,A']},{'产品':['A,']},{'日期_s':['2024-03-01'],'日期_e':['2024-02-29']},{'日期':['2024-01-01']},{'金额':['10,20']},null]) assert.equal((await send(refer)).status,400);
+    assert.equal(calls.length,0);
+    for(const refer of [{'产品':['A,B'],'日期_s':['2024-02-29'],'金额':['-0.25']},{'产品':['null']},{}]) {
+      assert.equal((await send(refer)).status,200);assert.deepEqual(calls.at(-1).refer,refer);
+    }
+  }finally{await new Promise(r=>server.close(r));}
+});

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

@@ -0,0 +1,31 @@
+import assert from 'node:assert/strict';
+import {after,test} from 'node:test';
+import {createServer} from 'vite';
+const server=await createServer({configFile:false,cacheDir:'temp/vite-retail-tests',server:{middlewareMode:true,hmr:false}});
+after(()=>server.close());
+const {formatMetric,formatCategory}=await server.ssrLoadModule('/src/services/presentation.ts');
+const {configErrors}=await import('../src/finebi/config.js');
+const cell=(value,state='AVAILABLE')=>({value,display:null,state,reason:null});
+test('KPI display preserves decimal precision and formats ratios only by explicit configuration',()=>{
+  assert.equal(formatMetric(cell('9007199254740993.01'),'number'),'9,007,199,254,740,993.01');
+  assert.equal(formatMetric(cell('1.2345678e7'),'number'),'12,345,678');
+  assert.equal(formatMetric(cell('0.123456789'),'percent'),'12.35%');
+  assert.equal(formatMetric(cell('-0.00005'),'percent'),'-0.01%');
+  assert.equal(formatMetric(cell('42.0'),'number'),'42');
+  assert.equal(formatMetric(cell('100','RESTRICTED'),'number'),'受限');
+  assert.equal(formatMetric(cell(null,'NULL'),'percent'),'—');
+  assert.equal(formatMetric(cell('0.5')),'0.5');
+});
+test('month formatting is explicit, timezone-aware and preserves invalid or restricted values',()=>{
+  const binding={categoryFormat:'epoch-month',categoryTimeZone:'Asia/Shanghai'};
+  const timestamp=String(Date.UTC(2024,1,29,16));
+  assert.equal(formatCategory(cell(timestamp),binding),'2024-03');
+  assert.equal(formatCategory(cell(timestamp),{}),timestamp);
+  assert.equal(formatCategory(cell('not-a-date'),binding),'not-a-date');
+  assert.equal(formatCategory(cell(timestamp,'RESTRICTED'),binding),'受限');
+});
+test('display configuration rejects implicit date timezone and invalid formats',()=>{
+  const config={schemaVersion:'1',title:'Test',basePath:'/bi',layout:'retail',dashboardId:'r',maxRows:1000,pageSize:8,filters:[],widgets:[{entryId:'w',name:'Trend',type:'line',categoryFieldId:'x',valueFieldId:'y',categoryFormat:'epoch-month',categoryTimeZone:'Asia/Shanghai'}]};
+  assert.deepEqual(configErrors(config),[]);
+  for(const patch of [{categoryTimeZone:undefined},{categoryTimeZone:'Bad/Timezone'},{categoryFormat:'guess'},{valueFormat:'guess'}])assert.ok(configErrors({...config,widgets:[{...config.widgets[0],...patch}]}).length);
+});

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

@@ -0,0 +1,136 @@
+import assert from 'node:assert/strict';
+import {after, test} from 'node:test';
+import {createServer} from 'vite';
+const server = await createServer({configFile: false, cacheDir: 'temp/vite-tests', server: {middlewareMode: true, hmr: false}});
+after(() => server.close());
+const {normalize} = await server.ssrLoadModule('/src/finebi/normalize.ts');
+const {queryWidgets, FineBIError} = await server.ssrLoadModule('/src/finebi/client.ts');
+const {chartValues, selectDataset} = await server.ssrLoadModule('/src/services/view-data.ts');
+const detail = () => ({previewResult: {resultType: 'DETAIL', header: [
+  {dId: 'd', text: '重复名'}, {dId: 'n', text: '重复名'}, {dId: 't', text: '日期'}
+], items: [[{value: 'A', text: 'A', authority: true}, {value: '1234.50', formatText: '1,234.50元', authority: true}, {value: '1349020800000', formatText: '2012-10-01', authority: true}]], row: 1000, size: 1, hasNext: true}, widgetBean: {dimensions: {d: {type: 1}, n: {type: 2}, t: {type: 3}}}});
+test('detail preserves field identity, display, decimal and date values with honest range', () => {
+  const r = normalize(detail());
+  assert.equal(r.schemaVersion, '1');
+  assert.equal(r.normalization, 'COMPLETE');
+  assert.deepEqual(r.datasets[0].columns.map(c => c.key), ['c0','c1','c2']);
+  assert.deepEqual(r.datasets[0].rows[0].cells.map(c => c.value), ['A','1234.50','1349020800000']);
+  assert.equal(r.datasets[0].rows[0].cells[1].display, '1,234.50元');
+  assert.equal(r.range.total.value, 1000);
+  assert.ok(r.warnings.includes('NEXT_PAGE_UNSUPPORTED'));
+});
+test('restricted, display-only, missing, unknown and invalid dates cannot become computable values', () => {
+  const source = detail();
+  source.previewResult.items = [[{value: 'secret', text: '***', authority: false}, {value: null, text: '20%', authority: true}, {value: '9223372036854775808', authority: true}], []];
+  const r = normalize(source);
+  assert.equal(r.normalization, 'PARTIAL');
+  const cells = r.datasets[0].rows[0].cells;
+  assert.equal(cells[0].state, 'RESTRICTED');
+  assert.equal(cells[0].value, null);
+  assert.equal(cells[1].state, 'UNAVAILABLE');
+  assert.equal(cells[2].reason, 'INVALID_TIMESTAMP_VALUE');
+  delete source.widgetBean;
+  assert.equal(normalize(source).datasets[0].rows[0].cells[1].value, null);
+});
+test('full-looking page does not discard native hasNext; empty is different from unsupported', () => {
+  const source = detail(); source.previewResult.row = 1;
+  assert.ok(normalize(source).warnings.includes('NEXT_PAGE_UNSUPPORTED'));
+  source.previewResult.items = []; source.previewResult.row = 0; source.previewResult.hasNext = false;
+  assert.equal(normalize(source).datasets[0].returnedRowCount, 0);
+  assert.equal(normalize({previewResult: {resultType: 'BICROSS'}}).normalization, 'UNSUPPORTED');
+});
+test('chart permission placeholders and all supported detail date metadata preserve their semantics', () => {
+  const r=normalize({previewResult:{resultType:'CHART',geoms:[{dataModel:{fields:[{id:'n',name:'指标',fieldType:'MEASURE'}],colData:[['***']],rowCount:1}}]}});
+  assert.equal(r.datasets[0].rows[0].cells[0].state,'RESTRICTED');
+  for(const type of [3,13,15,20]) {const s=detail();s.widgetBean.dimensions.t.type=type;assert.equal(normalize(s).datasets[0].columns[2].type,'DATE');}
+});
+test('chart preserves multiple models, rejects formatted numeric strings and mismatched columns', () => {
+  const model = {fields: [{id:'x',name:'地区',fieldType:'DIMENSION'}, {id:'y',name:'金额',fieldType:'MEASURE'}], colData: [['East','West'], [12,'1,234']],rowCount:2};
+  const r = normalize({previewResult:{resultType:'CHART',geoms:[{dataModel:model},{dataModel:{...model,colData:[['A'],[]],rowCount:1}}]}});
+  assert.equal(r.datasets.length,2);
+  assert.equal(r.datasets[0].rows[0].cells[1].value,'12');
+  assert.equal(r.datasets[0].rows[1].cells[1].state,'UNAVAILABLE');
+  assert.equal(r.normalization,'PARTIAL');
+});
+const config = {schemaVersion:'1',title:'Test',layout:'overview',pageSize:8,basePath:'/webroot/decision',dashboardId:'report',maxRows:1000,widgets:[{entryId:'table',type:'table',name:'明细'}],filters:[{name:'地区',label:'地区',options:[{label:'西部',value:'West'}]}]};
+test('query sends scoped refer, cookie credentials and bounded pageLimit without browser token storage', async () => {
+  let sent;
+  const r = await queryWidgets(config, {'地区':'West'}, undefined, async (url, init) => {
+    sent = {url, ...init};
+    return new Response(JSON.stringify({success:true,data:{table:detail()}}));
+  });
+  assert.equal(sent.credentials,'include');
+  assert.equal(sent.headers['X-Requested-With'],'XMLHttpRequest');
+  assert.deepEqual(JSON.parse(sent.body).refer, {'地区':['West']});
+  assert.equal(JSON.parse(sent.body).pageLimit,1000);
+  assert.equal(sent.headers.Authorization,undefined);
+  assert.equal(r.table.datasets[0].returnedRowCount,1);
+  await assert.rejects(queryWidgets({...config,maxRows:10001},{},undefined,()=>{throw new Error('must not fetch');}), /maxRows/);
+  await assert.rejects(queryWidgets(config,{'未知':'x'}), /筛选/);
+});
+test('auth expiry, permission denial, login HTML and missing widget stay distinct from empty data', async () => {
+  for (const [response, code] of [[new Response('',{status:302,headers:{Location:'/login'}}),'AUTH_REQUIRED'],[new Response('',{status:401}),'AUTH_REQUIRED'],[new Response('',{status:403}),'PERMISSION_DENIED'],[new Response(JSON.stringify({errorCode:'TIME_OUT'})),'AUTH_REQUIRED'],[new Response('<html>login</html>',{headers:{'content-type':'text/html'}}),'AUTH_REQUIRED'],[new Response(JSON.stringify({success:true,data:{}})),'INVALID_RESPONSE']]) {
+    await assert.rejects(queryWidgets(config,{},undefined,async()=>response), e=>e instanceof FineBIError && e.code===code);
+  }
+});
+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);
+  assert.deepEqual(chartValues(selectDataset(r),{categoryFieldId:'x',valueFieldId:'y'}),[{name:'East',value:12},{name:'West',value:5}]);
+  assert.throws(()=>chartValues(selectDataset(r),{categoryFieldId:'x',valueFieldId:'missing'}),/字段/);
+  r.datasets.push({...r.datasets[0],id:'model1'});
+  assert.throws(()=>selectDataset(r),/模型/);
+  assert.equal(selectDataset(r,'model1').id,'model1');
+});
+test('date filters accept calendar dates without options and omit cleared dates', async () => {
+  const dateConfig = {...config, filters:[{name:'日期',label:'日期',type:'date'},...config.filters]};
+  let sent;
+  const fetchImpl=async (_url,init)=>{sent=JSON.parse(init.body);return new Response(JSON.stringify({success:true,data:{table:detail()}}));};
+  for (const value of ['2012-10-02','2024-02-29','0001-01-01','9999-12-31']) {
+    await queryWidgets(dateConfig,{'日期':value},undefined,fetchImpl);
+    assert.deepEqual(sent.refer,{'日期':[value]});
+  }
+  await queryWidgets(dateConfig,{'日期':''},undefined,fetchImpl);
+  assert.deepEqual(sent.refer,{});
+  for (const value of ['2023-02-29','2024-02-30','2024-04-31','0000-01-01','10000-01-01','2024-13-01','2024-1-01','2024-01-01T00:00:00Z']) {
+    await assert.rejects(queryWidgets(dateConfig,{'日期':value},undefined,()=>{assert.fail('invalid date must not be sent');}),/筛选/);
+  }
+  for (const filter of [{name:'日期',label:'日期',type:'date',options:[]},{name:'日期',label:'日期',type:'unknown'}]) {
+    await assert.rejects(queryWidgets({...config,filters:[filter]},{},undefined,()=>{assert.fail('invalid configuration must not be sent');}),/筛选/);
+  }
+});
+
+test('typed filters encode native multi-value, null and open date ranges without guessing', async () => {
+  const filters=[
+    {name:'文本',label:'文本',type:'text',allowNull:true},
+    {name:'多选',label:'多选',type:'multi-select',options:[{label:'东',value:'East'},{label:'西',value:'West'}]},
+    {name:'数值',label:'数值',type:'number'},
+    {name:'区间',label:'区间',type:'date-range'},
+    {name:'月份',label:'月份',type:'month-range'},
+    {name:'年',label:'年',type:'year'}, {name:'季',label:'季',type:'quarter'},
+    {name:'标签',label:'标签',type:'time-label',options:[{label:'本月',value:'本月,动态'}]},
+  ];
+  let sent;
+  const send=values=>queryWidgets({...config,filters},values,undefined,async (_url,init)=>{
+    sent=JSON.parse(init.body);return new Response(JSON.stringify({success:true,data:{table:detail()}}));
+  });
+  await send({'文本':' North ','多选':['East','West'],'数值':'12345678901234567890.25','区间':{start:'2024-02-29',end:'2024-03-01'},'月份':{start:'2024-01',end:''},'年':'2024','季':'2024-3','标签':'本月,动态'});
+  assert.deepEqual(sent.refer,{'文本':[' North '],'多选':['East,West'],'数值':['12345678901234567890.25'],'区间_s':['2024-02-29'],'区间_e':['2024-03-01'],'月份_s':['2024-01'],'年':['2024'],'季':['2024-3'],'标签':['本月,动态']});
+  await send({'文本':null,'多选':[],'区间':{start:'',end:''}});
+  assert.deepEqual(sent.refer,{'文本':['null']});
+  await send({}); assert.deepEqual(sent.refer,{});
+  for(const values of [{'文本':'A,B'},{'文本':'null'},{'多选':['East,West']},{'多选':['East','East']},{'多选':[null]},{'数值':'1e3'},{'区间':{start:'2024-03-02',end:'2024-03-01'}},{'区间':{start:'2024-02-30',end:''}},{'月份':{start:'2024-13',end:''}},{'年':'0000'},{'季':'2024-5'},{'标签':'未知'},{'区间':null},{'未知':''}]) {
+    await assert.rejects(send(values),/筛选/);
+  }
+});
+
+test('filter configuration rejects ambiguous native keys and unrepresentable choices before fetching',async()=>{
+  for(const filters of [
+    [{name:'范围',label:'范围',type:'date-range'},{name:'范围_s',label:'起始',type:'date'}],
+    [{name:'重复',label:'A',type:'text'},{name:'重复',label:'B',type:'date'}],
+    [{name:'x',label:'x',options:[{label:'逗号',value:'A,B'}]}],
+    [{name:'x',label:'x',options:[{label:'字面空值',value:'null'}]}],
+    [{name:'x',label:'x',type:'number-range'}],
+    [{name:'x',label:'x',type:'date',allowNull:true}],
+  ]) await assert.rejects(queryWidgets({...config,filters},{},undefined,()=>assert.fail('invalid config must not fetch')),/筛选/);
+});

package/templates/web-app/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "compilerOptions": {"target":"ES2020","lib":["ES2020","DOM","DOM.Iterable"],"module":"ESNext","moduleResolution":"Bundler","jsx":"react-jsx","strict":true,"skipLibCheck":true,"esModuleInterop":true,"resolveJsonModule":true,"isolatedModules":true,"noEmit":true},
+  "include":["src","vite.config.ts"]
+}

package/templates/web-app/vite.config.ts

@@ -0,0 +1,15 @@
+import {readFileSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {defineConfig, loadEnv} from 'vite';
+// @ts-expect-error The development-only Node module is tested directly with node:test.
+import {createDevMiddleware} from './scripts/dev-proxy.mjs';
+export default defineConfig(({mode}) => ({
+  base: './',
+  resolve:{alias:[{find:/^date-fns\/locale$/,replacement:fileURLToPath(new URL('./src/components/calendar-locales.ts',import.meta.url))}]},
+  server: {host:'127.0.0.1',port:4173,strictPort:true},
+  plugins:[{name:'finebi-development-session',apply:'serve',configureServer(server) {
+    const config=JSON.parse(readFileSync(new URL('./public/app-config.json',import.meta.url),'utf8'));
+    const env={...loadEnv(mode,process.cwd(),'FINEBI_DEV_'),...process.env};
+    server.middlewares.use(createDevMiddleware(config,env));
+  }}],
+}));