@carthooks/arcubase-cli 0.1.2 → 0.1.3

package/sdk-dist/docs/runtime-reference/entity-schema/selects.md

@@ -0,0 +1,51 @@
+# selects
+
+## Purpose
+
+Multi-select dropdown field.
+
+## Frontend capability flags
+
+- `group: normal`
+- `useFormula: true`
+- `useRelation: true`
+- `inlineEdtiable: true`
+- `events: ['change']`
+
+## Minimal shape
+
+```json
+{
+  "type": "selects",
+  "options": {
+    "placeholder": "",
+    "lengthLimit": false,
+    "lengthMin": 0,
+    "lengthMax": 10,
+    "options": {
+      "mode": "custom",
+      "colorful": false,
+      "items": [
+        { "key": 1, "value": "Option 1" }
+      ]
+    }
+  }
+}
+```
+
+## Common options
+
+- `placeholder`
+- `lengthLimit`
+- `lengthMin`
+- `lengthMax`
+- `options.items`
+- `options.mode`
+- `options.colorful`
+- `options.relation`
+- `options.relation_filter`
+- `options.international`
+
+## Constraints
+
+- `options.items` at least one item

package/sdk-dist/docs/runtime-reference/entity-schema/serialnumber.md

@@ -0,0 +1,48 @@
+# serialnumber
+
+## Purpose
+
+Serial number field.
+
+## Frontend capability flags
+
+- `group: advanced`
+- `operator: text`
+- `switchgroup: text`
+- `inlineEdtiable: true`
+- `oncopy` clears the copied value
+
+## Minimal shape
+
+```json
+{
+  "type": "serialnumber",
+  "options": {
+    "parts": [
+      {
+        "mode": "buildin",
+        "type": "serial",
+        "options": {
+          "length": 6,
+          "lenfixed": true,
+          "random": false,
+          "reset": "no"
+        }
+      }
+    ]
+  }
+}
+```
+
+## Common parts
+
+- `buildin/string`
+- `buildin/date`
+- `buildin/serial`
+- `field`
+
+## Constraints
+
+- `parts` at least one item
+- `buildin/date` requires `format` or `perdefinedFormat`
+- `buildin/serial` requires `length`

package/sdk-dist/docs/runtime-reference/entity-schema/signature.md

@@ -0,0 +1,31 @@
+# signature
+
+## Purpose
+
+Signature field.
+
+## Frontend capability flags
+
+- `notImportAble: true`
+- `notExportAble: true`
+- `events: ['change']`
+
+## Minimal shape
+
+```json
+{
+  "type": "signature",
+  "options": {
+    "placeholder": ""
+  }
+}
+```
+
+## Common options
+
+- `placeholder`
+
+## Constraints
+
+- `required` is controlled by generic field flags
+- In the current direct-write pathyou may keep only an empty `placeholder`

package/sdk-dist/docs/runtime-reference/entity-schema/status.md

@@ -0,0 +1,70 @@
+# status
+
+## Purpose
+
+Status field.
+
+## Frontend capability flags
+
+- `group: normal`
+- `operator: enum`
+- `switchgroup: enum`
+- `useFormula: true`
+- `useRelation: true`
+- `inlineEdtiable: true`
+- `events: ['change']`
+
+## Minimal shape
+
+```json
+{
+  "type": "status",
+  "options": {
+    "horizontal": false,
+    "numberMax": "",
+    "numberMin": "",
+    "numberRange": false,
+    "repeatRemind": "This value already exists and duplicate submission is not allowed",
+    "options": {
+      "mode": "custom",
+      "colorful": false,
+      "items": [
+        { "key": 1, "code": 1, "value": "Pending" }
+      ]
+    }
+  }
+}
+```
+
+## Common options
+
+- `horizontal`
+- `numberMax`
+- `numberMin`
+- `numberRange`
+- `repeatRemind`
+- `hideInList`
+- `options.items`
+- `options.mode`
+- `options.colorful`
+
+## Constraints
+
+- each item must contain at least `code` and `value`
+- keep `code` stable once the field is live
+- row values should use the status `code`
+
+## Save-ready reminder
+
+For `arcubase-admin entity admin-save-entity`, keep the full base `FieldVO`.
+
+The field-specific part only covers `options`. The saved field still needs:
+
+- `id`
+- `label`
+- `required`
+- `editable`
+- `visible`
+- `number_decimal`
+- `key`
+- `children: null`

