@sparkerp/plugin-sdk 0.1.0

package/bundle/docs/tutorial/01-create-the-plugin.md

@@ -0,0 +1,157 @@
+---
+title: "1. Create the plugin"
+audience: tenant
+---
+
+# 1. Create the plugin
+
+## Scaffold
+
+```bash
+erp plugin create example-plugin --name "Office Equipment" --type business-app
+```
+
+> The folder is `example-plugin/` to match this docs tree. The plugin **id** we
+> use is `office-equipment` — set below. (In real life pick one name and use it
+> for both.)
+
+You get `example-plugin/spk-assembly/` with empty `metadata/*` folders and a
+`plugin.json` with `"mainClass": null`.
+
+## Edit the manifest
+
+`spk-assembly/plugin.json` — the finished version
+([real file](./example-plugin/spk-assembly/plugin.json)):
+
+```json
+{
+  "id": "office-equipment",
+  "name": "Office Equipment",
+  "version": "1.0.3",
+  "type": "business-application",
+  "schemaName": "erp_core",
+  "vendor": "ACME Corp",
+  "license": "Proprietary",
+  "licenseTier": "free",
+  "category": "custom",
+  "erpVersion": "*",
+  "minErpVersion": "1.0",
+  "maxErpVersion": "99.0",
+  "mainClass": null,
+  "dependencies": [],
+  "optionalDependencies": [],
+  "owner": "business",
+  "editable": false,
+  "extendable": true,
+  "capabilitiesProvided": [],
+  "capabilitiesRequired": [],
+  "featureFlags": [],
+  "configSchemaJson": null,
+  "roles": [
+    {
+      "name": "Office Equipment Manager",
+      "code": "OFFICE_EQUIPMENT_MANAGER",
+      "description": "Full control of the Office Equipment module.",
+      "permissionKeys": [
+        "OeqCategory.View", "OeqCategory.Create", "OeqCategory.Edit",
+        "OeqEquipment.View", "OeqEquipment.Create", "OeqEquipment.Edit",
+        "OeqCheckout.View", "OeqCheckout.Create", "OeqCheckout.Submit", "OeqCheckout.Approve",
+        "Dashboard.View"
+      ]
+    }
+  ],
+  "runtimeModes": ["embedded"],
+  "serviceDeployment": null
+}
+```
+
+Key choices:
+
+- **`id: "office-equipment"`** — used in every route, page id, and i18n key
+  from here on. Chosen once.
+- **`role.name` and `role.code`** are prefixed (`Office Equipment Manager` /
+  `OFFICE_EQUIPMENT_MANAGER`). A plain "Equipment Manager" would collide with
+  another installed plugin's role and fail the install — this actually happened
+  while writing the tutorial.
+- **`schemaName: "erp_core"`** — the scaffold default. See the note in
+  [Add an entity](../guides/add-an-entity.md) about when a dedicated schema is
+  worth it; for this module `erp_core` is fine end to end, including the
+  reminder job in chapter 7.
+
+## No Java class
+
+This tutorial module ships **zero Java**. `plugin.json` keeps `"mainClass":
+null` exactly as the scaffold wrote it, and there is no `spk-assembly/lib/`.
+On install the platform loads the plugin through a built-in generic no-op PF4J
+entry point — start/stop/enable/disable/upgrade, migrations, and data seeding
+all run normally. Everything the module does is JSON under
+`spk-assembly/metadata/`.
+
+You would only add a Java class (a `Plugin` subclass, compiled against `pf4j` +
+`slf4j-api`, jar in `spk-assembly/lib/`, `mainClass` set to its FQN) for
+behaviour the Entity / Query / Rule / Workflow / Job engines genuinely can't
+express — this module never needs one.
+
+## The application and module (standalone plugin)
+
+A standalone plugin (one that isn't part of a bigger suite like HCM) ships its
+own application and module so its pages are routable.
+
+`spk-assembly/metadata/application/office-equipment-app.json`
+([real file](./example-plugin/spk-assembly/metadata/application/office-equipment-app.json)):
+
+```json
+{
+  "name": "office-equipment-app",
+  "description": "The Office Equipment plugin's own Application.",
+  "definition": {
+    "id": "office-equipment",
+    "titleKey": "office-equipment.application.title",
+    "urlSlug": "office-equipment",
+    "homeRoute": "/app/office-equipment/equipment/office-equipment/equipment-register",
+    "tier": "solution",
+    "icon": "devices",
+    "color": "#2563EB"
+  }
+}
+```
+
+`spk-assembly/metadata/module/office-equipment-module.json`
+([real file](./example-plugin/spk-assembly/metadata/module/office-equipment-module.json)):
+
+```json
+{
+  "name": "office-equipment",
+  "description": "The single Module the Office Equipment pages attach to.",
+  "definition": {
+    "id": "office-equipment-module",
+    "titleKey": "office-equipment.module.title",
+    "urlSlug": "equipment",
+    "tier": "solution",
+    "icon": "inventory_2",
+    "color": "#2563EB"
+  },
+  "applications": ["office-equipment-app"]
+}
+```
+
+The reachable URL for a page is
+`/app/<app urlSlug>/<module urlSlug>/<pluginId>/<page name>` — so
+`/app/office-equipment/equipment/office-equipment/equipment-register`.
+
+## Verify
+
+```bash
+erp plugin test example-plugin/spk-assembly
+```
+
+```
+Plugin Tests
+────────────────────────────────────────
+✓ plugin.json:valid-json
+1 passed, 0 failed, 0 semantic warning(s), 3 skipped
+```
+
+A healthy empty plugin. Next: give it a table.
+
+**Next:** [2. The equipment category entity + seeded data](./02-category-entity-and-seed.md)

package/bundle/docs/tutorial/02-category-entity-and-seed.md

@@ -0,0 +1,94 @@
+---
+title: "2. The equipment category entity + seeded data"
+audience: tenant
+---
+
+# 2. The equipment category entity + seeded data
+
+## The entity
+
+`spk-assembly/metadata/entities/oeq_category.json`
+([real file](./example-plugin/spk-assembly/metadata/entities/oeq_category.json)):
+
+```json
+{
+  "entity": {
+    "name": "oeq_category",
+    "tableName": "oeq_category",
+    "label": "{\"en\":\"Equipment Category\"}",
+    "category": "office-equipment",
+    "icon": "category",
+    "color": "#2563EB",
+    "pkStrategy": "identity"
+  },
+  "fields": [
+    { "fieldName": "category_code", "label": "\"Category Code\"", "dataType": "text", "nullable": false, "required": true, "isUnique": true, "isIndexed": true, "isDisplayField": true, "displayOrder": 1 },
+    { "fieldName": "category_name", "label": "\"Category Name\"", "dataType": "text", "nullable": false, "required": true, "displayOrder": 2 },
+    { "fieldName": "description", "label": "\"Description\"", "dataType": "text", "nullable": true, "required": false, "displayOrder": 3 },
+    { "fieldName": "status", "label": "\"Status\"", "dataType": "enum", "nullable": false, "required": true, "isIndexed": true, "defaultValue": "ACTIVE", "typeParams": "{\"enumValues\":[\"ACTIVE\",\"INACTIVE\"]}", "displayOrder": 4 },
+    { "fieldName": "seeded_by", "label": "\"Seeded By\"", "dataType": "text", "nullable": true, "required": false, "displayOrder": 5 }
+  ]
+}
+```
+
+Note the two JSON-encoding rules: `entity.label` is `"{\"en\":\"...\"}"` (an
+i18n object as a string), each field `label` is `"\"...\""` (a JSON string
+literal). A bare string in either place fails the install.
+
+`seeded_by` is a plain text column the seeder will stamp with the plugin id.
+
+## The seed data
+
+`spk-assembly/metadata/seed-data/office-equipment-categories.json`
+([real file](./example-plugin/spk-assembly/metadata/seed-data/office-equipment-categories.json)):
+
+```json
+{
+  "entity": "oeq_category",
+  "keyFields": ["category_code"],
+  "source": "office-equipment",
+  "rows": [
+    { "category_code": "LAPTOP",  "category_name": "Laptops",  "description": "Portable computers", "status": "ACTIVE", "seeded_by": "office-equipment" },
+    { "category_code": "MONITOR", "category_name": "Monitors", "description": "External displays",  "status": "ACTIVE", "seeded_by": "office-equipment" },
+    { "category_code": "PHONE",   "category_name": "Phones",   "description": "Mobile handsets",    "status": "ACTIVE", "seeded_by": "office-equipment" },
+    { "category_code": "HEADSET", "category_name": "Headsets", "description": "Audio headsets",     "status": "ACTIVE", "seeded_by": "office-equipment" }
+  ]
+}
+```
+
+- `keyFields: ["category_code"]` — the natural key. Re-installs match on this and
+  never duplicate.
+- `source: "office-equipment"` — stamped into `seeded_by`.
+
+## Verify
+
+```bash
+erp schema validate spk-assembly/metadata/entities/oeq_category.json --schema entity-definition
+erp schema validate spk-assembly/metadata/seed-data/office-equipment-categories.json --schema plugin-seed-data
+```
+
+Both print `OK — ... matches schema ...`.
+
+After the module is published (chapter 8), this is what the seeding did — from
+the real install log:
+
+```
+PluginDataSeedInstaller: office-equipment-categories.json -> entity oeq_category (tenant 2): 4 created, 0 updated, 0 unchanged
+```
+
+and the rows are live:
+
+```bash
+$ erp api get "/api/v1/entities/oeq_category/records/query?size=10"
+{ "rows": [
+  { "id": 1, "category_code": "LAPTOP",  "category_name": "Laptops",  "status": "ACTIVE", "seeded_by": "office-equipment" },
+  { "id": 2, "category_code": "MONITOR", "category_name": "Monitors", "status": "ACTIVE", "seeded_by": "office-equipment" },
+  { "id": 3, "category_code": "PHONE",   "category_name": "Phones",   "status": "ACTIVE", "seeded_by": "office-equipment" },
+  { "id": 4, "category_code": "HEADSET", "category_name": "Headsets", "status": "ACTIVE", "seeded_by": "office-equipment" }
+], "total": 4 }
+```
+
+Publish again with a fifth category and only that one is inserted — the seeder is
+idempotent by `keyFields`.
+
+**Next:** [3. The equipment register entity](./03-equipment-entity.md)

package/bundle/docs/tutorial/03-equipment-entity.md

@@ -0,0 +1,121 @@
+---
+title: "3. The equipment register entity"
+audience: tenant
+---
+
+# 3. The equipment register entity
+
+## The entity
+
+`spk-assembly/metadata/entities/oeq_equipment.json`
+([real file](./example-plugin/spk-assembly/metadata/entities/oeq_equipment.json)):
+
+```json
+{
+  "entity": {
+    "name": "oeq_equipment",
+    "tableName": "oeq_equipment",
+    "label": "{\"en\":\"Equipment\"}",
+    "category": "office-equipment",
+    "icon": "devices",
+    "color": "#2563EB",
+    "pkStrategy": "identity"
+  },
+  "fields": [
+    { "fieldName": "asset_tag", "label": "\"Asset Tag\"", "dataType": "text", "nullable": false, "required": true, "isUnique": true, "isIndexed": true, "isDisplayField": true, "displayOrder": 1 },
+    { "fieldName": "name", "label": "\"Name\"", "dataType": "text", "nullable": false, "required": true, "displayOrder": 2 },
+    { "fieldName": "category_id", "label": "\"Category Id\"", "dataType": "long", "nullable": true, "required": false, "isIndexed": true, "displayOrder": 3 },
+    { "fieldName": "category_name", "label": "\"Category\"", "dataType": "text", "nullable": true, "required": false, "displayOrder": 4 },
+    { "fieldName": "serial_number", "label": "\"Serial Number\"", "dataType": "text", "nullable": true, "required": false, "displayOrder": 5 },
+    { "fieldName": "status", "label": "\"Status\"", "dataType": "enum", "nullable": false, "required": true, "isIndexed": true, "defaultValue": "AVAILABLE", "typeParams": "{\"enumValues\":[\"AVAILABLE\",\"ASSIGNED\",\"MAINTENANCE\",\"RETIRED\"]}", "displayOrder": 6 },
+    { "fieldName": "purchase_date", "label": "\"Purchase Date\"", "dataType": "date", "nullable": true, "required": false, "displayOrder": 7 },
+    { "fieldName": "warranty_expiry_date", "label": "\"Warranty Expiry Date\"", "dataType": "date", "nullable": true, "required": false, "displayOrder": 8 },
+    { "fieldName": "notes", "label": "\"Notes\"", "dataType": "text", "nullable": true, "required": false, "displayOrder": 9 }
+  ]
+}
+```
+
+## Design notes
+
+- **`category_id` (long) + `category_name` (text)** — we *denormalize* the
+  category name so the grid can show it without a join. The create dialog writes
+  both. (The alternative — a `reference` flag — needs a registered provider;
+  chapter 5 uses that for the employee field, where one exists.)
+- **`status` enum** with `AVAILABLE` as default.
+- **`asset_tag`** is `isDisplayField` and `isUnique`.
+
+## The provider
+
+Every entity you want a grid over needs a data provider.
+`spk-assembly/metadata/provider/oeq-equipment-provider.json`
+([real file](./example-plugin/spk-assembly/metadata/provider/oeq-equipment-provider.json)):
+
+```json
+{
+  "name": "oeq-equipment-provider",
+  "description": "Data Provider for oeq_equipment (grid + CRUD).",
+  "definition": {
+    "kind": "rest",
+    "connectionRef": "self",
+    "basePath": "/api/v1/entities/oeq_equipment/records",
+    "supports": ["search", "get", "create", "update"]
+  },
+  "metadata": {}, "modules": []
+}
+```
+
+## The category lookup plumbing
+
+The register page's create dialog will have a **category picker**. That needs a
+Data View producing `{ value, label }` pairs and a `search` Data Service over it.
+
+`spk-assembly/metadata/data_view/oeq-category-select-options-view.json`
+([real file](./example-plugin/spk-assembly/metadata/data_view/oeq-category-select-options-view.json)) —
+selects `t.id` as `value` and a concatenated `category_code - category_name` as
+`label`.
+
+`spk-assembly/metadata/data_service/oeq-category-search.json`
+([real file](./example-plugin/spk-assembly/metadata/data_service/oeq-category-search.json)):
+
+```json
+{
+  "name": "oeq-category-search",
+  "description": "Typeahead category search for the category lookup field.",
+  "definition": {
+    "operation": "search",
+    "source": { "kind": "dataView", "dataViewName": "oeq-category-select-options-view" },
+    "filters": [ { "field": "t.category_name", "operator": "contains", "value": "${param.search}" } ],
+    "parameters": [ { "name": "search", "type": "string" } ]
+  },
+  "metadata": {}, "modules": []
+}
+```
+
+## The KPI Data Services
+
+The register page shows Total / Available / Assigned. Three `count` services plus
+a `composite`:
+
+- `oeq-equipment-count-total.json` — `count`, no filter
+- `oeq-equipment-count-available.json` — `count`, `filters: [{ "field": "status", "operator": "eq", "value": "AVAILABLE" }]`
+- `oeq-equipment-count-assigned.json` — `count`, filter `status = ASSIGNED`
+- `oeq-equipment-kpis.json` — `composite` with three steps `total`/`available`/`assigned`
+
+([all four real files](./example-plugin/spk-assembly/metadata/data_service/))
+
+## Verify
+
+```bash
+node developer-docs/examples/test-examples.mjs
+```
+
+validates every one of these files against its schema. After publishing:
+
+```bash
+$ erp api post "/api/v1/data-services/oeq-equipment-kpis/execute" --body "{}"
+{ "results": { "total": { "value": 0 }, "available": { "value": 0 }, "assigned": { "value": 0 } } }
+```
+
+That `results.<step>.value` shape is what the page will bind.
+
+**Next:** [4. The equipment register page](./04-equipment-register-page.md)

package/bundle/docs/tutorial/04-equipment-register-page.md

@@ -0,0 +1,153 @@
+---
+title: "4. The equipment register page"
+audience: tenant
+---
+
+# 4. The equipment register page
+
+The full page file is large — every widget is spelled out — so read
+[`equipment-register.json`](./example-plugin/spk-assembly/metadata/page/equipment-register.json)
+open in another tab. This chapter walks its structure section by section.
+
+## The wrapper
+
+```json
+{
+  "name": "equipment-register",
+  "description": "Office Equipment tutorial - Equipment Register.",
+  "definition": {
+    "contractVersion": 1,
+    "id": "office-equipment.equipment-register",
+    "version": "1.0.0",
+    "publisher": "office-equipment",
+    "title": "office-equipment.equipment-register.title",
+    "usesAppShell": true,
+    "route": { "pattern": "/office-equipment/equipment-register", "params": [] },
+    "designer": {
+      "displayNameKey": "office-equipment.equipment-register.title",
+      "descriptionKey": "office-equipment.equipment-register.title",
+      "icon": "devices", "category": "list", "propertyGroups": [], "preview": { "kind": "page" }
+    },
+    "rows": [ { "id": "row-1", "columns": [ { "id": "col-1", "items": [ /* the 6 sections */ ] } ] } ]
+  },
+  "metadata": { "dataSource": "oeq-equipment-provider" },
+  "modules": ["office-equipment"]
+}
+```
+
+- **`metadata.dataSource: "oeq-equipment-provider"`** — the whole grid wiring. It
+  matches the provider file's `name`. Page-level.
+- **`modules: ["office-equipment"]`** — the module `name`, so the page lists in
+  the sidenav.
+- **`id`** must be `<pluginId>.<name>`.
+
+## Section 1 — the mount loader
+
+A hidden `core.container` whose `mounted` event calls the KPI composite and
+seeds page state:
+
+```json
+"events": { "mounted": { "source": "action-chain", "actions": [
+  { "id": "a0", "order": 0, "type": "callApi",
+    "config": { "connectionRef": "self", "path": "/api/v1/data-services/oeq-equipment-kpis/execute", "httpMethod": "POST", "params": {} },
+    "output": "kpi" },
+  { "id": "a1", "order": 1, "type": "setValue", "config": { "field": "page.kpiTotal",     "value": "${kpi.results.total.value}" } },
+  { "id": "a2", "order": 2, "type": "setValue", "config": { "field": "page.kpiAvailable", "value": "${kpi.results.available.value}" } },
+  { "id": "a3", "order": 3, "type": "setValue", "config": { "field": "page.kpiAssigned",  "value": "${kpi.results.assigned.value}" } },
+  { "id": "a4", "order": 4, "type": "setValue", "config": { "field": "page.gridRefreshTick", "value": 0 } },
+  { "id": "a5", "order": 5, "type": "setValue", "config": { "field": "page.formDialogOpen", "value": false } }
+] } }
+```
+
+`${kpi.results.total.value}` — composite response shape. This was verified live.
+
+## Section 2 — the header
+
+A flex `core.container` with the title/subtitle labels on the left and two
+buttons on the right: **Export CSV** (a `downloadFile` action to
+`/api/v1/entities/oeq_equipment/records/export?format=csv`) and **New** (clears
+the form keys, opens the dialog).
+
+## Section 3 — the KPI row
+
+Three `core.kpi-card` blocks bound to `page.kpiTotal` / `kpiAvailable` /
+`kpiAssigned`, each with a `labelKey`, `format: "number"`, `colorToken`, `icon`.
+
+## Section 4 — the filter row
+
+A `core.text-input` bound to `page.gridExternalFilter.search` and a
+`core.select` bound to `page.gridExternalFilter.status`. Each has a `committed`
+handler writing `${event.new}` back to its key.
+
+## Section 5 — the grid
+
+```json
+{
+  "blockType": "core.grid",
+  "properties": {
+    "columns": { "source": "static", "value": [
+      { "name": "asset_tag", "type": "string", "headerKey": "office-equipment.equipment-register.column.asset_tag" },
+      { "name": "name", "type": "string", "headerKey": "...column.name" },
+      { "name": "category_name", "type": "string", "headerKey": "...column.category_name" },
+      { "name": "serial_number", "type": "string", "headerKey": "...column.serial_number" },
+      { "name": "status", "type": "string", "headerKey": "...column.status", "renderAs": "chip",
+        "colorMap": { "AVAILABLE": "success", "ASSIGNED": "info", "MAINTENANCE": "warning", "RETIRED": "default" } }
+    ] },
+    "pageSize": { "source": "static", "value": 25 },
+    "externalFilter": { "source": "binding", "binding": { "scope": "page", "key": "gridExternalFilter" } },
+    "refreshTrigger": { "source": "binding", "binding": { "scope": "page", "key": "gridRefreshTick" } }
+  }
+}
+```
+
+The grid has **no** data property — it reads the page's `metadata.dataSource`.
+`category_name` shows the denormalized value.
+
+## Section 6 — the create dialog
+
+A `core.dialog` bound to `page.formDialogOpen`. Inside: text inputs for asset
+tag, name, serial number, notes; a `core.select` for status; `core.date-picker`
+for the two dates; and a **`core.lookup`** for the category:
+
+```json
+{
+  "blockType": "core.lookup",
+  "properties": {
+    "value": { "source": "binding", "binding": { "scope": "page", "key": "formCategoryId" } },
+    "recordType": { "source": "static", "value": "OeqCategory" },
+    "optionsSourceKey": { "source": "static", "value": "oeq-category-search" }
+  },
+  "events": { "committed": { "source": "action-chain", "actions": [
+    { "id": "a0", "order": 0, "type": "setValue", "config": { "field": "page.formCategoryId", "value": "${event.new}" } }
+  ] } }
+}
+```
+
+The Save button `POST`s to `/api/v1/entities/oeq_equipment/records` with a
+`params` map built from `${page.form*}`, closes the dialog, toggles
+`page.gridRefreshTick`, and shows a toast.
+
+## Verify
+
+```bash
+erp plugin test example-plugin/spk-assembly
+```
+
+```
+✓ page:equipment-register.json
+4 passed, 0 failed, 0 semantic warning(s), 3 skipped
+```
+
+`0 semantic warning(s)` means PAGE-DS-001 (data source wiring) and I18N-001
+(missing keys) both passed. After publish, drive the Save chain from the API:
+
+```bash
+$ erp api post "/api/v1/entities/oeq_equipment/records" \
+    --body '{"asset_tag":"LAP-001","name":"Dell Latitude 7440","category_id":1,"category_name":"Laptops","status":"AVAILABLE"}'
+{ "id": 1, "asset_tag": "LAP-001", "name": "Dell Latitude 7440", "status": "AVAILABLE",
+  "created_by": "you@example.com", "created_at": "2026-09-10T08:08:33.282+00:00" }
+```
+
+That row now appears in the grid.
+
+**Next:** [5. The checkout entity, page, and lookups](./05-checkout-entity-and-page.md)

package/bundle/docs/tutorial/05-checkout-entity-and-page.md

@@ -0,0 +1,116 @@
+---
+title: "5. The checkout entity, page, and lookups"
+audience: tenant
+---
+
+# 5. The checkout entity, page, and lookups
+
+## The entity
+
+`spk-assembly/metadata/entities/oeq_checkout.json`
+([real file](./example-plugin/spk-assembly/metadata/entities/oeq_checkout.json)):
+
+```json
+{
+  "entity": {
+    "name": "oeq_checkout",
+    "tableName": "oeq_checkout",
+    "label": "{\"en\":\"Equipment Checkout\"}",
+    "category": "office-equipment",
+    "icon": "assignment_ind",
+    "color": "#2563EB",
+    "pkStrategy": "identity"
+  },
+  "fields": [
+    { "fieldName": "checkout_number", "label": "\"Checkout Number\"", "dataType": "text", "nullable": false, "required": true, "isUnique": true, "isIndexed": true, "isDisplayField": true, "displayOrder": 1 },
+    { "fieldName": "equipment_id", "label": "\"Equipment Id\"", "dataType": "long", "nullable": false, "required": true, "isIndexed": true, "displayOrder": 2 },
+    { "fieldName": "equipment_tag", "label": "\"Equipment\"", "dataType": "text", "nullable": true, "required": false, "displayOrder": 3 },
+    { "fieldName": "employee_id", "label": "\"Employee Id\"", "dataType": "long", "nullable": false, "required": true, "isIndexed": true, "flags": "{\"reference\":{\"entityType\":\"Employee\"}}", "displayOrder": 4 },
+    { "fieldName": "checkout_date", "label": "\"Checkout Date\"", "dataType": "date", "nullable": false, "required": true, "displayOrder": 5 },
+    { "fieldName": "due_date", "label": "\"Due Date\"", "dataType": "date", "nullable": false, "required": true, "isIndexed": true, "displayOrder": 6 },
+    { "fieldName": "purpose", "label": "\"Purpose\"", "dataType": "text", "nullable": true, "required": false, "displayOrder": 9 },
+    { "fieldName": "status", "label": "\"Status\"", "dataType": "enum", "nullable": false, "required": true, "isIndexed": true, "defaultValue": "DRAFT", "typeParams": "{\"enumValues\":[\"DRAFT\",\"PENDING_APPROVAL\",\"APPROVED\",\"CHECKED_OUT\",\"DUE_SOON\",\"OVERDUE\",\"RETURNED\",\"REJECTED\"]}", "displayOrder": 10 }
+  ]
+}
+```
+
+### The reference flag
+
+```json
+"flags": "{\"reference\":{\"entityType\":\"Employee\"}}"
+```
+
+on `employee_id` turns on automatic id → name resolution. Every read of an
+`oeq_checkout` row now includes a sibling `employee_id_label`. **Verified live:**
+
+```bash
+$ erp api post "/api/v1/entities/oeq_checkout/records" \
+    --body '{"checkout_number":"CO-001","equipment_id":3,"employee_id":1,"checkout_date":"2026-09-10","due_date":"2026-10-10","status":"CHECKED_OUT"}'
+{ "id": 1, "checkout_number": "CO-001", "employee_id": 1,
+  "employee_id_label": "Aria Chen", "status": "CHECKED_OUT" }
+```
+
+`"Employee"` is a registered provider (backed by the HCM employee plugin), so the
+flag works. For `equipment` — which is *your own* entity, with no registered
+provider — we denormalize `equipment_tag` instead.
+
+### The status enum
+
+`DUE_SOON` and `OVERDUE` are in the enum because the reminder job (chapter 7)
+flips the status into them.
+
+## The lookups
+
+The checkout create dialog needs an **equipment** picker and an **employee**
+picker.
+
+- **Equipment** — your own entity, so build the pair:
+  `oeq-equipment-select-options-view.json` (Data View: `t.id` → `value`,
+  `asset_tag - name` → `label`) and `oeq-equipment-search.json` (`search` Data
+  Service over it). The dialog's `core.lookup` sets
+  `optionsSourceKey: "oeq-equipment-search"`.
+- **Employee** — a registered reference type. The `core.lookup` sets
+  `optionsSourceKey: "employee-search"` (the platform-provided search service)
+  and `recordType: "Employee"`.
+
+## The page
+
+[`equipment-checkout.json`](./example-plugin/spk-assembly/metadata/page/equipment-checkout.json)
+follows the same 6-section shape as the register page, with two differences:
+
+1. **KPIs** are Currently Out / Overdue, from `oeq-checkout-kpis` (a `composite`
+   of `count` services filtered on `status = CHECKED_OUT` and `status = OVERDUE`).
+2. **A detail dialog.** The grid's `rowClicked` fetches the record into
+   `page.detailRecord` and opens `page.detailDialogOpen`. Inside, an overview
+   card shows `detailRecord.checkout_number`, `equipment_tag`,
+   `employee_id_label`, `status`, and an actions card with a **Submit for
+   approval** button (chapter 6) and a Close button.
+
+The grid's status column chip map includes the new values:
+
+```json
+"colorMap": { "DRAFT": "default", "PENDING_APPROVAL": "warning", "APPROVED": "info",
+              "CHECKED_OUT": "success", "DUE_SOON": "warning", "OVERDUE": "error",
+              "RETURNED": "default", "REJECTED": "error" }
+```
+
+## Verify
+
+```bash
+erp plugin test example-plugin/spk-assembly
+```
+
+```
+✓ page:equipment-checkout.json
+✓ page:equipment-register.json
+✓ page:equipment-catalog.json
+```
+
+After publish, the reference flag and the KPI service:
+
+```bash
+$ erp api post "/api/v1/data-services/oeq-checkout-kpis/execute" --body "{}"
+{ "results": { "open": { "value": 1 }, "overdue": { "value": 0 } } }
+```
+
+**Next:** [6. The checkout approval workflow](./06-checkout-approval-workflow.md)