cabloy 5.1.49 → 5.1.51

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

@@ -0,0 +1,162 @@
+# Captcha Guide
+
+## Why captcha matters in Vona
+
+Vona treats captcha as a reusable framework capability rather than a one-off image challenge.
+
+That matters because different business flows may need different captcha types, different verification strategies, and different frontend/backend interaction patterns.
+
+## Core captcha model
+
+The `a-captcha` module provides a general captcha system built around two concepts:
+
+- **captcha provider**
+- **captcha scene**
+
+### Provider
+
+A provider implements a captcha mechanism, such as image-text captcha or another verification style.
+
+### Scene
+
+A scene chooses how captcha should be used in a specific business context.
+
+A scene can:
+
+- select one provider
+- rotate across multiple providers
+- vary provider choice by user state or other business context
+
+## `bean.captcha`
+
+Vona exposes a global bean `bean.captcha` so backend code can work with captcha through one unified entrypoint.
+
+Representative generation workflow:
+
+```bash
+npm run vona :create:bean captchaProvider imageText -- --module=captcha-simple
+npm run vona :create:bean captchaScene simple -- --module=captcha-simple
+```
+
+The main operations are:
+
+- `create`
+- `refresh`
+- `verify`
+- `verifyImmediate`
+
+### Create captcha
+
+```typescript
+const captcha = await this.bean.captcha.create('captcha-simple:simple');
+```
+
+### Refresh captcha
+
+```typescript
+const captchaNew = await this.bean.captcha.refresh(captchaId, 'captcha-simple:simple');
+```
+
+### Verify captcha
+
+```typescript
+const passed = await this.bean.captcha.verify(captchaId, '1234', 'captcha-simple:simple');
+```
+
+### Immediate verification
+
+```typescript
+const tokenOrFalse = await this.bean.captcha.verifyImmediate(captchaId, '1234');
+```
+
+Immediate verification can return a secondary token that must still be verified again on form submission.
+
+## Provider model
+
+A provider defines:
+
+- token type
+- payload type
+- creation logic
+- verification logic
+- provider-specific options
+
+A representative provider can implement image-text captcha with fields such as:
+
+- `type`
+- `fontPath`
+- `opts`
+
+That makes captcha providers extensible rather than hardcoded to one built-in shape.
+
+The image-text example is a good mental model: provider code decides how to create and verify one captcha mechanism, while scene code decides when and why that mechanism should be chosen.
+
+## Scene model
+
+A scene defines:
+
+- which providers are available
+- how one provider is resolved for the current request
+- how provider-level options can be configured or overridden
+
+That means business policy can be expressed at the scene layer while implementation details remain in the provider layer.
+
+A representative scene can choose one provider statically, rotate among several providers, or vary difficulty and provider options by request context or user state.
+
+## Captcha verify interceptor
+
+Vona also provides a local interceptor for captcha verification:
+
+```typescript
+@Core.captchaVerify({ scene: 'captcha-simple:simple' })
+```
+
+This interceptor supports:
+
+- normal form verification
+- secondary verification after `verifyImmediate`
+
+This is the most important request-path integration point for captcha in ordinary controller code.
+
+## Built-in captcha API
+
+The `a-captcha` module exposes out-of-the-box captcha APIs for:
+
+- `create`
+- `refresh`
+- `verifyImmediate`
+
+The direct `verify` path is usually consumed through the interceptor-oriented request flow.
+
+## Configuration
+
+Captcha behavior can be configured through app config, including:
+
+- whether to expose the token for debugging
+- captcha token TTL
+- secondary-token TTL
+- provider-specific options
+- scene-specific provider setup
+
+A useful separation rule is:
+
+- module config for broad captcha defaults such as `showToken`
+- `config.onions.captchaProvider` for provider-level TTL and option tuning
+- `config.onions.captchaScene` for scene-level provider selection and overrides
+
+## Relationship to auth flows
+
+Captcha is often used in login, registration, or other user-facing flows, but it should remain a separate framework concern.
+
+That makes it easier to reuse the same captcha capability across different account-related APIs.
+
+## Implementation checks for captcha-sensitive changes
+
+When editing captcha-sensitive flows, ask:
+
+1. is the right layer the provider, the scene, or the request interceptor?
+2. does the flow need immediate verification, form verification, or both?
+3. should the captcha policy vary by business scenario?
+4. is there already an existing scene/provider combination that should be reused?
+
+That helps AI keep captcha behavior aligned with Vona’s reusable verification model.