package/sdk-dist/docs/runtime-reference/entity-schema/subform.md

@@ -0,0 +1,74 @@
+# subform
+
+## Purpose
+
+Subform field.
+
+
+
+## Frontend capability flags
+
+- `group: advanced`
+- `useFormula: true`
+- `useRelation: true`
+
+## Minimal shape
+
+```json
+{
+  "type": "subform",
+  "options": {},
+  "children": []
+}
+```
+
+## Available options
+
+- `lengthLimit`
+- `lengthMin`
+- `lengthMax`
+- `new_record_btn`
+- `hideInList`
+
+## Constraints
+
+- `children: FieldVO[]`
+- Child ids also consume the global field-id space
+- Do not write `layout` separately in the current saved payload
+- The display order of child fields is the order of `children[]`
+- when `new_record_btn` is not configured, prefer `0`
+- when `lengthLimit=true`, it is recommended to provide both `lengthMin` and `lengthMax`
+
+## Row payload
+
+For row commands such as:
+
+- `arcubase workflow insert-entity`
+- `arcubase workflow update-entity-row`
+
+the current writable row shape is:
+
+```json
+[
+  {
+    "id": 0,
+    "fields": {
+      "1007": "SKU-001",
+      "1008": 2
+    }
+  }
+]
+```
+
+Use `id: 0` for a new child row.
+
+Do not use this incorrect shape:
+
+```json
+[
+  {
+    "1007": "SKU-001",
+    "1008": 2
+  }
+]
+```

package/sdk-dist/docs/runtime-reference/entity-schema/tags.md

@@ -0,0 +1,19 @@
+# tags
+
+## Purpose
+
+System tags field.
+
+## Frontend capability flags
+
+- `operator: $in`
+- `useFormula: false`
+- `useRelation: false`
+- `notImportAble: true`
+- `notExportAble: true`
+- `readonly: true`
+
+## Usage rules
+
+- Do not manually add `tags` when creating a normal business schema
+- This is a system-managed field and is not part of normal manual schema modeling

package/sdk-dist/docs/runtime-reference/entity-schema/text.md

@@ -0,0 +1,76 @@
+# text
+
+## Purpose
+
+Single-line text field.
+
+
+
+## Frontend capability flags
+
+- `group: normal`
+- `uniqueAble: true`
+- `useFormula: true`
+- `useRelation: true`
+- `switchgroup: text`
+- `inlineEdtiable: true`
+- `events: ['change']`
+
+## Minimal shape
+
+```json
+{
+  "type": "text",
+  "options": {
+    "placeholder": "",
+    "type": "text",
+    "lengthLimit": false,
+    "lengthMin": 0,
+    "lengthMax": 255
+  }
+}
+```
+
+## Available options
+
+- `placeholder`
+- `type`
+- `lengthLimit`
+- `lengthMin`
+- `lengthMax`
+- `link`
+
+## Constraints
+
+- it can participate in formula and relation conditions
+- it may be marked `unique`
+- when `lengthLimit=true`, it is recommended to provide both `lengthMin` and `lengthMax`
+- in the current direct-write path, prefer the default `"text"` type
+
+## Save-ready reminder
+
+For `arcubase-admin entity admin-save-entity`, do not send only `type + options`.
+
+Wrap this field-specific shape in the full base `FieldVO` described in `entity-schema.md`, including:
+
+- `id`
+- `label`
+- `required`
+- `unique`
+- `editable`
+- `visible`
+- `show_label`
+- `scannable`
+- `default_value_mode`
+- `description`
+- `value`
+- `number_decimal`
+- `depends`
+- `key`
+- `code_index`
+- `transfers`
+- `children`
+
+## Common mistakes
+
+- `lengthLimit=true` but `lengthMax` is missing

package/sdk-dist/docs/runtime-reference/entity-schema/textarea.md

