cabloy 5.1.60 → 5.1.61

package/cabloy-docs/frontend/zova-vs-vue3-comparison.md

@@ -0,0 +1,308 @@
+# Zova vs Vue 3 Comparison
+
+This page compares **Zova’s frontend programming model** with the **default mental model many developers bring from Vue 3**.
+
+The goal is not to argue that one replaces the other.
+
+The goal is to explain two things clearly:
+
+1. **Zova still stands on top of Vue 3 runtime and reactivity foundations**
+2. **Zova deliberately changes the preferred authoring surface, architectural center, and code-organization habits built on top of those foundations**
+
+Use this page together with:
+
+- [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+- [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood)
+- [Zova Source Reading Map](/frontend/zova-source-reading-map)
+
+## Why this page exists
+
+A Vue developer can look at Zova code and ask questions like these:
+
+- why is this state a plain class field instead of a `ref`?
+- why is derived state wired in `__init__` instead of declared in `setup()`?
+- why does route state appear on the controller instance instead of being pulled through `useRoute()`?
+- why does the page grow into controller/render/style/service beans instead of only more composables and child components?
+
+Those questions are reasonable.
+
+This page answers them by comparing the two programming models across a few stable architectural dimensions.
+
+## The shortest accurate summary
+
+If you only want the shortest answer, use this one:
+
+> Vue 3 usually presents reactivity as explicit local primitives and composition-oriented setup logic, while Zova presents reactivity through framework-managed bean instances and controller-oriented architecture.
+
+Under the surface, Zova still uses Vue runtime/reactivity capabilities.
+
+The big difference is the **business-facing programming model**.
+
+## Side-by-side comparison table
+
+| Dimension | Zova | Vue 3 default mental model |
+| --- | --- | --- |
+| Reactive host | controller or bean instance | local `ref` / `reactive` values inside `setup()` |
+| Derived state | `$computed()` often assigned to instance fields | `computed()` usually assigned to local variables |
+| Main wiring surface | `__init__` and bean lifecycle | `setup()` and composition hooks |
+| Route state access | page-controller surface such as `$route`, `$params`, `$query` | composables such as `useRoute()` |
+| Sharing model | IoC containers and bean scopes unify more sharing patterns | composables, props/emits, `provide/inject`, and store layers often coexist |
+| Render organization | controller-oriented; render can stay in controller or move to render beans | component-oriented; template/render/setup stay the obvious center |
+| Growth path | split into controller, render, style, service, model, or other beans | split into composables, child components, and store or helper layers |
+| Architectural emphasis | explicit object roles, scope ownership, and runtime-managed surfaces | flexible local composition with more developer-managed assembly |
+
+## 1. Reactive host
+
+### Zova
+
+Zova often makes the controller or bean instance the visible reactive surface.
+
+That is why code can look like:
+
+```typescript
+count: number = 0;
+
+increment() {
+  this.count++;
+}
+```
+
+The important idea is not only shorter syntax.
+
+The important idea is that the framework is making the bean instance itself the business-facing state host.
+
+### Vue 3
+
+The default Vue mental model usually starts with explicit primitives:
+
+```typescript
+const count = ref(0);
+
+function increment() {
+  count.value++;
+}
+```
+
+### Comparison takeaway
+
+- Vue 3 teaches you to build reactivity from visible primitives
+- Zova teaches you to work on top of a framework-managed reactive object
+
+## 2. Derived state
+
+### Zova
+
+Derived state often looks like instance wiring:
+
+```typescript
+protected async __init__() {
+  this.count2 = this.$computed(() => {
+    return `=== ${this.count} ===`;
+  });
+}
+```
+
+This makes derived state feel like part of object initialization and lifecycle wiring.
+
+### Vue 3
+
+Derived state often looks like local reactive declaration:
+
+```typescript
+const count2 = computed(() => `=== ${count.value} ===`);
+```
+
+### Comparison takeaway
+
+- Vue 3 presents derived state as a local reactive value
+- Zova often presents it as an instance-level property of a controller or bean
+
+## 3. Main wiring surface
+
+### Zova
+
+Zova concentrates many setup concerns inside bean lifecycle methods such as:
+
+- `__init__`
+- `__dispose__`
+
+That is where you often wire:
+
+- computed values
+- watchers
+- derived state
+- lifecycle cleanup
+
+### Vue 3
+
+Vue 3 usually treats `setup()` as the main assembly point, then uses composition hooks around it.
+
+### Comparison takeaway
+
+- Vue 3 is more obviously composition-function-centered
+- Zova is more obviously lifecycle-and-object-centered
+
+## 4. Route state access
+
+### Zova
+
+For page controllers, route-aware state is often part of the controller surface:
+
+- `$route`
+- `$params`
+- `$query`
+
+This keeps route-aware page logic close to the page controller itself.
+
+### Vue 3
+
+Vue code more often pulls route state through:
+
+- `useRoute()`
+- `useRouter()`
+
+### Comparison takeaway
+
+- Vue 3 usually pulls route state into local composition code
+- Zova usually pushes route-aware state into the page-controller surface
+
+## 5. Sharing model
+
+### Zova
+
+Zova uses IoC as a larger frontend architectural answer, not only as a small dependency-injection convenience.
+
+That means questions often become:
+
+- which bean owns this behavior?
+- which scope should this bean live in?
+- should this be resolved through injection or lookup?
+
+### Vue 3
+
+Vue projects often combine several distinct sharing tools depending on the team and codebase:
+
+- props and emits
+- composables
+- `provide/inject`
+- store layers
+
+### Comparison takeaway
+
+- Vue 3 gives a flexible base that can lead to multiple sharing styles in one codebase
+- Zova tries to unify more of those patterns through bean and scope architecture
+
+## 6. Render organization
+
+### Zova
+
+Zova treats render as part of a controller-oriented architecture.
+
+A page can:
+
+- render directly inside the controller
+- later split render into a dedicated render bean
+- also split style into a style bean
+- later move additional state or behavior into service beans
+
+### Vue 3
+
+Vue usually treats the component itself as the natural render center:
+
+- template
+- render function
+- `setup()` locals feeding the component render
+
+### Comparison takeaway
+
+- Vue 3 makes the component the obvious render center
+- Zova makes the page or component controller architecture the larger center
+
+## 7. Growth path as complexity increases
+
+### Zova
+
+A common Zova growth path is:
+
+1. start with one page controller
+2. split render into a render bean
+3. split style into a style bean
+4. extract state or logic into service or model beans when ownership becomes clearer
+
+### Vue 3
+
+A common Vue growth path is:
+
+1. start with one component
+2. extract composables
+3. add child components
+4. introduce or extend store ownership where needed
+
+### Comparison takeaway
+
+- Vue 3 complexity growth often feels more composition-first
+- Zova complexity growth often feels more role-and-boundary-first
+
+## 8. Code-reading experience
+
+### Zova
+
+When reading Zova, you often ask:
+
+- which bean am I looking at?
+- is this a page, component, service, model, render, or style role?
+- what scope owns this bean?
+- what runtime surface is being injected or refreshed onto it?
+
+### Vue 3
+
+When reading Vue, you often ask:
+
+- what lives in `setup()`?
+- which composables are being used?
+- which local refs/computeds feed the render?
+- where does state ownership move to a store or parent component?
+
+### Comparison takeaway
+
+The reading rhythm itself changes.
+
+That is why a Vue expert can still feel unfamiliar inside Zova at first even though the lower-level reactive runtime is related.
+
+## What is the same underneath
+
+Despite all the differences above, a few important foundations are still shared:
+
+- Vue reactivity still matters underneath
+- dependency tracking still matters underneath
+- recomputation and rerender still matter underneath
+- component runtime behavior still matters underneath
+
+So the comparison is **not**:
+
+- Zova versus Vue runtime
+
+It is mostly:
+
+- Zova’s architectural authoring model versus Vue’s default authoring habits
+
+## When to prefer this comparison page
+
+Use this page when:
+
+- you already know Vue and want a clean translation layer into Zova
+- you want one page that summarizes the biggest architectural differences quickly
+- you need to explain to another developer why Zova code should not be auto-refactored back toward generic Vue patterns
+
+If you want the next level of detail after this page, continue with:
+
+- [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood)
+- [Zova Source Reading Map](/frontend/zova-source-reading-map)
+
+## Final takeaway
+
+The most important comparison insight is simple:
+
+> Vue 3 usually teaches explicit reactive primitives first and architectural composition second. Zova keeps the Vue runtime foundation but teaches explicit architectural roles first and hides more of the reactive primitive management behind framework-managed controller and bean surfaces.
+
+Once that shift is clear, Zova code becomes much easier to read on its own terms.

package/cabloy-docs/fullstack/contract-loop-playbook.md

@@ -0,0 +1,350 @@
+# Contract Loop Playbook
+
+This page is the canonical playbook for Cabloy’s bidirectional fullstack contract loop.
+
+Use it when you need to decide:
+
+- where source truth lives for a change
+- which generated handoff should be refreshed
+- which side is actually stale
+- whether the problem is source drift, generated-output drift, consumer drift, or local dependency drift
+
+## Why this playbook exists
+
+Cabloy’s fullstack collaboration is not only backend-to-frontend.
+
+The same monorepo supports two symmetric chains:
+
+- **forward chain** — backend contract emission and frontend consumption
+- **reverse chain** — frontend metadata or resource handoff and backend consumption
+
+The core model applies to both **Cabloy Basic** and **Cabloy Start**.
+
+What changes by edition is not the model itself, but the operational branch:
+
+- flavor names
+- UI-resource examples
+- generated-output paths
+- build commands
+
+So the first question is always:
+
+1. which chain am I in?
+2. which edition is active?
+
+## Shared vocabulary
+
+Use these terms consistently:
+
+- **contract loop** — the full bidirectional Vona↔Zova collaboration model
+- **forward chain** — backend contract truth flows into generated frontend consumers
+- **reverse chain** — frontend-owned metadata or resources flow into backend consumers
+- **contract source** — the authored layer that currently owns truth
+- **generated handoff** — the generated output that carries truth to the other side
+- **consumer drift** — downstream consumers no longer match current truth
+- **local dependency drift** — generated artifacts are already correct, but installed local file dependencies are still stale
+
+## The two chains
+
+### Forward chain
+
+Use the forward chain when backend-authored contract surfaces changed.
+
+Typical contract sources:
+
+- controller request or response signatures
+- DTOs
+- entity field metadata
+- validation rules
+- OpenAPI metadata
+
+Typical handoff:
+
+- Swagger or OpenAPI output
+- generated Zova SDK or schema-aware helpers
+- flavor-built REST output when the workflow depends on it
+
+Typical consumers:
+
+- generated frontend API files
+- thin frontend model facades
+- schema-driven UI
+- custom row or page actions
+
+### Reverse chain
+
+Use the reverse chain when frontend-owned metadata or resources changed and backend-side tooling or metadata will consume them.
+
+Typical contract sources:
+
+- frontend routes
+- frontend components
+- frontend icons
+- custom form-field or table-cell resources
+- module metadata consumed by backend `ZovaRender.*(...)` references
+
+Typical handoff:
+
+- generated metadata
+- flavor build output
+- local file dependency sync into Vona
+
+Typical consumers:
+
+- backend metadata that references frontend resources
+- backend-side tooling and type hints
+- SSR or integration paths that depend on refreshed frontend output
+
+## Decision tree
+
+Use this decision tree before editing or regenerating anything.
+
+### 1. Did backend contract truth change?
+
+Examples:
+
+- DTO shape changed
+- controller request or response changed
+- validation changed
+- OpenAPI metadata changed
+
+Then use the **forward chain**:
+
+1. change backend truth first
+2. prove emitted contract output is correct
+3. regenerate frontend consumers
+4. keep frontend follow-up thin
+5. verify consumer alignment
+
+See [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+
+### 2. Did frontend-owned metadata or resource truth change?
+
+Examples:
+
+- a custom table cell was added
+- a custom form field was added
+- routes, components, or icons changed
+- backend metadata now references new frontend resources
+
+Then use the **reverse chain**:
+
+1. change frontend source truth
+2. regenerate metadata when applicable
+3. build the relevant frontend flavor output
+4. run `npm run deps:vona`
+5. verify backend consumers can see the refreshed handoff
+
+See [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend).
+
+### 3. Do generated artifacts look stale?
+
+Examples:
+
+- generated SDK still reflects an old endpoint shape
+- generated metadata is missing a new resource
+- rest output did not pick up the latest source change
+
+Then diagnose **generated-output drift**:
+
+1. confirm the source layer was changed in the right place
+2. confirm the correct generation path was used
+3. regenerate instead of hand-patching
+4. verify the generated output itself before debugging downstream code
+
+### 4. Do generated artifacts already look correct, but consumers still behave stale?
+
+Examples:
+
+- generated `.zova-rest` output already contains the new keys or types
+- generated SDK already contains the new method
+- backend or frontend still behaves as if old local file packages are installed
+
+Then suspect **local dependency drift**:
+
+1. stop editing source files
+2. prove the generated handoff is already correct
+3. rerun the normal sync flow
+4. only then repair the local install state if consumers still look stale
+
+## Forward chain playbook
+
+### Stage 1: Backend contract source
+
+Author the truth in Vona first.
+
+Typical layers:
+
+- controllers
+- DTOs
+- entities
+- validation helpers
+- OpenAPI annotations
+
+Rule:
+
+- do **not** patch generated frontend consumers first when the backend owns truth
+
+### Stage 2: Emitted contract proof
+
+Before regeneration, verify the backend output is actually correct.
+
+Typical checks:
+
+- controller contract matches intent
+- DTO and validation align
+- OpenAPI output reflects the intended shape
+
+If the emitted contract is wrong, regeneration will only spread the mistake.
+
+### Stage 3: Module ownership and generation
+
+Regenerate the frontend consumer path deliberately.
+
+Typical commands include:
+
+```bash
+npm run zova :openapi:config <module-name>
+npm run zova :openapi:generate <module-name>
+```
+
+When the target is a module-local SDK, keep ownership constrained with `operations.match` so the module only generates the API surface it actually owns.
+
+### Stage 4: Thin frontend follow-up
+
+After regeneration, keep frontend follow-up thin.
+
+That means:
+
+- prefer generated contract consumers over hand-written duplicates
+- use **thin model facades** as semantic wrappers over generated APIs
+- **reuse the existing resource-owner** when the custom API still belongs to an existing resource
+
+For resource-bound custom endpoints, prefer `rest-resource.model.resource` as the state owner. A module-local model may still exist, but it should remain a semantic facade instead of becoming a second cache owner.
+
+See the downstream pattern in `.claude/skills/cabloy-contract-loop/references/resource-custom-state-pattern.md`.
+
+### Stage 5: Consumer verification
+
+Verify that generated output and frontend consumers agree.
+
+Typical checks:
+
+- generated API contains the intended methods
+- model or schema consumers still typecheck
+- UI behavior now matches the regenerated contract
+
+## Reverse chain playbook
+
+### Stage 1: Frontend-owned source truth
+
+Start from the frontend resource or metadata that actually changed.
+
+Typical layers:
+
+- bean resources
+- components
+- metadata wrappers
+- routes
+- icons
+
+Rule:
+
+- do **not** treat a frontend-owned resource handoff as frontend-only cleanup if backend consumers depend on it
+
+### Stage 2: Generated handoff
+
+Refresh the generated metadata or build output that carries the change across the boundary.
+
+Typical commands may include:
+
+```bash
+npm run zova :tools:metadata <module-name>
+```
+
+and then the relevant build path for the active edition and flavor.
+
+### Stage 3: Vona sync handoff
+
+After the frontend-generated handoff is ready, re-sync Vona’s local file dependencies.
+
+For the current **Cabloy Basic Admin** branch, the representative sequence is:
+
+```bash
+npm run build:zova:admin
+npm run deps:vona
+```
+
+If the same resource path must also be available to Web, also refresh the Web branch.
+
+For **Cabloy Start**, use the same reverse-chain logic, but resolve the Start-specific flavor names and output paths from the active Start repo before recommending commands.
+
+### Stage 4: Consumer verification
+
+Verify that backend consumers can now resolve the refreshed frontend-generated handoff.
+
+Typical checks:
+
+- backend metadata resolves the new frontend resource names
+- generated shared types now appear in backend-side consumers
+- SSR or integration behavior sees the refreshed output
+
+## Recovery path for local dependency drift
+
+Use this branch only when all of these are already true:
+
+- source truth was edited in the right place
+- generation or build output already contains the intended change
+- the normal sync flow already ran
+- consumers still behave stale
+
+Then treat the problem as **local dependency drift**.
+
+Representative recovery path:
+
+```bash
+cd vona && rm -rf node_modules && pnpm install
+```
+
+This is a recovery step, not the first response.
+
+## Verification by branch
+
+### Forward chain
+
+- backend source truth is correct
+- emitted OpenAPI or contract output is correct
+- module ownership is constrained
+- generated frontend consumer output is refreshed
+- frontend consumers and UI behavior align
+
+### Reverse chain
+
+- frontend source truth is correct
+- metadata or build output is refreshed
+- Vona dependency sync completed
+- backend consumers resolve the updated frontend-generated handoff
+
+### Local dependency drift
+
+- generated artifacts already prove the change exists
+- sync flow already ran
+- reinstall is justified only because consumers still behave stale
+
+## Tutorial map
+
+Use the tutorial series as examples of the two chains:
+
+- [Tutorial 3: Frontend Metadata Sharing](/fullstack/tutorial-3-frontend-metadata-sharing) — reverse chain, built-in metadata branch
+- [Tutorial 4: Custom Form/Table Renderers for Level](/fullstack/tutorial-4-custom-level-renderers) — reverse chain, custom resource handoff branch
+- [Tutorial 5: Backend Contract Sharing](/fullstack/tutorial-5-backend-contract-sharing) — forward chain, backend-emitted contract branch
+- [Tutorial 6: One Contract Surface, Four Uses](/fullstack/tutorial-6-one-contract-four-uses) — one field story spanning multiple contract surfaces
+
+## Related docs
+
+- [Fullstack Introduction](/fullstack/introduction)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
+- [Vona + Zova Integration](/fullstack/vona-zova-integration)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [API Schema Guide](/frontend/api-schema-guide)