package/cabloy-docs/backend/cli.md

@@ -0,0 +1,173 @@
+# Backend CLI
+
+This guide explains how to use the Vona CLI in the Cabloy monorepo.
+
+## Why the CLI matters
+
+Vona provides a large number of CLI commands for generating code skeletons and running backend workflows.
+
+For implementation work, the CLI is especially important because it encodes framework conventions directly. If a command already exists, use it before writing backend scaffolding manually.
+
+## Entry from repo root
+
+The current monorepo entrypoint is defined at the repo root:
+
+```bash
+npm run vona :
+```
+
+That wrapper points to the Vona CLI under `vona/packages-cli/` while preserving the monorepo project path.
+
+## Command discovery pattern
+
+Vona commands follow a consistent discovery model.
+
+### 1. List all command groups and commands
+
+```bash
+npm run vona :
+```
+
+### 2. List commands for a specific group
+
+```bash
+npm run vona :create
+```
+
+### 3. Inspect help for one command
+
+```bash
+npm run vona :create:bean --help
+```
+
+This discovery pattern should be the default contributor workflow before inventing manual scaffolding steps.
+
+## High-value command families
+
+From the current source tree, the most useful Vona command families for day-to-day development are:
+
+- `bin:*`
+- `create:*`
+- `init:*`
+- `tools:*`
+
+Typical use cases include:
+
+- scaffold suites, modules, beans, and tests
+- initialize config, locale, constants, assets, types, and related module-scope resources
+- generate CRUD-oriented resources
+- refresh metadata and dependency-related output
+- run build, dev, test, typecheck, playground, and database reset flows
+
+## Generator-first workflow
+
+A practical backend workflow is:
+
+1. inspect the command family
+2. run the generator or initializer
+3. inspect the generated suite/module/bean structure
+4. only then add the minimal manual logic the task actually needs
+
+This matters because backend modularization, naming, and bean scenes are part of the framework architecture, not only coding style.
+
+## Representative generation examples
+
+### Create a suite
+
+```bash
+npm run vona :create:suite suiteName
+```
+
+### Create a module
+
+```bash
+npm run vona :create:module moduleName -- [--suite=]
+```
+
+### Create a service bean
+
+```bash
+npm run vona :create:bean service student -- --module=demo-student
+```
+
+### Create a model bean
+
+```bash
+npm run vona :create:bean model student -- --module=demo-student
+```
+
+### Create an entity bean
+
+```bash
+npm run vona :create:bean entity student -- --module=demo-student
+```
+
+### Create a DTO bean
+
+```bash
+npm run vona :create:bean dto studentCreate -- --module=demo-student
+```
+
+### Create a startup bean
+
+```bash
+npm run vona :create:bean startup log -- --module=demo-student
+```
+
+These examples show that the CLI is tightly connected to module boundaries and bean scenes such as service, model, entity, DTO, and startup.
+
+A practical bean-scene reading is:
+
+- `service`, `model`, `entity`, `dto`, and `startup` are representative bean scenes
+- `:create:bean sceneName beanName -- --module=...` uses `sceneName` as the operational family slot inside the bean identifier
+- this is why generated bean names later appear in forms such as `module.scene.bean`
+
+## Initializer-family examples
+
+Not every backend resource is created through bean scenes.
+
+Representative initializer commands include:
+
+```bash
+npm run vona :init:constant demo-student
+npm run vona :init:types demo-student
+npm run vona :init:asset static -- --module=demo-student
+```
+
+A practical distinction is:
+
+- `:create:bean` creates scene-based backend beans
+- `:init:*` commands create module-scope resources such as constants, typings, or asset-resource structure
+
+## Relationship to modules, suites, and package metadata
+
+The backend CLI is not only a code generator. It is also one of the clearest expressions of Vona’s modular architecture.
+
+CLI generation decisions affect:
+
+- where files live
+- which suite or module owns the resource
+- how bean identifiers and onion names are derived
+- how package metadata and dependencies should be interpreted later
+
+For the current repo structure, also see [Package Map](/reference/package-map).
+
+## CLI vs scripts
+
+A practical distinction is:
+
+- use [Backend Scripts](/backend/scripts) for root dev/build/start/test workflows
+- use the Vona CLI when you are discovering commands, generating backend resources, or running backend-specific tool flows
+
+This keeps contributor workflows clear instead of mixing runtime scripts with generator commands.
+
+## Generator-first workflow checklist
+
+When creating backend code:
+
+1. inspect `npm run vona :` or the relevant command family
+2. prefer the matching generator or initializer
+3. inspect the generated output
+4. only then make minimal follow-up edits
+
+This reduces unnecessary manual scaffolding and keeps the implementation aligned with Vona conventions.

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

