cabloy 5.1.59 → 5.1.61

package/cabloy-docs/fullstack/frontend-metadata-to-backend.md

@@ -1,11 +1,13 @@
 # Frontend Metadata Back to Backend
 
-This page documents the reverse direction of Cabloy’s fullstack collaboration loop: frontend-generated metadata that improves backend-side development and tooling.
+This page is the **reverse chain** deep dive for Cabloy’s bidirectional contract loop: frontend-generated metadata that improves backend-side development and tooling.
 
 ## Why this path matters
 
 The fullstack collaboration loop in Cabloy is not one-way.
 
+In the bidirectional [Contract Loop Playbook](/fullstack/contract-loop-playbook), this page covers the **reverse chain**.
+
 For the forward contract-bridge direction from backend OpenAPI to frontend consumption, also see [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
 
 The backend does not only feed the frontend through OpenAPI. The frontend also generates information that can improve backend-side type hints and integration confidence.
@@ -44,6 +46,8 @@ A practical collaboration loop often looks like this:
 
 ## Edition awareness
 
+The reverse-chain mental model applies to both Cabloy Basic and Cabloy Start.
+
 This path is especially sensitive to edition differences because Basic and Start do not expose the same frontend module and UI shape.
 
 So when AI reasons about frontend-generated metadata, it should verify:
@@ -51,6 +55,7 @@ So when AI reasons about frontend-generated metadata, it should verify:
 - which repo is active
 - which flavor is active
 - which generated output belongs to that edition
+- which concrete build and sync commands belong to that edition
 
 ## Implementation checks for frontend-metadata changes
 
@@ -62,3 +67,41 @@ When changing frontend structural resources such as routes or components, ask:
 4. should the next action be generation and verification rather than only source edits?
 
 That keeps the reverse contract loop visible instead of accidental.
+
+## When backend consumes newly added frontend resources
+
+This reverse handoff matters most when you create or change frontend resources that backend-side workflows will later consume, such as:
+
+- custom form-field renderers
+- custom table-cell renderers
+- other generated frontend metadata that backend `ZovaRender.*(...)` references depend on
+
+In that case, do not stop after source edits alone. Use this representative sequence:
+
+1. regenerate frontend metadata when applicable
+2. build the relevant frontend flavor output so the shared REST/type surface is refreshed
+3. run `npm run deps:vona` so Vona re-syncs its local file dependencies
+4. if generated `.zova-rest` output already contains the expected new keys or types but backend-side consumers still look stale, rebuild `vona/node_modules` and reinstall dependencies
+
+For the current Cabloy Basic admin flow, the representative commands are:
+
+```bash
+npm run zova :tools:metadata <module-name>
+npm run build:zova:admin
+npm run deps:vona
+```
+
+If the same resource path must also be available for Web, add:
+
+```bash
+npm run build:zova:web
+npm run deps:vona
+```
+
+If Vona still cannot see the refreshed shared types after the normal sync flow, use this recovery path:
+
+```bash
+cd vona && rm -rf node_modules && pnpm install
+```
+
+The key rule is simple: if frontend-generated resources are later consumed by backend tooling or backend metadata, treat the work as a reverse fullstack handoff, not as frontend-only cleanup.

package/cabloy-docs/fullstack/introduction.md

@@ -62,6 +62,46 @@ Use this path when the task depends on edition boundaries, UI assumptions, or cr
 
 This combination keeps backend and frontend development close enough for code sharing, workflow reuse, and AI vibe coding workflows.
 
+## Cabloy fullstack framework principles
+
+Cabloy’s fullstack model can be understood through two core principles.
+
+### 1. Frontend build output participates directly in backend SSR
+
+Zova owns the frontend application, but its build output is not treated as a completely separate artifact that the backend ignores.
+
+In Cabloy’s fullstack flow:
+
+- the frontend is built from Zova source
+- the generated bundle and related SSR output are consumed by the Vona-side SSR runtime
+- backend rendering and frontend hydration stay in one coordinated SSR path rather than two unrelated systems
+
+In earlier standalone-repo explanations, this was often described as placing the frontend bundle into the backend for direct SSR rendering. In the current monorepo, the important principle stays the same while the workflow is cleaner: shared scripts and integrated repository structure let frontend build artifacts flow into the backend-side SSR process.
+
+For the integration workflow and current monorepo shape, see [Vona + Zova Integration](/fullstack/vona-zova-integration) and [SSR Overview](/frontend/ssr-overview).
+
+### 2. Type information flows in both directions
+
+Cabloy does not treat type sharing as backend-to-frontend only. The collaboration loop is bidirectional:
+
+- **Backend → Frontend**: Vona emits Swagger/OpenAPI contracts that Zova uses to generate frontend SDKs and related schema-aware helpers
+- **Frontend → Backend**: Zova generates structural metadata and types such as routes, components, and icons, which can be reflected back into backend-side tooling and type hints
+
+This two-way contract loop reduces duplicate declarations and lets backend and frontend evolve from generated source truth instead of hand-maintained memory.
+
+Start with the canonical [Contract Loop Playbook](/fullstack/contract-loop-playbook), then use the directional deep dives [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) and [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend).
+
+Use the playbook to distinguish four cases clearly:
+
+- forward chain
+- reverse chain
+- consumer drift
+- local dependency drift
+
+The contract-loop model is shared across Cabloy Basic and Cabloy Start. Detect the edition to choose concrete flavor commands and generated-output paths, not to redefine the workflow model.
+
+When the reverse direction involves newly added frontend resources that backend tooling or backend metadata will consume, treat that as an operational handoff rather than a conceptual one: refresh generated frontend output, run the relevant flavor build, run `npm run deps:vona`, and if Vona still sees stale shared types, rebuild `vona/node_modules` and reinstall dependencies.
+
 ## How the fullstack system stays connected
 
 At the repository level, shared scripts, shared terminology, and CLI-first workflows keep Vona and Zova aligned as one framework system.

package/cabloy-docs/fullstack/openapi-to-sdk.md

@@ -1,10 +1,10 @@
 # Backend OpenAPI to Frontend SDK
 
-This page turns one of Cabloy’s most important fullstack collaboration paths into an explicit guide.
+This page is the **forward chain** deep dive for Cabloy’s bidirectional contract loop.
 
 ## Why this path matters
 
-Cabloy’s fullstack productivity depends heavily on a contract loop:
+In the bidirectional [Contract Loop Playbook](/fullstack/contract-loop-playbook), this page covers the **forward chain**:
 
 1. Vona emits backend API metadata through Swagger/OpenAPI
 2. Zova consumes that metadata to generate frontend SDKs and schema-aware helpers
@@ -12,7 +12,7 @@ Cabloy’s fullstack productivity depends heavily on a contract loop:
 
 This is one of the strongest AI-leverage paths in the repo because it reduces duplicated type work and keeps backend/frontend coordination closer to source truth.
 
-## The contract loop in practical terms
+## The forward chain in practical terms
 
 A useful split is:
 
@@ -20,7 +20,9 @@ A useful split is:
 - fullstack docs define the bridge from emitted contract to generated SDK
 - frontend docs define the consumption side of the generated contract
 
-That means this page is the fullstack contract-bridge page, not the backend authoring page and not the frontend usage page.
+That means this page is the forward-chain bridge page, not the backend authoring page and not the frontend usage page.
+
+If the changed source is actually a frontend-owned resource that backend consumers later depend on, switch to the reverse-chain guide: [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend).
 
 ## Backend side: Vona emits the contract
 
@@ -70,23 +72,31 @@ cd zova && npm run build:rest:cabloyBasicAdmin
 cd zova && npm run build:rest:cabloyBasicWeb
 ```
 
-A practical contract-loop sequence is:
+A practical forward-chain sequence is:
 
 1. author or change the backend contract
 2. emit or inspect backend OpenAPI output
-3. configure frontend module ownership if needed
-4. generate module-level OpenAPI SDK output
-5. run the rest build for the active Basic flavor when needed
-6. consume the generated contract from frontend code instead of re-declaring it manually
+3. if the frontend generator reads from a local Swagger endpoint, start the backend service first so the endpoint is reachable — in this repo, `npm run dev` is the normal path and exposes Swagger at `http://localhost:7102/swagger/json?version=V31`
+4. configure frontend module ownership if needed
+5. generate module-level OpenAPI SDK output
+6. run the rest build for the active flavor when needed
+7. consume the generated contract from frontend code instead of re-declaring it manually
+8. keep frontend follow-up thin by wrapping generated consumers with semantic facades instead of re-declaring the contract
+9. when the custom API still belongs to an existing resource, reuse the existing resource-owner instead of creating a competing cache owner
 
 A practical responsibility split is:
 
 - project-level OpenAPI config decides where the backend Swagger/OpenAPI source comes from
 - module-level OpenAPI config decides which generated contract slice belongs to which frontend module
+- module-level ownership should be declared explicitly with `operations.match` or `operations.ignore`
+
+If both `operations.match` and `operations.ignore` are empty, frontend SDK generation should fail fast instead of generating a large unrelated contract surface for the module. That fail-fast behavior helps both developers and AI agents notice the missing ownership boundary immediately and repair the config before the wrong SDK slice is generated.
 
 A practical regeneration rule is:
 
 - if the backend contract changed, prefer regenerating the SDK/rest layer before hand-editing frontend request code
+- if `npm run zova :openapi:generate ...` fails because the local Swagger source is unavailable, first start the backend service and confirm `http://localhost:7102/swagger/json?version=V31` is reachable before treating generation as broken
+- if the generated consumer path is already correct, but frontend behavior still looks stale, stop patching generated files and diagnose consumer drift or local dependency drift instead
 
 ## Cabloy Start workflow
 

package/cabloy-docs/fullstack/quickstart.md

@@ -92,7 +92,13 @@ npm run zova :create
 
 Then narrow into the specific command family you need.
 
-## 8. Shared verification commands for deeper workflow checks
+## 8. Next step: follow the quick start tutorials
+
+If you want a beginner-friendly path that connects modules, CRUD, bidirectional contract sharing, and schema-driven workflows into one story, continue with:
+
+- [Fullstack Quick Start Tutorials](/fullstack/tutorials-overview)
+
+## 9. Shared verification commands for deeper workflow checks
 
 If you are validating framework-aware changes or a broader workflow, use the shared project scripts before declaring a workflow correct:
 

package/cabloy-docs/fullstack/tutorial-1-first-module.md

@@ -0,0 +1,111 @@
+# Tutorial 1: Create Your First Module
+
+<Badge type="info" text="Basic" />
+
+In this tutorial, one prompt lets AI create the first backend and frontend module skeleton for the **Student Training Center** story through a CLI-first workflow.
+
+## Goal
+
+By the end of this tutorial, you will understand:
+
+- when to use Vona and when to use Zova
+- how to inspect the CLI before creating files
+- how a Cabloy business capability starts as a module on both sides of the stack
+
+## AI Prompt
+
+Give AI a prompt like this:
+
+```text
+I'm building a Student Training Center project. Please create a demo-student module for both the backend and frontend.
+```
+
+## Why this step matters
+
+This is the right first step because Cabloy treats the module as the unit that owns business code, metadata, generated assets, and docs.
+
+If AI jumps directly into CRUD, contracts, or rendering before the module boundary exists, the work loses its natural owner. This step keeps the rest of the Student Training Center story aligned from the start.
+
+## CLI commands to inspect/use
+
+Work from the repo root, not from `vona/` or `zova/` directly.
+
+Inspect the CLI surface first:
+
+```bash
+npm run vona :
+npm run zova :
+
+npm run vona :create
+npm run zova :create
+```
+
+Representative module-generation commands:
+
+```bash
+npm run vona :create:module demo-student -- --suite=
+npm run zova :create:module demo-student -- --suite=
+```
+
+Usage notes:
+
+- use `npm run vona :create:module` for the backend module boundary
+- use `npm run zova :create:module` for the frontend module boundary
+- use an empty `--suite=` when you want an independent module rather than a suite-owned module
+- rerun `npm run dev` after module creation so the local workflow picks up the new modules cleanly
+
+## Generated or affected files
+
+After both generators run, inspect the generated module roots before editing anything else.
+
+Typical paths in this repo are:
+
+- backend module root: `vona/src/module/<module>/`
+- frontend module root without suite placement: `zova/src/module/<module>/`
+- frontend module root with suite placement: `zova/src/suite/<suite>/modules/<module>/`
+
+In this series, the target module roots are:
+
+- `vona/src/module/demo-student/`
+- `zova/src/module/demo-student/`
+
+A minimal frontend module usually starts with files like:
+
+- `zova/src/module/demo-student/package.json`
+- `zova/src/module/demo-student/src/index.ts`
+- `zova/src/module/demo-student/src/.metadata/index.ts`
+
+## What those files mean in the business thread
+
+At this stage, the key idea is ownership, not business logic yet.
+
+- the backend module root is where the Student resource, entity, DTOs, controller, tests, and backend metadata will live later
+- the frontend module root is where generated OpenAPI output, model helpers, render resources, and frontend metadata will live later
+- the frontend `.metadata` entrypoint is part of how the module exposes its local registration surface
+
+A good beginner rule is: do not rush into editing business logic until you can explain which module roots were created and why they will own the next tutorials.
+
+## Verification
+
+1. make sure the local dev workflow is running:
+
+```bash
+npm run dev
+```
+
+2. confirm that both module roots now exist
+3. inspect the generated files before editing them
+4. confirm that the generated module roots match the target paths for this series:
+   - `vona/src/module/demo-student/`
+   - `zova/src/module/demo-student/`
+
+## Read more
+
+- [Fullstack CLI](/fullstack/cli)
+- [CLI Reference](/reference/cli-reference)
+- [Backend Quickstart](/backend/quickstart)
+- [Frontend Quickstart](/frontend/quickstart)
+
+## Next step
+
+Continue to [Tutorial 2: Create Your First CRUD](/fullstack/tutorial-2-first-crud).

package/cabloy-docs/fullstack/tutorial-2-first-crud.md

@@ -0,0 +1,122 @@
+# Tutorial 2: Create Your First CRUD
+
+<Badge type="info" text="Basic" />
+
+In this tutorial, one prompt lets AI turn the new module into its first real business thread by generating a `student` CRUD workflow.
+
+## Goal
+
+By the end of this tutorial, you will understand:
+
+- why Cabloy prefers CRUD generation over hand-written boilerplate
+- what the generated backend thread usually includes
+- how the generated entity and DTO surface becomes the contract foundation for later tutorials
+- why this step does not generate any frontend code, but already gives you a complete CRUD admin page through Cabloy’s existing schema-driven surface
+
+## AI Prompt
+
+Give AI a prompt like this:
+
+```text
+Please generate the first CRUD flow for the Student resource.
+```
+
+## Why this step matters
+
+Once the module exists, this is the next useful step because the prompt can drive the CRUD generator instead of hand-building controller, service, model, entity, DTO, metadata, locale, and tests one by one.
+
+That keeps the conversation focused on the generated business thread rather than on repetitive scaffolding details.
+
+## CLI commands to inspect/use
+
+Inspect the CRUD family first:
+
+```bash
+npm run vona :tools
+npm run vona :tools:crud --help
+npm run vona :tools:crudBasic --help
+```
+
+Generate the `student` CRUD thread:
+
+```bash
+npm run vona :tools:crud student -- --module=demo-student
+```
+
+Equivalent Basic-specific entrypoint:
+
+```bash
+npm run vona :tools:crudBasic student -- --module=demo-student
+```
+
+Usage notes:
+
+- `:tools:crud` is the public entrypoint beginners should prefer
+- `:tools:crudBasic` is useful when you want to inspect the Basic-specific underlying path directly
+- after generation, verify the result from the admin UI instead of stopping at file inspection
+
+## Generated or affected files
+
+After generation, inspect the resulting backend thread before refining anything.
+
+By the end of this tutorial, your `demo-student` backend thread should have a representative shape under `vona/src/module/demo-student/src/`:
+
+- `controller/student.ts`
+- `service/student.ts`
+- `model/student.ts`
+- `entity/student.tsx`
+- `dto/studentCreate.tsx`
+- `dto/studentUpdate.tsx`
+- `dto/studentView.tsx`
+- `dto/studentSelectReq.tsx`
+- `dto/studentSelectRes.tsx`
+- `dto/studentSelectResItem.tsx`
+- `bean/meta.version.ts`
+
+There is also a test anchor at:
+
+- `vona/src/module/demo-student/test/student.test.ts`
+
+## What those files mean in the business thread
+
+As you inspect the generated files, pay attention to the division of responsibility:
+
+1. `controller/student.ts` exposes the HTTP contract
+2. `service/student.ts` owns orchestration
+3. `model/student.ts` owns persistence behavior
+4. `entity/student.tsx` defines the field-oriented contract surface
+5. the DTO files define operation-specific request and response contracts
+6. `bean/meta.version.ts` anchors the module schema/version thread
+7. `test/student.test.ts` gives you a verification anchor for the generated backend flow
+
+This is the backend contract thread that later tutorials will extend with `level`, `mobile`, render metadata, OpenAPI output, and row actions.
+
+## Verification
+
+1. make sure the local dev workflow is running:
+
+```bash
+npm run dev
+```
+
+2. open `http://localhost:7102/admin/`
+3. enter the **Student** list page from the **Student** menu
+4. trigger create, read, update, and delete operations from the page
+5. inspect the generated backend files and confirm that the CRUD layers are present:
+   - `vona/src/module/demo-student/src/entity/student.tsx`
+   - `vona/src/module/demo-student/src/controller/student.ts`
+   - `vona/src/module/demo-student/src/dto/studentSelectResItem.tsx`
+
+## Read more
+
+- [CRUD Workflow](/backend/crud-workflow)
+- [Controller Guide](/backend/controller-guide)
+- [Service Guide](/backend/service-guide)
+- [Model Guide](/backend/model-guide)
+- [Entity Guide](/backend/entity-guide)
+- [DTO Guide](/backend/dto-guide)
+- [Validation Guide](/backend/validation-guide)
+
+## Next step
+
+Continue to [Tutorial 3: Frontend Metadata Sharing](/fullstack/tutorial-3-frontend-metadata-sharing).

package/cabloy-docs/fullstack/tutorial-3-frontend-metadata-sharing.md

@@ -0,0 +1,131 @@
+# Tutorial 3: Frontend Metadata Sharing
+
+<Badge type="info" text="Basic" />
+
+In this tutorial, one prompt lets AI show the **reverse chain** of Cabloy’s fullstack contract loop: backend field metadata can reference frontend render resources.
+
+You start with the simplest path first: reuse the existing built-in rendering resources for the `level` field.
+
+## Goal
+
+By the end of this tutorial, you will understand:
+
+- why Cabloy fullstack sharing is bidirectional
+- how a backend field can reuse frontend rendering resources through metadata
+- how one `level` field can participate in schema-driven form and table behavior without a custom component yet
+
+## AI Prompt
+
+Give AI a prompt like this:
+
+```text
+Please add a level field to the Student resource. It should be a required number field with these enum values:
+
+- 1: beginner
+- 2: intermediate
+- 3: advanced
+```
+
+## Why this step matters
+
+This is the right step because it teaches one very specific Cabloy distinction.
+
+The goal is not to make backend and frontend share arbitrary component code. The goal is to keep the backend field contract in charge while letting that contract reference frontend render resources through metadata.
+
+In other words, this step is about **frontend metadata sharing**: the backend field contract references frontend render resources through metadata.
+
+## CLI commands to inspect/use
+
+This tutorial is mainly a contract-refinement step, so the most important habit is inspection before editing.
+
+Useful discovery commands from the repo root:
+
+```bash
+npm run vona :
+npm run zova :
+npm run zova :create
+```
+
+You usually do **not** need to generate a custom bean in this tutorial.
+
+Instead, inspect the current contract surfaces first:
+
+- `vona/src/module/demo-student/src/entity/student.tsx`
+- `vona/src/module/demo-student/src/dto/studentSelectReq.tsx`
+
+Usage notes:
+
+- keep the backend entity as the main source of truth for the `level` field
+- prefer built-in frontend render resources first
+- delay custom renderer authoring to the next tutorial
+
+## Generated or affected files
+
+The key backend contract anchor is:
+
+- `vona/src/module/demo-student/src/entity/student.tsx`
+
+By the end of this tutorial, the `level` field should follow a built-in path like this:
+
+```typescript
+@Api.field(
+  v.title($locale('Level')),
+  v.required(),
+  ZovaRender.order(3),
+  ZovaRender.field('basic-select:formFieldSelect', {
+    items: levelItems,
+    placeholder: $locale('LevelPlaceholder'),
+  }),
+  ZovaRender.cell('basic-select:select', { items: levelItems }),
+  levelSchema,
+)
+level: number;
+```
+
+A related DTO anchor is:
+
+- `vona/src/module/demo-student/src/dto/studentSelectReq.tsx`
+
+That DTO already shows how filter-side field metadata can also participate in schema-driven UI.
+
+## What those files mean in the business thread
+
+This tutorial teaches one core mental model:
+
+- the backend still owns the business field contract
+- the frontend still owns the render resources
+- metadata is the bridge between them
+
+Concretely:
+
+- `entity/student.tsx` defines `level` as a real business field
+- `levelItems` gives that field a stable set of business options
+- `ZovaRender.field('basic-select:formFieldSelect', ...)` makes the form side schema-aware
+- `ZovaRender.cell('basic-select:select', ...)` makes the table side schema-aware
+- `dto/studentSelectReq.tsx` reminds you that filter-side metadata is also part of the same contract story
+
+At this stage, you do not need a custom frontend component to understand the reverse-sharing model.
+
+## Verification
+
+1. make sure the local dev workflow is running:
+
+```bash
+npm run dev
+```
+
+2. open `http://localhost:7102/admin/`
+3. enter the **Student** list page from the **Student** menu
+4. verify that the `level` field appears with select-style behavior in the relevant schema-driven surfaces
+5. inspect `vona/src/module/demo-student/src/entity/student.tsx` and confirm that the backend field contract now points to built-in frontend render resources instead of page-local hard-coded UI logic
+
+## Read more
+
+- [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [Server Data](/frontend/server-data)
+- [Frontend CLI](/frontend/cli)
+
+## Next step
+
+Continue to [Tutorial 4: Custom Form/Table Renderers for Level](/fullstack/tutorial-4-custom-level-renderers).