@veltra/sheet 2.1.1 → 2.3.0

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

@@ -0,0 +1,239 @@
+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('describe：服务端返回 label 时保留中文显示名', async () => {
+    stubFetch(async () => ({
+      ok: true,
+      fields: [
+        { name: 'customer', label: '客户名称', type: 'string' },
+        { name: 'amount', label: '金额', type: 'number' }
+      ]
+    }))
+    const connector = createHttpConnector({ endpoint: ENDPOINT })
+
+    const result = await connector.describe(CONNECTION, SQL)
+
+    expect(result).toEqual({
+      ok: true,
+      data: [
+        { name: 'customer', label: '客户名称', type: 'string' },
+        { name: 'amount', label: '金额', type: 'number' }
+      ]
+    })
+  })
+
+  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 filled = buildFilledSheet()
+    filled.setColWidth(0, 120)
+    filled.setColWidth(1, 140)
+    const buffer = await exportFilledReportXlsx(filled)
+
+    // 合法 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'])
+  })
+})

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

@@ -0,0 +1,156 @@
+import { describe, expect, it } from 'vitest'
+
+import { buildParamDefs, extractParamIds, resolveBoundDatasetParams } from '../params'
+import type { QueryParamDef } from '../types'
+
+describe('report params', () => {
+  describe('extractParamIds', () => {
+    it('从 SQL 提取 ${param} 占位符并去重', () => {
+      expect(
+        extractParamIds(
+          'SELECT * FROM orders WHERE order_date >= ${dateFrom} AND order_date <= ${dateTo}'
+        )
+      ).toEqual(['dateFrom', 'dateTo'])
+
+      expect(
+        extractParamIds("SELECT * FROM orders WHERE region = ${region} AND ${region} != ''")
+      ).toEqual(['region'])
+      expect(extractParamIds('SELECT * FROM orders')).toEqual([])
+    })
+
+    it('忽略空白占位符与未闭合占位符', () => {
+      expect(extractParamIds('WHERE a = ${ } AND b = ${ x }')).toEqual(['x'])
+      expect(extractParamIds('WHERE a = ${unclosed')).toEqual([])
+    })
+  })
+
+  describe('buildParamDefs', () => {
+    it('等值比较推断 number 类型（旧行为；编辑器通常覆盖为 select/text）', () => {
+      expect(buildParamDefs('SELECT customer FROM orders WHERE region = ${region}')).toEqual([
+        { id: 'region', label: 'region', type: 'number', defaultValue: 0 }
+      ])
+    })
+
+    it('BETWEEN 单参数推断 date-range 类型', () => {
+      const params = buildParamDefs(
+        'SELECT customer FROM orders WHERE order_date BETWEEN ${dateRange}'
+      )
+      expect(params).toHaveLength(1)
+      expect(params[0]?.id).toBe('dateRange')
+      expect(params[0]?.type).toBe('date-range')
+      expect(params[0]?.defaultValue).toEqual(['', ''])
+    })
+
+    it('BETWEEN 双参数：首参推断 date，次参无 AND 后续回落 text（旧行为）', () => {
+      const sql = 'SELECT customer FROM orders WHERE order_date BETWEEN ${dateFrom} AND ${dateTo}'
+      const params = buildParamDefs(sql)
+      const types = Object.fromEntries(params.map((p) => [p.id, p.type]))
+      expect(types).toEqual({ dateFrom: 'date', dateTo: 'text' })
+    })
+
+    it('LIKE 推断 text、数值比较推断 number', () => {
+      expect(
+        buildParamDefs('SELECT customer FROM orders WHERE customer LIKE ${keyword}')[0]?.type
+      ).toBe('text')
+      expect(
+        buildParamDefs('SELECT customer FROM orders WHERE amount > ${minAmount}')[0]?.type
+      ).toBe('number')
+    })
+
+    it('元数据覆盖 label / 类型 / 默认值 / 选项', () => {
+      const params = buildParamDefs('SELECT customer FROM orders WHERE region = ${region}', {
+        region: {
+          label: '地区',
+          type: 'select',
+          defaultValue: '',
+          options: [
+            { label: '华东', value: '华东' },
+            { label: '华南', value: '华南' }
+          ]
+        }
+      })
+      expect(params[0]).toEqual({
+        id: 'region',
+        label: '地区',
+        type: 'select',
+        defaultValue: '',
+        options: [
+          { label: '华东', value: '华东' },
+          { label: '华南', value: '华南' }
+        ]
+      })
+    })
+  })
+
+  describe('resolveBoundDatasetParams', () => {
+    const DATE_FROM: QueryParamDef = {
+      id: 'dateFrom',
+      label: '开始日期',
+      type: 'date',
+      defaultValue: '2024-01-01'
+    }
+    const DATE_TO: QueryParamDef = {
+      id: 'dateTo',
+      label: '结束日期',
+      type: 'date',
+      defaultValue: '2024-12-31'
+    }
+    const REGION: QueryParamDef = {
+      id: 'region',
+      label: '地区',
+      type: 'select',
+      defaultValue: '',
+      options: [{ label: '华东', value: '华东' }]
+    }
+    const ALERT_THRESHOLD: QueryParamDef = {
+      id: 'alertThreshold',
+      label: '库存预警阈值',
+      type: 'number',
+      defaultValue: 80
+    }
+
+    const datasetParams: Record<string, QueryParamDef[]> = {
+      orders: [DATE_FROM, DATE_TO, REGION],
+      customers: [REGION],
+      'sales-matrix': [REGION],
+      'inventory-alerts': [ALERT_THRESHOLD]
+    }
+
+    it('按绑定数据集合并查询参数并去重', () => {
+      const merged = resolveBoundDatasetParams(
+        [],
+        ['orders', 'customers'],
+        (id) => datasetParams[id] ?? []
+      )
+      expect(merged.map((item) => item.id).sort()).toEqual(['dateFrom', 'dateTo', 'region'])
+
+      const matrix = resolveBoundDatasetParams(
+        [],
+        ['sales-matrix'],
+        (id) => datasetParams[id] ?? []
+      )
+      expect(matrix.map((item) => item.id)).toEqual(['region'])
+
+      const inventory = resolveBoundDatasetParams(
+        [],
+        ['inventory-alerts'],
+        (id) => datasetParams[id] ?? []
+      )
+      expect(inventory.map((item) => item.id)).toEqual(['alertThreshold'])
+    })
+
+    it('无绑定数据集时回退全局参数', () => {
+      const fallback = resolveBoundDatasetParams([REGION], [], () => [])
+      expect(fallback.map((item) => item.id)).toEqual(['region'])
+    })
+
+    it('同名参数先见为准', () => {
+      const overridden: QueryParamDef = { ...REGION, label: '覆盖地区' }
+      const merged = resolveBoundDatasetParams([], ['orders', 'customers'], (id) =>
+        id === 'orders' ? [REGION] : [overridden]
+      )
+      expect(merged).toHaveLength(1)
+      expect(merged[0]?.label).toBe('地区')
+    })
+  })
+})