@@ -0,0 +1,47 @@
+# textarea
+
+## Purpose
+
+Multi-line text field.
+
+
+
+## Frontend capability flags
+
+- `group: normal`
+- `useFormula: true`
+- `useRelation: true`
+- `hideInList: true`
+- `inlineEdtiable: false`
+- `events: ['change']`
+
+## Minimal shape
+
+```json
+{
+  "type": "textarea",
+  "options": {
+    "placeholder": "",
+    "html": false,
+    "size": "default",
+    "lengthLimit": false,
+    "lengthMin": 0,
+    "lengthMax": 2000
+  }
+}
+```
+
+## Available options
+
+- `placeholder`
+- `html`
+- `size`
+- `lengthLimit`
+- `lengthMin`
+- `lengthMax`
+
+## Constraints
+
+- `placeholder` matters only when `html=false`
+- when `lengthLimit=true`, it is recommended to provide both `lengthMin` and `lengthMax`
+- keep `size` within the values returned by the current editor; do not invent extra enum values

package/sdk-dist/docs/runtime-reference/entity-schema/workflow_status.md

@@ -0,0 +1,17 @@
+# workflow_status
+
+## Purpose
+
+Workflow system status field.
+
+## Frontend capability flags
+
+- `useFormula: false`
+- `useRelation: false`
+- `notImportAble: true`
+- `notExportAble: true`
+
+## Usage rules
+
+- Do not manually add `workflow_status` when creating a normal business schema
+- This is a system-managed field and is not part of normal manual schema modeling

package/sdk-dist/docs/runtime-reference/entity-schema.md

@@ -0,0 +1,197 @@
+# Entity Schema
+
+Use this page when writing the full table schema with `arcubase-admin`.
+
+Primary command:
+
+```bash
+arcubase-admin entity admin-save-entity \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --body-file save-entity.json
+```
+
+Before writing `save-entity.json`, always fetch the current shell:
+
+```bash
+arcubase-admin entity admin-get-entity-info \
+  --app-id <app_id> \
+  --entity-id <entity_id>
+```
+
+If you already know the field type you want, go to:
+
+- `entity-schema/README.md`
+
+## One successful path
+
+The current direct-write path is:
+
+1. create the entity shell
+2. fetch the current shell
+3. save the full schema
+4. probe rows with `arcubase workflow query-entity`
+
+Do not treat shell creation as “table created”.
+
+## Top-level save payload
+
+The practical save-ready shape is:
+
+```json
+{
+  "id": 2188889845,
+  "app_id": 2188889844,
+  "name": "Order",
+  "workflow_enabled": false,
+  "fields": [],
+  "layout": [],
+  "options": {},
+  "schema_version": 0,
+  "field_id_seq": 1001,
+  "current_serial": null
+}
+```
+
+Rules:
+
+- start from the current shell
+- reuse `schema_version` from the shell
+- keep `id`, `app_id`, `name`, and `workflow_enabled`
+- do not rebuild top-level `options` unless you really need to
+
+## Shell placeholder normalization
+
+The fetched shell may contain placeholder `null` values such as:
+
+- `layout: null`
+- `current_serial: null`
+- `options.Buttons: null`
+- `options.CustomActions: null`
+- `options.FrontendEvents: null`
+- `options.TitleFormat.Fields: null`
+- `options.TitleFormat.Parts: null`
+- `options.misc: null`
+
+Normalize them before saving:
+
+- `layout -> []`
+- remove `current_serial` when it is `null`
+- `Buttons/CustomActions/FrontendEvents -> []`
+- `TitleFormat.Fields/Parts -> []`
+- `misc -> {}`
+
+The CLI already performs this normalization on the direct save path. Your `save-entity.json` should follow the same shape.
+
+## Global invariants
+
+- `fields` must be `FieldVO[]`
+- field ids should start from `1001`
+- field ids must be positive and non-zero
+- `field_id_seq > max(field.id)`
+- `layout` is `number[][]`
+- top-level `layout` may only reference top-level field ids
+- for non-`subform` fields, `children` should be `null`
+- saved `subform` payload keeps `children` only
+- do not write `subform.layout`
+- `lookup.options.relation.local_linkto_field_id` must point to a `linkto` field
+- `rollup.options.relation.local_linkto_field_id` must point to a `linkto` field
+- formula references must point to real field ids
+- do not manually add `tags`
+- do not manually add `workflow_status`
+
+## Generic field shape
+
+Each field in `fields[]` keeps the full base `FieldVO` shape:
+
+```json
+{
+  "id": 1001,
+  "label": "Order No.",
+  "type": "text",
+  "required": true,
+  "unique": false,
+  "editable": true,
+  "visible": true,
+  "show_label": true,
+  "scannable": false,
+  "default_value_mode": 0,
+  "description": "",
+  "value": null,
+  "number_decimal": 0,
+  "depends": [],
+  "key": "order_no",
+  "code_index": false,
+  "options": {},
+  "transfers": null,
+  "children": null
+}
+```
+
+Field pages focus on field-specific `options`, but your real `save-entity.json` still needs the full base shape around them.
+
+## Layout shape
+
+`layout` is not a flat array. Use `number[][]`.
+
+Example:
+
+```json
+[
+  [1001, 1002],
+  [1003],
+  [1004]
+]
+```
+
+Each inner array is one layout row. Only reference top-level field ids here.
+
+## Entity-level options boundary
+
+This document is for `admin-save-entity`.
+
+Keep that command focused on:
+
+- `name`
+- `workflow_enabled`
+- `fields`
+- `layout`
+- `field_id_seq`
+
+Do not overload this save file with unrelated UI payloads just because the shell contains them.
+
+## Fast-fail rules
+
+The CLI should stop immediately when:
+
+- `fields` is an object instead of an array
+- `field_id_seq` is too small
+- `layout` references a missing field id
+- saved payload includes `subform.layout`
+- `local_linkto_field_id` points to a non-`linkto` field
+- formula references a missing field id
+
+Also:
+
+- if the JSON response contains a top-level `error`, treat the command as failed even when the HTTP status is `200`
+
+## Minimal success criteria
+
+Do not call schema creation successful until:
+
+1. `arcubase-admin entity admin-save-entity ...` succeeds without top-level `error`
+2. `arcubase workflow query-entity ...` succeeds against the saved table
+
+If row probing still fails, the table is not ready.
+
+## Row payload reminder
+
+This document is only for schema save.
+
+If you need row payloads after the schema is ready:
+
+- read `row-crud.md`
+
+If you need field-specific save fragments:
+
+- read `entity-schema/README.md`

