@veltra/sheet 2.0.1 → 2.2.0

package/src/report/__test__/binding.test.ts

@@ -0,0 +1,218 @@
+import type { CellAddress } from '@veltra/sheet-core'
+import { describe, expect, it } from 'vitest'
+
+import {
+  applyReportPreset,
+  createReportBinding,
+  formatBindingPlaceholder,
+  formatCellAddress,
+  inferDropPreset,
+  inferReportPreset,
+  isExpansionBandRow,
+  parseCellAddress,
+  presetBindingPatch,
+  setBindingCatalog
+} from '../binding'
+import type { DatasetCatalogItem, ReportBinding } from '../types'
+
+/** 内联 catalog fixture（单一事实源在测试自身，不依赖 playground mock） */
+const ORDERS_DATASET: DatasetCatalogItem = {
+  id: 'orders',
+  label: '销售明细',
+  fields: [
+    { name: 'customer', label: '客户', type: 'string' },
+    { name: 'orderNo', label: '订单号', type: 'string' },
+    { name: 'region', label: '地区', type: 'string' },
+    { name: 'amount', label: '金额', type: 'number' },
+    { name: 'orderDate', label: '下单日期', type: 'date' }
+  ]
+}
+
+setBindingCatalog([ORDERS_DATASET])
+
+describe('report binding', () => {
+  it('createReportBinding 默认 list + 纵向扩展 + 明细预设', () => {
+    const binding = createReportBinding(ORDERS_DATASET, 'amount')
+    expect(binding).toEqual({
+      dataset: 'orders',
+      field: 'amount',
+      aggregate: 'list',
+      expand: 'down',
+      preset: 'detail',
+      sort: 'none',
+      conditionalRules: []
+    })
+  })
+
+  it('formatBindingPlaceholder 中文标签（含 list / max / min）', () => {
+    expect(formatBindingPlaceholder(createReportBinding(ORDERS_DATASET, 'amount'))).toBe(
+      '明细 · 金额'
+    )
+
+    const group = createReportBinding(ORDERS_DATASET, 'customer')
+    group.aggregate = 'group'
+    expect(formatBindingPlaceholder(group)).toBe('分组 · 客户')
+
+    const sum = createReportBinding(ORDERS_DATASET, 'amount')
+    sum.aggregate = 'sum'
+    sum.expand = 'none'
+    expect(formatBindingPlaceholder(sum)).toBe('求和 · 金额')
+
+    const max = createReportBinding(ORDERS_DATASET, 'amount')
+    max.aggregate = 'max'
+    max.expand = 'none'
+    expect(formatBindingPlaceholder(max)).toBe('最大 · 金额')
+
+    const min = createReportBinding(ORDERS_DATASET, 'amount')
+    min.aggregate = 'min'
+    min.expand = 'none'
+    expect(formatBindingPlaceholder(min)).toBe('最小 · 金额')
+  })
+
+  it('presetBindingPatch / applyReportPreset 映射表', () => {
+    const rowParent = { row: 1, col: 0 }
+    const colParent = { row: 0, col: 1 }
+    const base: ReportBinding = {
+      dataset: 'orders',
+      field: 'amount',
+      expand: 'down',
+      aggregate: 'list',
+      rowParent,
+      colParent
+    }
+
+    expect(presetBindingPatch('groupHeader')).toEqual({
+      preset: 'groupHeader',
+      expand: 'down',
+      aggregate: 'group'
+    })
+    expect(presetBindingPatch('groupHeader', { transpose: true })).toMatchObject({
+      expand: 'right',
+      aggregate: 'group'
+    })
+
+    expect(presetBindingPatch('detail')).toEqual({
+      preset: 'detail',
+      expand: 'down',
+      aggregate: 'list'
+    })
+    expect(presetBindingPatch('detail', { transpose: true })).toMatchObject({
+      expand: 'right',
+      aggregate: 'list'
+    })
+
+    expect(presetBindingPatch('subtotal')).toEqual({
+      preset: 'subtotal',
+      expand: 'none',
+      aggregate: 'sum'
+    })
+    expect(applyReportPreset(base, 'subtotal').rowParent).toEqual(rowParent)
+
+    expect(presetBindingPatch('grandTotal')).toEqual({
+      preset: 'grandTotal',
+      expand: 'none',
+      aggregate: 'sum',
+      rowParent: undefined,
+      colParent: undefined
+    })
+    expect(applyReportPreset(base, 'grandTotal').rowParent).toBeUndefined()
+    expect(applyReportPreset(base, 'grandTotal').colParent).toBeUndefined()
+
+    expect(presetBindingPatch('cross')).toEqual({
+      preset: 'cross',
+      expand: 'none',
+      aggregate: 'sum'
+    })
+    expect(applyReportPreset(base, 'cross').rowParent).toEqual(rowParent)
+    expect(applyReportPreset(base, 'cross').colParent).toEqual(colParent)
+  })
+
+  it('inferReportPreset 从字段组合推断预设', () => {
+    expect(
+      inferReportPreset({
+        dataset: 'orders',
+        field: 'customer',
+        aggregate: 'group',
+        expand: 'down'
+      })
+    ).toBe('groupHeader')
+
+    expect(
+      inferReportPreset({
+        dataset: 'orders',
+        field: 'orderNo',
+        aggregate: 'list',
+        expand: 'down',
+        rowParent: { row: 1, col: 0 }
+      })
+    ).toBe('detail')
+
+    expect(
+      inferReportPreset({
+        dataset: 'orders',
+        field: 'amount',
+        aggregate: 'sum',
+        expand: 'none',
+        rowParent: { row: 1, col: 0 }
+      })
+    ).toBe('subtotal')
+
+    expect(
+      inferReportPreset({ dataset: 'orders', field: 'amount', aggregate: 'sum', expand: 'none' })
+    ).toBe('grandTotal')
+
+    expect(
+      inferReportPreset({
+        dataset: 'orders',
+        field: 'amount',
+        aggregate: 'sum',
+        expand: 'none',
+        rowParent: { row: 1, col: 0 },
+        colParent: { row: 0, col: 1 }
+      })
+    ).toBe('cross')
+
+    expect(
+      inferReportPreset({
+        dataset: 'orders',
+        field: 'amount',
+        aggregate: 'avg',
+        expand: 'none',
+        rowParent: { row: 1, col: 0 }
+      })
+    ).toBeNull()
+  })
+
+  it('inferDropPreset / isExpansionBandRow 落格推断', () => {
+    const groupAddr = { row: 1, col: 0 }
+    const group = createReportBinding(ORDERS_DATASET, 'customer')
+    group.aggregate = 'group'
+    group.expand = 'down'
+
+    const getBindingAt = (addr: CellAddress) => {
+      if (addr.row === groupAddr.row && addr.col === groupAddr.col) return group
+      return undefined
+    }
+
+    expect(isExpansionBandRow(1, getBindingAt)).toBe(true)
+    expect(isExpansionBandRow(0, getBindingAt)).toBe(false)
+    expect(inferDropPreset({ row: 2, col: 0 }, 'number', getBindingAt)).toBe('subtotal')
+    expect(inferDropPreset({ row: 2, col: 0 }, 'string', getBindingAt)).toBe('detail')
+  })
+
+  it('formatCellAddress / parseCellAddress 支持多字母列互逆', () => {
+    const single = { row: 2, col: 1 }
+    expect(formatCellAddress(single)).toBe('B3')
+    expect(parseCellAddress('B3')).toEqual(single)
+
+    const wide = { row: 0, col: 26 }
+    expect(formatCellAddress(wide)).toBe('AA1')
+    expect(parseCellAddress('AA1')).toEqual(wide)
+
+    const wider = { row: 99, col: 701 }
+    expect(formatCellAddress(wider)).toBe('ZZ100')
+    expect(parseCellAddress('ZZ100')).toEqual(wider)
+
+    expect(parseCellAddress('bad')).toBeNull()
+  })
+})

