@finebi/finebi-cli 1.6.1 → 1.6.3

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/tests/table-normalize.test.mjs

@@ -0,0 +1,189 @@
+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-table-tests', server: {middlewareMode: true, hmr: false}});
+after(() => server.close());
+const {normalize} = await server.ssrLoadModule('/src/finebi/normalize.ts');
+const {DataTable} = await server.ssrLoadModule('/src/components/DataTable.tsx');
+const {tableCsv} = await server.ssrLoadModule('/src/services/table-data.ts');
+const metric = (text, rowSumInfo = {totalSum: false, innerSum: false}, extra = {}) => ({dId: 'amount', text, authority: true, rowSumInfo, ...extra});
+const group = items => ({previewResult: {resultType: 'BIGROUP', header: [{dId: 'region', text: '地区'}, {dId: 'city', text: '城市'}, {dId: 'amount', text: '金额'}], items, hasNext: true, hasPrev: false}, widgetBean: {dimensions: {region: {type: 1}, city: {type: 1}}, settings: {tableStyle: {rowCounts: 10}}}});
+const detailInfo = {totalSum: false, innerSum: false};
+const totalInfo = {totalSum: true, innerSum: false};
+const node = (dId, text, children = null, values = null) => ({dId, text, formatText: text, authority: true, children, values});
+const crossMetric = (text, colSumInfo = detailInfo, rowSumInfo = detailInfo, dId = 'amount') => ({dId, text, authority: true, colSumInfo, rowSumInfo});
+const cross = (top, left) => ({previewResult: {resultType: 'BICROSS', top: {header: [{dId: 'year', text: '年'}], items: [node(null, null, top)]}, left: {header: [{dId: 'region', text: '地区'}], items: [node(null, null, left)]}, hasXNext: true, hasXPrev: false, hasYNext: false, hasYPrev: false}});
+
+test('cross display removes only repeated metric captions and DATA summary carriers', () => {
+  const source = cross([node('region', '金额', [node('target-name', '金额', null, [node('amount', '金额')])])], [
+    node('region', '合计', [node('__summary_dim_id__', '合计', null, [crossMetric('1')])]),
+    node('__summary_dim_id__', '合计', null, [crossMetric('2', detailInfo, totalInfo)]),
+    node('__summary_dim_id__', '合计', null, [crossMetric('3', detailInfo, {totalSum: false, innerSum: true})]),
+    node('__summary_dim_id__', '合计', null, [{...crossMetric('4'), rowSumInfo: null}]),
+  ]);
+  const data = normalize(source).datasets[0];
+  assert.equal(data.columns[1].name, '金额 / 金额', 'real repeated grouping labels must remain');
+  assert.equal(data.columns[1].path.length, 3, 'source path metadata must remain intact');
+  assert.equal(data.rows[0].cells[0].display, '合计', 'business dimension named 合计 must remain');
+  assert.equal(data.rows[0].path.length, 2);
+  assert.deepEqual(data.rows.slice(1).map(row => [row.kind, row.cells[0].display]), [['GRAND_TOTAL', '合计'], ['SUBTOTAL', '合计'], ['UNKNOWN', '合计']]);
+});
+
+test('cross metric rows deduplicate only the verified trailing metric caption', () => {
+  const rows = [
+    node('region', '金额', [node('target-name', '金额', [node('amount', '金额', null, [crossMetric('7')])])]),
+    node('region', '金额', [node('other-dimension', '金额', null, [crossMetric('8')])]),
+    node('target-name', '金额', [node('amount', '别名', null, [crossMetric('9')])]),
+    node('target-name', '金额', [node('amount', '金额', null, [crossMetric('10', detailInfo, detailInfo, 'count')])]),
+  ];
+  const data = normalize(cross([node('year', '2024', null, [{}])], rows)).datasets[0];
+  assert.deepEqual(data.rows.map(r => r.cells[0].display), ['金额 / 金额', '金额 / 金额', '金额 / 别名', '金额 / 金额']);
+  assert.equal(data.rows[0].path.length, 3);
+  assert.equal(data.rows[0].cells[1].sourceFieldId, 'amount');
+  const html = renderToStaticMarkup(createElement(DataTable, {dataset: data, pageSize: 10, binding: {type: 'table'}}));
+  assert.doesNotMatch(html, /金额 \/ 金额 \/ 金额/);
+  assert.doesNotMatch(tableCsv(data, data.rows), /金额 \/ 金额 \/ 金额/);
+});
+
+test('cross real null renders as dash while placeholders, missing payload and permissions stay distinct', () => {
+  const empty = {...crossMetric(null), value: null, formatText: null};
+  const cells = [empty, {...empty, dId: null}, {...empty, authority: false}, {...empty, authority: undefined}, {dId: 'amount', authority: true}, {...empty, formatText: '仅展示'}];
+  const data = normalize(cross([node('year', '2024', null, cells.map(() => ({})))], [node('region', '东部', null, cells)])).datasets[0];
+  assert.deepEqual(data.rows[0].cells.slice(1).map(c => c.state), ['NULL', 'UNAVAILABLE', 'RESTRICTED', 'UNAVAILABLE', 'UNAVAILABLE', 'UNAVAILABLE']);
+  assert.equal(data.rows[0].cells[1].reason, null);
+  const html = renderToStaticMarkup(createElement(DataTable, {dataset: data, pageSize: 10, binding: {type: 'table'}}));
+  assert.match(html, /<td>—<\/td><td>不可用<\/td><td>受限<\/td>/);
+  assert.match(tableCsv(data, data.rows), /"—","不可用","受限"/);
+});
+
+test('cross placeholders without valid metric ids never become available numeric values', () => {
+  const cells = [null, undefined, '', ' ', 12].map(dId => ({...crossMetric('12'), dId, value: 12}));
+  const data = normalize(cross([node('year', '2024', null, cells.map(() => ({})))], [node('region', '东部', null, cells)])).datasets[0];
+  for (const cell of data.rows[0].cells.slice(1)) {
+    assert.equal(cell.state, 'UNAVAILABLE');
+    assert.equal(cell.value, null);
+    assert.equal(cell.sourceFieldId, null);
+  }
+});
+
+test('cross table aligns repeated metric ids by column slots and preserves both axes and totals', () => {
+  for (const totalFirst of [false, true]) {
+    const columns = [node('year', '2024', null, [node('amount', '金额')]), node('year', '2025', null, [node('amount', '金额')])];
+    const summary = node('__summary_dim_id__', '合计', [node('amount', '金额', null, [{}])]);
+    columns.splice(totalFirst ? 0 : columns.length, 0, summary);
+    const values = [crossMetric('9007199254740993.12'), crossMetric('2.50')];
+    values.splice(totalFirst ? 0 : values.length, 0, crossMetric('9007199254740995.62', totalInfo));
+    const source = cross(columns, [node('region', '东部', [node('__summary_dim_id__', null, null, values)]), node('__summary_dim_id__', '合计', [node('amount', '金额', null, values.map(v => ({...v, rowSumInfo: totalInfo})))])]);
+    const result = normalize(source), data = result.datasets[0];
+    assert.equal(result.resultType, 'CROSS_TABLE'); assert.equal(result.normalization, 'COMPLETE');
+    assert.deepEqual(data.rows[0].cells.slice(1).map(c => c.value), values.map(v => v.text));
+    assert.equal(new Set(data.columns.map(c => c.fieldId)).size, 4);
+    assert.equal(data.rows[0].cells[1].sourceFieldId, 'amount');
+    assert.deepEqual(data.rows.map(r => r.kind), ['DATA', 'GRAND_TOTAL']);
+    assert.equal(data.columns[totalFirst ? 1 : 3].kind, 'GRAND_TOTAL');
+    assert.equal(result.range.mode, 'INITIAL_VIEW'); assert.equal(result.range.page, null);
+    assert.deepEqual(result.range.axes, {horizontal: {hasNext: true, hasPrevious: false}, vertical: {hasNext: false, hasPrevious: false}});
+    assert.equal(result.range.hasNext, true); assert.ok(result.warnings.includes('NEXT_PAGE_UNSUPPORTED'));
+    const html = renderToStaticMarkup(createElement(DataTable, {dataset: data, pageSize: 10, binding: {type: 'table'}}));
+    assert.match(html, /2024/); assert.match(html, /2025/); assert.match(html, /总计/);
+    assert.match(tableCsv(data, data.rows), /9007199254740993.12/);
+    assert.equal(source.previewResult.top.items[0].children.length, 3);
+  }
+});
+
+test('cross table supports metrics on rows and multi-level columns without id joins', () => {
+  const source = cross([node('year', '2024', [node('quarter', 'Q1', null, []), node('quarter', 'Q2', null, [])])], [
+    node('region', '东部', [node('target-name', '金额', [node('amount', '金额', null, [crossMetric('12'), crossMetric('18')])]), node('target-name', '数量', [node('count', '数量', null, [crossMetric('3', detailInfo, detailInfo, 'count'), crossMetric('4', detailInfo, detailInfo, 'count')])])]),
+  ]);
+  const data = normalize(source).datasets[0];
+  assert.equal(data.columns.length, 3); assert.equal(data.rows.length, 2);
+  assert.match(data.columns[1].name, /2024.*Q1/);
+  assert.match(data.rows[1].cells[0].display, /东部.*数量/);
+  assert.deepEqual(data.rows[1].cells.slice(1).map(c => c.sourceFieldId), ['count', 'count']);
+});
+
+test('cross table never exposes restricted axis labels and retains missing/ambiguous value states', () => {
+  const secret = node('year', 'secret column', null, [{}]); secret.authority = false;
+  const row = node('region', 'secret row', null, [crossMetric('123')]); row.authority = false;
+  const result = normalize(cross([secret], [row]));
+  assert.doesNotMatch(JSON.stringify(result), /secret column|secret row/);
+  assert.equal(result.datasets[0].rows[0].cells[0].state, 'RESTRICTED');
+  assert.equal(result.datasets[0].rows[0].cells[1].state, 'RESTRICTED');
+  const source = cross([node('year', 'A', null, [{}, {}])], [node('region', 'X', null, [{...crossMetric('1万'), formatText: '1万'}])]);
+  const incomplete = normalize(source);
+  assert.equal(incomplete.normalization, 'PARTIAL');
+  assert.equal(incomplete.datasets[0].rows[0].cells[1].state, 'UNAVAILABLE');
+  assert.equal(incomplete.datasets[0].rows[0].cells[2].reason, 'MISSING_CELL');
+  source.previewResult.left.items[0].children[0].values.push(crossMetric('2'), crossMetric('3'));
+  assert.equal(normalize(source).normalization, 'UNSUPPORTED', 'extra values must not be silently dropped');
+});
+
+test('cross table distinguishes empty views, missing axes and unsupported mixed node topology', () => {
+  assert.equal(normalize(cross([], [])).normalization, 'COMPLETE');
+  assert.equal(normalize(cross([], [])).datasets[0].returnedRowCount, 0);
+  assert.equal(normalize({previewResult: {resultType: 'BICROSS', left: {header: [], items: []}}}).normalization, 'UNSUPPORTED');
+  assert.equal(normalize(cross([node('x', 'A', [node('x', 'B')], [{}])], [])).normalization, 'UNSUPPORTED');
+});
+
+test('cross table handles no column dimensions and preserves metric-name intersection placeholders', () => {
+  const source = cross([], [node('target', '金额', null, [crossMetric('7'), {dId: null, text: null, value: null, authority: true}])]);
+  source.previewResult.top = {header: [], items: []};
+  const result = normalize(source);
+  assert.equal(result.normalization, 'COMPLETE');
+  assert.deepEqual(result.datasets[0].rows[0].cells.slice(1).map(c => c.state), ['AVAILABLE', 'UNAVAILABLE']);
+  assert.equal(result.datasets[0].rows[0].cells[2].value, null);
+  const swapped = cross([node('year', '2024', null, [node('amount', '金额')])], [node('region', '东部', null, [crossMetric('1', detailInfo, detailInfo, 'count')])]);
+  assert.equal(normalize(swapped).normalization, 'PARTIAL');
+  assert.equal(normalize(swapped).datasets[0].rows[0].cells[1].reason, 'AMBIGUOUS_FIELD');
+});
+
+test('group preserves parent keys, totals, metric precision and the first group page', () => {
+  const source = group([{dId: 'region', text: '东部', authority: true, values: [metric('9007199254740993.12', {totalSum: false, innerSum: true})], children: [
+    {dId: 'city', text: '甲城', authority: true, values: [metric('12.50', undefined, {formatText: '12.50元'})]},
+  ]}, {values: [metric('9007199254741005.62', {totalSum: true, innerSum: false})]}]);
+  const result = normalize(source), data = result.datasets[0];
+  assert.equal(result.resultType, 'GROUP_TABLE');
+  assert.equal(result.normalization, 'COMPLETE');
+  assert.deepEqual(data.rows.map(r => r.kind), ['SUBTOTAL', 'DATA', 'GRAND_TOTAL']);
+  assert.deepEqual(data.rows[1].cells.map(c => c.value), ['东部', '甲城', '12.50']);
+  assert.equal(data.rows[0].cells[2].value, '9007199254740993.12');
+  assert.equal(data.returnedRowCount, 3);
+  assert.deepEqual(result.range, {mode: 'PAGE', page: 1, pageSize: 10, pageUnit: 'GROUP', hasNext: true, hasPrevious: false, total: {value: null, unit: 'GROUP'}});
+  assert.ok(result.warnings.includes('NEXT_PAGE_UNSUPPORTED'));
+  const html = renderToStaticMarkup(createElement(DataTable, {dataset: data, pageSize: 10, binding: {type: 'table'}}));
+  assert.match(html, /小计/); assert.match(html, /总计/);
+  assert.match(tableCsv(data, data.rows), /GRAND_TOTAL/);
+});
+
+test('group keeps restricted and ambiguous cells unavailable and does not infer numeric group keys', () => {
+  const source = group([{dId: 'region', text: '42', authority: true, values: [metric('12万', undefined, {formatText: '12万'})], children: [
+    {dId: 'city', text: '秘密', authority: false, values: [metric('999', undefined, {authority: false})]},
+    {dId: 'city', text: '乙城', authority: true, values: [metric('1'), metric('2')]},
+    {dId: 'city', text: '丙城', authority: true, values: [metric(null, null)]},
+  ]}]);
+  source.widgetBean.dimensions.region.type = 2;
+  const result = normalize(source), rows = result.datasets[0].rows;
+  assert.equal(rows[0].cells[0].reason, 'GROUP_KEY_SEMANTICS_UNKNOWN');
+  assert.equal(rows[0].cells[2].state, 'UNAVAILABLE');
+  assert.equal(rows[1].cells[1].state, 'RESTRICTED');
+  assert.equal(rows[1].cells[2].state, 'RESTRICTED');
+  assert.equal(rows[2].cells[2].reason, 'AMBIGUOUS_FIELD');
+  assert.equal(rows[3].cells[2].state, 'UNAVAILABLE');
+  assert.equal(rows[3].kind, 'UNKNOWN');
+  assert.equal(result.normalization, 'PARTIAL');
+});
+
+test('group header expansion reports an initial view and malformed groups are not empty successes', () => {
+  const source = group([]);
+  source.widgetBean.settings.tableStyle.showRowHeaderIcon = true;
+  const result = normalize(source);
+  assert.equal(result.range.mode, 'INITIAL_VIEW');
+  assert.equal(result.range.page, null);
+  assert.equal(result.range.hasNext, null);
+  assert.equal(result.datasets[0].returnedRowCount, 0);
+  assert.equal(normalize({previewResult: {resultType: 'BIGROUP'}}).normalization, 'UNSUPPORTED');
+  source.previewResult.items = [null, {dId: 'unknown', values: [metric('1')]}];
+  assert.equal(normalize(source).normalization, 'PARTIAL');
+});

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/tests/vite-auth.test.mjs

