cabloy 5.1.50 → 5.1.52

package/cabloy-docs/backend/aop-overview.md

@@ -0,0 +1,128 @@
+# AOP Overview
+
+## Why AOP matters in Vona
+
+Vona uses AOP to make cross-cutting backend behavior explicit, composable, and framework-native.
+
+That matters because concerns such as middleware flow, authentication checks, validation, transactions, logging, caching, and error handling should not be re-implemented ad hoc in every controller or service method.
+
+## The three AOP capability families
+
+Vona AOP can be understood in three capability families:
+
+1. **Controller AOP** for request-path behavior around controller actions
+2. **Internal AOP** for adding behavior inside a class through decorators or magic methods
+3. **External AOP** for attaching behavior to a class from the outside without editing the class source code
+
+## Controller AOP families
+
+The controller-facing AOP system includes five main aspect families:
+
+- **middleware**
+- **guard**
+- **interceptor**
+- **pipe**
+- **filter**
+
+These families work together to shape request execution, parameter handling, error behavior, and API policy.
+
+## Execution model
+
+Two controller AOP families use an onion-style execution model:
+
+- **middleware**
+- **interceptor**
+
+That means they can run logic both before and after the controller action.
+
+Other controller AOP families participate in more specialized stages:
+
+- **guard** checks access or execution preconditions
+- **pipe** transforms or validates request values
+- **filter** handles exceptions and logging behavior
+
+A practical controller-path mental model is:
+
+1. system middleware runs before route matching
+2. route matching happens
+3. global and local middleware wrap the matched route
+4. guards enforce access preconditions
+5. pipes transform and validate incoming values
+6. interceptors wrap controller execution
+7. the controller action runs
+8. filters handle thrown exceptions and logging customization when failures occur
+
+That model is the fastest way to decide which aspect family should own a change.
+
+## System, global, and local scope
+
+Controller AOP also varies by scope:
+
+- **system** middleware runs before route matching
+- **global** aspects are auto-loaded and can be applied broadly with runtime filters such as `match`, `ignore`, `mode`, or `flavor`
+- **local** aspects are attached directly to a controller class or action
+
+Built-in aspects and shorthand decorators sit on top of the same general model.
+
+Across controller, internal, and external AOP, the same operational ideas appear repeatedly:
+
+- default options in the aspect definition
+- per-usage option overrides
+- app-config overrides through `config.onions`
+- enable/disable switches
+- runtime targeting through `mode` and `flavor`
+- ordering through `dependencies` and `dependents`
+- inspection of the effective chains at runtime
+
+That consistency is one of the biggest reasons the Vona AOP surface stays learnable even though it covers many different extension points.
+
+## Validation, OpenAPI, and AOP
+
+Vona’s AOP model is closely connected to:
+
+- controller argument handling through `@Arg.*`
+- Zod-based validation
+- Swagger/OpenAPI generation
+
+That means AOP is not only about request middleware. It is also part of how Vona turns request contracts into typed, machine-readable framework behavior.
+
+## Internal AOP
+
+Internal AOP provides two main mechanisms:
+
+- **AOP Method** for decorating class methods
+- **Magic Method** for dynamic behavior such as `__get__`, `__set__`, or `__method__`
+
+These mechanisms help keep code concise while still making transactions, logging, caching, scope lookup, and dynamic access patterns explicit.
+
+## External AOP
+
+External AOP uses `@Aop({ match: ... })` to attach behavior to another class by bean name.
+
+This is useful when the desired extension logic should live outside the target class, for example when layering timing, logging, lifecycle hooks, or dynamic method interception onto an existing service or bean.
+
+A simple ownership rule is:
+
+- choose **controller AOP** when the concern belongs to the HTTP request path
+- choose **internal AOP** when the behavior belongs naturally to the class that owns the method
+- choose **external AOP** when the behavior should remain decoupled from the target class source
+
+## Recommended reading path
+
+For the unified docs, use this progression:
+
+1. [Controller AOP Guide](/backend/controller-aop-guide)
+2. [Validation Guide](/backend/validation-guide)
+3. [Internal AOP Guide](/backend/internal-aop-guide)
+4. [External AOP Guide](/backend/external-aop-guide)
+
+## Questions for AOP-sensitive changes
+
+When changing backend behavior in Vona, ask:
+
+1. is this concern already represented by middleware, guard, interceptor, pipe, or filter?
+2. should this logic be expressed through an internal AOP decorator instead of manual repetition?
+3. is an external aspect a better fit than modifying the target class directly?
+4. does the change interact with validation, OpenAPI, caching, transactions, or runtime environment controls?
+
+That helps AI keep backend changes aligned with Vona’s real execution model rather than rewriting them into generic framework patterns.

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

