@carthooks/arcubase-cli 0.1.10 → 0.1.12

package/sdk-dist/docs/runtime-reference/condition.md

@@ -0,0 +1,182 @@
+# Condition
+
+There are three different condition shapes. Do not mix them.
+
+## 1. Selection Condition
+
+Used only inside:
+
+- `EntitySelectionVO.condition`
+- `arcubase row bulk-update`
+- `arcubase row selection-action`
+
+Shape:
+
+```json
+{
+  "selection": {
+    "type": "condition",
+    "length": 10,
+    "condition": {
+      "q": "SO-1001",
+      "filter_:1002": "%7B%22is%22%3A%22new%22%7D",
+      "selectAll": true
+    }
+  }
+}
+```
+
+Rules:
+
+- route-query search state
+- keys: `q`, `tab`, `filter_<column>`, `selectAll`
+- `selectAll` must be `true`
+- `filter_<column>` value is URL-encoded `FilterCond` JSON
+- not `ConditionSet`
+- not `{field, operator, value}`
+
+Source paths:
+
+- `backend/app/controllers/entityUtils/queryContext.go`
+- `frontend/src/views/Entity/ListView.vue`
+- `frontend/src/views/Entity/Admin/Data/Index.vue`
+- `$ARCUBASE_SDK_ROOT/types/user-action.ts`
+
+## 2. FilterCond
+
+Used as the decoded value of route-query `filter_<column>`.
+
+Shape:
+
+```json
+{
+  "is": "new"
+}
+```
+
+More shapes:
+
+```json
+{"in":["new","qualified"]}
+```
+
+```json
+{"number_in":[2188890411,2188890412]}
+```
+
+```json
+{"gt":0,"le":100}
+```
+
+Rules:
+
+- encode before putting into `filter_<column>`
+- field columns use `:<field_id>`, for example `filter_:1002`
+- property columns use the property name, for example `filter_id`
+- supported keys: `is`, `in`, `number_in`, `null`, `lt`, `gt`, `ge`, `le`, `eq`, `at`, `expr`
+
+Encoded example:
+
+```json
+{
+  "selection": {
+    "type": "condition",
+    "length": 1,
+    "condition": {
+      "filter_:1002": "%7B%22is%22%3A%22new%22%7D",
+      "selectAll": true
+    }
+  }
+}
+```
+
+Source paths:
+
+- `backend/app/models/permit/listOptions.go`
+- `backend/app/controllers/entityUtils/queryContext.go`
+- `frontend/src/types/vo/permit.ts`
+
+## 3. ConditionSet
+
+Used by configuration systems:
+
+- access-rule policies
+- list tabs
+- relation/linkto field config
+- automate rules
+- workflow branches
+- dashboard widgets
+
+Shape:
+
+```json
+{
+  "mode": "and",
+  "conditions": [
+    {
+      "column": ":1004",
+      "operator": "$eq",
+      "value": "confirmed"
+    }
+  ]
+}
+```
+
+Relation value shape:
+
+```json
+{
+  "mode": "and",
+  "conditions": [
+    {
+      "column": ":2002",
+      "operator": "$eq",
+      "value_from": 2,
+      "value_relation": ":1001"
+    }
+  ]
+}
+```
+
+Nested shape:
+
+```json
+{
+  "mode": "or",
+  "conditions": [
+    {
+      "subset": {
+        "mode": "and",
+        "conditions": [
+          { "column": ":1002", "operator": "$eq", "value": "A" }
+        ]
+      }
+    }
+  ]
+}
+```
+
+Rules:
+
+- this is not valid inside `selection.condition`
+- `column` and `value_relation` are `PermitEntityProp`, for example `:1001`
+- operators use backend operators such as `$eq`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`
+- empty condition set is `{ "mode": "and", "conditions": [] }`
+
+Source paths:
+
+- `backend/app/models/permit/policy.go`
+- `backend/app/models/permit/listOptions.go`
+- `backend/app/models/linkto/types.go`
+- `frontend/src/types/vo/condition.vo.ts`
+- `$ARCUBASE_SDK_ROOT/types/common.ts`
+
+## Quick Decision
+
+| Need | Use |
+| --- | --- |
+| Act on exact rows | `selection.type=ids` |
+| Act on current filtered list | `selection.type=condition` with route-query keys |
+| Query all rows through selection-action | `selection.type=all` |
+| Filter one route-query column | `FilterCond` JSON under `filter_<column>` |
+| Configure permission/rule/relation/workflow condition | `ConditionSet` |

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

@@ -3,10 +3,10 @@
 Use this directory while building `save-entity.json` for:
 
 ```bash
