@carthooks/arcubase-cli 0.1.13 → 0.1.16

package/sdk-dist/docs/runtime-reference/row-crud.md

@@ -152,6 +152,61 @@ Success result:
 
 The update command returns `true`, not the updated row body.
 
+## Import Records
+
+Excel:
+
+```bash
+arcubase row import-excel \
+  --app-id <app_id> \
+  --table-id <table_id> \
+  --file records.xlsx \
+  --mapping-file mapping.excel.json \
+  --ttl-seconds 300
+```
+
+CSV:
+
+```bash
+arcubase row import-csv \
+  --app-id <app_id> \
+  --table-id <table_id> \
+  --file records.csv \
+  --mapping-file mapping.csv.json \
+  --ttl-seconds 300
+```
+
+Both commands accept local file paths only. CSV mapping uses headers. Excel mapping uses column letters. The mapping file is validated locally before the import task is started.
+
+Excel `mapping.excel.json`:
+
+```json
+{
+  "sheet": "Sheet1",
+  "mode": "addonly",
+  "headerRow": 1,
+  "dataStartRow": 2,
+  "fields": [
+    { "fieldId": 1001, "column": "A" }
+  ]
+}
+```
+
+CSV `mapping.csv.json`:
+
+```json
+{
+  "mode": "addonly",
+  "header": true,
+  "dataStartRow": 2,
+  "fields": [
+    { "fieldId": 1001, "header": "客户名称" }
+  ]
+}
+```
+
+For `updateonly` and `addorupdate`, include `recordId` in the mapping. Use `arcubase-admin table get --app-id <app_id> --table-id <table_id>` to inspect numeric field ids.
+
 ## Delete rows
 
 Command:

package/sdk-dist/docs/runtime-reference/search-and-bulk-actions.md