package/sdk-dist/docs/runtime-reference/examples/README.md

@@ -0,0 +1,51 @@
+# Runtime Examples
+
+Use this directory when the field-level reference is not enough and you need a business-shaped example.
+
+These examples are:
+
+- genericized from real production structures
+- written in English
+- stripped of tenant-specific branding
+- stripped of market-specific vocabulary
+- intended as copy-and-adapt templates for CLI usage
+
+These examples are not raw tenant exports.
+
+## Rules
+
+- Keep table names and field names in English.
+- Remove company-specific words.
+- Remove region-specific words when they are not essential to the workflow.
+- Prefer neutral names such as `sku_code`, `sales_order`, `goods_receipt`, and `stock_issue`.
+- When a save payload needs shell values, replace placeholder tokens such as `__APP_ID__`, `__ENTITY_ID__`, and `__SCHEMA_VERSION__` from the current shell returned by:
+
+```bash
+arcubase-admin entity admin-get-entity-info \
+  --app-id <app_id> \
+  --entity-id <entity_id>
+```
+
+## Available example sets
+
+- `oms-01/`
+  - order management
+  - item master
+  - goods receipt
+  - stock issue
+  - picking list
+  - purchase order
+  - sales order
+- `mes-01/`
+  - manufacturing execution examples
+- `wms-01/`
+  - warehouse and inventory examples
+- `crm-01/`
+  - customer, quote, and invoice examples
+
+## Recommended reading order
+
+1. `../table-lifecycle.md`
+2. `../entity-schema.md`
+3. `oms-01/README.md`
+4. the exact `*.schema.json` and `*.json` example you need

package/sdk-dist/docs/runtime-reference/examples/crm-01/README.md

@@ -0,0 +1,20 @@
+# CRM Example 01
+
+This directory is reserved for a generic CRM and quote example set.
+
+Planned tables:
+
+- `Customer`
+- `Contact`
+- `Quote`
+- `Invoice`
+
+Planned field patterns:
+
+- `text`
+- `select`
+- `status`
+- `member`
+- `textarea`
+
+All names will remain generic and English-only.