cabloy 5.1.59 → 5.1.60

package/cabloy-docs/frontend/ssr-troubleshooting-guide.md

@@ -0,0 +1,301 @@
+# SSR Troubleshooting Guide
+
+This guide explains how to debug common SSR problems in Zova within the Cabloy monorepo.
+
+## Why this page exists
+
+The other SSR pages explain how the SSR model is supposed to work.
+
+This page answers a different question:
+
+- when SSR behavior is wrong, where should you look first?
+
+That matters because SSR issues are easy to misclassify.
+
+A symptom that looks like “frontend rendering is broken” can actually come from:
+
+- SSR site routing on the backend side
+- a missing or stale frontend bundle
+- SSR-only route or data-loading behavior
+- hydration mismatch on the client
+- edition-specific theme assumptions
+
+A good troubleshooting flow starts by identifying **which layer is failing** before trying to patch the symptom directly.
+
+## Start with the four-layer model
+
+Use the [SSR Architecture Overview](/frontend/ssr-architecture-overview) as the first mental model.
+
+For troubleshooting, the practical layer split is:
+
+1. **Vona SSR orchestration**
+   - request entry
+   - SSR site matching
+   - dev proxy versus built asset versus SSR render
+2. **frontend build output**
+   - SSR entry
+   - manifest
+   - client assets
+3. **Zova SSR server render**
+   - route resolution
+   - HTML render
+   - state/meta/preload generation
+4. **client hydration**
+   - initial state reuse
+   - browser-only behavior
+   - final theme and DOM state
+
+If you identify the failing layer first, most SSR debugging becomes much faster.
+
+## Fast symptom-to-layer map
+
+Use this quick map before diving deeper.
+
+| Symptom | Start here |
+| --- | --- |
+| request does not hit the expected SSR page | Vona SSR orchestration |
+| dev works but prod fails | frontend build output + SSR env/runtime |
+| HTML appears but hydration is wrong | client hydration |
+| server-rendered data is missing or refetched unexpectedly | Zova SSR server render + init data flow |
+| SEO/meta output is missing | Zova SSR server render + meta flow |
+| first paint theme is wrong | SSR env + theme rules |
+| static assets 404 after SSR deploy | frontend build output |
+
+## Symptom 1: the request does not hit the expected SSR page
+
+Typical signs:
+
+- a page that should be SSR-rendered falls through to another route
+- a URL returns the wrong site
+- SSR works for one path prefix but not another
+
+Start with these questions:
+
+1. is the request entering the correct SSR site at all?
+2. is the path prefix/site selection correct?
+3. are you expecting SSR where the route is actually a normal backend or static path?
+
+A practical debugging order is:
+
+- confirm the target URL and SSR site assumptions
+- re-check the SSR architecture split in [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+- verify whether the problem is a site-entry issue rather than a page-render issue
+
+If the request never reaches the intended SSR site, do **not** start by changing page components or hydration logic.
+
+## Symptom 2: dev works but prod fails
+
+Typical signs:
+
+- SSR works through the dev server but breaks after build
+- dev shows the page, while prod returns missing asset or render errors
+- only built deployments show the problem
+
+This usually means the issue is not only “SSR logic.”
+
+It often means one of these instead:
+
+- build output is stale or incomplete
+- the expected frontend bundle was not generated for the target flavor
+- SSR env/runtime assumptions differ between dev and prod
+- asset paths or manifest assumptions are wrong after build
+
+Start with these checks:
+
+1. was the relevant frontend SSR build actually regenerated?
+2. are you targeting the correct flavor for the active edition?
+3. does the issue happen before page render, during page render, or only after hydration?
+
+Read together:
+
+- [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+- [SSR Environment Variables](/frontend/ssr-env)
+- [Fullstack Vona + Zova Integration](/fullstack/vona-zova-integration)
+
+## Symptom 3: HTML appears, but hydration is wrong
+
+Typical signs:
+
+- server HTML looks right at first, then changes unexpectedly on the client
+- hydration mismatch warnings appear
+- browser-only UI behaves differently from the server output
+- the first screen “flashes” into a different state after load
+
+This usually means the server render and the browser’s final state are not using exactly the same assumptions.
+
+Common causes include:
+
+- browser-only logic running too early
+- client-only components not being isolated properly
+- theme-sensitive output being treated as authoritative on the server when it is not
+- state that was expected to transfer through SSR not being reused correctly during hydration
+
+Start with these checks:
+
+1. does this UI depend on browser APIs or client-only rendering behavior?
+2. should part of the UI be wrapped in `ClientOnly`?
+3. is the code assuming the server already knows the browser’s final theme?
+4. is the client reusing server-provided state, or recomputing a different result?
+
+Read together:
+
+- [SSR ClientOnly](/frontend/ssr-client-only)
+- [SSR Init Data](/frontend/ssr-init-data)
+- [SSR Environment Variables](/frontend/ssr-env)
+- [Theme Guide](/frontend/theme-guide)
+
+## Symptom 4: server-rendered data is missing or is fetched again unexpectedly
+
+Typical signs:
+
+- the page renders without expected data on the server
+- the client repeats the first data fetch that should have been prepared already
+- loading behavior is different between SSR and client navigation
+
+A better default in Zova is:
+
+- prepare SSR data through the intended model/controller flow
+- let hydration reuse that prepared state on the client
+
+Start with these checks:
+
+1. is the data prepared in the intended SSR lifecycle rather than in an ad hoc client path?
+2. is the data-loading logic aligned with the model-based SSR flow?
+3. are you accidentally bypassing the existing hydration reuse path?
+
+Read together:
+
+- [SSR Init Data](/frontend/ssr-init-data)
+- [Server Data](/frontend/server-data)
+- [Model State Guide](/frontend/model-state-guide)
+
+## Symptom 5: SEO/meta output is missing or inconsistent
+
+Typical signs:
+
+- page title is wrong after SSR
+- expected meta tags are missing in server-rendered HTML
+- metadata looks correct on the client but not in the initial server response
+
+This usually means the metadata is not being produced through the intended SSR-aware path.
+
+Start with these checks:
+
+1. are you using `$useMeta` instead of a parallel custom mechanism?
+2. is the metadata available during SSR rather than only after client boot?
+3. are multiple metadata layers overwriting each other intentionally or accidentally?
+
+Read together:
+
+- [SSR SEO Meta](/frontend/ssr-seo-meta)
+- [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+
+## Symptom 6: theme or dark-mode behavior is wrong on first paint
+
+Typical signs:
+
+- server output uses one theme, then the browser switches to another immediately
+- dark/light SSR output looks unstable
+- the result differs between Web SSR and Admin SSR
+
+This area is especially sensitive because SSR theme authority is not identical in every flavor.
+
+Start with these checks:
+
+1. are you treating the server’s theme-sensitive read as final browser truth?
+2. does the active flavor support cookie-backed SSR theme resolution?
+3. are you applying a Basic-specific theme assumption to a different edition or adapter?
+
+Read together:
+
+- [SSR Environment Variables](/frontend/ssr-env)
+- [Theme Guide](/frontend/theme-guide)
+- [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+
+A practical rule is:
+
+- if exact browser theme matching matters, keep the output hydration-tolerant unless the active SSR path provides a stronger server-side guarantee
+
+## Symptom 7: static assets 404 after SSR deploy
+
+Typical signs:
+
+- HTML response appears, but CSS or JS assets do not load
+- SSR page shell renders without expected styling or scripts
+- built deployment fails while local dev works
+
+This usually points to bundle output or deployment-path issues rather than page logic.
+
+Start with these checks:
+
+1. was the correct frontend build generated?
+2. are the expected client assets present for the deployed bundle?
+3. does the deployment path still match the built asset assumptions?
+
+Read together:
+
+- [Fullstack Vona + Zova Integration](/fullstack/vona-zova-integration)
+- [Environment and Config Guide](/frontend/environment-config-guide)
+- [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+
+## A safe debugging order
+
+When SSR breaks and the failure is unclear, use this order.
+
+### Step 1: identify the first broken stage
+
+Ask:
+
+- is the request entering the intended SSR site?
+- is the server returning HTML at all?
+- is the HTML already wrong before hydration?
+- does it only go wrong after the browser starts running?
+
+### Step 2: separate server-render problems from hydration problems
+
+This split removes a lot of confusion.
+
+- if the initial HTML is wrong, focus on SSR entry, route resolution, render, data, or meta
+- if the initial HTML is right but the browser changes it incorrectly, focus on hydration, client-only boundaries, theme authority, or client state reuse
+
+### Step 3: check edition-sensitive assumptions
+
+Especially for theme or UI-sensitive work, confirm:
+
+- active edition
+- active UI layer
+- whether the rule is shared across editions or adapter-specific
+
+### Step 4: reuse the framework’s intended abstractions
+
+Before adding custom fixes, ask whether the framework already provides the right surface:
+
+- `ClientOnly` for browser-only UI
+- model/controller SSR init flow for data preparation
+- `$useMeta` for SEO/meta
+- existing theme/env rules for theme-sensitive SSR behavior
+
+## Recommended reading order for troubleshooting
+
+Use this path when SSR behavior is wrong and you need to narrow the problem quickly:
+
+1. this page for symptom triage
+2. [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+3. [SSR Overview](/frontend/ssr-overview)
+4. [SSR Init Data](/frontend/ssr-init-data)
+5. [SSR ClientOnly](/frontend/ssr-client-only)
+6. [SSR SEO Meta](/frontend/ssr-seo-meta)
+7. [SSR Environment Variables](/frontend/ssr-env)
+8. [Theme Guide](/frontend/theme-guide)
+9. [Fullstack Vona + Zova Integration](/fullstack/vona-zova-integration)
+
+## Implementation checks for SSR troubleshooting
+
+Before finalizing an SSR fix, ask:
+
+1. did I identify the failing SSR layer before changing code?
+2. is this actually a server-render issue, or a hydration issue?
+3. am I reusing the intended framework abstraction instead of adding a parallel workaround?
+4. does the fix accidentally assume an edition-specific UI or theme rule is universal?
+
+That keeps SSR debugging aligned with the Cabloy fullstack model and reduces one-off fixes that solve only the symptom.

package/cabloy-docs/fullstack/framework-performance.md

@@ -42,17 +42,17 @@ For the current public explanation of this backend capability, see [Cache Guide]
 
 This is the kind of result Cabloy is designed to support: a framework that stays operationally calm even when the system keeps running for long periods.
 
-One internally generated project was kept running continuously for **33 hours**. At one representative PM2 snapshot, the process looked like this:
+One internally generated project was kept running continuously for **2 days**. At one representative PM2 snapshot, the process looked like this:
 
 ```text
 ┌────┬─────────────────┬─────────────┬─────────┬─────────┬──────────┬────────┬──────┬───────────┬──────────┬──────────┬──────────┬──────────┐
 │ id │ name            │ namespace   │ version │ mode    │ pid      │ uptime │ ↺    │ status    │ cpu      │ mem      │ user     │ watching │
 ├────┼─────────────────┼─────────────┼─────────┼─────────┼──────────┼────────┼──────┼───────────┼──────────┼──────────┼──────────┼──────────┤
-│ 0  │ cabloy_store    │ default     │ N/A     │ cluster │ 226947   │ 33h    │ 17   │ online    │ 0%       │ 401.9mb  │ ubuntu   │ disabled │
+│ 0  │ cabloy_***    │ default     │ N/A     │ cluster │ 226947   │ 2D    │ 17   │ online    │ 0%       │ 376.2mb  │ ubuntu   │ disabled │
 └────┴─────────────────┴─────────────┴─────────┴─────────┴──────────┴────────┴──────┴───────────┴──────────┴──────────┴──────────┴──────────┘
 ```
 
-For this 33-hour continuous run, the observed result was **0 memory leak**.
+For this 2-day continuous run, the observed result was **0 memory leak**.
 
 The value of this example is not that it is a synthetic micro-benchmark. The value is that it reflects a real long-running project process with a clear, inspectable runtime footprint.
 

package/cabloy-docs/fullstack/introduction.md

@@ -62,6 +62,35 @@ 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.
+
+For the two directions in more detail, see [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) and [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend).
+
 ## 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/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).