-arcubase-admin entity admin-save-entity \
+arcubase-admin table update-schema \
   --app-id <app_id> \
   --table-id <table_id> \
-  --body-file save-entity.json
+  --body-file save-entity.json | --body-json <json-string>
 ```
 
 ## How to use these field pages
@@ -14,7 +14,7 @@ arcubase-admin entity admin-save-entity \
 1. fetch the current shell with:
 
 ```bash
-arcubase-admin entity admin-get-entity-info \
+arcubase-admin table get \
   --app-id <app_id> \
   --table-id <table_id>
 ```
@@ -32,7 +32,7 @@ These field pages do **not** replace the full base field shape. They only explai
 ## Global save rules
 
 - `fields` must be `FieldVO[]`
-- field ids should start from `1001`
+- first field id is `1001`; `1000` is the empty-schema baseline
 - field ids must be non-zero
 - `field_id_seq > max(field.id)`
 - top-level `layout` may only reference top-level field ids
@@ -53,8 +53,9 @@ If you need row payloads, read:
 
 Current important row rules:
 
-- row delete uses:
+- row delete / restore uses:
   - `arcubase row delete`
+  - `arcubase row update`
   - `selection.type = "ids"`
 - `subform` row values use:
   - `[{ "id": 0, "fields": { ... } }]`

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

@@ -47,7 +47,7 @@ Multi-select enum field.
 
 ## Save-ready reminder
 
-For `arcubase-admin entity admin-save-entity`, keep the full base `FieldVO`.
+For `arcubase-admin table update-schema`, keep the full base `FieldVO`.
 
 The saved field still needs:
 

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

@@ -48,6 +48,6 @@ File upload field.
 When inserting or updating row data for a `file` field:
 
 - do not construct upload payload objects by hand
-- run `arcubase upload <local-file>` first
-- use the returned `data` array directly as the row field value
+- use the `upload token` flow in `../uploads.md`
+- pass the returned upload value array directly as the row field value
 - read `../uploads.md`

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

@@ -47,6 +47,6 @@ Image upload field.
 When inserting or updating row data for an `image` field:
 
 - do not construct upload payload objects by hand
-- run `arcubase upload <local-file>` first
-- use the returned `data` array directly as the row field value
+- use the `upload token` flow in `../uploads.md`
+- pass the returned upload value array directly as the row field value
 - read `../uploads.md`

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

@@ -25,7 +25,7 @@ Relation picker field.
     "structure": "multiple",
     "relation": {
       "app_id": 1,
-      "table_id": 2,
+      "entity_id": 2,
       "type": "entity",
       "show_fields": [1001],
       "queryFields": [1001],
@@ -45,7 +45,7 @@ Relation picker field.
 - `backfill`
 - `addValue`
 - `relation.app_id`
-- `relation.table_id`
+- `relation.entity_id`
 - `relation.type`
 - `relation.show_fields`
 - `relation.queryFields`
@@ -55,7 +55,7 @@ Relation picker field.
 
 ## Constraints
 
-- `relation.app_id` and `relation.table_id` are required
+- `relation.app_id` and `relation.entity_id` are required
 - `relation.show_fields` should be explicit
 - `relation.sorts` should include at least one default sort
 - row CRUD may store an empty array when no linked record is selected

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

@@ -58,7 +58,7 @@ Numeric field.
 
 ## Save-ready reminder
 
-For `arcubase-admin entity admin-save-entity`, keep the full base `FieldVO`.
+For `arcubase-admin table update-schema`, keep the full base `FieldVO`.
 
 In practice, do not forget:
 

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

@@ -15,7 +15,7 @@ Selection-query field based on relation config.
     "addValue": true,
     "relation": {
       "app_id": 1,
-      "table_id": 2,
+      "entity_id": 2,
       "type": "entity",
       "show_fields": [1001],
       "queryFields": [1001],
@@ -32,7 +32,7 @@ Selection-query field based on relation config.
 - `structure`
 - `addValue`
 - `relation.app_id`
-- `relation.table_id`
+- `relation.entity_id`
 - `relation.type`
 - `relation.show_fields`
 - `relation.queryFields`
@@ -41,7 +41,7 @@ Selection-query field based on relation config.
 
 ## Constraints
 
-- `relation.app_id` and `relation.table_id` are required
+- `relation.app_id` and `relation.entity_id` are required
 - `relation.type` must be explicit; use `entity`
 - `relation.show_fields` should be explicit
 - `relation.queryFields` should be explicit in manual mode

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

@@ -14,7 +14,7 @@ Entity relation field.
     "placeholder": "",
     "relation": {
       "app_id": 1,
-      "table_id": 2,
+      "entity_id": 2,
       "type": "entity",
       "show_fields": [1001],
       "queryFields": [1001],
@@ -33,7 +33,7 @@ Entity relation field.
 - `structure`
 - `addValue`
 - `relation.app_id`
-- `relation.table_id`
+- `relation.entity_id`
 - `relation.type`
 - `relation.show_fields`
 - `relation.queryFields`
@@ -44,7 +44,7 @@ Entity relation field.
 
 ## Constraints
 
-- `relation.app_id` and `relation.table_id` are required
+- `relation.app_id` and `relation.entity_id` are required
 - `relation.show_fields` should be explicit
 - `relation.sorts` should include at least one default sort
 - In the current direct-write path, `mode` common values:

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

@@ -12,7 +12,7 @@ Derived field that reads a target value through an existing relation field.
   "options": {
     "relation": {
       "app_id": 1,
-      "table_id": 2,
+      "entity_id": 2,
       "type": "entity"
     }
   }
@@ -22,7 +22,7 @@ Derived field that reads a target value through an existing relation field.
 ## Available options
 
 - `relation.app_id`
-- `relation.table_id`
+- `relation.entity_id`
 - `relation.type`
 - `relation.show_fields`
 - `relation.queryFields`
@@ -33,6 +33,6 @@ Derived field that reads a target value through an existing relation field.
 ## Constraints
 
 - `options.relation` is required
-- `relation.app_id` and `relation.table_id` are required
+- `relation.app_id` and `relation.entity_id` are required
 - use `relation.type = "entity"` in the current direct-write path
 - do not send empty `options`

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

@@ -56,7 +56,7 @@ Status field.
 
 ## Save-ready reminder
 
-For `arcubase-admin entity admin-save-entity`, keep the full base `FieldVO`.
+For `arcubase-admin table update-schema`, keep the full base `FieldVO`.
 
 The field-specific part only covers `options`. The saved field still needs:
 

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

@@ -49,7 +49,7 @@ Single-line text field.
 
 ## Save-ready reminder
 
-For `arcubase-admin entity admin-save-entity`, do not send only `type + options`.
+For `arcubase-admin table update-schema`, do not send only `type + options`.
 
 Wrap this field-specific shape in the full base `FieldVO` described in `entity-schema.md`, including:
 

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

@@ -1,23 +1,25 @@
 # Entity Schema
 
-Use this page when writing the full table schema with `arcubase-admin`.
+Use this page when creating or updating a table schema with `arcubase-admin`.
 
 Primary command:
 
 ```bash
