@finebi/finebi-cli 1.6.0 → 1.6.2

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

@@ -1,77 +1,235 @@
-import type {Cell, Column, Dataset, QueryResult} from './types';
-
-// Native preview JSON is deliberately confined to this boundary.
-type Native = Record<string, any>;
-const unavailable = (reason: string, display: string | null = null): Cell => ({value: null, display, state: 'UNAVAILABLE', reason});
-const text = (value: unknown): string | null => typeof value === 'string' ? value : null;
-const column = (id: string, name: string, index: number, type: Column['type']): Column => ({key: `c${index}`, fieldId: id, name, type, encoding: ({STRING: 'STRING', DECIMAL: 'DECIMAL_STRING', DATE: 'EPOCH_MILLIS_STRING', UNKNOWN: null})[type]});
-const warn = (r: QueryResult, message: string) => {if (!r.warnings.includes(message)) r.warnings.push(message);};
-const partial = (r: QueryResult, message: string) => {r.normalization = 'PARTIAL'; warn(r, message);};
-
-function value(raw: unknown, display: string | null, authority: unknown, type: Column['type']): Cell {
-  if (authority === false) return {value: null, display, state: 'RESTRICTED', reason: 'SOURCE_VALUE_RESTRICTED'};
-  if (authority !== true) return unavailable('AUTHORITY_UNAVAILABLE', display);
-  if (raw == null) return display === null ? {value: null, display: null, state: 'NULL', reason: null} : unavailable('DISPLAY_ONLY', display);
-  if (type === 'STRING' && typeof raw === 'string') return {value: raw, display, state: 'AVAILABLE', reason: null};
-  if (type === 'DATE') {
-    const s = String(raw);
-    if ((typeof raw === 'string' || typeof raw === 'number' && Number.isSafeInteger(raw)) && /^[+-]?\d+$/.test(s)) {
-      const n = BigInt(s);
-      if (n >= -9223372036854775808n && n <= 9223372036854775807n) return {value: s, display, state: 'AVAILABLE', reason: null};
-    }
-    return unavailable('INVALID_TIMESTAMP_VALUE', display);
-  }
-  if (type === 'DECIMAL' && (typeof raw === 'string' || typeof raw === 'number')) {
-    if (typeof raw === 'number' && (!Number.isFinite(raw) || Number.isInteger(raw) && !Number.isSafeInteger(raw))) return unavailable('UNSAFE_NUMERIC_VALUE', display);
-    if (/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(String(raw))) return {value: String(raw), display, state: 'AVAILABLE', reason: null};
-  }
-  return unavailable(type === 'UNKNOWN' ? 'TYPE_UNAVAILABLE' : 'DISPLAY_ONLY', display);
-}
-
-export function normalize(source: Native): QueryResult {
-  const p = source?.previewResult;
-  const r: QueryResult = {schemaVersion: '1', resultType: 'UNKNOWN', normalization: 'COMPLETE', datasets: [], warnings: [], range: {mode: 'UNKNOWN', page: null, pageSize: null, pageUnit: null, hasNext: null, hasPrevious: null, total: {value: null, unit: null}}};
-  if (p?.resultType === 'DETAIL' && Array.isArray(p.header) && Array.isArray(p.items)) {
-    r.resultType = 'DETAIL_TABLE';
-    r.range = {mode: 'PAGE', page: 1, pageSize: Number.isSafeInteger(p.size) ? p.size : null, pageUnit: 'ROW', hasNext: typeof p.hasNext === 'boolean' ? p.hasNext : null, hasPrevious: typeof p.hasPrev === 'boolean' ? p.hasPrev : null, total: {value: Number.isSafeInteger(p.row) && p.row >= 0 ? p.row : null, unit: 'DETAIL_ROW'}};
-    const dataset: Dataset = {id: 'main', columns: p.header.map((h: Native, i: number) => column(h.dId, h.text, i, detailType(source.widgetBean?.dimensions?.[h.dId]?.type))), rows: [], returnedRowCount: p.items.length};
-    for (const row of p.items) {
-      if (!Array.isArray(row) || row.length !== dataset.columns.length) partial(r, 'ROW_WIDTH_MISMATCH');
-      dataset.rows.push({kind: 'DATA', cells: dataset.columns.map((c, i) => {
-        const cell = row?.[i];
-        if (!cell || typeof cell !== 'object' || cell.dId && cell.dId !== c.fieldId) {partial(r, 'ROW_FIELD_MISMATCH'); return unavailable('MISSING_CELL');}
-        return value(cell.value, text(cell.formatText) ?? text(cell.text), cell.authority, c.type);
-      })});
-    }
-    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 === 'CHART') {
-    r.resultType = 'CHART'; r.range.mode = 'UNPAGED';
-    const models: Native[] = [];
-    for (const geom of p.geoms || []) {
-      if (geom?.dataModel) models.push(geom.dataModel); else partial(r, 'GEOMETRY_WITHOUT_INLINE_DATA');
-    }
-    if (p.shared?.data) models.push(p.shared.data);
-    if (p.computedState) partial(r, 'CHART_COMPUTED_STATE_NOT_NORMALIZED');
-    for (const model of new Set(models)) {
-      if (!Array.isArray(model.fields) || !Array.isArray(model.colData) || !Number.isSafeInteger(model.rowCount) || model.rowCount < 0) {partial(r, 'INVALID_CHART_MODEL'); continue;}
-      const dataset: Dataset = {id: `model${r.datasets.length}`, columns: model.fields.map((f: Native, i: number) => column(f.id, f.name, i, f.fieldType === 'MEASURE' ? 'DECIMAL' : f.fieldType === 'DIMENSION' ? 'STRING' : 'UNKNOWN')), rows: [], returnedRowCount: model.rowCount};
-      if (model.colData.length !== model.fields.length || model.colData.some((c: unknown[]) => !Array.isArray(c) || c.length !== model.rowCount)) partial(r, 'ROW_WIDTH_MISMATCH');
-      for (let i = 0; i < model.rowCount; i++) dataset.rows.push({kind: 'UNKNOWN', cells: dataset.columns.map((c, j) => {
-        if (!Array.isArray(model.colData[j]) || i >= model.colData[j].length) return unavailable('MISSING_CELL');
-        const raw = model.colData[j][i];
-        if (raw === '***') return {value: null, display: '***', state: 'RESTRICTED', reason: 'SOURCE_VALUE_RESTRICTED'};
-        if (c.type === 'DECIMAL' && typeof raw === 'string') return unavailable('CHART_VALUE_SEMANTICS_UNKNOWN');
-        return value(raw, c.type === 'STRING' ? text(raw) : null, true, c.type);
-      })});
-      r.datasets.push(dataset);
-    }
-    if (!r.datasets.length) {r.normalization = 'UNSUPPORTED'; warn(r, 'NO_INLINE_CHART_DATA');}
-  } else {r.normalization = 'UNSUPPORTED'; warn(r, 'RESULT_TYPE_UNSUPPORTED');}
-  return r;
-}
-
-function detailType(type: number): Column['type'] {
-  return type === 1 ? 'STRING' : type === 2 ? 'DECIMAL' : [3,13,15,20].includes(type) ? 'DATE' : 'UNKNOWN';
-}
+import type {AxisLabel, Cell, Column, Dataset, QueryResult, RowKind} from './types';
+
+// Native preview JSON is deliberately confined to this boundary.
+type Native = Record<string, any>;
+const unavailable = (reason: string, display: string | null = null): Cell => ({value: null, display, state: 'UNAVAILABLE', reason});
+const text = (value: unknown): string | null => typeof value === 'string' ? value : null;
+const column = (id: string, name: string, index: number, type: Column['type']): Column => ({key: `c${index}`, fieldId: id, name, type, encoding: ({STRING: 'STRING', DECIMAL: 'DECIMAL_STRING', DATE: 'EPOCH_MILLIS_STRING', UNKNOWN: null})[type]});
+const warn = (r: QueryResult, message: string) => {if (!r.warnings.includes(message)) r.warnings.push(message);};
+const partial = (r: QueryResult, message: string) => {r.normalization = 'PARTIAL'; warn(r, message);};
+
+function value(raw: unknown, display: string | null, authority: unknown, type: Column['type']): Cell {
+  if (authority === false) return {value: null, display, state: 'RESTRICTED', reason: 'SOURCE_VALUE_RESTRICTED'};
+  if (authority !== true) return unavailable('AUTHORITY_UNAVAILABLE', display);
+  if (raw == null) return display === null ? {value: null, display: null, state: 'NULL', reason: null} : unavailable('DISPLAY_ONLY', display);
+  if (type === 'STRING' && typeof raw === 'string') return {value: raw, display, state: 'AVAILABLE', reason: null};
+  if (type === 'DATE') {
+    const s = String(raw);
+    if ((typeof raw === 'string' || typeof raw === 'number' && Number.isSafeInteger(raw)) && /^[+-]?\d+$/.test(s)) {
+      const n = BigInt(s);
+      if (n >= -9223372036854775808n && n <= 9223372036854775807n) return {value: s, display, state: 'AVAILABLE', reason: null};
+    }
+    return unavailable('INVALID_TIMESTAMP_VALUE', display);
+  }
+  if (type === 'DECIMAL' && (typeof raw === 'string' || typeof raw === 'number')) {
+    if (typeof raw === 'number' && (!Number.isFinite(raw) || Number.isInteger(raw) && !Number.isSafeInteger(raw))) return unavailable('UNSAFE_NUMERIC_VALUE', display);
+    if (/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(String(raw))) return {value: String(raw), display, state: 'AVAILABLE', reason: null};
+  }
+  return unavailable(type === 'UNKNOWN' ? 'TYPE_UNAVAILABLE' : 'DISPLAY_ONLY', display);
+}
+
+export function normalize(source: Native): QueryResult {
+  const p = source?.previewResult;
+  const r: QueryResult = {schemaVersion: '1', resultType: 'UNKNOWN', normalization: 'COMPLETE', datasets: [], warnings: [], range: {mode: 'UNKNOWN', page: null, pageSize: null, pageUnit: null, hasNext: null, hasPrevious: null, total: {value: null, unit: null}}};
+  if (p?.resultType === 'DETAIL' && Array.isArray(p.header) && Array.isArray(p.items)) {
+    r.resultType = 'DETAIL_TABLE';
+    r.range = {mode: 'PAGE', page: 1, pageSize: Number.isSafeInteger(p.size) ? p.size : null, pageUnit: 'ROW', hasNext: typeof p.hasNext === 'boolean' ? p.hasNext : null, hasPrevious: typeof p.hasPrev === 'boolean' ? p.hasPrev : null, total: {value: Number.isSafeInteger(p.row) && p.row >= 0 ? p.row : null, unit: 'DETAIL_ROW'}};
+    const dataset: Dataset = {id: 'main', columns: p.header.map((h: Native, i: number) => column(h.dId, h.text, i, detailType(source.widgetBean?.dimensions?.[h.dId]?.type))), rows: [], returnedRowCount: p.items.length};
+    for (const row of p.items) {
+      if (!Array.isArray(row) || row.length !== dataset.columns.length) partial(r, 'ROW_WIDTH_MISMATCH');
+      dataset.rows.push({kind: 'DATA', cells: dataset.columns.map((c, i) => {
+        const cell = row?.[i];
+        if (!cell || typeof cell !== 'object' || cell.dId && cell.dId !== c.fieldId) {partial(r, 'ROW_FIELD_MISMATCH'); return unavailable('MISSING_CELL');}
+        return value(cell.value, text(cell.formatText) ?? text(cell.text), cell.authority, c.type);
+      })});
+    }
+    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[] = [];
+    for (const geom of p.geoms || []) {
+      if (geom?.dataModel) models.push(geom.dataModel); else partial(r, 'GEOMETRY_WITHOUT_INLINE_DATA');
+    }
+    if (p.shared?.data) models.push(p.shared.data);
+    if (p.computedState) partial(r, 'CHART_COMPUTED_STATE_NOT_NORMALIZED');
+    for (const model of new Set(models)) {
+      if (!Array.isArray(model.fields) || !Array.isArray(model.colData) || !Number.isSafeInteger(model.rowCount) || model.rowCount < 0) {partial(r, 'INVALID_CHART_MODEL'); continue;}
+      const dataset: Dataset = {id: `model${r.datasets.length}`, columns: model.fields.map((f: Native, i: number) => column(f.id, f.name, i, f.fieldType === 'MEASURE' ? 'DECIMAL' : f.fieldType === 'DIMENSION' ? 'STRING' : 'UNKNOWN')), rows: [], returnedRowCount: model.rowCount};
+      if (model.colData.length !== model.fields.length || model.colData.some((c: unknown[]) => !Array.isArray(c) || c.length !== model.rowCount)) partial(r, 'ROW_WIDTH_MISMATCH');
+      for (let i = 0; i < model.rowCount; i++) dataset.rows.push({kind: 'UNKNOWN', cells: dataset.columns.map((c, j) => {
+        if (!Array.isArray(model.colData[j]) || i >= model.colData[j].length) return unavailable('MISSING_CELL');
+        const raw = model.colData[j][i];
+        if (raw === '***') return {value: null, display: '***', state: 'RESTRICTED', reason: 'SOURCE_VALUE_RESTRICTED'};
+        if (c.type === 'DECIMAL' && typeof raw === 'string') return unavailable('CHART_VALUE_SEMANTICS_UNKNOWN');
+        return value(raw, c.type === 'STRING' ? text(raw) : null, true, c.type);
+      })});
+      r.datasets.push(dataset);
+    }
+    if (!r.datasets.length) {r.normalization = 'UNSUPPORTED'; warn(r, 'NO_INLINE_CHART_DATA');}
+  } else {r.normalization = 'UNSUPPORTED'; warn(r, 'RESULT_TYPE_UNSUPPORTED');}
+  return r;
+}
+
+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,18 +1,20 @@
-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 QueryResult = {
-  schemaVersion: '1'; resultType: 'DETAIL_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}};
-};
-export type WidgetBinding = {entryId: string; name: string; type: 'table' | 'bar' | 'line' | 'pie' | 'kpi'; datasetId?: string; categoryFieldId?: string; valueFieldId?: 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}
-  | {type?: 'select' | 'multi-select'; options: {label: string; value: string}[]; allowNull?: boolean}
-  | {type: 'time-label'; options: {label: string; value: string}[]; allowNull?: never}
-);
-export type FilterValue = string | string[] | {start:string;end:string} | null | undefined;
-export type FilterState = Record<string,FilterValue>;
-export type AppConfig = {schemaVersion: '1'; title: string; basePath: string; layout: 'overview' | 'workbench'; dashboardId: string; maxRows: number; pageSize: number; widgets: WidgetBinding[]; filters: FilterBinding[]};
+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' | 'GROUP_TABLE' | 'CROSS_TABLE' | 'CHART' | 'UNKNOWN';
+  normalization: 'COMPLETE' | 'PARTIAL' | 'UNSUPPORTED'; datasets: Dataset[]; warnings: string[];
+  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; 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}
+  | {type?: 'select' | 'multi-select'; options: {label: string; value: string}[]; allowNull?: boolean}
+  | {type: 'time-label'; options: {label: string; value: string}[]; allowNull?: never}
+);
+export type FilterValue = string | string[] | {start:string;end:string} | null | undefined;
+export type FilterState = Record<string,FilterValue>;
+export type AppConfig = {schemaVersion: '1'; title: string; description?:string; basePath: string; layout: 'overview' | 'workbench' | 'cockpit' | 'retail'; dashboardId: string; directoryEntryId?:string; insights?:boolean; dataNotes?:string[]; maxRows: number; pageSize: number; widgets: WidgetBinding[]; filters: FilterBinding[]};

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