package/src/report/__test__/connector.test.ts

@@ -0,0 +1,218 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { createHttpConnector, resolvePortOnTypeChange } from '../connector'
+import type { DataConnection } from '../connector'
+import type { ParamValues } from '../types'
+
+const CONNECTION: DataConnection = {
+  id: 'demo',
+  label: '演示业务库',
+  type: 'mysql',
+  host: '127.0.0.1',
+  port: 3306,
+  database: 'demo_business',
+  username: 'demo',
+  password: 'demo'
+}
+
+const SQL = 'SELECT customer, amount FROM orders WHERE region = ${region}'
+const VALUES: ParamValues = { region: '华东' }
+
+const ENDPOINT = 'https://api.example.com/report'
+
+interface FetchCall {
+  url: string
+  method: string
+  headers: Headers
+  body: unknown
+}
+
+function stubFetch(respond: (url: string, init: RequestInit) => Promise<unknown>): FetchCall[] {
+  const calls: FetchCall[] = []
+  const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input)
+    const method = init?.method ?? 'GET'
+    const headers = new Headers(init?.headers)
+    const body = typeof init?.body === 'string' ? (JSON.parse(init.body) as unknown) : undefined
+    calls.push({ url, method, headers, body })
+    const payload = await respond(url, init ?? {})
+    return new Response(JSON.stringify(payload), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' }
+    })
+  })
+  vi.stubGlobal('fetch', fetchMock)
+  return calls
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('createHttpConnector', () => {
+  it('test：POST {endpoint}/test，请求体为 { connection }，成功返回 ok 且无 data', async () => {
+    const calls = stubFetch(async () => ({ ok: true }))
+    const connector = createHttpConnector({ endpoint: ENDPOINT })
+
+    const result = await connector.test(CONNECTION)
+
+    expect(result).toEqual({ ok: true, data: undefined })
+    expect(calls).toHaveLength(1)
+    expect(calls[0]!.url).toBe(`${ENDPOINT}/test`)
+    expect(calls[0]!.method).toBe('POST')
+    expect(calls[0]!.headers.get('content-type')).toBe('application/json')
+    expect(calls[0]!.body).toEqual({ connection: CONNECTION })
+  })
+
+  it('describe：POST {endpoint}/describe，请求体 { connection, sql }，fields 归一化为 DatasetField', async () => {
+    const calls = stubFetch(async () => ({
+      ok: true,
+      fields: [{ name: 'customer' }, { name: 'amount', type: 'number' }]
+    }))
+    const connector = createHttpConnector({ endpoint: ENDPOINT })
+
+    const result = await connector.describe(CONNECTION, SQL)
+
+    expect(result).toEqual({
+      ok: true,
+      data: [
+        { name: 'customer', label: 'customer', type: 'string' },
+        { name: 'amount', label: 'amount', type: 'number' }
+      ]
+    })
+    expect(calls[0]!.url).toBe(`${ENDPOINT}/describe`)
+    expect(calls[0]!.body).toEqual({ connection: CONNECTION, sql: SQL })
+  })
+
+  it('query：POST {endpoint}/query，请求体 { connection, sql, values }，返回 fields + rows', async () => {
+    const calls = stubFetch(async () => ({
+      ok: true,
+      fields: [{ name: 'customer', type: 'string' }],
+      rows: [{ customer: '甲公司' }]
+    }))
+    const connector = createHttpConnector({ endpoint: ENDPOINT })
+
+    const result = await connector.query(CONNECTION, SQL, VALUES)
+
+    expect(result).toEqual({
+      ok: true,
+      data: {
+        fields: [{ name: 'customer', label: 'customer', type: 'string' }],
+        rows: [{ customer: '甲公司' }]
+      }
+    })
+    expect(calls[0]!.url).toBe(`${ENDPOINT}/query`)
+    expect(calls[0]!.body).toEqual({ connection: CONNECTION, sql: SQL, values: VALUES })
+  })
+
+  it('业务错误分叉：200 + { ok: false, error } 原样透传（三端点一致）', async () => {
+    stubFetch(async () => ({
+      ok: false,
+      error: { code: 'CONNECTION_REFUSED', message: '无法连接到数据库' }
+    }))
+    const connector = createHttpConnector({ endpoint: ENDPOINT })
+
+    const testResult = await connector.test(CONNECTION)
+    expect(testResult).toEqual({
+      ok: false,
+      error: { code: 'CONNECTION_REFUSED', message: '无法连接到数据库' }
+    })
+
+    const describeResult = await connector.describe(CONNECTION, SQL)
+    expect(describeResult).toEqual({
+      ok: false,
+      error: { code: 'CONNECTION_REFUSED', message: '无法连接到数据库' }
+    })
+
+    const queryResult = await connector.query(CONNECTION, SQL, VALUES)
+    expect(queryResult).toEqual({
+      ok: false,
+      error: { code: 'CONNECTION_REFUSED', message: '无法连接到数据库' }
+    })
+  })
+
+  it('传输层错误：非 2xx 折叠为 HTTP_<status> 错误结果', async () => {
+    const fetchMock = vi.fn(async () => new Response('Internal Server Error', { status: 500 }))
+    vi.stubGlobal('fetch', fetchMock)
+    const connector = createHttpConnector({ endpoint: ENDPOINT })
+
+    const result = await connector.test(CONNECTION)
+
+    expect(result).toEqual({
+      ok: false,
+      error: { code: 'HTTP_500', message: '请求失败（HTTP 500）' }
+    })
+  })
+
+  it('网络异常：fetch reject 折叠为 NETWORK_ERROR', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => Promise.reject(new Error('fetch failed')))
+    )
+    const connector = createHttpConnector({ endpoint: ENDPOINT })
+
+    const result = await connector.test(CONNECTION)
+
+    expect(result).toEqual({ ok: false, error: { code: 'NETWORK_ERROR', message: 'fetch failed' } })
+  })
+
+  it('响应不可解析：非 JSON / 缺字段折叠为 BAD_RESPONSE', async () => {
+    const notJson = vi.fn(async () => new Response('<html>oops</html>', { status: 200 }))
+    vi.stubGlobal('fetch', notJson)
+    const connector = createHttpConnector({ endpoint: ENDPOINT })
+
+    const invalidJson = await connector.describe(CONNECTION, SQL)
+    expect(invalidJson).toEqual({
+      ok: false,
+      error: { code: 'BAD_RESPONSE', message: '响应不是合法 JSON' }
+    })
+
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response(JSON.stringify({ ok: true }), { status: 200 }))
+    )
+    const missingFields = await connector.describe(CONNECTION, SQL)
+    expect(missingFields).toEqual({
+      ok: false,
+      error: { code: 'BAD_RESPONSE', message: 'describe 响应缺少合法的 fields 数组' }
+    })
+
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response(JSON.stringify({ ok: true, fields: [] }), { status: 200 }))
+    )
+    const missingRows = await connector.query(CONNECTION, SQL, VALUES)
+    expect(missingRows).toEqual({
+      ok: false,
+      error: { code: 'BAD_RESPONSE', message: 'query 响应缺少 rows 数组' }
+    })
+  })
+
+  it('ok:false 但 error 形状非法时回退 SERVER_ERROR', async () => {
+    stubFetch(async () => ({ ok: false, error: 'oops' }))
+    const connector = createHttpConnector({ endpoint: ENDPOINT })
+
+    const result = await connector.test(CONNECTION)
+
+    expect(result).toEqual({
+      ok: false,
+      error: { code: 'SERVER_ERROR', message: '服务端返回未知错误' }
+    })
+  })
+})
+
+describe('resolvePortOnTypeChange', () => {
+  it('默认端口随类型切换：MySQL 3306 ↔ PostgreSQL 5432', () => {
+    expect(resolvePortOnTypeChange('mysql', 'postgresql', 3306)).toBe(5432)
+    expect(resolvePortOnTypeChange('postgresql', 'mysql', 5432)).toBe(3306)
+  })
+
+  it('自定义端口不随类型切换而改变', () => {
+    expect(resolvePortOnTypeChange('mysql', 'postgresql', 3307)).toBe(3307)
+    expect(resolvePortOnTypeChange('postgresql', 'mysql', 5433)).toBe(5433)
+  })
+
+  it('端口为 0 时切到新类型默认端口', () => {
+    expect(resolvePortOnTypeChange('mysql', 'postgresql', 0)).toBe(5432)
+  })
+})