@@ -0,0 +1,151 @@
+# Auth Guide
+
+## Why auth matters in Vona
+
+Vona treats authentication as a framework-level capability rather than a one-off login endpoint.
+
+That matters because real systems often need more than one authentication method, more than one credential source, and more than one post-auth workflow.
+
+## Core auth model
+
+The `a-auth` module provides a general authentication system built around **auth providers**.
+
+This model supports:
+
+- multiple authentication methods such as username/password and OAuth
+- multiple clients per provider
+- association of multiple authentication methods to one user
+- migration of authentication methods from one user to another
+
+## `bean.auth`
+
+Vona exposes a global bean `bean.auth` so backend code can use all registered auth providers through one unified entrypoint.
+
+Representative provider-generation workflow:
+
+```bash
+npm run vona :create:bean authProvider simple -- --module=auth-simple
+npm run vona :create:bean authProvider oauth -- --module=auth-oauth
+```
+
+Those providers still plug into the shared `:create:bean` command surface, which keeps auth extension aligned with the rest of Vona’s bean architecture.
+
+### Username/password example
+
+```typescript
+const jwt = await this.bean.auth.authenticate('auth-simple:simple', {
+  clientOptions: { username: 'admin', password: '123456' },
+});
+```
+
+### OAuth example
+
+```typescript
+await this.bean.auth.authenticate('auth-oauth:oauth', {
+  clientName: 'github',
+  state: { redirect: '/' },
+});
+```
+
+## Auth provider types
+
+### `auth-simple`
+
+`auth-simple` provides an out-of-the-box username/password provider.
+
+Representative flows include:
+
+- register a new user by calling `bean.auth.authenticate(..., { state: { intention: 'register' } })`
+- log in by calling `bean.auth.authenticate(..., { state: { intention: 'login' } })`
+- sign out through `bean.passport.signout()`
+
+It also exposes password-hash configuration through app config.
+
+### `auth-oauth`
+
+`auth-oauth` provides an OAuth-based provider model.
+
+Representative capabilities include:
+
+- built-in support for GitHub
+- adding new OAuth strategies such as Google through client configuration and interface merging
+- unified callback handling
+- exchanging the returned OAuth code for a JWT token through the Passport API flow
+- optional mock login behavior in development
+
+## Provider and client model
+
+A provider can expose multiple clients.
+
+For example, one OAuth provider can expose `github`, `google`, or other client entries, each with its own strategy and credentials.
+
+That means auth configuration is not hardwired to one provider/credential pair.
+
+## State and auth intent
+
+Authentication calls can carry state such as:
+
+- `register`
+- `login`
+- `associate`
+- `migrate`
+- redirect target after successful OAuth flow
+
+This is one of the reasons Vona auth can support richer account flows without scattering those rules across unrelated controller code.
+
+## Profile-driven user creation
+
+Auth providers usually return profile data rather than directly creating a final user shape by hand.
+
+That profile is then consumed by the broader user and passport system.
+
+This separation helps Vona keep provider logic, user logic, and business customization decoupled.
+
+A practical rule is that the provider should prove identity and return a stable profile, while user creation and passport assembly remain downstream responsibilities handled by the user/passport layers.
+
+## OAuth credentials and callback flow
+
+OAuth credentials are configured through app config under the relevant auth provider client entry.
+
+The typical flow is:
+
+1. redirect to the provider
+2. receive the OAuth callback code
+3. exchange the code for a JWT token
+4. continue through the passport and user flow
+
+The out-of-the-box Passport controller in `home-user` exposes that exchange as `createPassportJwtFromOauthCode`, which is why frontend OAuth flows usually stay thin: the provider redirect happens first, and the frontend then asks the Passport API to finish JWT creation.
+
+## Passport API relationship
+
+The `home-user` module exposes out-of-the-box Passport APIs for common account flows such as:
+
+- current passport retrieval
+- login
+- logout
+- registration
+- OAuth login
+- associate / migrate auth methods
+- token refresh
+- temporary auth token creation
+
+In the current repo implementation, these flows live in `home-user/src/controller/passport.ts`, where register/login call `bean.auth.authenticate(...)`, OAuth login uses provider/module path parameters, and token-oriented follow-up endpoints stay concentrated in one controller surface.
+
+This guide focuses on the framework-level auth model. For the user/passport side, see [User Access Guide](/backend/user-access-guide).
+
+## Relationship to controller AOP
+
+Auth behavior is closely connected to controller AOP, especially guards.
+
+Built-in passport-oriented guard shorthands such as `@Passport.public()` are documented from the request-path perspective in [Controller AOP Guide](/backend/controller-aop-guide).
+
+## Implementation checks for authentication changes
+
+When editing authentication behavior, ask:
+
+1. is the right layer `bean.auth`, `bean.passport`, or controller guard configuration?
+2. does this flow belong to username/password auth, OAuth auth, or both?
+3. does a provider already exist instead of needing custom authentication code?
+4. does the flow need register, login, associate, migrate, or redirect-aware state?
+
+That helps AI keep auth logic aligned with Vona’s real backend architecture.