@@ -0,0 +1,41 @@
+import assert from 'node:assert/strict';
+import {test} from 'node:test';
+import {createServer as httpServer} from 'node:http';
+import {mkdir,mkdtemp,cp,writeFile,readFile} from 'node:fs/promises';
+import {resolve} from 'node:path';
+import {createServer} from 'vite';
+
+test('real Vite uses project env, persists sessions, blocks credential files and survives token updates',async()=>{
+  await mkdir('temp',{recursive:true});
+  const root=await mkdtemp(resolve('temp','vite-auth-'));
+  for(const name of ['vite.config.ts','scripts','src','public','index.html','package.json'])await cp(resolve(name),resolve(root,name),{recursive:true});
+  await mkdir(resolve(root,'temp'));
+  await writeFile(resolve(root,'temp','staged-session'),'staged-secret');
+  let logins=0,queries=0;
+  const upstream=httpServer(async(req,res)=>{
+    for await(const _ of req){};
+    res.setHeader('content-type','application/json');
+    if(req.url==='/decision/login'){logins++;res.end(JSON.stringify({data:{accessToken:'persisted-session'}}));return;}
+    assert.equal(req.headers.cookie,'fine_auth_token=persisted-session');queries++;
+    res.end(JSON.stringify({success:true,data:{}}));
+  });
+  await new Promise(r=>upstream.listen(0,'127.0.0.1',r));
+  const baseUrl=`http://127.0.0.1:${upstream.address().port}/decision`;
+  await writeFile(resolve(root,'.env.local'),`FINEBI_DEV_BASE_URL=${baseUrl}\nFINEBI_DEV_USERNAME=alice\nFINEBI_DEV_PASSWORD=password\n`);
+  await writeFile(resolve(root,'public','app-config.json'),JSON.stringify({basePath:'/decision',dashboardId:'r',widgets:[{entryId:'w'}],maxRows:10,filters:[]}));
+  const server=await createServer({root,configFile:resolve(root,'vite.config.ts'),cacheDir:resolve(root,'temp','cache'),server:{port:0},logLevel:'silent'});
+  try {
+    await server.listen();
+    const url=`http://127.0.0.1:${server.httpServer.address().port}`;
+    assert.equal((await fetch(url+'/')).status,200,'project under a temp parent must still serve its index');
+    assert.equal((await fetch(url+'/src/main.tsx')).status,200,'project source must remain loadable');
+    const send=()=>fetch(url+'/decision/v5/api/dashboard/report/r/widgets/query',{method:'POST',headers:{'Content-Type':'application/json','X-Requested-With':'XMLHttpRequest'},body:JSON.stringify({widgetIds:['w'],pageLimit:10})});
+    const result=await send();assert.equal(result.status,200);assert.doesNotMatch(await result.text(),/persisted-session|password/);
+    assert.match(await readFile(resolve(root,'.env.local'),'utf8'),/FINEBI_DEV_TOKEN="persisted-session"/);
+    assert.equal((await fetch(url+'/.env.local')).status,403);
+    assert.equal((await fetch(url+'/temp/staged-session')).status,403);
+    // Allow the file watcher to process the save; it must not restart the session manager.
+    await new Promise(r=>setTimeout(r,400));
+    assert.equal((await send()).status,200);assert.equal(logins,1);assert.equal(queries,2);
+  } finally {await server.close();await new Promise(r=>upstream.close(r));}
+});

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