package/src/report/__test__/export-xlsx.test.ts

@@ -0,0 +1,118 @@
+import { Sheet } from '@veltra/sheet-core'
+import { buildWorkbookFromHucre } from '@veltra/sheet-core/core/io/import'
+import { readXlsx } from 'hucre/xlsx'
+import { describe, expect, it } from 'vitest'
+
+import { REPORT_META_NAMESPACE, createReportBinding } from '../binding'
+import { buildColumnDefs, exportFilledReportXlsx, pxToExcelColWidth } from '../export-xlsx'
+import { renderReport } from '../render'
+import type { DatasetCatalogItem } from '../types'
+
+// ---- 内联 fixtures ----
+
+const ORDERS_DATASET: DatasetCatalogItem = {
+  id: 'orders',
+  label: '销售明细',
+  fields: [
+    { name: 'customer', label: '客户', type: 'string' },
+    { name: 'amount', label: '金额', type: 'number' }
+  ]
+}
+
+const ORDER_ROWS: Record<string, unknown>[] = [
+  { customer: '甲公司', amount: 100 },
+  { customer: '乙公司', amount: 400 }
+]
+
+/** 金额 > 300 标红（条件样式打平进快照后随导出保真） */
+const RED_RULE = { operator: 'gt' as const, value: 300, style: { font: { color: '#DC2626' } } }
+
+/** 分组（客户）+ 明细（金额，带条件规则）模板 */
+function buildFilledSheet(): Sheet {
+  const sheet = new Sheet()
+  sheet.setCells([
+    { addr: { row: 0, col: 0 }, data: { v: '客户' } },
+    { addr: { row: 0, col: 1 }, data: { v: '金额' } }
+  ])
+  sheet.setCellStyle(
+    { start: { row: 0, col: 0 }, end: { row: 0, col: 1 } },
+    { font: { bold: true }, fill: { color: '#E8EEF7' } }
+  )
+
+  const groupAddr = { row: 1, col: 0 }
+  const group = createReportBinding(ORDERS_DATASET, 'customer')
+  group.preset = 'groupHeader'
+  group.aggregate = 'group'
+  group.expand = 'down'
+  sheet.setCellMeta(groupAddr, REPORT_META_NAMESPACE, group)
+
+  const amount = createReportBinding(ORDERS_DATASET, 'amount')
+  amount.rowParent = groupAddr
+  amount.conditionalRules = [RED_RULE]
+  sheet.setCellMeta({ row: 1, col: 1 }, REPORT_META_NAMESPACE, amount)
+
+  const filled = renderReport(sheet.snapshot(), { orders: ORDER_ROWS })
+  const filledSheet = new Sheet()
+  filledSheet.restore(filled)
+  filledSheet.restoreContent(filled)
+  return filledSheet
+}
+
+describe('exportFilledReportXlsx', () => {
+  it('导出保真 XLSX：值 / 表头样式 / 条件样式打平后随快照导出', async () => {
+    const buffer = await exportFilledReportXlsx(buildFilledSheet(), [
+      [0, 120],
+      [1, 140]
+    ])
+
+    // 合法 ZIP（xlsx）字节
+    expect(buffer[0]).toBe(0x50)
+    expect(buffer[1]).toBe(0x4b)
+
+    const hucreWb = await readXlsx(buffer, { readStyles: true })
+    const workbook = buildWorkbookFromHucre(hucreWb)
+    const sheet = workbook.getSheets()[0]!
+
+    // 展开值保真（分组头 + 明细值）
+    const values: unknown[] = []
+    for (const [, data] of sheet.store.entries()) values.push(data.v)
+    expect(values).toContain('甲公司')
+    expect(values).toContain('乙公司')
+    expect(values).toContain(400)
+
+    // 条件样式打平：amount=400（>300）的明细格带红字
+    let redFound = false
+    for (const [, data] of sheet.store.entries()) {
+      if (data.v !== 400 || data.s == null) continue
+      const style = sheet.stylePool.get(data.s)
+      if (style?.font?.color === '#DC2626') redFound = true
+    }
+    expect(redFound).toBe(true)
+
+    // 表头静态样式保真（加粗 + 底色）
+    const header = sheet.getCellData({ row: 0, col: 0 })
+    const headerStyle = header?.s != null ? sheet.stylePool.get(header.s) : undefined
+    expect(headerStyle?.font?.bold).toBe(true)
+    expect(headerStyle?.fill?.color).toBe('#E8EEF7')
+  })
+})
+
+describe('buildColumnDefs / pxToExcelColWidth', () => {
+  it('像素列宽换算为 Excel 字符宽度并写入对应列', () => {
+    expect(pxToExcelColWidth(120)).toBe(16)
+    expect(pxToExcelColWidth(0)).toBe(1)
+
+    const columns = buildColumnDefs([
+      [0, 120],
+      [2, 145]
+    ])
+    expect(columns).toHaveLength(3)
+    expect(columns[0]).toEqual({ width: 16 })
+    expect(columns[1]).toEqual({})
+    expect(columns[2]).toEqual({ width: 20 })
+  })
+
+  it('空列宽不产生 columns 定义', () => {
+    expect(buildColumnDefs([])).toEqual([])
+  })
+})