package/cabloy-docs/backend/backend-essentials.md

@@ -0,0 +1,128 @@
+# Backend Essentials
+
+## Why this page exists
+
+The backend docs already explain many Vona workflows in detail, but the core backend mental model spans several pages.
+
+This page provides one compact entrypoint for that model.
+
+Use it when you want to understand how backend code is organized before diving into feature-specific guides.
+
+For the broader backend entry page that groups the main families, also see [Backend (Vona)](/backend/introduction).
+
+## The three core clusters
+
+The backend essentials family is easiest to understand as three connected clusters:
+
+### 1. IoC and bean containers
+
+Vona backend code is built around framework-managed beans rather than ad hoc class instantiation.
+
+The key concepts are:
+
+- app container
+- ctx container
+- new-bean creation
+- dependency injection
+- dependency lookup
+- direct bean access
+- bean identifiers and onion names
+- bean scenes
+- bean lifecycle hooks
+- BeanBase built-in members
+
+Read next:
+
+- [Backend Foundation](/backend/foundation)
+- [Service Guide](/backend/service-guide)
+- [Class Placement Rule](/ai/class-placement-rule)
+- [Backend Startup Guide](/backend/startup-guide)
+
+### 2. Scope and module resource access
+
+The most practical backend access model is module scope.
+
+That includes:
+
+- local module access through `this.scope`
+- cross-module access through `this.$scope`
+- resource categories such as service, model, entity, config, constant, locale, and error
+- explicit leaves such as [Config Guide](/backend/config-guide) and [Error Guide](/backend/error-guide)
+
+A useful refinement is that `constant` and `locale` should be treated as first-class scope resources too, not as secondary extras.
+
+A practical split is:
+
+- `config` and `error` help define backend policy and failure behavior
+- `constant` and `locale` help define stable module vocabulary and translatable text surfaces
+- all of them still fit the same scope-based access model rather than requiring ad hoc imports everywhere
+
+This is one of the reasons backend code can stay concise without flattening everything into imports or manual container wiring.
+
+Read next:
+
+- [Service Guide](/backend/service-guide)
+- [Model Guide](/backend/model-guide)
+- [Entity Guide](/backend/entity-guide)
+- [DTO Guide](/backend/dto-guide)
+
+### 3. Modularization across suite / module / package
+
+Vona backend architecture is also organized around structural units, not just source folders.
+
+The main units are:
+
+- suite
+- module
+- package
+
+Those boundaries matter because they shape:
+
+- naming
+- dependency declarations
+- generated file placement
+- module-scope resource access
+- backend CLI workflows
+
+Read next:
+
+- [Backend CLI](/backend/cli)
+- [Backend Scripts](/backend/scripts)
+- [Package Map](/reference/package-map)
+
+## Suggested reading path
+
+If you are new to backend architecture, read in this order:
+
+1. [Backend Foundation](/backend/foundation)
+2. [Backend CLI](/backend/cli)
+3. [Backend Scripts](/backend/scripts)
+4. [Service Guide](/backend/service-guide)
+5. [Model Guide](/backend/model-guide)
+6. [Entity Guide](/backend/entity-guide)
+7. [DTO Guide](/backend/dto-guide)
+8. [Runtime and Flavors](/backend/runtime-and-flavors)
+9. [Backend Startup Guide](/backend/startup-guide)
+
+## How this page relates to the rest of the backend docs
+
+This page is a compact family hub, not the deep technical home for each backend topic.
+
+A practical split is:
+
+- [Backend (Vona)](/backend/introduction) is the broader backend entry page
+- [Backend Foundation](/backend/foundation) explains the architecture-first model
+- [Service Guide](/backend/service-guide) explains the most practical access patterns
+- [Backend CLI](/backend/cli) and [Backend Scripts](/backend/scripts) explain workflow entrypoints
+- [Package Map](/reference/package-map) grounds the structure in the real monorepo
+
+## Implementation checks for backend-architecture changes
+
+When changing backend code, ask:
+
+1. is this capability best reached through local module scope, cross-module scope, injection, or direct bean access?
+2. does the change belong to a module, a suite, or a shared package boundary?
+3. is there already a CLI workflow or bean type that should be reused instead of manual scaffolding?
+4. does the change belong to the architecture spine first, or only to one feature-specific guide?
+
+That helps AI keep backend changes aligned with Vona’s real architecture instead of only copying local code patterns.

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