@@ -1,15 +1,20 @@
 import {readFileSync} from 'node:fs';
+import {resolve} from 'node:path';
 import {fileURLToPath} from 'node:url';
-import {defineConfig, loadEnv} from 'vite';
+import {defineConfig, loadEnv, normalizePath} from 'vite';
 // @ts-expect-error The development-only Node module is tested directly with node:test.
 import {createDevMiddleware} from './scripts/dev-proxy.mjs';
+const projectTemp=normalizePath(fileURLToPath(new URL('./temp',import.meta.url)))+'/**';
 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},
+  server: {host:'127.0.0.1',port:4173,strictPort:true,watch:{ignored:['**/.env.local',projectTemp]},
+    fs:{deny:['.env','.env.*','*.{crt,pem}','**/.git/**',projectTemp]}},
   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));
+    const env={...loadEnv(mode,server.config.root,'FINEBI_DEV_'),...process.env};
+    const middleware=createDevMiddleware(config,env,fetch,{file:resolve(server.config.root,'.env.local')});
+    server.middlewares.use(middleware);
+    server.httpServer?.once('close',()=>middleware.dispose());
   }}],
 }));

package/src/app.js

@@ -40,6 +40,7 @@ export async function createApp(args, context = {}) {
   try {
     const templateRoot = context.templateRoot ? resolve(context.templateRoot) : TEMPLATE_ROOT;
     const templatePackage = JSON.parse(await readFile(resolve(templateRoot, "package.json"), "utf8"));
+    const gitignore = await readFile(resolve(templateRoot, "gitignore.template"), "utf8");
     const templateConfigPath = resolve(templateRoot, "public", "app-config.json");
     let config = {schemaVersion: "1", title: name, basePath: "/webroot/decision", layout: "overview", dashboardId: "", maxRows: 1000, pageSize: 8, widgets: [], filters: []};
     try {
@@ -53,6 +54,7 @@ export async function createApp(args, context = {}) {
       return invalid("app.create", error.code === "EEXIST" ? `Destination already exists: ${destination}` : `Cannot create destination: ${error.message}`);
     }
     await copyTemplateContents(templateRoot, destination);
+    await writeFile(resolve(destination, ".gitignore"), gitignore, "utf8");
     if(options.value.layout) config.layout=options.value.layout;
     if(config.layout==='cockpit') config.insights=true;
     await mkdir(resolve(destination, "public"), {recursive: true});
@@ -78,6 +80,7 @@ async function copyTemplateContents(sourceRoot, destinationRoot, relativeDirecto
   const destinationDirectory = resolve(destinationRoot, relativeDirectory);
   for (const entry of (await readdir(sourceDirectory, {withFileTypes: true})).sort((left, right) => left.name.localeCompare(right.name, "en"))) {
     const relativePath = `${relativeDirectory}/${entry.name}`.replace(/^\//u, "");
+    if (relativePath === ".gitignore" || relativePath === "gitignore.template") continue;
     if (!templatePathAllowed(relativePath)) continue;
     const sourcePath = resolve(sourceDirectory, entry.name);
     const destinationPath = resolve(destinationDirectory, entry.name);
@@ -111,16 +114,20 @@ async function inspectApp(args) {
     if (!(await stat(project)).isDirectory()) return invalid("app.inspect", "path must point to a project directory.");
     const configPath = resolve(project, "public", "app-config.json");
     const config = JSON.parse(await readFile(configPath, "utf8"));
-    const {configErrors}=await import('../templates/web-app/src/finebi/config.js');
-    const errors = configErrors(config);
-    if (errors.length) return failure("app.inspect", cliError("INVALID_ARGUMENT", {path: "public/app-config.json", message: errors.join(" ")}));
+    if (!config || typeof config !== "object" || Array.isArray(config)) return invalid("app.inspect", "app-config.json must contain a JSON object.");
+    if (options.value.strict) {
+      const {configErrors}=await import('../templates/web-app/src/finebi/config.js');
+      const errors = configErrors(config);
+      if (errors.length) return failure("app.inspect", cliError("INVALID_ARGUMENT", {path: "public/app-config.json", message: errors.join(" ")}));
+    }
     return success("app.inspect", {
       path: project,
-      dashboardId: config.dashboardId,
-      layout: config.layout,
+      dashboardId: config.dashboardId ?? null,
+      layout: config.layout ?? null,
       directoryEntryId: config.directoryEntryId || null,
-      widgets: config.widgets.length,
+      widgets: Array.isArray(config.widgets) ? config.widgets.length : null,
       templateVersion: config.templateVersion || null,
+      configValidated: options.value.strict === true,
       remoteValidated: false,
     });
   } catch (error) {
@@ -133,6 +140,11 @@ function parseOptions(args, command) {
   for (let index = 0; index < args.length; index++) {
     const option = args[index];
     if (option === "--json") continue;
+    if (option === "--strict" && command === "app.inspect") {
+      if (value.strict) return {ok: false, error: invalid(command, "--strict must only be supplied once.")};
+      value.strict = true;
+      continue;
+    }
     if (!["--name","--path",...(command==='app.create'?['--layout']:[])].includes(option)) return {ok: false, error: invalid(command, `Unsupported option: ${option}`)};
     const key = option.slice(2);
     const next = args[++index];

package/src/browser-auth.js

@@ -160,9 +160,8 @@ function abortedAuthorization() {
 function validateBaseUrl(value) {
   try {
     const url = new URL(value);
-    const localHttp = url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]", "::1"].includes(url.hostname.toLowerCase());
-    if (url.protocol !== "https:" && !localHttp) {
-      throw new Error("Browser authorization requires HTTPS, except for localhost development.");
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+      throw new Error("Browser authorization requires an HTTP or HTTPS URL.");
     }
     if (url.username || url.password || url.search || url.hash) {
       throw new Error("Browser authorization base URL must not contain credentials, a query, or a fragment.");
@@ -172,7 +171,7 @@ function validateBaseUrl(value) {
     return failure("auth.login", cliError("BROWSER_AUTH_URL_INVALID", {
       path: "baseUrl",
       message: error instanceof Error ? error.message : String(error),
-      nextActions: ["finebi-cli config set base-url <https-url>"],
+      nextActions: ["finebi-cli config set base-url <http-or-https-url>"],
     }));
   }
 }

package/src/config.js

@@ -8,7 +8,7 @@ import {CLI_CONFIG_DIRECTORY} from "./branding.js";
 import {maskSecret} from "./output.js";
 
 export const DEFAULT_TIMEOUT_MS = 30000;
-export const DEFAULT_CAPABILITY_TTL_MS = 600000;
+export const DEFAULT_CAPABILITY_TTL_MS = 20 * 60 * 60 * 1000;
 
 export function defaultConfigPath(env = process.env) {
   const home = env.USERPROFILE || env.HOME || homedir();

package/src/error-catalog.js

@@ -19,8 +19,8 @@ export const ERROR_CATALOG = [
         recoverableByAgent: true,
         defaultRetryable: false,
         pathSemantics: "Browser authorization base URL",
-        canonicalNextActions: ["finebi-cli config set base-url <https-url>"],
-        expectedAgentBehaviors: ["configure an HTTPS URL or localhost HTTP URL", "rerun browser login"],
+        canonicalNextActions: ["finebi-cli config set base-url <http-or-https-url>"],
+        expectedAgentBehaviors: ["configure an HTTP or HTTPS URL", "rerun browser login"],
         benchmarkTags: ["auth", "browser", "url-validation"],
     },
     {

package/src/help.js

@@ -116,10 +116,13 @@ const BUILT_IN_RESOURCES = {
       },
       {
         name: "inspect",
-        summary: "Check a local web app project configuration without remote validation.",
-        usage: "finebi-cli app inspect --path <project>",
-        options: [{name: "--path", type: "string", description: "Existing project directory; relative paths resolve from the current directory."}],
-        details: ["Checks app-config.json structure and widget bindings locally. Remote dashboard and permission checks are not performed."],
+        summary: "Summarize a local web app configuration; optionally validate against the bundled template.",
+        usage: "finebi-cli app inspect --path <project> [--strict]",
+        options: [
+          {name: "--path", type: "string", description: "Existing project directory; relative paths resolve from the current directory."},
+          {name: "--strict", type: "boolean", description: "Validate against this CLI's bundled template rules; custom app extensions may not match."},
+        ],
+        details: ["By default, reads app-config.json as a JSON object and reports a summary with configValidated: false. --strict enables local template validation. Neither mode validates remote resources or permissions; inspection is not an application acceptance gate."],
       },
     ],
   },
@@ -171,7 +174,7 @@ const BUILT_IN_RESOURCES = {
         examples: [
           "finebi-cli config set base-url http://localhost:37799/webroot/decision",
           "finebi-cli config set timeout-ms 30000",
-          "finebi-cli config set capability-ttl-ms 600000",
+          "finebi-cli config set capability-ttl-ms 72000000",
         ],
       },
       {

package/templates/web-app/AGENTS.md

@@ -3,17 +3,30 @@
 ## 开发顺序
 
 1. 用 FineBI CLI 搜索并读取 dashboard info/data，确认唯一来源、看板实例 entryId、queryFields.dId 和真实控件 filterName。按[验收文档](docs/acceptance.md#1-绑定与设计准备)记录指标公式/聚合、单位、时间粒度与时区、筛选作用范围及数据完整性；必要时读取 bean，未知项明确标记，不按组件标题猜语义。
-2. 阅读 [数据契约](docs/data-contract.md)、[筛选](docs/filters.md)、[认证部署](docs/auth-and-deploy.md)，再修改 public/app-config.json。
+2. 按下方[阅读路径](#阅读路径)读取当前步骤需要的章节，再修改 public/app-config.json；不要求开场通读全部文档。
 3. 按[设计选择](docs/design.md#设计选择与信息组织)写出页面面向谁、首屏重点、导航、图表分组和信息密度，遵循用户已确认的方向继续开发。新风格说明与已有布局在结构、层级和视觉上的区别。从 overview、workbench、cockpit 或 retail 起步，示例配置仅含占位绑定。
-4. 先跑通一个指标、一张图和一个真实控件（源看板有控件时）的查询、展示、应用与恢复默认，再扩展整页。使用真实接口开发；合成样本仅用于 tests，禁止将开发查询数据写入正式页面、配置或回退数据。
+4. 整页绑定前，按[最小真实查询](docs/acceptance.md#11-最小真实查询)先配置一个组件，启动开发页面，通过开发代理确认真实身份、查询、解析和页面值；再补齐本页需要的指标、图表与真实筛选链路，通过后扩展整页。使用真实接口开发；合成样本仅用于 tests，禁止将开发查询数据写入正式页面、配置或回退数据。
 5. 业务转换放 src/services，页面放 src/pages 或 App.tsx，通用请求与原生解析复用 src/finebi。改动共享组件时检查其他布局，不为换风格复制查询、认证或筛选编码。
 6. 按[分层验收](docs/acceptance.md)执行 npm test、npm run build、浏览器冒烟及真实绑定验收。检查整页和关键状态，分别记录 CLI、开发身份、生产 Cookie 的验证结论；构建成功不等于认证、取数或视觉验收通过。
 
+## 阅读路径
+
+首次进入项目先读本文件、[数据契约](docs/data-contract.md)和[绑定与设计准备](docs/acceptance.md#1-绑定与设计准备)。其余文档在对应步骤读取，同一任务中已读且未变化的章节直接复用。
+
+| 当前步骤 | 阅读内容 |
+|---|---|
+| 配置并启动最小真实查询 | [README 开始](README.md#开始)、[本地开发认证](docs/auth-and-deploy.md#本地开发)、[最小真实查询](docs/acceptance.md#11-最小真实查询) |
+| 绑定真实筛选控件 | [筛选与联动](docs/filters.md)中对应控件类型、作用范围、应用与恢复默认的规则；无控件时无需预读 |
+| 确定页面结构、配置展示或扩展 UI | [设计选择与信息组织](docs/design.md#设计选择与信息组织)及本次布局、展示能力对应章节 |
+| 执行整页验收与交付 | [开发与验收](docs/acceptance.md)第 2–5 节 |
+| 部署或验证生产身份 | [生产认证与部署](docs/auth-and-deploy.md#生产) |
+
 ## 数据规则
 
-- 用 CLI 指定 `--dimension-ids` 时，必须同时列出需要的维度和指标；只传维度会关闭未选指标。模板目前不提供字段选择配置，浏览器查询沿用保存配置；完整语义见[数据契约](docs/data-contract.md#字段选择)。
+- `widgets[].dimensionIds` 为可选字段，常规绑定省略以沿用保存配置；需要指定时列出所需维度和指标的完整白名单，只传维度会关闭未选指标。与 CLI `--dimension-ids` 使用同一来源的可选 dId，完整语义见[数据契约](docs/data-contract.md#字段选择)。
 - 先检查 normalization、warnings、range，再选择唯一 dataset；多模型需显式 datasetId。
 - display 用于显示；计算仅使用 AVAILABLE 的 value，保留 DECIMAL_STRING 精度。禁止从百分比/千分位/单位文本恢复数值。受限值、未知值不能补零。
+- 分组表 BIGROUP 使用 table 展示，按原生汇总标记区分数据、小计和总计；不能混加各类行。交叉表 BICROSS 按 top 槽位对应 left 数值，仅用 table 展示当前矩阵，不能按重复的指标 dId 合并列或固定绑定跨查询槽位。详见 docs/data-contract.md。
 - 不按名称猜字段、不累加 UNKNOWN 行、不从首页估算全量 KPI。KPI 示例仅消费单行结果。
 - 控件筛选通过真实名称生成 refer；无控件时不伪造服务端过滤。搜索和排序的范围必须在页面说明。
 - 筛选绑定先核对源控件类型，配置/状态/请求统一通过 src/finebi/filters.js 校验。完整支持矩阵、逗号和 null 保留字、恢复默认与筛选空值语义见 docs/filters.md；不以更换 type 绕过服务端能力限制。
@@ -21,9 +34,9 @@
 
 ## 认证与交付
 
-- 开发凭证只存在服务端环境 FINEBI_DEV_* 或内存；禁止 VITE_* 凭证、前端 localStorage token、提交 .env 和认证日志。
+- 开发凭证由 Node 从 FINEBI_DEV_* 环境或项目 .env.local 读取；新会话自动保存到 .env.local。优先复用 token，获取时密码优先、浏览器授权兜底，具体流程见 docs/auth-and-deploy.md。禁止 VITE_* 凭证、前端 localStorage token、提交凭据文件和认证秘密日志。
 - 生产应用使用同源当前用户 Cookie。开发代理不属于构建产物；不要把它部署为共享多用户服务。
-- 目录来源配置 directoryEntryId，原生请求保留 reportEntryId；需目标平台 HTTP 接口支持目录权限预检与 MOUNT 查询，不得失败后回退到分析主题。不支持交叉表、服务端续页、全局排序或托管发布命令。
+- 目录来源配置 directoryEntryId，原生请求保留 reportEntryId；需目标平台 HTTP 接口支持目录权限预检与 MOUNT 查询，不得失败后回退到分析主题。不支持服务端续页、全局排序或托管发布命令。
 - 图表按生命周期销毁；异步请求取消且旧响应不得覆盖新条件。失败状态不得展示过期数据充当最新结果。
 - 验收证据、截图和临时脚本放项目 temp/，不随包发布。交付记录已验证/失败/未验证项、运行方式、模板版本和业务绑定范围；模板维护流程由 CLI 源仓库负责，本项目无需其脚本才能开发和验收。
 

package/templates/web-app/README.md

@@ -4,14 +4,19 @@
 
 ## 开始
 
+按 [Agent 阅读路径](AGENTS.md#阅读路径)分阶段读取文档，再执行以下步骤。
+
 1. 安装依赖：`npm ci`。
-2. 填写 `public/app-config.json`。`dashboardId` 来自目标看板；`widgets[].entryId` 使用板内实例 ID；图表 `categoryFieldId/valueFieldId` 使用本次 `dashboard info` 的结果字段 dId。相同实例可以有不同展示，但 KPI 必须对应单行查询结果。
-3. 在当前进程设置 `FINEBI_DEV_BASE_URL`（完整 decision 地址）和 `FINEBI_DEV_USERNAME/FINEBI_DEV_PASSWORD`，或 `FINEBI_DEV_TOKEN`。不要把值写入 VITE_* 或 app-config。
-4. `npm run dev`，访问 `http://localhost:4173`。开发代理仅监听本机，自动以开发身份登录，凭证不返回浏览器。
-5. 按[开发与验收](docs/acceptance.md)执行 `npm test`、`npm run build`、`npm run test:browser`，再验证真实绑定。浏览器验收页使用合成数据，不连接 FineBI。`npm run preview` 只展示 dist，不启用开发身份代理；真实生产取数需要同源 FineBI 路径。
+2. 先在 `public/app-config.json` 中填写一个真实组件的最小绑定。`dashboardId` 来自目标看板；`widgets[].entryId` 使用板内实例 ID；图表 `categoryFieldId/valueFieldId` 使用本次 `dashboard info` 的结果字段 dId。相同实例可以有不同展示，但 KPI 必须对应单行查询结果。
+3. 在项目 `.env.local` 设置 `FINEBI_DEV_BASE_URL`（完整 decision 地址）；有账密时填写 `FINEBI_DEV_USERNAME/FINEBI_DEV_PASSWORD`，只有 SSO 时省略。也可提供已有的 FineBI 会话 `FINEBI_DEV_TOKEN`，不能使用 CLI Access Key。不要把值写入 VITE_* 或 app-config。
+4. `npm run dev`，访问 `http://localhost:4173`。代理优先复用 token，再尝试密码，最后按终端提示进行浏览器授权。新 token 自动保存到 `.env.local`；过期后恢复并重试一次。浏览器授权的服务端插件和 HTTPS 要求见 [认证与部署](docs/auth-and-deploy.md)。
+5. 按[最小真实查询](docs/acceptance.md#11-最小真实查询)核对实际请求与页面值，补齐适用的代表性图表和筛选链路，通过后再扩展整页。
+6. 按[开发与验收](docs/acceptance.md)执行 `npm test`、`npm run build`、`npm run test:browser`，并完成整页真实绑定验收。浏览器验收页使用合成数据，不连接 FineBI。`npm run preview` 只展示 dist，不启用开发身份代理；真实生产取数需要同源 FineBI 路径。
 
 ## 配置
 
+`widgets[].dimensionIds` 可选，常规绑定省略以沿用组件保存配置。需要指定维度和指标时填写完整白名单，`[]` 会关闭全部可选字段；示例、代理校验与同实例多绑定规则见[字段选择](docs/data-contract.md#字段选择)。
+
 `layout` 为 `overview`（顶部概览）、`workbench`（侧栏工作台）、`cockpit`（绿色经营驾驶舱）或 `retail`（米白经营简报）。可用 `finebi-cli app create --name my-retail --path <parent> --layout retail` 创建；默认配置仍为空绑定，不会请求示例资源。`maxRows` 默认 1000，上限 10000；`pageSize` 是本地展示页大小，1–100。
 
 ```json
@@ -31,6 +36,8 @@ cockpit 的配置骨架在 [examples/cockpit.config.json](examples/cockpit.confi
 
 retail 的 [examples/retail.config.json](examples/retail.config.json) 提供零售分析绑定骨架：四项 KPI、趋势、门店 TOP10、区域/品类、门店类型和明细。采用横向导航、米白背景和蓝橙图表，不依赖侧栏。示例不含业务数据，`REPLACE_*`、模型选择、时区及筛选作用范围必须核实替换；普通分析来源需删除目录入口占位字段。金额与百分比、毫秒月份的显式显示配置见[页面骨架](docs/design.md)。
 
+分组表 BIGROUP 可使用 `type: "table"` 展示，保留分组键及小计、总计行；字段和值状态、首页范围见[数据契约](docs/data-contract.md#分组表)。交叉表 BICROSS 同样绑定为 `type: "table"`，按行列分组路径显示当前矩阵；通常省略 tableFieldIds，以保留随查询变化的全部交叉列。它不提供服务端翻页、节点展开或原生合并单元格，字段和双轴范围见[交叉表契约](docs/data-contract.md#交叉表)。
+
 目录发布看板在配置中增加 `directoryEntryId`，使用与该入口匹配的 dashboardId/实例。模板将其原样作为 `reportEntryId` 传给 Cookie 查询接口及开发代理；目标平台需同时支持目录权限预检和 MOUNT 查询，不能只支持 CLI 目录查询。错误独立显示，不回退“我的分析”。
 
-筛选先编辑、再点击“应用筛选”；“恢复全部默认”重新查询看板保存条件。模板支持文本、单选/多选、数值选择和日期类控件，完整类型、空值语义与配置示例以[筛选契约](docs/filters.md)为准；`app inspect` 仅检查本地配置，绑定后仍需验证真实条件生效。
+筛选先编辑、再点击“应用筛选”；“恢复全部默认”重新查询看板保存条件。模板支持文本、单选/多选、数值选择和日期类控件，完整类型、空值语义与配置示例以[筛选契约](docs/filters.md)为准；`app inspect` 默认只查看配置摘要；可选 `--strict` 检查与 CLI 内置模板规则的兼容性，不作为定制应用验收门禁。绑定后仍需通过项目测试、构建与真实浏览器验证条件生效。

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

@@ -10,12 +10,25 @@
 |---|---|
 | 来源 | CLI profile、目标地址、dashboardId、目录入口或分析主题；板内实例 entryId |
 | 字段与指标 | queryFields.dId、选定 datasetId、维度/指标、公式或聚合、单位；记录数不能自动解释为去重对象数 |
+| 字段选择 | 常规绑定省略 dimensionIds；配置时核对完整白名单与输出列，分别验证省略、维度加指标、仅指标和空列表；同实例不同展示绑定分别核对请求 |
 | 时间 | 时间粒度、原值编码、显示时区；日期条件与时间戳轴标签分开核实 |
 | 筛选 | 真实控件名、类型、默认行为、候选项来源、组件作用范围；无源控件时不添加服务端筛选 |
 | 范围 | 返回行数、hasNext、normalization、warnings；不根据首页推算全量 |
 | 设计 | 使用者和主要决策、首屏重点、导航/分组/密度，与既有布局的区别 |
 
-先完成一个指标、一张图，以及存在时的一个真实筛选：源结果 → 页面值 → 应用条件 → 恢复保存默认。证据不足时说明未知项，继续不依赖该项的工作。
+清单先覆盖最小绑定，扩展组件时逐项补齐；不必先完成整板配置。证据不足时说明未知项，继续不依赖该项的工作。
+
+### 1.1 最小真实查询
+
+在配置整页组件之前，先验证开发页面的真实取数链路：
+
+1. 用同一来源的 CLI info/data 选择一个模板支持且有可核对数据的组件，例如单行 KPI；检查 resultType、normalization、warnings、range 和结果字段，不按标题或 chartType 判断可用性。CLI 查询成功仅用于准备绑定，不能证明浏览器适配和开发身份可用。
+2. 在 public/app-config.json 中只填写该组件的真实绑定及必要配置；目录来源保留 directoryEntryId，需要字段选择时保留相同 dimensionIds。不要先复制整页占位组件，也不为测试凭空创建源指标或控件。
+3. 按 [README 开始](../README.md#开始)安装依赖、配置开发身份并运行 npm run dev。打开实际应用，通过开发代理触发原生查询；优先复用已有会话，需要登录时遵循[本地开发认证](auth-and-deploy.md#本地开发)，不要把 CLI Access Key 当作会话 token，也不要在已有会话可用时重复索要密码。
+4. 核对请求来源和参数、业务响应、适配状态与页面显示值。单凭 HTTP 200、CLI 成功或合成验收页 PASS 不算通过；空结果只能证明当前空态，需另选有可核对数据的组件或条件验证值的消费。脱敏证据放项目 temp/，不得记录凭证。
+5. 该组件通过后，按本页需求补齐一个指标和一张图的代表性绑定；源中不存在或本页不需要的类型注明不适用。有真实筛选时验证“源结果 → 页面值 → 应用条件 → 恢复保存默认”，确认请求及显示与条件一致。完成这些适用检查后再扩展整页，并继续验证新增绑定。
+
+身份、权限、接口或适配失败时，记录失败层与原因，先解决当前链路再扩大绑定；缺少访问条件时可继续不依赖真实数据的设计工作，但真实查询须标记未验证。开发身份通过不代表生产 Cookie 验证通过，身份边界见第 4 节。
 
 ## 2. 本地自动检查
 

package/templates/web-app/docs/auth-and-deploy.md

@@ -2,9 +2,24 @@
 
 ## 本地开发
 
-Vite开发插件读取服务端环境 `FINEBI_DEV_BASE_URL`、`FINEBI_DEV_USERNAME/FINEBI_DEV_PASSWORD`，或已有短期 `FINEBI_DEV_TOKEN`。BASE_URL必须是目标完整decision地址。支持由本地.env.local提供，禁止提交文件；不要使用VITE_前缀。
+Vite开发插件读取项目 `.env.local` 或进程环境中的 `FINEBI_DEV_BASE_URL`（完整 decision 地址），可选 `FINEBI_DEV_USERNAME/FINEBI_DEV_PASSWORD` 和已有 FineBI 会话 `FINEBI_DEV_TOKEN`。进程环境优先；不要使用 `VITE_` 前缀，不要把 CLI Access Key 填入 TOKEN。
 
-代理在内存保存开发会话，只接受本机同源、带XMLHttpRequest标记的POST；白名单限制为配置看板及组件查询，不代理登录管理或任意接口。浏览器无需持有开发账号凭证。失效返回AUTH_REQUIRED；密码方式下一次显式重试重新登录，token方式需更新token并重启开发服务。不要向他人开放开发服务端口。
+```dotenv
+FINEBI_DEV_BASE_URL=https://bi.example/webroot/decision
+# 有用户名密码时填写；只有 SSO 时省略这两项。
+FINEBI_DEV_USERNAME=your-user
+FINEBI_DEV_PASSWORD=your-password
+```
+
+首次查询按以下顺序认证：复用有效 token；需要登录时先尝试配置的用户名密码；没有完整账密或密码明确被拒绝时，终端显示浏览器授权链接和确认码，并尝试打开浏览器。先通过客户原 FineBI/SSO 入口登录，再打开授权链接核对账号与确认码。开发进程主动轮询领取会话，不要求 FineBI 服务器连接本机，也不改变 SSO 回跳地址。
+
+浏览器授权要求服务端插件提供 `/api/bi-cli/dev-session-auth/*`，使用 HTTPS（仅回环允许 HTTP）。旧插件返回 `AUTH_PLUGIN_REQUIRED`，应更新插件；密码路径不依赖新增端点。客户端终端只显示授权地址、确认码、账号与状态，不显示密码或 token。
+
+新会话写入 `.env.local` 的 `FINEBI_DEV_TOKEN`、`FINEBI_DEV_TOKEN_BASE_URL`、`FINEBI_DEV_TOKEN_USERNAME`；保留其他配置，缺少 BASE_URL 时补入本次地址。保存的 token 与目标地址绑定，切换地址不复用旧 token。文件写入先限制权限（POSIX 0600；Windows 当前用户、SYSTEM、Administrators），失败返回 `AUTH_STORAGE_FAILED`。文件禁止提交或随包发布。token 只由 Node 读取；授权交出的是真实会话权限，并非仅限本应用看板。
+
+明确过期时清除保存的旧 token，按上述顺序恢复，再重试原查询一次。并发请求共享认证；旧请求不能清除新会话。再次失效、授权拒绝或超时后返回 `AUTH_REQUIRED`，用户处理后点击重试。密码明确拒绝后本次运行不重复尝试；网络故障、上游 5xx、查询 403 不触发浏览器授权。认证文件保存会更新内存，不需要重启；手动修改地址或账密配置后需重启开发服务。若进程环境还设置了旧 TOKEN，它会覆盖文件，重新启动前应移除该覆盖。
+
+代理只接受本机同源、带 XMLHttpRequest 标记的 POST；白名单限制为配置看板及组件查询，不向浏览器开放登录管理或任意接口。不要向他人开放开发服务端口。Vite 禁止访问 `.env*` 和 `temp/`，关闭服务会取消待完成的授权。会话有效期由 FineBI 决定；SSO 的 IP/终端/附加 Cookie 约束、退出登录行为及多节点部署需在客户环境验证，自动化测试不等于所有 SSO 已兼容。
 
 代理使用共享筛选校验器校验配置与 refer，类型、编码、候选值和默认语义统一见[筛选契约](filters.md)，不维护独立编码规则。