cabloy 5.1.50 → 5.1.51

package/cabloy-docs/backend/quickstart.md

@@ -0,0 +1,141 @@
+# Backend Quickstart
+
+This guide explains the fastest way to get oriented on the backend side of the Cabloy framework repository.
+
+If you want to create and use a Cabloy project, start with [Fullstack Quickstart](/fullstack/quickstart).
+
+## When to use this page
+
+Use this page when you are contributing backend work in the framework repository and want to understand Cabloy quickly:
+
+- required runtime dependencies
+- how backend development starts in the monorepo
+- what the historical project templates mean
+- which commands are the real source of truth today
+- which essentials pages to read next
+
+## Prerequisites
+
+| Name       | Version   |
+| ---------- | --------- |
+| pnpm       | >=10.19.0 |
+| Node.js    | >=24.8.0  |
+| Redis      | >=7.2.6   |
+| Sqlite3    | Built-in  |
+| MySQL      | >=8       |
+| Postgresql | >=16      |
+
+Notes:
+
+- Redis underpins capabilities such as queue, startup, election-adjacent distributed coordination, schedule, broadcast, caching, two-layer cache, and redlock.
+- If you use Sqlite3, make sure the node-gyp toolchain is ready so native dependencies can compile correctly.
+
+## Framework repository entrypoint
+
+In the Cabloy framework repository, start from the root scripts instead of thinking in terms of a standalone Vona repo.
+
+These commands are repository-root workflows for framework development, not the default bootstrap path for a normal Cabloy project.
+
+### Install and initialize
+
+```bash
+npm run init
+```
+
+### Start backend development
+
+```bash
+npm run dev
+```
+
+### Run tests
+
+```bash
+npm run test
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Start production output
+
+```bash
+npm run start
+```
+
+## Backend essentials reading path
+
+Before diving into feature-specific backend guides, it helps to read the essentials spine first:
+
+1. [Backend (Vona)](/backend/introduction)
+2. [Backend Foundation](/backend/foundation)
+3. [Backend Essentials](/backend/backend-essentials)
+4. [Backend CLI](/backend/cli)
+5. [Backend Scripts](/backend/scripts)
+6. [Service Guide](/backend/service-guide)
+7. [Package Map](/reference/package-map)
+
+This gives the architectural vocabulary for bean, scope, suite, module, package, and backend access patterns.
+
+## Historical template context
+
+Legacy Vona docs described creating projects from templates such as `cabloy-basic` and `cabloy-start`.
+
+That history still matters, because it explains why the Cabloy ecosystem now supports two editions:
+
+- **Cabloy Basic**: public reference repo with DaisyUI + TailwindCSS oriented frontend modules
+- **Cabloy Start**: sibling private repo with Vuetify-oriented frontend modules and different value-add composition
+
+In the current monorepo docs, do not treat these as just template names. Treat them as edition boundaries that affect frontend integration, scripts, and examples.
+
+## Backend configuration reminder
+
+Backend setup may still require editing `.env` values for database and Redis selection. In the monorepo, the exact values should always be taken from the current repo files under `vona/env/` rather than copied from archived guidance blindly.
+
+For the backend runtime/config family, read these pages together:
+
+- [Runtime and Flavors](/backend/runtime-and-flavors)
+- [Config Guide](/backend/config-guide)
+- [Backend Startup Guide](/backend/startup-guide)
+- [Multi-Instance and Instance Resolution](/backend/multi-instance-and-instance-resolution)
+- [Multi-Database and Datasource Guide](/backend/multi-database-datasource)
+
+## Recommended next pages
+
+Choose the next reading path based on the kind of backend task you are doing.
+
+### Architecture spine
+
+- [Backend (Vona)](/backend/introduction)
+- [Backend Foundation](/backend/foundation)
+- [Backend Essentials](/backend/backend-essentials)
+- [Backend CLI](/backend/cli)
+- [Backend Scripts](/backend/scripts)
+
+### Backend contract and data family
+
+- [Controller Guide](/backend/controller-guide)
+- [DTO Guide](/backend/dto-guide)
+- [Entity Guide](/backend/entity-guide)
+- [Model Guide](/backend/model-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [ORM Guide](/backend/orm-guide)
+
+### Runtime and distributed family
+
+- [Runtime and Flavors](/backend/runtime-and-flavors)
+- [Config Guide](/backend/config-guide)
+- [Backend Startup Guide](/backend/startup-guide)
+- [Multi-Instance and Instance Resolution](/backend/multi-instance-and-instance-resolution)
+- [Worker Guide](/backend/worker-guide)
+- [Election Guide](/backend/election-guide)
+- [Queue Guide](/backend/queue-guide)
+- [Broadcast Guide](/backend/broadcast-guide)
+
+### Fullstack bridge
+
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Fullstack Vona + Zova Integration](/fullstack/vona-zova-integration)

package/cabloy-docs/backend/redis-guide.md

@@ -0,0 +1,70 @@
+# Redis Guide
+
+This guide explains how Redis fits into Vona within the Cabloy monorepo.
+
+## Why Redis matters in Vona
+
+Redis is not a niche optional integration in Vona. It underpins several distributed capabilities across the framework.
+
+Redis supports a broad set of roles such as:
+
+- cache
+- queue and schedule
+- broadcast
+- redlock
+- other internal distributed services
+
+That makes Redis part of the Cabloy backend foundation rather than just an external service attachment.
+
+## Config model
+
+Redis configuration is organized around:
+
+- `base`
+- `clients`
+
+This is important because Vona treats Redis as a multi-client capability surface rather than as one undifferentiated connection.
+
+Representative built-in client roles include:
+
+- `default`
+- `cache`
+- `io`
+- `summer`
+- `model`
+- `redlock`
+- `queue`
+- `broadcast`
+
+## Key-prefix isolation
+
+Redis also supports `keyPrefix`.
+
+This matters because multiple projects or components may share Redis infrastructure, and keyspace isolation is a practical requirement rather than an afterthought.
+
+## Independent client configuration
+
+For larger systems, different distributed components can use independent Redis client configuration.
+
+That is important because queue, broadcast, locking, and caching may have different operational needs.
+
+## Adding a new Redis client
+
+The framework uses a typed extension model for adding clients:
+
+1. add client type definition
+2. add client config
+3. retrieve the client through the Redis bean
+
+This is valuable because Redis usage remains part of the typed application model.
+
+## Implementation checks for Redis-related backend changes
+
+When touching distributed or cache-heavy backend code, ask:
+
+1. which Redis client role is the right one for this behavior?
+2. does the existing config already define the needed client?
+3. should the change preserve key-prefix isolation?
+4. does the capability belong at the cache, queue, redlock, or broadcast layer rather than as an ad hoc Redis call?
+
+That keeps Redis usage aligned with the framework’s architecture.

package/cabloy-docs/backend/redlock-guide.md

@@ -0,0 +1,60 @@
+# Redlock Guide
+
+This guide explains how Redlock works in Vona within the Cabloy monorepo.
+
+## Why redlock matters
+
+In distributed systems, some operations need mutual exclusion across workers or nodes.
+
+Vona provides a Redlock-based distributed lock abstraction so that mutual exclusion can be expressed as a framework-level capability rather than improvised with ad hoc coordination code.
+
+## Create a redlock definition
+
+Example: create redlock metadata in module `demo-student`.
+
+```bash
+npm run vona :create:bean meta redlock -- --module=demo-student
+```
+
+## Lock resource types
+
+One important design point is that lock resources should be typed.
+
+Representative areas include:
+
+- lock resources for `lock`
+- lock resources for `lockIsolate`
+
+This is valuable because lock identity becomes part of the typed contract rather than a random string scattered across the codebase.
+
+## `lock` vs `lockIsolate`
+
+Two lock methods are supported:
+
+- `lock`
+- `lockIsolate`
+
+The key difference is that `lockIsolate` incorporates datasource-level isolation to help avoid deadlocks related to datasource contention.
+
+That is a very important Vona-specific detail.
+
+## Template-literal resource names
+
+Lock-resource types can also use template literal patterns such as per-user lock names.
+
+This is important because it lets the code remain both flexible and typed.
+
+## Inspection
+
+The effective redlock list can be inspected, which is useful for debugging and operational understanding.
+
+## Implementation checks for distributed-lock changes
+
+When asked to protect a distributed critical section, ask:
+
+1. does this need a distributed lock at all?
+2. should it use `lock` or `lockIsolate`?
+3. what should the lock resource identity be?
+4. does the resource identity need a typed or templated naming scheme?
+
+That keeps distributed locking aligned with Vona’s intended concurrency model.

package/cabloy-docs/backend/relations-guide.md

@@ -0,0 +1,250 @@
+# Relations Guide
+
+This guide explains how ORM relations work in Vona within the Cabloy monorepo.
+
+## Why relations matter
+
+In Vona, relationships are not only for nicer reads. They shape:
+
+- query composition
+- nested CRUD behavior
+- aggregate/group behavior on related data
+- DTO inference
+- OpenAPI-facing contract shape
+- cross-model navigation in business code
+
+That makes relations one of the most important bridges between persistence structure and fullstack contract design.
+
+## Four relation kinds
+
+Four main relation types are supported:
+
+- `hasOne`
+- `belongsTo`
+- `hasMany`
+- `belongsToMany`
+
+Together they cover common `1:1`, `n:1`, `1:n`, and `n:n` structures.
+
+## Static relations vs dynamic relations
+
+A useful distinction is:
+
+- **static relations** are declared in model metadata and reused across operations
+- **dynamic relations** are declared at the usage site through `with`
+
+A practical rule is:
+
+- prefer static relations when the relation is part of the model’s stable business structure
+- use dynamic relations when the relation is situational, cross-module, or too numerous to declare everywhere up front
+
+## `hasOne`
+
+Representative static definition:
+
+```typescript
+@Model({
+  entity: EntityPost,
+  relations: {
+    postContent: $relation.hasOne('test-vona:postContent', 'postId', {
+      columns: ['id', 'content'],
+    }),
+  },
+})
+class ModelPost {}
+```
+
+`hasOne` is important because the same relation can participate in:
+
+- nested insert
+- nested get
+- nested update
+- nested delete
+
+through `include` or `with`.
+
+## `belongsTo`
+
+`belongsTo` is mainly a query-time relationship.
+
+Representative pattern:
+
+```typescript
+const postContent = await this.scope.model.postContent.select({
+  include: {
+    post: true,
+  },
+});
+```
+
+That means it is especially useful for retrieving related parent-side data through model-aware query operations.
+
+## `hasMany`
+
+`hasMany` is especially important because it supports main-details structures, including scenarios where nested create/update/delete behavior happens together with the parent record.
+
+Representative pattern:
+
+```typescript
+await this.scope.model.order.update(
+  {
+    id: orderCreate.id,
+    orderNo: 'Order001-Update',
+    products: [
+      { name: 'Peach' },
+      { id: orderCreate.products?.[0].id, name: 'Apple-Update' },
+      { id: orderCreate.products?.[1].id, deleted: true },
+    ],
+  },
+  {
+    include: {
+      products: true,
+    },
+  },
+);
+```
+
+This is one of the strongest reasons Cabloy can express CRUD-oriented business flows compactly.
+
+## `belongsToMany`
+
+`belongsToMany` models `n:n` relations through an intermediate model.
+
+Representative definition:
+
+```typescript
+@Model({
+  entity: EntityUser,
+  relations: {
+    roles: $relation.belongsToMany('test-vona:roleUser', 'test-vona:role', 'userId', 'roleId', {
+      columns: ['id', 'name'],
+    }),
+  },
+})
+class ModelUser {}
+```
+
+The key point is that relation-aware CRUD here operates on the intermediate model, not directly on the target model.
+
+## `include` vs `with`
+
+A practical distinction is:
+
+- use `include` when operating on a declared static relation
+- use `with` when declaring a dynamic relation inline for the current operation
+
+| Relation-loading style | Best for                                           | Typical source of truth      |
+| ---------------------- | -------------------------------------------------- | ---------------------------- |
+| `include`              | stable business relations reused across operations | model metadata               |
+| `with`                 | situational, dynamic, or cross-module relations    | usage-site query or mutation |
+
+Dynamic relations are especially useful when a model cannot reasonably declare every cross-module or situational relation in advance.
+
+Representative static pattern:
+
+```typescript
+return this.scope.model.order.select({
+  ...params,
+  include: {
+    products: true,
+  },
+});
+```
+
+Representative dynamic pattern:
+
+```typescript
+const postContent = await this.scope.model.postContent.select({
+  with: {
+    post: $relationDynamic.belongsTo(
+      () => ModelPostContent,
+      () => ModelPost,
+      'postId',
+      {
+        columns: ['id', 'title'],
+      },
+    ),
+  },
+});
+```
+
+## Autoload and tree-shaped relations
+
+`autoload: true` is useful when a relation should usually travel with the main model.
+
+That is especially helpful for tree-shaped structures.
+
+Representative idea:
+
+- a self-referential `hasMany` relation with `autoload: true` can express parent-to-children trees
+- a self-referential `belongsTo` relation with `autoload: true` can express reverse traversal from child to parent
+
+A practical example is a category model whose `children` relation autoloads and only exposes the tree-oriented fields that usually matter for navigation, such as `id` and `name`.
+
+This keeps tree-shaped domain structures inside the ORM relation model instead of hand-authoring traversal logic everywhere.
+
+## Relation aggregation and grouping
+
+Relations are not limited to row-oriented loading. They can also express aggregate- or group-oriented derived data.
+
+Examples include:
+
+- a dynamic `hasMany` relation with `aggrs`
+- a dynamic `hasMany` relation with `groups` + `aggrs`
+- static relations that autoload grouped or aggregated related summaries
+
+That means relation metadata can shape reporting-style substructures as well as ordinary object graphs.
+
+For deeper summary-query guidance, also see [ORM Aggregate and Group Guide](/backend/orm-aggregate-group-guide).
+
+## Relation options and datasource metadata
+
+Representative relation option areas include:
+
+- `autoload`
+- `columns`
+- `include`
+- `with`
+- `meta.client`
+- `meta.table`
+- `distinct`
+- `where`
+- `joins`
+- `orders`
+- `limit`
+- `offset`
+- `aggrs`
+- `groups`
+
+A particularly important advanced point is that `meta.client` and related datasource metadata can route relations across datasources.
+
+That is why relation design must sometimes be read together with multi-datasource architecture rather than treated as a purely local model concern.
+
+## Metadata regeneration
+
+Relation changes require regenerating metadata.
+
+That is important for AI workflows because relation changes are not purely local edits. They can affect type generation and downstream framework behavior.
+
+## Relationship to ORM depth pages
+
+Read this guide together with:
+
+- [ORM Select Guide](/backend/orm-select-guide)
+- [ORM Mutation Guide](/backend/orm-mutation-guide)
+- [ORM Aggregate and Group Guide](/backend/orm-aggregate-group-guide)
+- [Multi-Database and Datasource Guide](/backend/multi-database-datasource)
+- [DTO Infer and Generation](/backend/dto-infer-generation)
+
+## Implementation checks for model-relationship changes
+
+When adding or editing model relationships, ask:
+
+1. which relation kind actually matches the business structure?
+2. should the relation be static metadata or a dynamic usage-site relation?
+3. should the relation participate only in queries, or also in nested CRUD behavior?
+4. does the relation carry grouped or aggregated derived data?
+5. do metadata need to be regenerated?
+6. does the relation change affect DTO inference, OpenAPI, or frontend integration?
+
+That keeps relations aligned with the broader Cabloy contract system.