package/src/report/__test__/filter-bar.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+
+import { parseDateRangeValue, patchParamValues, resolveNumberParamValue } from '../filter-bar'
+
+describe('parseDateRangeValue', () => {
+  it('解析数组形式的日期范围', () => {
+    expect(parseDateRangeValue(['2024-01-01', '2024-12-31'])).toEqual(['2024-01-01', '2024-12-31'])
+  })
+
+  it('解析 from/to 对象形式', () => {
+    expect(parseDateRangeValue({ from: '2024-03-01', to: '2024-03-31' })).toEqual([
+      '2024-03-01',
+      '2024-03-31'
+    ])
+  })
+
+  it('解析 start/end 对象形式', () => {
+    expect(parseDateRangeValue({ start: '2024-06-01', end: '2024-06-30' })).toEqual([
+      '2024-06-01',
+      '2024-06-30'
+    ])
+  })
+
+  it('空值回退为空字符串元组', () => {
+    expect(parseDateRangeValue(undefined)).toEqual(['', ''])
+    expect(parseDateRangeValue(null)).toEqual(['', ''])
+    expect(parseDateRangeValue('')).toEqual(['', ''])
+  })
+})
+
+describe('resolveNumberParamValue', () => {
+  it('保留有限数字', () => {
+    expect(resolveNumberParamValue(42)).toBe(42)
+    expect(resolveNumberParamValue('12.5')).toBe(12.5)
+  })
+
+  it('空值与非法值返回 undefined', () => {
+    expect(resolveNumberParamValue('')).toBeUndefined()
+    expect(resolveNumberParamValue(null)).toBeUndefined()
+    expect(resolveNumberParamValue(undefined)).toBeUndefined()
+    expect(resolveNumberParamValue('abc')).toBeUndefined()
+  })
+})
+
+describe('patchParamValues', () => {
+  it('合并单参数变更且保留其余值', () => {
+    const next = patchParamValues({ region: '华东', qty: 10 }, 'region', '华南')
+    expect(next).toEqual({ region: '华南', qty: 10 })
+  })
+
+  it('支持 date-range 元组写入', () => {
+    const next = patchParamValues({ dateRange: ['2024-01-01', '2024-01-31'] }, 'dateRange', [
+      '2024-02-01',
+      '2024-02-28'
+    ])
+    expect(next.dateRange).toEqual(['2024-02-01', '2024-02-28'])
+  })
+})