@@ -1,5 +1,5 @@
-import React from 'react';
-import {createRoot} from 'react-dom/client';
-import App from './App';
-import './styles.css';
-createRoot(document.getElementById('root')!).render(<React.StrictMode><App/></React.StrictMode>);
+import React from 'react';
+import {createRoot} from 'react-dom/client';
+import App from './App';
+import './styles.css';
+createRoot(document.getElementById('root')!).render(<React.StrictMode><App/></React.StrictMode>);

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/src/retail.css

@@ -0,0 +1,13 @@
+.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[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}
+.retail .kpi-grid{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:0;border:1px solid #d6d3ca;border-radius:8px;overflow:hidden;background:#fffefb}.retail .kpi-grid .panel{border:0;border-right:1px solid #dedbd3;border-radius:0;background:transparent;padding:23px 25px 18px;display:flex;flex-direction:column;position:relative}.retail .kpi-grid .panel:last-child{border-right:0}.retail .kpi-grid .panel:first-child{background:#eaeefb}.retail .kpi-grid .panel-heading{display:block}.retail .kpi-grid h2{font-size:13px;font-weight:550;margin-bottom:12px}.retail .kpi-grid .component-status{font-size:10px;color:#878b90}.retail .kpi{font-size:clamp(25px,2.45vw,39px);font-weight:600;font-variant-numeric:tabular-nums;letter-spacing:-1.5px;color:#252a34;order:1;margin:10px 0 6px}.retail .kpi-grid .panel:first-child .kpi{color:#3158d5}.retail .kpi-grid .muted{order:2;font-size:11px;margin:2px 0;min-height:32px}.retail .kpi-grid .query-details{order:3}.retail .kpi-grid .notice{order:4}
+.retail .grid{gap:20px;grid-template-columns:repeat(2,minmax(0,1fr))}.retail .grid .panel{border:1px solid #dedbd3;border-radius:8px;padding:26px;background:#fffefb;box-shadow:none}.retail .panel-heading{display:flex;justify-content:space-between;align-items:baseline;gap:14px}.retail .panel-heading h2{font-size:16px;font-weight:600;letter-spacing:-.3px;margin-bottom:6px}.retail .component-status{color:#898d88;font-size:10px;white-space:nowrap}.retail .component-status.failed{color:#a74632}.retail .grid .muted{font-size:11px;margin:6px 0 10px}.retail .query-details{font-size:10px;color:#91938c;margin:8px 0}.retail .query-details summary{display:inline-block}.retail .notice{font-size:11px;background:#f9f2e4;border-color:#d9ae66;padding:8px 11px;border-radius:2px;color:#857044}.retail .notice details{font-size:10px;margin:2px 0;color:inherit}.retail .series-controls{display:flex;gap:18px;flex-wrap:wrap;font-size:12px;margin:16px 0}.retail .series-controls input{accent-color:#3158d5;margin-right:6px}.retail .chart-sort{font-size:10px;margin:10px 0}.retail .chart-sort select{border-color:#e4e2da;background:#fffefb;font-size:10px;padding:4px 8px}.retail .chart{height:310px}.retail details{font-size:11px}.retail .data-notes{border-top:1px solid #d6d3ca;padding-top:22px;margin-top:30px;line-height:1.9;color:#737870}.retail .data-notes>summary{font-size:13px;color:#404740;font-weight:600}.retail th{background:#f3f2ec;color:#525954;font-size:11px}.retail td{border-color:#ebe9e1;font-size:12px}.retail tbody tr:hover{background:#f6f7fc}.retail .table-tools{font-size:12px;flex-wrap:wrap}.retail .table-tools input{max-width:100%}.retail footer{font-size:10px;color:#8b8d85;text-align:center;letter-spacing:.5px}
+@media(max-width:1000px){.retail main{padding:30px 24px}.retail-nav{padding:0 24px}.retail .kpi-grid{grid-template-columns:repeat(2,minmax(0,1fr))}.retail .kpi-grid .panel{border-bottom:1px solid #dedbd3}.retail .kpi-grid .panel:nth-child(2n){border-right:0}.retail .kpi-grid .panel:nth-last-child(-n+2){border-bottom:0}.retail header{align-items:flex-start}.retail h1{font-size:29px}.retail .header-actions{flex-direction:column;gap:10px;align-items:flex-end}}
+@media(max-width:700px){.retail main{padding:24px 16px}.retail-nav{height:auto;min-height:68px;padding:16px;flex-wrap:wrap;gap:16px}.retail-nav>div{order:3;width:100%;justify-content:space-between;gap:12px;font-size:12px}.retail .retail-brand{font-size:14px}.retail h1{font-size:26px}.retail header{display:block}.retail .header-actions{flex-direction:row;justify-content:flex-end;margin-top:16px}.retail .grid{grid-template-columns:1fr}.retail .grid .panel{padding:20px 16px}.retail .kpi-grid .panel{padding:18px 15px}.retail .kpi{font-size:26px;letter-spacing:-1px}.retail .section-heading{gap:10px;flex-wrap:wrap;margin-top:28px}.retail .section-heading p{width:100%;margin:0}.retail .section-heading>span{font-size:9px}.retail .panel-heading{display:block}.retail .chart{height:285px}.retail .filter-card{padding:18px 16px}.retail .filter-bottom{align-items:stretch;flex-direction:column}.retail .filter-buttons{justify-content:flex-end}.retail .filter-buttons .ant-btn{font-size:12px}.retail .pager{gap:8px;flex-wrap:wrap;font-size:11px}}
+@media(min-width:900px){.retail .filter-card{display:grid;grid-template-columns:minmax(0,1fr) auto;column-gap:32px;align-items:start}.retail .filter-heading{grid-column:1/-1;margin-bottom:12px}.retail .filter-fields{width:min(100%,640px)}.retail .filter-bottom{border:0;padding:26px 0 0;margin:0;flex-direction:column;align-items:flex-end;gap:8px}.retail .filter-bottom>p{order:2;font-size:10px}.retail .filter-fields:has(>.filter-field:only-child){max-width:640px}}
+@media(max-width:700px){.retail :is(#dashboard,#components,#data-notes){scroll-margin-top:128px}}

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

@@ -0,0 +1,36 @@
+import type {Cell,WidgetBinding} from '../finebi/types';
+import {displayCell} from './view-data';
+
+// Decimal strings stay strings/integers: formatting a large amount must not lose cents.
+export function formatMetric(cell:Cell,format?:WidgetBinding['valueFormat']):string {
+  if(!format||cell.state!=='AVAILABLE'||cell.value===null)return displayCell(cell);
+  const match=/^(-?)(\d+)(?:\.(\d+))?(?:e([+-]?\d+))?$/i.exec(cell.value);
+  if(!match)return displayCell(cell);
+  const exponent=Number(match[4]??0),fraction=match[3]??'';
+  if(Math.abs(exponent)>100)return displayCell(cell);
+  let digits=(match[2]+fraction).replace(/^0+(?=\d)/,'');
+  let scale=fraction.length-exponent;
+  if(format==='percent') {
+    scale-=2;
+    const shift=2-scale;
+    let amount=BigInt(digits);
+    if(shift>=0)amount*=10n**BigInt(shift);
+    else {const divisor=10n**BigInt(-shift);amount=(amount+divisor/2n)/divisor;}
+    digits=amount.toString();scale=2;
+  }
+  if(scale<0){digits+='0'.repeat(-scale);scale=0;}
+  digits=digits.padStart(scale+1,'0');
+  const whole=(scale?digits.slice(0,-scale):digits).replace(/\B(?=(\d{3})+(?!\d))/g,',');
+  const tail=scale?digits.slice(-scale):'';
+  const decimal=format==='percent'?tail:tail.replace(/0+$/,'');
+  const sign=match[1]&&/[1-9]/.test(digits)?'-':'';
+  return `${sign}${whole}${decimal?'.'+decimal:''}${format==='percent'?'%':''}`;
+}
+
+export function formatCategory(cell:Cell,binding:Pick<WidgetBinding,'categoryFormat'|'categoryTimeZone'>):string {
+  if(binding.categoryFormat!=='epoch-month'||!binding.categoryTimeZone||cell.state!=='AVAILABLE'||!cell.value||! /^-?\d+$/.test(cell.value))return displayCell(cell);
+  const timestamp=Number(cell.value);
+  if(!Number.isSafeInteger(timestamp)||!Number.isFinite(new Date(timestamp).getTime()))return displayCell(cell);
+  const parts=new Intl.DateTimeFormat('en',{year:'numeric',month:'2-digit',timeZone:binding.categoryTimeZone}).formatToParts(new Date(timestamp));
+  return `${parts.find(p=>p.type==='year')!.value}-${parts.find(p=>p.type==='month')!.value}`;
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/src/services/table-data.ts

@@ -0,0 +1,47 @@
+import type {Cell,Dataset,WidgetBinding} from '../finebi/types';
+import {displayCell} from './view-data';
+function decimal(value:string) {
+  const match=/^([+-]?)(\d*\.?\d+|\d+\.)(?:e([+-]?\d+))?$/i.exec(value);
+  if(!match)throw new Error('无效十进制值');
+  const [whole,fraction='']=match[2].split('.');
+  const digits=(whole+fraction).replace(/^0+/,'').replace(/0+$/,'');
+  const significant=(whole+fraction).replace(/^0+/,'');
+  return {sign:!digits?0:match[1]==='-'?-1:1,digits,order:BigInt(significant.length)+BigInt(match[3]||0)-BigInt(fraction.length)};
+}
+export function compareDecimal(a:string,b:string) {
+  const x=decimal(a),y=decimal(b);
+  if(x.sign!==y.sign)return x.sign<y.sign?-1:1;
+  if(x.sign===0)return 0;
+  const length=Math.max(x.digits.length,y.digits.length);
+  const left=x.digits.padEnd(length,'0'),right=y.digits.padEnd(length,'0');
+  const order=x.order!==y.order?(x.order<y.order?-1:1):left===right?0:left<right?-1:1;
+  return order===0?0:order*x.sign;
+}
+export function tableDataset(dataset:Dataset,binding:WidgetBinding):Dataset {
+  if(!binding.tableFieldIds)return dataset;
+  const indices=binding.tableFieldIds.map(id=>fieldIndex(dataset,id));
+  return {...dataset,columns:indices.map(i=>dataset.columns[i]),rows:dataset.rows.map(row=>({...row,cells:indices.map(i=>row.cells[i])}))};
+}
+export function fieldIndex(dataset:Dataset,id:string) {
+  const index=dataset.columns.findIndex(c=>c.fieldId===id);
+  if(index<0)throw new Error(`结果字段绑定缺失：${id}`);
+  return index;
+}
+type Options={search:string;sort?:{fieldId:string;direction:'asc'|'desc'};filters:Record<string,string>};
+export function tableRows(dataset:Dataset,{search,sort,filters}:Options) {
+  const columns=Object.entries(filters).map(([id,value])=>({index:fieldIndex(dataset,id),value}));
+  const rows=dataset.rows.filter(row=>row.cells.some(c=>displayCell(c).toLocaleLowerCase().includes(search.toLocaleLowerCase()))&&columns.every(({index,value})=>!value||displayCell(row.cells[index])===value));
+  if(!sort)return rows;
+  const index=fieldIndex(dataset,sort.fieldId),numeric=dataset.columns[index].type==='DECIMAL';
+  return [...rows].sort((a,b)=>{
+    const x=a.cells[index],y=b.cells[index];
+    const valid=(c:Cell)=>c.state==='AVAILABLE'&&c.value!==null;
+    if(!valid(x)||!valid(y))return valid(x)?-1:valid(y)?1:0;
+    const order=numeric?compareDecimal(x.value!,y.value!):displayCell(x).localeCompare(displayCell(y),'zh-CN');
+    return sort.direction==='asc'?order:-order;
+  });
+}
+export function tableCsv(dataset:Dataset,rows:Dataset['rows']) {
+  const escape=(value:string)=>`"${(/^[\s]*[=+\-@]/.test(value)?"'"+value:value).replace(/"/g,'""')}"`;
+  return '\uFEFF'+[[...dataset.columns.map(c=>c.name),'行类型'],...rows.map(row=>[...row.cells.map(displayCell),row.kind])].map(row=>row.map(escape).join(',')).join('\r\n');
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/src/services/view-data.ts

@@ -1,18 +1,18 @@
-import type {Cell, Dataset, QueryResult, WidgetBinding} from '../finebi/types';
-export function selectDataset(result: QueryResult, id?: string): Dataset {
-  if (result.normalization === 'UNSUPPORTED') throw new Error('当前结果类型尚未支持，请使用 FineBI 原生查看页');
-  const dataset = id ? result.datasets.find(d => d.id === id) : result.datasets.length === 1 ? result.datasets[0] : undefined;
-  if (!dataset) throw new Error('请绑定唯一的数据模型 datasetId');
-  return dataset;
-}
-export const displayCell = (cell: Cell) => cell.state === 'RESTRICTED' ? '受限' : cell.display ?? (cell.state === 'AVAILABLE' ? cell.value : null) ?? (cell.state === 'NULL' ? '—' : '不可用');
-export function chartValues(dataset: Dataset, binding: Pick<WidgetBinding, 'categoryFieldId' | 'valueFieldId'>) {
-  const x = dataset.columns.findIndex(c => c.fieldId === binding.categoryFieldId);
-  const y = dataset.columns.findIndex(c => c.fieldId === binding.valueFieldId);
-  if (x < 0 || y < 0 || dataset.columns[y].type !== 'DECIMAL') throw new Error('图表字段绑定缺失或类型不匹配');
-  return dataset.rows.map(row => {
-    const cell = row.cells[y];
-    const n = cell.state === 'AVAILABLE' ? Number(cell.value) : NaN;
-    return {name: displayCell(row.cells[x]), value: Number.isFinite(n) ? n : null};
-  });
-}
+import type {Cell, Dataset, QueryResult, WidgetBinding} from '../finebi/types';
+export function selectDataset(result: QueryResult, id?: string): Dataset {
+  if (result.normalization === 'UNSUPPORTED') throw new Error('当前结果类型尚未支持，请使用 FineBI 原生查看页');
+  const dataset = id ? result.datasets.find(d => d.id === id) : result.datasets.length === 1 ? result.datasets[0] : undefined;
+  if (!dataset) throw new Error('请绑定唯一的数据模型 datasetId');
+  return dataset;
+}
+export const displayCell = (cell: Cell) => cell.state === 'RESTRICTED' ? '受限' : cell.display ?? (cell.state === 'AVAILABLE' ? cell.value : null) ?? (cell.state === 'NULL' ? '—' : '不可用');
+export function chartValues(dataset: Dataset, binding: Pick<WidgetBinding, 'categoryFieldId' | 'valueFieldId'>) {
+  const x = dataset.columns.findIndex(c => c.fieldId === binding.categoryFieldId);
+  const y = dataset.columns.findIndex(c => c.fieldId === binding.valueFieldId);
+  if (x < 0 || y < 0 || dataset.columns[y].type !== 'DECIMAL') throw new Error('图表字段绑定缺失或类型不匹配');
+  return dataset.rows.map(row => {
+    const cell = row.cells[y];
+    const n = cell.state === 'AVAILABLE' ? Number(cell.value) : NaN;
+    return {name: displayCell(row.cells[x]), value: Number.isFinite(n) ? n : null};
+  });
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/src/services/widget-queries.ts

@@ -0,0 +1,18 @@
+import {queryWidget} from '../finebi/client';
+import type {AppConfig,FilterState,QueryResult,WidgetBinding} from '../finebi/types';
+export type WidgetState={loading:boolean;result?:QueryResult;error?:Error;at?:string};
+export const widgetKey=(binding:WidgetBinding,index:number)=>`${index}:${binding.entryId}`;
+export async function loadWidgets(config:AppConfig,filters:FilterState,signal:AbortSignal,onState:(id:string,state:WidgetState)=>void,fetchImpl:typeof fetch=fetch) {
+  const queue=config.widgets.map((binding,index)=>({binding,key:widgetKey(binding,index)}));
+  const worker=async()=>{
+    while(queue.length&&!signal.aborted) {
+      const {binding,key}=queue.shift()!;
+      onState(key,{loading:true});
+      try {
+        const result=await queryWidget(config,binding,filters,signal,fetchImpl);
+        if(!signal.aborted)onState(key,{loading:false,result,at:new Date().toLocaleTimeString()});
+      } catch(error) {if(!signal.aborted)onState(key,{loading:false,error:error instanceof Error?error:new Error('查询失败')});}
+    }
+  };
+  await Promise.all(Array.from({length:Math.min(3,queue.length)},worker));
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/tests/browser/fixtures.mjs

@@ -0,0 +1,28 @@
+// Synthetic native responses, confined to the browser acceptance page.
+export function fixtureConfig(layout, chartCount = 8) {
+  return {schemaVersion: '1', title: '合成门店经营验证', basePath: '/fixture-decision', layout,
+    dashboardId: 'fixture-dashboard', directoryEntryId: 'fixture-directory', maxRows: 1000, pageSize: 8,
+    filters: [{name: '区域', label: '区域', type: 'text'}], widgets: [
+      ...Array.from({length: 4}, (_, i) => ({entryId: `kpi${i}`, name: i === 3 ? '独立范围指标' : `合成指标 ${i + 1}`,
+        type: 'kpi', valueFieldId: 'amount', valueFormat: 'number', filterNames: i === 3 ? [] : ['区域']})),
+      ...Array.from({length: chartCount}, (_, i) => ({entryId: `chart${i}`, name: `${['趋势','对比','构成'][i % 3]} ${i + 1} · 较长标题用于检查文字换行和布局边界`,
+        type: ['line','bar','pie'][i % 3], categoryFieldId: 'region', valueFieldId: 'amount', filterNames: ['区域']})),
+      {entryId: 'table', name: '合成明细', type: 'table', filterNames: ['区域']},
+    ]};
+}
+
+export function nativeFixture(id, refer, scenario) {
+  const filtered = refer['区域']?.[0] === '华东';
+  const kpi = id.startsWith('kpi');
+  const headers = kpi ? [{dId: 'amount', text: '金额'}] : [{dId: 'region', text: '区域'}, {dId: 'amount', text: '金额'}];
+  const cell = (value, authority = true) => ({value, authority});
+  let rows = kpi ? [[cell(filtered ? '120' : '260')]]
+    : (filtered ? [['华东','120']] : [['华东','120'],['华北','80'],['华南','60']]).map(([region, amount]) => [cell(region), cell(amount)]);
+  if (!filtered && id === 'chart0') rows = [[cell('华东'),cell('120')],[cell('华北'),cell(null)],[cell('华南'),cell('-20')]];
+  if (!filtered && id === 'table') rows[1][1] = cell('hidden', false);
+  if (scenario === 'empty') rows = [];
+  const partial = scenario === 'partial' && id === 'chart0';
+  if (partial) rows[1] = [cell('华北')];
+  return {previewResult: {resultType: 'DETAIL', header: headers, items: rows, row: partial ? 30 : rows.length,
+    size: 1000, hasNext: partial}, widgetBean: {dimensions: {region: {type: 1}, amount: {type: 2}}}};
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/tests/browser/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>FineBI 模板浏览器验收</title></head>
+<body>
+  <section id="browser-checks" aria-label="浏览器验收">
+    <h1>模板浏览器验收 · 合成数据</h1>
+    <p>复用实际页面组件，不连接 FineBI。调整浏览器视口后重新运行；真实身份、业务口径与视觉质量需另外核对。</p>
+    <label>测试布局 <select id="test-layout"><option>overview</option><option>workbench</option><option>cockpit</option><option selected>retail</option></select></label>
+    <button id="test-run">运行浏览器检查</button>
+    <strong id="test-result" role="status">未运行</strong>
+    <ol id="test-checks"></ol>
+  </section>
+  <div id="root"></div>
+  <script type="module" src="./main.tsx"></script>
+</body>
+</html>