cabloy 5.1.59 → 5.1.61

package/cabloy-docs/frontend/ssr-build-deploy-guide.md

@@ -0,0 +1,308 @@
+# SSR Build and Deploy Guide
+
+This guide explains the public SSR build and deploy workflow in Zova within the Cabloy monorepo.
+
+## Why this page exists
+
+The other SSR pages explain architecture, behavior, and troubleshooting.
+
+This page answers a more operational question:
+
+- how do you build and package SSR output correctly for Cabloy?
+
+That matters because Cabloy SSR is a fullstack workflow, not only a frontend build command.
+
+A complete SSR deployment path usually needs all of these pieces to stay aligned:
+
+- the correct frontend SSR flavor build
+- any related REST/type generation steps used by the target workflow
+- the backend runtime that consumes the built frontend output
+- environment/config choices that differ between dev and prod
+
+## Start from the shared root scripts
+
+In Cabloy Basic, the root `package.json` is the first workflow surface.
+
+Representative current root scripts include:
+
+```bash
+npm run dev:zova:admin
+npm run dev:zova:web
+npm run build:zova
+npm run build:zova:admin
+npm run build:zova:web
+npm run build
+```
+
+A practical rule is:
+
+1. start from the root wrapper when the normal repo workflow already covers your need
+2. drop into deeper Zova flavor-specific scripts only when you need tighter control or debugging detail
+
+Read together with:
+
+- [Repo Scripts](/reference/repo-scripts)
+- [Frontend Scripts](/frontend/scripts)
+- [Fullstack Vona + Zova Integration](/fullstack/vona-zova-integration)
+
+## Detect the edition first
+
+Before documenting or automating SSR build commands, detect the active edition.
+
+In the current public repo:
+
+- `__CABLOY_BASIC__` means Cabloy Basic
+- current public root wrappers target Basic-specific flavors such as `cabloyBasicAdmin` and `cabloyBasicWeb`
+
+For Cabloy Start:
+
+- the same high-level SSR workflow still applies
+- but flavor names, site baselines, assets, and project paths can differ
+- do not reuse Basic flavor examples blindly in Start-specific documentation or automation
+
+## Two common workflow levels
+
+### Level 1: root-wrapper workflow
+
+Use this when you want the standard Cabloy Basic monorepo workflow.
+
+Representative commands:
+
+```bash
+npm run dev:zova:admin
+npm run dev:zova:web
+npm run build:zova
+npm run build
+```
+
+Practical interpretation:
+
+- `dev:zova:*` is for normal frontend SSR development entry
+- `build:zova` builds frontend SSR output in batch mode
+- `build:zova:admin` and `build:zova:web` are explicit root-wrapper paths for flavor-specific SSR output plus related REST generation
+- `build` is the fullstack alignment path when frontend and backend output should move together
+
+### Level 2: flavor-specific Zova workflow
+
+Use this when you need appMode/flavor detail explicitly.
+
+Representative current Basic examples include:
+
+```bash
+cd zova && npm run dev:ssr:cabloyBasicAdmin
+cd zova && npm run dev:ssr:cabloyBasicWeb
+cd zova && npm run build:ssr:cabloyBasicAdmin
+cd zova && npm run build:ssr:cabloyBasicWeb
+cd zova && npm run build:rest:cabloyBasicAdmin
+cd zova && npm run build:rest:cabloyBasicWeb
+```
+
+This level is useful when you need to separate:
+
+- admin vs web
+- SSR output vs REST/type output
+- root-wrapper behavior vs lower-level flavor behavior
+
+## Development workflow
+
+A normal SSR development workflow in Cabloy Basic is:
+
+```bash
+npm run dev:zova:admin
+```
+
+or:
+
+```bash
+npm run dev:zova:web
+```
+
+Use this when the task is:
+
+- page development
+- route debugging
+- SSR UI iteration
+- hydration behavior review
+
+If you need deeper script control or need to verify the exact Zova flavor path, inspect the flavor-specific scripts described in [Frontend Scripts](/frontend/scripts).
+
+## Build workflow
+
+### Build frontend SSR output only
+
+Use this when you need the frontend SSR artifacts refreshed but do not yet need the full backend build flow.
+
+Representative current Basic command:
+
+```bash
+npm run build:zova
+```
+
+This is the first useful step when:
+
+- frontend SSR code changed
+- static assets or SSR bundle output need regeneration
+- you want to distinguish frontend build problems from backend runtime problems
+
+### Build the fullstack output together
+
+Use this when frontend SSR output and backend runtime should be aligned in one workflow.
+
+Representative current root command:
+
+```bash
+npm run build
+```
+
+In the current repo, this means:
+
+- build Zova SSR output first
+- then build Vona
+
+This is the safer default when a change crosses the frontend/backend SSR boundary.
+
+## Where REST/type generation fits
+
+Some workflows need more than SSR HTML output alone.
+
+In current Basic examples, there are separate REST/type generation commands such as:
+
+```bash
+cd zova && npm run build:rest:cabloyBasicAdmin
+cd zova && npm run build:rest:cabloyBasicWeb
+```
+
+Treat these deliberately.
+
+Use them when the workflow depends on generated contract-aligned frontend surfaces in addition to SSR bundle output.
+
+Do **not** assume every SSR-only change needs manual extra regeneration, but do verify whether your target workflow depends on these generated artifacts.
+
+## Dev vs prod mindset
+
+A frequent SSR mistake is assuming that “works in dev” means “ready for deploy.”
+
+Dev and prod can differ in important ways:
+
+- dev may proxy through a frontend dev server
+- prod depends on built SSR output and built client assets
+- asset path assumptions can differ after build
+- runtime env/config choices can differ between dev and prod
+
+That is why SSR deployment work should always include both:
+
+1. the build step
+2. a targeted verification pass against built behavior
+
+Read together with:
+
+- [SSR Troubleshooting Guide](/frontend/ssr-troubleshooting-guide)
+- [Environment and Config Guide](/frontend/environment-config-guide)
+
+## Practical deployment checklist
+
+Use this checklist before treating an SSR build as deploy-ready.
+
+### 1. confirm the target edition and flavor
+
+Ask:
+
+- am I in Cabloy Basic or Cabloy Start?
+- is this admin or web?
+- am I using the correct SSR flavor for that target?
+
+### 2. confirm the intended workflow level
+
+Ask:
+
+- is the root wrapper enough?
+- do I need the lower-level Zova flavor script for this task?
+- does the workflow also depend on REST/type generation?
+
+### 3. rebuild the relevant frontend SSR output
+
+Use the narrowest meaningful build first.
+
+Typical options:
+
+- `npm run build:zova`
+- targeted `build:ssr:*` commands inside `zova`
+
+### 4. align backend and frontend when the change crosses the boundary
+
+If the change affects the integrated SSR runtime path, prefer:
+
+```bash
+npm run build
+```
+
+That reduces the chance of testing stale frontend output against newer backend code or the reverse.
+
+### 5. verify built behavior, not only dev behavior
+
+At minimum, re-check:
+
+- the expected page loads through SSR
+- client assets load correctly
+- hydration behaves as expected
+- no edition-specific UI/theme assumption breaks the real target flavor
+
+## Common deployment mistakes
+
+### Mistake 1: only testing dev mode
+
+Dev success does not prove that the built SSR bundle and built client assets are correct.
+
+### Mistake 2: building the wrong flavor
+
+A command can succeed while still producing output for the wrong target.
+
+Always confirm whether the target is:
+
+- Basic vs Start
+- admin vs web
+- root-wrapper path vs direct flavor script
+
+### Mistake 3: forgetting the fullstack boundary
+
+If the issue appears only after frontend/backend integration, a frontend-only build check may be insufficient.
+
+Use the fullstack build path when the change crosses the SSR boundary.
+
+### Mistake 4: assuming deploy problems are page-logic problems
+
+Some SSR deploy failures come from stale output, missing assets, wrong flavor selection, or env/config mismatch before they come from page logic itself.
+
+## How this guide relates to other SSR docs
+
+Use these pages together:
+
+- [SSR Overview](/frontend/ssr-overview) for the baseline SSR feature model
+- [SSR Architecture Overview](/frontend/ssr-architecture-overview) for the fullstack mental model
+- [SSR Troubleshooting Guide](/frontend/ssr-troubleshooting-guide) for symptom-based diagnosis
+- [Frontend Scripts](/frontend/scripts) for script lookup
+- [Environment and Config Guide](/frontend/environment-config-guide) for runtime/config selection
+- [Fullstack Vona + Zova Integration](/fullstack/vona-zova-integration) for the monorepo integration model
+
+## Recommended reading order
+
+If you are deploying or packaging SSR behavior, use this path:
+
+1. this page for build/deploy workflow
+2. [Frontend Scripts](/frontend/scripts)
+3. [Environment and Config Guide](/frontend/environment-config-guide)
+4. [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+5. [SSR Troubleshooting Guide](/frontend/ssr-troubleshooting-guide)
+6. [Fullstack Vona + Zova Integration](/fullstack/vona-zova-integration)
+
+## Implementation checks for SSR build/deploy changes
+
+Before finalizing an SSR build/deploy change, ask:
+
+1. did I detect the correct edition and target flavor first?
+2. did I choose the right workflow level: root wrapper or lower-level flavor script?
+3. did I rebuild the relevant frontend SSR output?
+4. if the change crosses the frontend/backend SSR boundary, did I verify the aligned fullstack build path?
+5. did I verify built behavior rather than relying only on dev behavior?
+
+That keeps SSR deployment guidance aligned with the real Cabloy monorepo workflow rather than with generic frontend-only assumptions.

package/cabloy-docs/frontend/ssr-review-checklist.md

@@ -0,0 +1,184 @@
+# SSR Review Checklist
+
+This checklist helps contributors and AI workflows review SSR-related changes in Zova within the Cabloy monorepo.
+
+## Why this page exists
+
+The other SSR pages explain architecture, build/deploy flow, and troubleshooting.
+
+This page answers a narrower review question:
+
+- what should you verify before accepting an SSR-related change?
+
+That matters because SSR changes can look correct in one narrow path while still being wrong at a framework boundary.
+
+Common review failures include:
+
+- checking only client behavior and skipping server-render behavior
+- checking only dev behavior and skipping built behavior
+- reviewing page logic without checking the SSR layer it depends on
+- assuming a theme or UI rule is shared across editions when it is not
+
+## Use this checklist with the layer model
+
+Use the [SSR Architecture Overview](/frontend/ssr-architecture-overview) as the base model.
+
+For review, the practical layers are:
+
+1. **Vona SSR orchestration**
+2. **frontend build output**
+3. **Zova SSR server render**
+4. **client hydration**
+
+A good SSR review starts by asking which of these layers the change touches.
+
+## Fast review checklist
+
+Use this short checklist for PR review, AI review, or self-review.
+
+- [ ] I identified which SSR layer the change touches first.
+- [ ] I checked whether the change affects server render, client hydration, or both.
+- [ ] I verified that the change uses existing SSR abstractions rather than inventing a parallel workaround.
+- [ ] I checked whether the change needs verification in built mode rather than only in dev mode.
+- [ ] I reviewed whether the change depends on edition-specific UI or theme assumptions.
+
+## Layer-by-layer review checklist
+
+### 1. Vona SSR orchestration
+
+Review these questions when the change affects SSR site routing, backend-side SSR integration, or request entry behavior.
+
+- [ ] Does the request still enter the correct SSR site?
+- [ ] Does the change preserve the intended SSR site/path assumptions?
+- [ ] If route-to-page handoff changed, is it still using the intended SSR render/redirect boundary?
+- [ ] If the issue is dev-only or prod-only, did I verify whether the failure belongs to orchestration rather than page logic?
+
+Read together:
+
+- [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+- [SSR Troubleshooting Guide](/frontend/ssr-troubleshooting-guide)
+
+### 2. Frontend build output
+
+Review these questions when the change affects scripts, flavors, generated assets, or deploy packaging.
+
+- [ ] Did I verify the correct edition and target flavor first?
+- [ ] Did I verify whether the change needs the root wrapper or a flavor-specific script path?
+- [ ] Did I check whether built SSR output, client assets, or related generated artifacts need regeneration?
+- [ ] If the change crosses the fullstack SSR boundary, did I verify the aligned build workflow rather than a frontend-only build assumption?
+
+Read together:
+
+- [SSR Build and Deploy Guide](/frontend/ssr-build-deploy-guide)
+- [Frontend Scripts](/frontend/scripts)
+- [Fullstack Vona + Zova Integration](/fullstack/vona-zova-integration)
+
+### 3. Zova SSR server render
+
+Review these questions when the change affects route resolution, server-side data, or server-generated HTML/meta.
+
+- [ ] Is the initial server-rendered HTML still correct before hydration begins?
+- [ ] If data is involved, is it prepared through the intended SSR/model/controller flow?
+- [ ] If metadata is involved, is it still produced through the intended SSR-aware meta path?
+- [ ] If the change touches SSR-only behavior, did I verify it at the server-render stage rather than only after client boot?
+
+Read together:
+
+- [SSR Init Data](/frontend/ssr-init-data)
+- [SSR SEO Meta](/frontend/ssr-seo-meta)
+- [SSR Troubleshooting Guide](/frontend/ssr-troubleshooting-guide)
+
+### 4. Client hydration
+
+Review these questions when the change affects browser-only behavior, first paint, or client takeover after SSR.
+
+- [ ] Is the client reusing server-provided state rather than recomputing a different first-screen result?
+- [ ] If browser-only behavior is involved, should part of the UI be isolated with `ClientOnly`?
+- [ ] Did I separate a hydration issue from a server-render issue before changing code?
+- [ ] If the final browser state differs from the server output, is that difference expected and framework-supported?
+
+Read together:
+
+- [SSR ClientOnly](/frontend/ssr-client-only)
+- [SSR Troubleshooting Guide](/frontend/ssr-troubleshooting-guide)
+
+## Theme and edition-sensitive review gate
+
+Use this gate whenever a change touches theme, tokens, first paint, or dark/light behavior.
+
+- [ ] I identified the active edition before reviewing SSR theme behavior.
+- [ ] I identified the active UI layer before assuming token or hydration behavior.
+- [ ] I checked whether the active SSR path provides cookie-backed theme resolution.
+- [ ] I did not treat server-side theme-sensitive reads as final browser truth when the active SSR path does not guarantee that.
+- [ ] I verified whether the rule is shared across editions or adapter-specific.
+
+Read together:
+
+- [Theme Guide](/frontend/theme-guide)
+- [SSR Environment Variables](/frontend/ssr-env)
+
+## Build/deploy review gate
+
+Use this gate whenever a change may pass in dev but fail in built SSR output.
+
+- [ ] I checked whether the change must be verified in built mode.
+- [ ] I verified the relevant build path instead of assuming dev success is enough.
+- [ ] I checked whether client assets and SSR output stay aligned for the target flavor.
+- [ ] If the change crosses the frontend/backend SSR boundary, I reviewed the fullstack build path too.
+
+## What a reviewer should flag immediately
+
+Flag the change for follow-up when any of these are true:
+
+- the review checked only client behavior and skipped server-render behavior
+- the fix adds a parallel SSR-specific workaround instead of using an existing framework abstraction
+- the change assumes one edition's theme/UI behavior applies universally
+- the change was validated only in dev even though the failure is deploy- or build-sensitive
+- the review never identified which SSR layer was actually changing
+
+## Reviewer template
+
+Use this short template in PR review, AI review, or self-review when a change touches SSR behavior.
+
+- [ ] I identified the SSR layer first.
+- [ ] I separated server-render checks from hydration checks.
+- [ ] I verified whether the change needs built-mode validation.
+- [ ] I checked whether the change reuses existing SSR abstractions.
+- [ ] I reviewed edition/theme assumptions where relevant.
+- [ ] I verified the most relevant neighboring guide for this change category.
+
+## Prompt-ready reviewer snippet
+
+Use this block directly in a reviewer-agent or code-review prompt when a change touches SSR behavior:
+
+```text
+Review this change with the Cabloy SSR checklist in mind.
+
+1. Identify which SSR layer the change touches: Vona SSR orchestration, frontend build output, Zova SSR server render, or client hydration.
+2. Separate server-render correctness from hydration correctness.
+3. Verify whether the change reuses the intended framework abstraction instead of adding a parallel workaround.
+4. Check whether the change needs built-mode validation rather than only dev-mode validation.
+5. Review edition-sensitive UI/theme assumptions when the change touches first paint, tokens, dark mode, or SSR env behavior.
+6. Flag any change whose review never identifies the failing or affected SSR layer.
+```
+
+## Read together
+
+Use this page together with:
+
+- [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+- [SSR Build and Deploy Guide](/frontend/ssr-build-deploy-guide)
+- [SSR Troubleshooting Guide](/frontend/ssr-troubleshooting-guide)
+- [Theme Guide](/frontend/theme-guide)
+- [Verification](/ai/verification)
+
+## Verification checklist
+
+Before accepting an SSR-related change, ask:
+
+1. did the review identify the affected SSR layer clearly?
+2. did the review cover both the relevant runtime stage and the relevant workflow stage?
+3. did the review verify edition/theme assumptions when the change was SSR-UI-sensitive?
+4. did the review use the smallest correct checklist rather than relying on intuition alone?
+
+That keeps SSR reviews consistent across human contributors and AI-assisted workflows.