@carthooks/arcubase-cli 0.1.2 → 0.1.4

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.

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

@@ -0,0 +1,21 @@
+# MES Example 01
+
+This directory is reserved for a generic manufacturing execution example set.
+
+Planned tables:
+
+- `Work Order`
+- `Bill Of Material`
+- `Routing Template`
+- `Production Checkpoint`
+
+Planned field patterns:
+
+- `subform`
+- `relation`
+- `relationfield`
+- `datasets`
+- `member`
+- `status`
+
+All names will remain generic and English-only.

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

@@ -0,0 +1,183 @@
+# OMS Example 01
+
+This example set models a compact order-management workflow.
+
+It is intentionally generic:
+
+- no tenant name
+- no company name
+- no country-specific codes
+- no region-specific channel names
+
+## Scope
+
+This set includes:
+
+- `Item Master`
+- `Goods Receipt`
+- `Stock Issue`
+- `Picking List`
+- `Sales Order`
+- `Purchase Order`
+
+## Why these tables
+
+This combination is enough to cover:
+
+- item master records
+- inbound stock
+- outbound stock
+- picking operations
+- sales orders with line items
+- purchase orders with planned and actual receipt subforms
+
+## Important genericization choices
+
+The production references contained market-specific naming such as:
+
+- local barcode naming
+- local purchase wording
+- local shipping wording
+- language-specific labels
+
+This example rewrites them into generic names such as:
+
+- `sku_code`
+- `source_channel`
+- `recipient_name`
+- `goods_receipt`
+- `stock_issue`
+
+## Files
+
+- `app-overview.md`
+- `create-app.json`
+- `sales-order.create-entity.json`
+- `item-master.create-entity.json`
+- `item-master.schema.json`
+- `goods-receipt.schema.json`
+- `stock-issue.schema.json`
+- `picking-list.schema.json`
+- `sales-order.schema.json`
+- `purchase-order.schema.json`
+- `goods-receipt.create-entity.json`
+- `stock-issue.create-entity.json`
+- `picking-list.create-entity.json`
+- `purchase-order.create-entity.json`
+- `sales-order.row.insert.json`
+- `sales-order.query.json`
+- `sales-order.selection.ids.json`
+- `sales-order.selection.condition.json`
+- `sales-order.bulk-update.json`
+
+## Save workflow
+
+For every `*.schema.json` file:
+
+1. create the entity shell
+2. fetch the shell with `admin-get-entity-info`
+3. replace:
+   - `__APP_ID__`
+   - `__ENTITY_ID__`
+   - `__SCHEMA_VERSION__`
+4. save the schema with `admin-save-entity`
+5. probe rows with `query-entity`
+
+These schema files are templates, not live shell exports.
+
+## CLI phases
+
+Phase 1 uses `arcubase-admin`:
+
+- create the app
+- create entity shells
+- fetch shells
+- save schemas
+
+Phase 2 uses `arcubase`:
+
+- insert rows
+- query rows
+- update rows
+- delete or restore rows
+- search, selection, and bulk actions
+
+Do not use `arcubase-admin` for row operations.
+
+## Minimal command path
+
+Create the app:
+
+```bash
+arcubase-admin app create-app-by-tenants --body-file create-app.json
+```
+
+Create the shell:
+
+```bash
+arcubase-admin app create-entity --id <app_id> --body-file sales-order.create-entity.json
+arcubase-admin app create-entity --id <app_id> --body-file item-master.create-entity.json
+arcubase-admin app create-entity --id <app_id> --body-file goods-receipt.create-entity.json
+arcubase-admin app create-entity --id <app_id> --body-file stock-issue.create-entity.json
+arcubase-admin app create-entity --id <app_id> --body-file picking-list.create-entity.json
+arcubase-admin app create-entity --id <app_id> --body-file purchase-order.create-entity.json
+```
+
+Fetch the shell:
+
+```bash
+arcubase-admin entity admin-get-entity-info --app-id <app_id> --entity-id <entity_id>
+```
+
+Save the schema:
+
+```bash
+arcubase-admin entity admin-save-entity --app-id <app_id> --entity-id <entity_id> --body-file sales-order.schema.json
+arcubase-admin entity admin-save-entity --app-id <app_id> --entity-id <entity_id> --body-file item-master.schema.json
+arcubase-admin entity admin-save-entity --app-id <app_id> --entity-id <entity_id> --body-file goods-receipt.schema.json
+arcubase-admin entity admin-save-entity --app-id <app_id> --entity-id <entity_id> --body-file stock-issue.schema.json
+arcubase-admin entity admin-save-entity --app-id <app_id> --entity-id <entity_id> --body-file picking-list.schema.json
+arcubase-admin entity admin-save-entity --app-id <app_id> --entity-id <entity_id> --body-file purchase-order.schema.json
+```
+
+Insert one row:
+
+```bash
+arcubase workflow insert-entity --app-id <app_id> --entity-id <entity_id> --body-file sales-order.row.insert.json
+```
+
+Query rows:
+
+```bash
+arcubase workflow query-entity --app-id <app_id> --entity-id <entity_id> --body-file sales-order.query.json
+```
+
+## Placeholder rules
+
+The schema files use placeholders for:
+
+- `__APP_ID__`
+- `__ENTITY_ID__`
+- `__SCHEMA_VERSION__`
+
+The relation-based templates also use:
+
+- `__ITEM_MASTER_ENTITY_ID__`
+
+When you replace them, keep these fields as JSON numbers:
+
+- `app_id`
+- `id`
+- `schema_version`
+- relation `app_id`
+- relation `entity_id`
+
+Do not leave the replaced values as JSON strings.
+
+## Dependency order
+
+`Goods Receipt` and `Stock Issue` both depend on an existing `Item Master` entity.
+
+Create and save `Item Master` first, then replace `__ITEM_MASTER_ENTITY_ID__`
+with the numeric entity id of that local `Item Master` shell before you save the
+dependent schemas.