@@ -0,0 +1,249 @@
+# Config Guide
+
+## Why config matters as a backend scope resource
+
+In Vona, configuration is not only a global backend settings concern. It is also a module-scoped resource that can be defined close to a module and then accessed through scope.
+
+That matters because backend capabilities often need both:
+
+- reusable module-local defaults
+- project-level overrides for the current application
+- runtime-sensitive configuration chosen by mode, flavor, and instance
+
+## Initialize the config skeleton
+
+Example: initialize config for module `demo-student`.
+
+```bash
+npm run vona :init:config demo-student
+```
+
+This gives the module its own config file under the module’s config area.
+
+## Define module config
+
+Representative pattern:
+
+```typescript
+export function config(_app: VonaApplication) {
+  return {
+    title: 'Hello World',
+  };
+}
+```
+
+The important point is that module config fields are declared directly, and the framework extracts the config typing from that shape.
+
+## Use config within the current module
+
+The current module’s config can be accessed through scope.
+
+Representative pattern:
+
+```typescript
+console.log(this.scope.config.title);
+```
+
+This keeps config access aligned with the same module-resource model used for service, model, entity, locale, and error.
+
+## Use config across modules
+
+Cross-module config access uses the cross-module scope surface.
+
+Representative pattern:
+
+```typescript
+console.log(this.$scope.demoStudent.config.title);
+```
+
+A practical distinction is:
+
+- `this.scope.config` for the current module
+- `this.$scope.<module>.config` for another module
+
+## Project config is layered, not single-file
+
+At the application level, Vona config is assembled from a cascading set of config files.
+
+In the current repo, representative project config files include:
+
+- `config.ts`
+- `config.dev.ts`
+- `config.dev.play.ts`
+- `config.test.ts`
+- `config.prod.ts`
+- `config.dev.local.ts`
+- `config.test.local.ts`
+- `config.prod.local.ts`
+- `config.local.tsx`
+
+That means effective config is built by merging general config with more specific runtime/flavor/local layers.
+
+A practical mental model is:
+
+1. start from the shared base config
+2. merge mode-specific config
+3. merge flavor-specific config when present
+4. merge local override config last
+
+This is one of the main reasons backend config should be understood together with [Runtime and Flavors](/backend/runtime-and-flavors).
+
+## Async config loading is normal
+
+In the current Vona startup flow, project config items are loaded asynchronously and then deep-merged.
+
+That means async config is a normal part of the framework model rather than a special workaround.
+
+A practical implication is:
+
+- config can safely derive values from runtime information, filesystem state, or other async setup needs during config assembly
+
+## How runtime env and flavor affect config
+
+Runtime metadata does not only choose env files. It also participates directly in config assembly.
+
+In the current app config, representative fields derived from env/meta include:
+
+- `config.meta.mode`
+- `config.meta.flavor`
+- `config.server.workers`
+- `config.server.listen.*`
+- `config.server.serve.*`
+- `config.database.defaultClient`
+- logger, Redis, and mail client settings
+
+That means config selection and runtime selection are part of one continuous flow rather than two unrelated systems.
+
+## Override module config at the project level
+
+Project-level config can override module-level defaults.
+
+Representative pattern:
+
+```typescript
+config.modules = {
+  'demo-student': {
+    title: 'Hello World!!',
+  },
+};
+```
+
+This is the key ownership rule:
+
+- module config defines reusable defaults close to the module
+- project config overrides those defaults for the current backend application
+
+## App config vs instance-merged config
+
+One important Vona distinction is:
+
+- `this.app.config` is the global application config
+- `this.ctx.config` is the effective config for the current instance-aware request context
+
+That matters in multi-instance or multi-tenant scenarios.
+
+In the current runtime, instance config is assembled by merging:
+
+1. the global app config
+2. any static config under `config.instance.instances[instanceName].config`
+3. any stored instance config data from the instance record
+
+A practical interpretation is:
+
+- use `app.config` when you need the backend-wide config baseline
+- use `ctx.config` when behavior should respect the active instance
+
+## Config access surfaces at a glance
+
+| Access surface                | Typical meaning                                        |
+| ----------------------------- | ------------------------------------------------------ |
+| `app.config`                  | app-wide baseline config                               |
+| `ctx.config`                  | effective config for the active instance-aware context |
+| `this.scope.config`           | current-module config resource                         |
+| `this.$scope.<module>.config` | another module’s config resource                       |
+
+A practical rule is:
+
+- use `scope` access when the task is about module-owned config
+- use `app.config` when the task is about backend-wide baseline behavior
+- use `ctx.config` when request-scoped behavior must respect the active instance
+
+## Effective instance-aware config merge order
+
+This page owns the config-layering view. For env-file precedence and mode/flavor selection, see [Runtime and Flavors](/backend/runtime-and-flavors). For the fuller request-context view of instance resolution and instance-aware config behavior, see [Multi-Instance and Instance Resolution](/backend/multi-instance-and-instance-resolution).
+
+In the current runtime, the effective instance-aware config can be understood at a high level like this:
+
+1. start from the app-wide baseline config
+2. merge static config from `config.instance.instances[instanceName].config`
+3. merge any persisted config stored on the instance record
+4. expose the merged result as `ctx.config`
+
+That means `ctx.config` is not just a pointer to `app.config`. It is the instance-aware effective config surface.
+
+## Instance config shape
+
+Representative instance config shape in the current repo looks like:
+
+```typescript
+config.instance = {
+  getInstanceName: undefined,
+  queryField: $protocolKey('x-vona-instance-name'),
+  headerField: $protocolKey('x-vona-instance-name'),
+  instances: {
+    '': { password: '', title: '' },
+    'isolateTest': {
+      password: '',
+      title: '',
+      id: 1000,
+      isolate: true,
+      isolateClient: 'isolateTest',
+    },
+  },
+};
+```
+
+The key point is that instance configuration is part of the config system itself, not an external plugin layer.
+
+## Config ownership layers
+
+A useful backend mental model is:
+
+- env files provide deployable runtime values
+- project config translates and organizes those values into backend config
+- module config provides reusable module-local defaults
+- `config.modules[...]` overrides module-local defaults for the current app
+- `config.instance.instances[...]` adds static per-instance behavior
+- `ctx.config` is the effective instance-aware result seen by request-scoped code
+
+This layered model is the safest way to reason about config changes in Cabloy.
+
+## Relationship to startup, model, and datasource behavior
+
+Config does not live in isolation. In many backend tasks, config interacts directly with:
+
+- runtime environment and flavor
+- startup lifecycle and startup bean overrides
+- model options
+- datasource defaults and isolated-instance routing
+
+Read this guide together with:
+
+- [Backend Essentials](/backend/backend-essentials)
+- [Backend Foundation](/backend/foundation)
+- [Runtime and Flavors](/backend/runtime-and-flavors)
+- [Backend Startup Guide](/backend/startup-guide)
+- [Model Guide](/backend/model-guide)
+- [Multi-Database and Datasource Guide](/backend/multi-database-datasource)
+
+## Implementation checks for backend configuration changes
+
+When editing backend configuration behavior, ask:
+
+1. should this value live in env files, project config, or module config?
+2. is the value consumed through current-module scope, cross-module scope, `app.config`, or `ctx.config`?
+3. does the config depend on runtime mode, flavor, or instance?
+4. is there already a module config skeleton or project config layer that should be extended instead of inventing a new pattern?
+5. will a config change alter startup, datasource, or model behavior indirectly?
+
+That helps AI keep backend configuration aligned with Vona’s module-resource model and current runtime layering.