-arcubase-admin entity admin-save-entity \
+arcubase-admin table create \
+  --app-id <app_id> \
+  --body-json <json-string> | --body-file table-create.json
+
+arcubase-admin table update-schema \
   --app-id <app_id> \
   --table-id <table_id> \
-  --body-file save-entity.json
+  --body-json <json-string> | --body-file save-entity.json
 ```
 
-Before writing `save-entity.json`, always fetch the current shell:
+Rules:
 
-```bash
-arcubase-admin entity admin-get-entity-info \
-  --app-id <app_id> \
-  --table-id <table_id>
-```
+- `table create` must include non-empty `fields`; empty table shell creation is not allowed
+- `table update-schema` is for changing an existing table
+- prefer `--body-json` to avoid an extra file operation
 
 If you already know the field type you want, go to:
 
@@ -27,16 +29,16 @@ If you already know the field type you want, go to:
 
 The current direct-write path is:
 
-1. create the entity shell
-2. fetch the current shell
-3. save the full schema
+1. create app
+2. create table with full schema
+3. verify `table get` returns non-empty `fields`
 4. probe rows with `arcubase row query`
 
-Do not treat shell creation as “table created”.
+Do not create or accept a table with empty `fields`.
 
 ## Top-level save payload
 
-The practical save-ready shape is:
+The practical create-ready shape is:
 
 ```json
 {
@@ -55,9 +57,9 @@ The practical save-ready shape is:
 
 Rules:
 
-- start from the current shell
-- reuse `schema_version` from the shell
-- keep `id`, `app_id`, `name`, and `workflow_enabled`
+- for `table create`, omit `id` and `app_id`; CLI fills them after creation
+- for `table update-schema`, keep `id`, `app_id`, `name`, and `workflow_enabled`
+- keep `schema_version` from the current table when updating
 - do not rebuild top-level `options` unless you really need to
 
 ## Shell placeholder normalization
@@ -86,7 +88,8 @@ The CLI already performs this normalization on the direct save path. Your `save-
 ## Global invariants
 
 - `fields` must be `FieldVO[]`
-- field ids should start from `1001`
+- `table create` requires at least one field
+- first field id is `1001`; `1000` is the empty-schema baseline
 - field ids must be positive and non-zero
 - `field_id_seq > max(field.id)`
 - `layout` is `number[][]`
@@ -99,6 +102,9 @@ The CLI already performs this normalization on the direct save path. Your `save-
 - formula references must point to real field ids
 - do not manually add `tags`
 - do not manually add `workflow_status`
+- use `text`, not `string`
+- use `member`, not `user`
+- for `select`, `radio`, `checkbox`, and `status`, use `options.options.items`
 
 ## Generic field shape
 
@@ -148,7 +154,7 @@ 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`.
+This document is for `table create` and `table update-schema`.
 
 Keep that command focused on:
 
@@ -179,8 +185,9 @@ Also:
 
 Do not call schema creation successful until:
 
-1. `arcubase-admin entity admin-save-entity ...` succeeds without top-level `error`
-2. `arcubase row query ...` succeeds against the saved table
+1. `arcubase-admin table create ...` or `arcubase-admin table update-schema ...` succeeds without top-level `error`
+2. `arcubase-admin table get ...` returns non-empty `fields`
+3. `arcubase row query ...` succeeds against the saved table
 
 If row probing still fails, the table is not ready.
 

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

@@ -21,7 +21,7 @@ These examples are not raw tenant exports.
 - 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 \
+arcubase-admin table get \
   --app-id <app_id> \
   --table-id <table_id>
 ```

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

@@ -1,20 +1,39 @@
 # CRM Example 01
 
-This directory is reserved for a generic CRM and quote example set.
+CRM lead, customer, contact, and follow-up example set.
 
-Planned tables:
+## Tables
 
 - `Customer`
 - `Contact`
-- `Quote`
-- `Invoice`
+- `Lead`
+- `Follow Up`
 
-Planned field patterns:
+## Files
 
-- `text`
-- `select`
-- `status`
-- `member`
-- `textarea`
+- `create-app.json`
+- `customer.create-entity.json`
+- `customer.schema.json`
+- `contact.create-entity.json`
+- `contact.schema.json`
+- `lead.create-entity.json`
+- `lead.schema.json`
+- `follow-up.create-entity.json`
+- `follow-up.schema.json`
+- `lead.query.json`
+- `lead.row.insert.json`
+- `lead.selection.condition.json`
+- `lead.bulk-update.json`
 
-All names will remain generic and English-only.
+## Commands
+
+```bash
+arcubase-admin app create --body-file create-app.json | --body-json <json-string>
+arcubase-admin table create --app-id <app_id> --body-file lead.create-entity.json | --body-json <json-string>
+arcubase-admin table get --app-id <app_id> --table-id <table_id>
+arcubase-admin table update-schema --app-id <app_id> --table-id <table_id> --body-file lead.schema.json | --body-json <json-string>
+arcubase row create --app-id <app_id> --table-id <table_id> --body-file lead.row.insert.json | --body-json <json-string>
+arcubase row query --app-id <app_id> --table-id <table_id> --body-file lead.query.json | --body-json <json-string>
+arcubase row bulk-update --app-id <app_id> --table-id <table_id> --body-file lead.bulk-update.json | --body-json <json-string>
+arcubase row selection-action --app-id <app_id> --table-id <table_id> --action archive --body-file lead.selection.condition.json | --body-json <json-string>
+```

package/sdk-dist/docs/runtime-reference/examples/crm-01/contact.create-entity.json

@@ -0,0 +1 @@
+{"name":"Contact"}

package/sdk-dist/docs/runtime-reference/examples/crm-01/contact.schema.json

@@ -0,0 +1 @@
+{"id":"__TABLE_ID__","app_id":"__APP_ID__","name":"Contact","workflow_enabled":false,"fields":[{"id":1001,"label":"Contact Name","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":"contact_name","code_index":false,"options":{},"transfers":null,"children":null},{"id":1002,"label":"Mobile","type":"mobile","required":false,"unique":false,"editable":true,"visible":true,"show_label":true,"scannable":false,"default_value_mode":0,"description":"","value":null,"number_decimal":0,"depends":[],"key":"mobile","code_index":false,"options":{},"transfers":null,"children":null}],"layout":[[1001],[1002]],"options":{},"schema_version":0,"field_id_seq":1003}

package/sdk-dist/docs/runtime-reference/examples/crm-01/create-app.json

@@ -0,0 +1 @@
+{"name":"CRM Example 01"}

package/sdk-dist/docs/runtime-reference/examples/crm-01/customer.create-entity.json

@@ -0,0 +1 @@
+{"name":"Customer"}

package/sdk-dist/docs/runtime-reference/examples/crm-01/customer.schema.json

@@ -0,0 +1 @@
+{"id":"__TABLE_ID__","app_id":"__APP_ID__","name":"Customer","workflow_enabled":false,"fields":[{"id":1001,"label":"Customer Name","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":"customer_name","code_index":false,"options":{},"transfers":null,"children":null},{"id":1002,"label":"Segment","type":"select","required":false,"unique":false,"editable":true,"visible":true,"show_label":true,"scannable":false,"default_value_mode":0,"description":"","value":null,"number_decimal":0,"depends":[],"key":"segment","code_index":false,"options":{"options":{"items":[{"key":1,"value":"Enterprise"},{"key":2,"value":"SMB"}]}},"transfers":null,"children":null}],"layout":[[1001],[1002]],"options":{},"schema_version":0,"field_id_seq":1003}

package/sdk-dist/docs/runtime-reference/examples/crm-01/follow-up.create-entity.json

@@ -0,0 +1 @@
+{"name":"Follow Up"}

package/sdk-dist/docs/runtime-reference/examples/crm-01/follow-up.schema.json

@@ -0,0 +1 @@
+{"id":"__TABLE_ID__","app_id":"__APP_ID__","name":"Follow Up","workflow_enabled":false,"fields":[{"id":1001,"label":"Follow Up At","type":"datetime","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":"follow_up_at","code_index":false,"options":{"type":"date"},"transfers":null,"children":null},{"id":1002,"label":"Notes","type":"textarea","required":false,"unique":false,"editable":true,"visible":true,"show_label":true,"scannable":false,"default_value_mode":0,"description":"","value":null,"number_decimal":0,"depends":[],"key":"notes","code_index":false,"options":{},"transfers":null,"children":null}],"layout":[[1001],[1002]],"options":{},"schema_version":0,"field_id_seq":1003}

package/sdk-dist/docs/runtime-reference/examples/crm-01/lead.bulk-update.json

@@ -0,0 +1 @@
+{"selection":{"type":"condition","condition":{"field":":1002","operator":"eq","value":"new"}},"values":{":1002":"qualified"}}

package/sdk-dist/docs/runtime-reference/examples/crm-01/lead.create-entity.json

@@ -0,0 +1 @@
+{"name":"Lead"}

package/sdk-dist/docs/runtime-reference/examples/crm-01/lead.query.json

@@ -0,0 +1 @@
+{"limit":20,"offset":0,"search":{"text_search":"lead"},"sorts":[{"column":":1001","order":"asc"}]}

package/sdk-dist/docs/runtime-reference/examples/crm-01/lead.row.insert.json

@@ -0,0 +1 @@
+{":1001":"Upgrade opportunity",":1002":"new"}

package/sdk-dist/docs/runtime-reference/examples/crm-01/lead.schema.json

@@ -0,0 +1 @@
+{"id":"__TABLE_ID__","app_id":"__APP_ID__","name":"Lead","workflow_enabled":false,"fields":[{"id":1001,"label":"Lead Title","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":"lead_title","code_index":false,"options":{},"transfers":null,"children":null},{"id":1002,"label":"Lead Status","type":"status","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":"lead_status","code_index":false,"options":{"options":{"items":[{"key":1,"code":"new","value":"New"},{"key":2,"code":"qualified","value":"Qualified"},{"key":3,"code":"lost","value":"Lost"}]}},"transfers":null,"children":null}],"layout":[[1001],[1002]],"options":{},"schema_version":0,"field_id_seq":1003}

package/sdk-dist/docs/runtime-reference/examples/crm-01/lead.selection.condition.json

@@ -0,0 +1 @@
+{"selection":{"type":"condition","condition":{"field":":1002","operator":"eq","value":"lost"}}}