package/sdk-dist/docs/runtime-reference/examples/oms-01/app-overview.md

@@ -0,0 +1,79 @@
+# OMS Example 01 Overview
+
+## Table set
+
+### 1. Item Master
+
+Purpose:
+
+- hold the canonical item record
+- provide `sku_code`
+- provide item naming and pricing
+
+### 2. Goods Receipt
+
+Purpose:
+
+- record inbound quantities
+- link a receipt row to one item
+
+### 3. Stock Issue
+
+Purpose:
+
+- record outbound quantities
+- link an issue row to one item
+
+### 4. Picking List
+
+Purpose:
+
+- group picked items for fulfillment
+- use a subform for item lines
+
+### 5. Sales Order
+
+Purpose:
+
+- capture recipient information
+- capture one order with multiple line items
+- support search, selection, and bulk update examples
+
+### 6. Purchase Order
+
+Purpose:
+
+- capture ordered quantities
+- track planned receipt slots
+- track actual receipt slots
+- show one `status` field example and two `subform` examples
+
+## Relationship model
+
+- `Goods Receipt` links to `Item Master`
+- `Stock Issue` links to `Item Master`
+- `Sales Order` has `line_items` as a subform
+- `Picking List` has `items` as a subform
+- `Purchase Order` has:
+  - `planned_receipts`
+  - `actual_receipts`
+
+## Field patterns covered
+
+- `text`
+- `textarea`
+- `number`
+- `datetime`
+- `select`
+- `radio`
+- `status`
+- `image`
+- `relation`
+- `subform`
+
+## What was intentionally removed
+
+- country-specific code naming
+- tenant-specific internal labels
+- region-specific channel names
+- company-specific workflow terms

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

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

package/sdk-dist/docs/runtime-reference/examples/oms-01/goods-receipt.create-entity.json

@@ -0,0 +1,3 @@
+{
+  "name": "Goods Receipt"
+}