@@ -38,13 +38,38 @@ For extra query-string parameters, also use:
   "limit": 20,
   "offset": 0,
   "search": {
-    "text_search": "ORD-3001"
+    "q": "ORD-3001"
   }
 }
 ```
 
 This is the current success path for free-text search.
 
+Rules:
+
+- `search` is route-query state, not `ConditionSet`
+- every `search` value must be a string
+- use `q` for free-text search
+- use `tab` for a list tab id
+- use `filter_:<field_id_or_prop>` for field filters
+- do not use `search.conditions`, `search.condition`, `search.field_filters`, `filter`, `filters`, `where`, `order`, or `orderBy`
+
+## Field filter
+
+`query.json`:
+
+```json
+{
+  "limit": 20,
+  "offset": 0,
+  "search": {
+    "filter_:1002": "%7B%22is%22%3A%22member_1%22%7D"
+  }
+}
+```
+
+`filter_:...` values are URL-encoded `FilterCond` JSON strings. For example, `%7B%22is%22%3A%22member_1%22%7D` decodes to `{"is":"member_1"}`.
+
 ## Sorts
 
 `query.json`:

package/sdk-dist/docs/runtime-reference/table-lifecycle.md

@@ -102,7 +102,7 @@ Minimal `table-create.json`:
       "depends": [],
       "key": "description",
       "code_index": false,
-      "options": {"placeholder": "", "html": false, "size": "default", "lengthLimit": false, "lengthMin": 0, "lengthMax": 2000},
+      "options": {"placeholder": "", "html": false, "size": 6, "lengthLimit": false, "lengthMin": 0, "lengthMax": 2000},
       "transfers": null,
       "children": null
     },

package/sdk-dist/generated/command_registry.generated.ts

@@ -68,6 +68,63 @@ export const adminCommands = [
     "queryParams": [],
     "responseType": "AppCreateByTenantsRespVO"
   },
+  {
+    "scope": "admin",
+    "module": "app",
+    "functionName": "createAppFromBundleURL",
+    "commandPath": [
+      "app",
+      "create-from-bundle-url"
+    ],
+    "method": "POST",
+    "endpoint": "/api/apps/import-task",
+    "pathParams": [],
+    "controller": "manual",
+    "requestType": null,
+    "queryParams": [
+      {
+        "key": "url",
+        "flag": "url",
+        "type": "string",
+        "hasDefault": false
+      },
+      {
+        "key": "name",
+        "flag": "name",
+        "type": "string",
+        "hasDefault": true
+      }
+    ],
+    "responseType": "AppBundleImportTaskCreateRespVO"
+  },
+  {
+    "scope": "admin",
+    "module": "app",
+    "functionName": "watchAppBundleImportTask",
+    "commandPath": [
+      "app",
+      "watch-import-task"
+    ],
+    "method": "GET",
+    "endpoint": "/api/apps/import-task/:task_id",
+    "pathParams": [
+      {
+        "param": "task_id",
+        "flag": "task-id"
+      }
+    ],
+    "controller": "manual",
+    "requestType": null,
+    "queryParams": [
+      {
+        "key": "ttl_seconds",
+        "flag": "ttl-seconds",
+        "type": "number",
+        "hasDefault": false
+      }
+    ],
+    "responseType": "AppBundleImportTaskStatusRespVO"
+  },
   {
     "scope": "admin",
     "module": "app",
@@ -791,6 +848,94 @@ export const userCommands = [
     "queryParams": [],
     "responseType": "EntityBulkUpdateRespVO"
   },
+  {
+    "scope": "user",
+    "module": "row",
+    "functionName": "importEntityRecordsFromExcel",
+    "commandPath": [
+      "row",
+      "import-excel"
+    ],
+    "method": "POST",
+    "endpoint": "/api/entity/:app_id/:entity_id/import",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "entity_id",
+        "flag": "table-id"
+      }
+    ],
+    "controller": "manual",
+    "requestType": null,
+    "queryParams": [
+      {
+        "key": "file",
+        "flag": "file",
+        "type": "string",
+        "hasDefault": false
+      },
+      {
+        "key": "mapping_file",
+        "flag": "mapping-file",
+        "type": "string",
+        "hasDefault": false
+      },
+      {
+        "key": "ttl_seconds",
+        "flag": "ttl-seconds",
+        "type": "number",
+        "hasDefault": true
+      }
+    ],
+    "responseType": "ImporterGetStateRespVO"
+  },
+  {
+    "scope": "user",
+    "module": "row",
+    "functionName": "importEntityRecordsFromCSV",
+    "commandPath": [
+      "row",
+      "import-csv"
+    ],
+    "method": "POST",
+    "endpoint": "/api/entity/:app_id/:entity_id/import",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "entity_id",
+        "flag": "table-id"
+      }
+    ],
+    "controller": "manual",
+    "requestType": null,
+    "queryParams": [
+      {
+        "key": "file",
+        "flag": "file",
+        "type": "string",
+        "hasDefault": false
+      },
+      {
+        "key": "mapping_file",
+        "flag": "mapping-file",
+        "type": "string",
+        "hasDefault": false
+      },
+      {
+        "key": "ttl_seconds",
+        "flag": "ttl-seconds",
+        "type": "number",
+        "hasDefault": true
+      }
+    ],
+    "responseType": "ImporterGetStateRespVO"
+  },
   {
     "scope": "user",
     "module": "row",

package/sdk-dist/types/common.ts

@@ -293,6 +293,7 @@ export interface KioskConfig {
   interactiveMode?: string;
   lookupFields?: number[];
   options?: Record<string, any>;
+  printers?: Record<string, any>[];
   screens?: KioskScreen[];
   theme?: string;
 }

package/src/generated/command_registry.generated.ts

@@ -68,6 +68,63 @@ export const adminCommands = [
     "queryParams": [],
     "responseType": "AppCreateByTenantsRespVO"
   },
+  {
+    "scope": "admin",
+    "module": "app",
+    "functionName": "createAppFromBundleURL",
+    "commandPath": [
+      "app",
+      "create-from-bundle-url"
+    ],
+    "method": "POST",
+    "endpoint": "/api/apps/import-task",
+    "pathParams": [],
+    "controller": "manual",
+    "requestType": null,
+    "queryParams": [
+      {
+        "key": "url",
+        "flag": "url",
+        "type": "string",
+        "hasDefault": false
+      },
+      {
+        "key": "name",
+        "flag": "name",
+        "type": "string",
+        "hasDefault": true
+      }
+    ],
+    "responseType": "AppBundleImportTaskCreateRespVO"
+  },
+  {
+    "scope": "admin",
+    "module": "app",
+    "functionName": "watchAppBundleImportTask",
+    "commandPath": [
+      "app",
+      "watch-import-task"
+    ],
+    "method": "GET",
+    "endpoint": "/api/apps/import-task/:task_id",
+    "pathParams": [
+      {
+        "param": "task_id",
+        "flag": "task-id"
+      }
+    ],
+    "controller": "manual",
+    "requestType": null,
+    "queryParams": [
+      {
+        "key": "ttl_seconds",
+        "flag": "ttl-seconds",
+        "type": "number",
+        "hasDefault": false
+      }
+    ],
+    "responseType": "AppBundleImportTaskStatusRespVO"
+  },
   {
     "scope": "admin",
     "module": "app",
@@ -791,6 +848,94 @@ export const userCommands = [
     "queryParams": [],
     "responseType": "EntityBulkUpdateRespVO"
   },
+  {
+    "scope": "user",
+    "module": "row",
+    "functionName": "importEntityRecordsFromExcel",
+    "commandPath": [
+      "row",
+      "import-excel"
+    ],
+    "method": "POST",
+    "endpoint": "/api/entity/:app_id/:entity_id/import",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "entity_id",
+        "flag": "table-id"
+      }
+    ],
+    "controller": "manual",
+    "requestType": null,
+    "queryParams": [
+      {
+        "key": "file",
+        "flag": "file",
+        "type": "string",
+        "hasDefault": false
+      },
+      {
+        "key": "mapping_file",
+        "flag": "mapping-file",
+        "type": "string",
+        "hasDefault": false
+      },
+      {
+        "key": "ttl_seconds",
+        "flag": "ttl-seconds",
+        "type": "number",
+        "hasDefault": true
+      }
+    ],
+    "responseType": "ImporterGetStateRespVO"
+  },
+  {
+    "scope": "user",
+    "module": "row",
+    "functionName": "importEntityRecordsFromCSV",
+    "commandPath": [
+      "row",
+      "import-csv"
+    ],
+    "method": "POST",
+    "endpoint": "/api/entity/:app_id/:entity_id/import",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "entity_id",
+        "flag": "table-id"
+      }
+    ],
+    "controller": "manual",
+    "requestType": null,
+    "queryParams": [
+      {
+        "key": "file",
+        "flag": "file",
+        "type": "string",
+        "hasDefault": false
+      },
+      {
+        "key": "mapping_file",
+        "flag": "mapping-file",
+        "type": "string",
+        "hasDefault": false
+      },
+      {
+        "key": "ttl_seconds",
+        "flag": "ttl-seconds",
+        "type": "number",
+        "hasDefault": true
+      }
+    ],
+    "responseType": "ImporterGetStateRespVO"
+  },
   {
     "scope": "user",
     "module": "row",

package/src/runtime/entity_import_mapping.ts

@@ -0,0 +1,172 @@
+import { CLIError } from './errors.js'
+
+export type ImportMode = 'addonly' | 'updateonly' | 'addorupdate'
+
+export type CompiledEntityImportConfig = {
+  fileFormat: 'excel' | 'csv'
+  importMode: ImportMode
+  workingSheet?: string
+  titleRowIndex: number
+  csvDelimiter?: string
+  mapper: Record<string, number>
+}
+
+type ExcelMapping = {
+  sheet: unknown
+  mode: unknown
+  headerRow?: unknown
+  dataStartRow: unknown
+  recordId?: { column?: unknown }
+  fields: Array<{ fieldId?: unknown; column?: unknown }>
+}
+
+type CSVMapping = {
+  mode: unknown
+  header: unknown
+  dataStartRow: unknown
+  delimiter?: unknown
+  recordId?: { header?: unknown }
+  fields: Array<{ fieldId?: unknown; header?: unknown }>
+}
+
+function fail(message: string, details: Record<string, unknown> = {}): never {
+  throw new CLIError('INVALID_IMPORT_MAPPING', message, 2, {
+    hint: 'run command help for a complete mapping example',
+    ...details,
+  })
+}
+
+function parseMode(value: unknown): ImportMode {
+  if (value === 'addonly' || value === 'updateonly' || value === 'addorupdate') return value
+  fail('mode must be one of addonly, updateonly, addorupdate')
+}
+
+function parseDataStartRow(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 2) {
+    fail('dataStartRow must be an integer greater than or equal to 2')
+  }
+  return value
+}
+
+function titleRowIndexFromDataStartRow(value: number): number {
+  return value - 2
+}
+
+function parseFieldId(value: unknown, path: string): number {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+    fail(`${path}.fieldId must be a number`, {
+      commonMistakes: ['fieldId must be numeric, not a quoted string', 'use arcubase-admin table get to inspect field ids'],
+    })
+  }
+  return value
+}
+
+function excelColumnToIndex(column: unknown, path: string): number {
+  if (typeof column !== 'string' || !/^[A-Za-z]+$/.test(column.trim())) {
+    fail(`${path} must be an Excel column such as A, B, or AA`)
+  }
+  let value = 0
+  for (const char of column.trim().toUpperCase()) {
+    value = value * 26 + (char.charCodeAt(0) - 64)
+  }
+  return value - 1
+}
+
+function assertUniqueTarget(mapper: Record<string, number>, key: string, index: number) {
+  if (key in mapper) {
+    fail(`duplicate field mapping for ${key}`)
+  }
+  if (Object.values(mapper).includes(index)) {
+    fail(`duplicate source column index ${index}`)
+  }
+  mapper[key] = index
+}
+
+function validateRecordId(mode: ImportMode, recordId: unknown) {
+  if ((mode === 'updateonly' || mode === 'addorupdate') && !recordId) {
+    fail('recordId is required for updateonly and addorupdate')
+  }
+}
+
+export function compileExcelImportMapping(input: unknown): CompiledEntityImportConfig {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    fail('excel mapping must be a JSON object')
+  }
+  const mapping = input as ExcelMapping
+  const mode = parseMode(mapping.mode)
+  validateRecordId(mode, mapping.recordId)
+  if (typeof mapping.sheet !== 'string' || mapping.sheet.trim() === '') {
+    fail('sheet is required for excel import')
+  }
+  if (!Array.isArray(mapping.fields) || mapping.fields.length === 0) {
+    fail('fields must be a non-empty array')
+  }
+  const mapper: Record<string, number> = {}
+  if (mapping.recordId?.column !== undefined) {
+    assertUniqueTarget(mapper, '$id', excelColumnToIndex(mapping.recordId.column, 'recordId.column'))
+  }
+  mapping.fields.forEach((field, index) => {
+    const fieldId = parseFieldId(field.fieldId, `fields.${index}`)
+    const columnIndex = excelColumnToIndex(field.column, `fields.${index}.column`)
+    assertUniqueTarget(mapper, String(fieldId), columnIndex)
+  })
+  return {
+    fileFormat: 'excel',
+    importMode: mode,
+    workingSheet: mapping.sheet.trim(),
+    titleRowIndex: titleRowIndexFromDataStartRow(parseDataStartRow(mapping.dataStartRow)),
+    mapper,
+  }
+}
+
+function parseDelimiter(value: unknown): string {
+  if (value === undefined || value === null || value === '') return ','
+  if (typeof value !== 'string' || [...value].length !== 1) {
+    fail('delimiter must be exactly one character')
+  }
+  return value
+}
+
+function headerIndex(headers: string[], wanted: unknown, path: string): number {
+  if (typeof wanted !== 'string' || wanted.trim() === '') {
+    fail(`${path} is required`)
+  }
+  const index = headers.indexOf(wanted)
+  if (index < 0) {
+    fail(`CSV header not found: ${wanted}`, {
+      suggestions: [`available headers: ${headers.join(', ')}`],
+    })
+  }
+  return index
+}
+
+export function compileCSVImportMapping(input: unknown, headers: string[]): CompiledEntityImportConfig {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    fail('csv mapping must be a JSON object')
+  }
+  const mapping = input as CSVMapping
+  const mode = parseMode(mapping.mode)
+  validateRecordId(mode, mapping.recordId)
+  if (mapping.header !== true) {
+    fail('csv mapping header must be true')
+  }
+  if (!Array.isArray(mapping.fields) || mapping.fields.length === 0) {
+    fail('fields must be a non-empty array')
+  }
+  const mapper: Record<string, number> = {}
+  if (mapping.recordId?.header !== undefined) {
+    assertUniqueTarget(mapper, '$id', headerIndex(headers, mapping.recordId.header, 'recordId.header'))
+  }
+  mapping.fields.forEach((field, index) => {
+    const fieldId = parseFieldId(field.fieldId, `fields.${index}`)
+    const columnIndex = headerIndex(headers, field.header, `fields.${index}.header`)
+    assertUniqueTarget(mapper, String(fieldId), columnIndex)
+  })
+  return {
+    fileFormat: 'csv',
+    importMode: mode,
+    titleRowIndex: titleRowIndexFromDataStartRow(parseDataStartRow(mapping.dataStartRow)),
+    csvDelimiter: parseDelimiter(mapping.delimiter),
+    mapper,
+  }
+}

package/src/runtime/entity_save_schema.ts

@@ -197,6 +197,15 @@ function makeSimpleFieldSchema(type: string) {
   }).strict()
 }
 
+const textareaFieldSchema = z.object({
+  ...fieldCommonShape,
+  type: z.literal('textarea'),
+  options: z.object({
+    size: z.number().int().min(1),
+  }).passthrough(),
+  children: z.null(),
+}).strict()
+
 function makeEnumFieldSchema(type: typeof enumFieldTypes[number]) {
   const itemSchema = type === 'status' ? statusItemSchema : enumItemSchema
   return z.object({
@@ -211,7 +220,9 @@ function makeEnumFieldSchema(type: typeof enumFieldTypes[number]) {
   }).strict()
 }
 
-const simpleFieldSchemas = simpleFieldTypes.map((type) => makeSimpleFieldSchema(type))
+const simpleFieldSchemas = simpleFieldTypes
+  .filter((type) => type !== 'textarea')
+  .map((type) => makeSimpleFieldSchema(type))
 const enumFieldSchemas = enumFieldTypes.map((type) => makeEnumFieldSchema(type))
 
 const formulaFieldSchema = z.object({
@@ -290,6 +301,7 @@ const genericFieldSchema = z.object({
 }).strict()
 
 const baseFieldSchemaVariants = [
+  textareaFieldSchema,
   ...simpleFieldSchemas,
   ...enumFieldSchemas,
   ...relationFieldSchemas,
@@ -395,7 +407,7 @@ const EntitySaveReqVOBaseSchema = z.object({
     schema_version: z.number().optional(),
     workflow_enabled: z.boolean().optional(),
   }).strict().superRefine((entity, ctx) => {
-    const fields = entity.fields
+    const fields = entity.fields as any[]
     const topLevelIds = new Set<number>(collectTopLevelFieldIds(fields))
     const allIds = collectAllFieldIds(fields)
     const allIdSet = new Set<number>()
@@ -492,6 +504,18 @@ const queryOrderSchema = z.object({
   order: z.string().min(1),
 }).strict()
 
+const routeQuerySearchKeySchema = z.string().superRefine((key, ctx) => {
+  if (key === 'q' || key === 'tab' || /^filter_:\d+$/.test(key)) {
+    return
+  }
+  ctx.addIssue({
+    code: z.ZodIssueCode.custom,
+    message: 'row query search only accepts route-query string keys: q, tab, and filter_:<field_id>',
+  })
+})
+
+const routeQuerySearchSchema = z.record(routeQuerySearchKeySchema, z.string().min(1))
+
 export const AppCreateByTenantsReqVOSchemaOverride: z.ZodTypeAny = z.object({
   icon_color: z.string().optional(),
   icon_name: z.string().optional(),
@@ -502,7 +526,7 @@ export const EntityQueryReqVOSchemaOverride: z.ZodTypeAny = z.object({
   limit: z.number().int().positive().optional(),
   offset: z.number().int().min(0).optional(),
   policy_id: z.string().optional(),
-  search: z.record(z.string(), z.any()).optional(),
+  search: routeQuerySearchSchema.optional(),
   sorts: z.array(queryOrderSchema).optional(),
   view_mode: z.string().optional(),
   viewMode: z.never().optional(),