@@ -0,0 +1,138 @@
+# Broadcast Guide
+
+This guide explains how broadcast works in Vona within the Cabloy monorepo.
+
+## Why broadcast matters
+
+Broadcast lets one worker emit a message that multiple worker processes can receive and act on.
+
+This is important because some business logic is not point-to-point background work. It is multi-worker coordination work.
+
+## Create a broadcast
+
+Example: create a broadcast named `echo` in module `demo-student`.
+
+```bash
+npm run vona :create:bean broadcast echo -- --module=demo-student
+```
+
+## Broadcast definition
+
+Representative shape:
+
+```typescript
+@Broadcast()
+export class BroadcastEcho
+  extends BeanBroadcastBase<TypeBroadcastEchoJobData>
+  implements IBroadcastExecute<TypeBroadcastEchoJobData>
+{
+  async execute(data: TypeBroadcastEchoJobData, isEmitter?: boolean) {
+    if (!isEmitter) {
+      console.log(`pid: ${process.pid} message: ${data.message}`);
+    }
+  }
+}
+```
+
+The `isEmitter` flag is especially important because it lets the current worker avoid duplicating work it already performed locally.
+
+## Emit a broadcast
+
+Representative usage:
+
+```typescript
+this.scope.broadcast.echo.emit({ message: 'Hello world' });
+```
+
+A practical interpretation is:
+
+- the emitter starts the fan-out
+- every receiving worker can execute the same logic
+- the emitter can skip duplicate local work by checking `isEmitter`
+
+## Broadcast options
+
+Broadcast options include:
+
+- `instance`
+- `transaction`
+
+Representative decorator pattern:
+
+```typescript
+@Broadcast({
+  instance: true,
+  transaction: true,
+})
+class BroadcastEcho {}
+```
+
+This matters because broadcast behavior may depend on tenant initialization or transactional execution guarantees.
+
+## Configure broadcasts in app config
+
+Broadcast options can also be overridden in app config.
+
+Representative pattern:
+
+```typescript
+config.onions = {
+  broadcast: {
+    'demo-student:echo': {
+      instance: true,
+      transaction: true,
+    },
+  },
+};
+```
+
+## Broadcast vs queue vs election
+
+Read this guide together with:
+
+- [Backend Startup Guide](/backend/startup-guide)
+- [Queue Guide](/backend/queue-guide)
+- [Election Guide](/backend/election-guide)
+- [Worker Guide](/backend/worker-guide)
+
+A practical split is:
+
+- use **broadcast** when many workers should all receive the same signal or perform the same category of work
+- use **queue** when one background execution path should process a job asynchronously
+- use **election** when only one worker, or a fixed small number of workers, should own the responsibility
+
+This distinction matters because all three features are distributed primitives, but they solve different coordination problems.
+
+## Relationship to backend runtime initialization
+
+Broadcast is not the same as startup.
+
+A useful mental model is:
+
+- startup initializes backend capabilities and lifecycle hooks
+- election chooses the owner for singleton-like responsibilities
+- broadcast fans out a message to many workers after the runtime is active
+
+That keeps runtime initialization separate from runtime signaling.
+
+## Inspection
+
+The effective broadcast list can be inspected for debugging and operational clarity.
+
+Representative pattern:
+
+```typescript
+this.bean.onion.broadcast.inspect();
+```
+
+## Implementation checks for multi-worker broadcast changes
+
+When evaluating multi-worker coordination needs, ask:
+
+1. is this really a queue job, or is it a broadcast?
+2. should the emitter worker also execute the business logic?
+3. does the logic require instance initialization?
+4. should the execution run inside a transaction?
+5. is this actually a singleton-ownership problem that belongs to election instead?
+
+That helps distribute the right kind of work through the right abstraction.

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

@@ -0,0 +1,70 @@
+# Cache Guide
+
+This guide explains how ORM caching works in Vona within the Cabloy monorepo.
+
+## Why caching is first-class in Vona
+
+Large business systems often fail not because performance is impossible, but because performance strategy is bolted on too late and too inconsistently.
+
+Vona responds by moving caching into the framework core.
+
+That means cache behavior is not only an optimization technique. It is part of the default data model.
+
+## Out-of-the-box behavior
+
+One major point is that Vona ORM offers out-of-the-box caching.
+
+In practice, that means ordinary ORM operations can benefit from framework-managed cache behavior without forcing the developer to hand-maintain every cache path.
+
+## Entity cache
+
+The entity cache centers on the mapping:
+
+- entity id -> entity data
+
+This is important because entity reads can become cheap and update/delete operations can invalidate the relevant entries systematically.
+
+## Query cache
+
+The query cache operates differently.
+
+For normal queries, the cache is based on:
+
+- hash of the query clause -> array of ids
+
+Then the final data is resolved through entity-cache retrieval.
+
+For aggregate and group operations, the cache can directly store the resulting computed data.
+
+This is one of the key Vona ideas: query cache and entity cache cooperate instead of duplicating responsibility blindly.
+
+## Cache configuration
+
+Cache configuration exists at both:
+
+- model options
+- app config
+
+Representative areas include:
+
+- entity-cache mode and ttl
+- query-cache mode and ttl
+- related-model cache clearing
+- custom cache-clearing logic
+
+## Consistency strategy
+
+Vona also clears or compensates cache automatically when model mutation occurs.
+
+That matters because a useful cache is not only about hits. It is about correctness under change.
+
+## Implementation checks for cache-sensitive data-access changes
+
+When changing data-access behavior, ask:
+
+1. is this path already covered by Vona’s built-in cache model?
+2. does the model cache config need to be updated?
+3. should related-model query caches also be cleared?
+4. does transaction-aware cache compensation matter for this change?
+
+That helps avoid both underusing and breaking the cache system.