cabloy 5.1.49 → 5.1.51

package/cabloy-docs/backend/controller-aop-guide.md

@@ -0,0 +1,270 @@
+# Controller AOP Guide
+
+## Why controller AOP matters
+
+Controller AOP is how Vona structures request-path behavior around controller actions.
+
+Instead of scattering authentication, validation, logging, error handling, or request transformation into unrelated code paths, Vona models them as explicit aspect families.
+
+## The five controller aspect families
+
+Vona provides five main controller-facing aspect families:
+
+- **middleware**
+- **guard**
+- **interceptor**
+- **pipe**
+- **filter**
+
+## Middleware
+
+Middleware is used for request-path behavior that wraps execution before and after the controller action.
+
+Representative CLI generation patterns from the legacy workflow include:
+
+```bash
+npm run vona :create:bean middlewareSystem logger -- --module=demo-student
+npm run vona :create:bean middleware logger -- --module=demo-student --boilerplate=global
+npm run vona :create:bean middleware logger -- --module=demo-student
+```
+
+These commands all go through the shared `:create:bean` entrypoint, but they target different middleware scopes and boilerplates.
+
+### Scope variants
+
+- **system middleware** runs before route matching
+- **global middleware** is auto-loaded and applied broadly
+- **local middleware** is attached directly to a controller class or action
+
+### Why system middleware is different
+
+System middleware executes before route matching, so it is the earliest controller-facing interception stage.
+
+This is where Vona places concerns such as not-found handling, request override behavior, app initialization, instance initialization, HTTP logging, CORS, and static-resource handling.
+
+### Representative local usage
+
+```typescript
+@Aspect.middleware('demo-student:logger')
+```
+
+### Representative global usage
+
+```typescript
+@Aspect.middlewareGlobal('demo-student:logger', { prefix: 'elapsed' })
+```
+
+### Representative built-in usage
+
+```typescript
+@Core.gate({
+  gate: {
+    flavor: 'normal',
+    mode: 'dev',
+  },
+})
+```
+
+The `@Core.gate(...)` shorthand still maps to `@Aspect.middlewareGlobal('a-core:gate', ...)`.
+
+## Guard
+
+Guards are used for access control and execution preconditions.
+
+Typical jobs include:
+
+- checking whether the current user is authenticated
+- checking whether a user is activated
+- checking whether a username or role name matches the required rule
+
+### Scope variants
+
+- **global guard** is auto-loaded and can be configured per API
+- **local guard** is attached directly to a controller class or action
+
+### Representative local usage
+
+```typescript
+@Aspect.guard('demo-student:admin')
+```
+
+### Representative built-in usage
+
+```typescript
+@Passport.public()
+@Passport.activated(false)
+@Passport.userName({ name: 'admin' })
+@Passport.roleName({ name: 'admin' })
+@Passport.admin()
+```
+
+These shorthands still map back to the generic aspect model.
+
+For the underlying auth, passport, and user-access model, see [Auth Guide](/backend/auth-guide) and [User Access Guide](/backend/user-access-guide).
+
+## Interceptor
+
+Interceptors provide onion-style around-execution behavior for controller actions.
+
+Typical jobs include:
+
+- timing and logging
+- wrapping response handling
+- enforcing consistent around-action behavior
+
+### Scope variants
+
+- **global interceptor** is auto-loaded and broadly configurable
+- **local interceptor** is attached directly to a controller class or action
+
+### Representative local usage
+
+```typescript
+@Aspect.interceptor('demo-student:logger')
+```
+
+### Representative built-in usage
+
+Built-in interceptors can be used for framework-level response behavior, such as body-wrapping interceptors provided by built-in modules. Vona also provides interceptor-driven verification helpers such as `@Core.captchaVerify(...)`; for the provider/scene architecture behind that flow, see [Captcha Guide](/backend/captcha-guide).
+
+## Pipe
+
+Pipes transform or validate request values before they reach controller logic.
+
+### Scope variants
+
+- **global pipe** is auto-loaded and broadly configurable
+- **local pipe** is attached directly to a controller class or action
+- **argument pipe** is the most common developer-facing style in normal application code
+
+### Representative local pipe usage
+
+```typescript
+@Aspect.pipe('demo-student:number')
+```
+
+### Argument pipe pattern
+
+Argument pipes are usually created from a local pipe:
+
+```typescript
+import { createArgumentPipe } from 'vona-module-a-aspect';
+
+export const ArgNumber = createArgumentPipe('demo-student:number');
+```
+
+Used on a controller parameter:
+
+```typescript
+async findOne(@ArgNumber() @Arg.param('id') id: any) {}
+```
+
+Order matters:
+
+- `@Arg.param(...)`
+- then custom argument pipes such as `@ArgNumber()`
+
+### Zod integration
+
+In many real cases, built-in `@Arg.*` handling with type inference or explicit Zod schema is enough:
+
+```typescript
+async findOne(@Arg.param('id') id: number) {}
+async findOne(@Arg.param('id', z.number().min(1)) id: number) {}
+```
+
+This is why custom argument pipes are now the exception rather than the default. Reach for a custom argument pipe when the transformation itself is reusable business behavior. Reach for typed `@Arg.*` plus Zod when ordinary parameter coercion and validation are enough.
+
+For broader validation guidance, see [Validation Guide](/backend/validation-guide).
+
+## Filter
+
+Filters handle exceptions and logging behavior.
+
+This is where request-path error customization becomes explicit.
+
+### Scope variants
+
+- **global filter** is auto-loaded and can be tuned per API or by app config
+- **local filter** is attached directly to a controller class or action
+
+### Representative local usage
+
+```typescript
+@Aspect.filter('demo-student:test')
+```
+
+### Built-in filter
+
+The built-in global filter `a-error:error` covers common error-handling and logging needs.
+
+Representative shorthand:
+
+```typescript
+@Core.error({ logs: { 422: false } })
+```
+
+## Shared configuration patterns
+
+Most controller aspect families support the same configuration ideas:
+
+- parameters with default values
+- parameter override at usage site
+- app-config override
+- enable/disable
+- `match` and `ignore`
+- `mode` and `flavor`
+- ordering through `dependencies` and `dependents`
+- inspection of the effective aspect list
+
+That consistency is one of the most important reasons controller AOP stays scalable in Vona.
+
+### Representative precedence model
+
+A representative precedence pattern is:
+
+- usage-site override
+- then app-config override in `config.onions`
+- then decorator default values
+
+For example, global middleware can define defaults in the bean, be overridden in app config, and then be overridden again at a specific controller action.
+
+### Representative inspect patterns
+
+Runtime inspection is especially useful when several global aspects combine on one route.
+
+Representative examples include:
+
+```typescript
+this.bean.onion.middlewareSystem.inspect();
+this.bean.onion.middleware.inspect();
+```
+
+Those inspection helpers help explain why a route is behaving a certain way before you start rewriting aspect definitions.
+
+## How to choose the right aspect family
+
+Use this rule of thumb:
+
+- **middleware** for request-path infrastructure behavior
+- **guard** for access checks and authorization preconditions
+- **interceptor** for around-execution behavior
+- **pipe** for request-value transformation or validation
+- **filter** for error handling and log customization
+
+## Relationship to controller design
+
+Controller AOP should be read together with [Controller Guide](/backend/controller-guide).
+
+The controller guide explains routing, `@Web.*`, and `@Arg.*`, while this guide explains the cross-cutting behavior that surrounds controller execution.
+
+## Questions for controller-AOP-sensitive changes
+
+When changing controller behavior, ask:
+
+1. is this concern really controller AOP rather than ordinary business logic?
+2. should it be local, global, or system-level?
+3. is there already a built-in shorthand or built-in aspect for this job?
+4. does the change also affect validation, OpenAPI, runtime flavor, or environment-specific behavior?
+
+That helps AI keep request-path logic aligned with Vona’s native execution model.

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

@@ -0,0 +1,347 @@
+# Controller Guide
+
+This guide explains how controllers work in Vona within the Cabloy monorepo.
+
+## Why controllers matter
+
+Controllers are the HTTP-facing contract surface of the backend.
+
+They define how routes, request parameters, validation, response typing, and OpenAPI metadata meet the rest of the backend thread.
+
+A useful contract-loop mental model is:
+
+- controller defines the route and request/response surface
+- service owns orchestration
+- model and entity shape persistence behavior
+- DTOs and validation shape explicit request/response contracts
+- OpenAPI emits the machine-readable contract that frontend SDK generation can consume
+
+## Create a controller
+
+Example: create a controller named `student` in module `demo-student`.
+
+### CLI command
+
+```bash
+npm run vona :create:bean controller student -- --module=demo-student
+```
+
+## Controller definition
+
+Representative pattern:
+
+```typescript
+@Controller<IControllerOptionsStudent>('student')
+export class ControllerStudent extends BeanBase {
+  @Web.post('')
+  @Api.body(v.tableIdentity())
+  async create(@Arg.body() student: DtoStudentCreate): Promise<TableIdentity> {
+    return (await this.scope.service.student.create(student)).id;
+  }
+}
+```
+
+The most important things to notice are:
+
+- the controller path is declared in `@Controller(...)`
+- the action path and request method are declared with `@Web.*`
+- request parameters are declared with `@Arg.*`
+- response metadata can be enriched for validation and OpenAPI generation
+
+## Route composition
+
+Vona uses automatic route registration for controller actions that use `@Web` decorators.
+
+The general route model is:
+
+```text
+Route Path = GlobalPrefix + Module Url + Controller Path + Action Path
+```
+
+Important pieces:
+
+- `GlobalPrefix`: from project config, commonly `/api`
+- `Module Url`: derived from the module name
+- controller path and action path: defined in the controller itself
+
+## Route simplification rules
+
+Three useful simplification rules apply here.
+
+### 1. Remove duplicate module path fragments
+
+If the controller path matches the module name, the duplicate fragment is removed from the final route.
+
+### 2. Leading `/` removes the module URL
+
+If the controller path or action path starts with `/`, the module URL is removed.
+
+### 3. Leading `//` removes both global prefix and module URL
+
+If the controller path or action path starts with `//`, both the global prefix and module URL are removed.
+
+This is useful for special routes such as the project homepage or a shared non-module-prefixed API path.
+
+## Request methods
+
+Vona groups HTTP method decorators under `@Web`, which helps reduce mental overhead.
+
+Representative methods include:
+
+- `@Web.post`
+- `@Web.get`
+- `@Web.delete`
+- `@Web.put`
+- `@Web.patch`
+- `@Web.options`
+- `@Web.head`
+
+## Request parameters
+
+Vona groups request-parameter decorators under `@Arg`.
+
+Representative parameter decorators include:
+
+- `@Arg.param`
+- `@Arg.query`
+- `@Arg.body`
+- `@Arg.headers`
+- `@Arg.fields`
+- `@Arg.field`
+- `@Arg.files`
+- `@Arg.file`
+- `@Arg.user`
+
+These decorators are also the main request-parameter surface for multipart upload flows; see [Upload Guide](/backend/upload-guide).
+
+## Parameter extraction patterns
+
+A useful distinction is:
+
+- specify a field name when you want one parameter only
+- omit the field name when you want the whole structured object
+
+Representative patterns:
+
+```typescript
+findOne(@Arg.query('id') id: number) {}
+```
+
+```typescript
+class DtoStudentInfo {
+  id: number;
+  name: string;
+}
+
+findOne(@Arg.query() query: DtoStudentInfo) {
+  console.log(query.id, query.name);
+}
+```
+
+This matters because controller signatures can express both simple and structured request shapes without leaving the framework’s contract surface.
+
+## Compact action-signature patterns
+
+A practical controller signature often combines route params, request body typing, and response metadata in one place.
+
+Representative pattern:
+
+```typescript
+@Web.patch('updateUser/:id')
+updateUser(
+  @Arg.param('id') id: TableIdentity,
+  @Arg.body(v.object(DtoUserUpdate)) user: DtoUserUpdate,
+) {
+  return this.scope.model.user.update(user, { where: { id } });
+}
+```
+
+When the response contract should follow inferred DTO shape directly, a pattern like this is also common:
+
+```typescript
+@Web.get('getUserDynamic')
+@Api.body($Dto.get('test-vona:post'))
+getPostDynamic() {}
+```
+
+A practical rule is:
+
+- use `@Arg.param(...)` and `@Arg.body(...)` together when the action mixes route identity and structured payload input
+- use return-type inference when the response contract is obvious
+- use `@Api.body(...)` when the response should expose a more specific inferred or customized contract shape
+
+## Validation, OpenAPI, and Controller AOP
+
+Controllers are strongly connected to three related capabilities:
+
+- parameter validation based on Zod-oriented patterns
+- Swagger/OpenAPI generation
+- middleware, guards, interceptors, pipes, and filters around the request path
+
+In practice, that means controllers are not only request handlers. They are also a key place where request and response shape become machine-readable for tooling and frontend integration, and where request-path policies are composed through controller AOP.
+
+For a dedicated explanation of middleware, guards, interceptors, pipes, and filters, see [Controller AOP Guide](/backend/controller-aop-guide).
+
+## Response body typing and schema declaration
+
+Vona can often infer response schema from the declared return type.
+
+Representative automatically inferred cases include:
+
+- basic types such as `string`, `number`, and `boolean`
+- DTO classes
+- Entity classes
+
+When inference is not enough, use explicit schema declaration.
+
+Representative pattern:
+
+```typescript
+@Api.body(v.array(String))
+findOne(): string[] {
+  return ['Tom'];
+}
+```
+
+A practical rule is:
+
+- use return-type inference when the contract is obvious and simple
+- use explicit `@Api.body(...)` when the response shape needs more control or the inference boundary becomes unclear
+
+## Response wrapper behavior
+
+By default, Vona wraps the response body in a standard wrapper object.
+
+That means a plain response value conceptually becomes a response shape like:
+
+```typescript
+{
+  code: string;
+  message: string;
+  data: string;
+}
+```
+
+### Disable the wrapper
+
+Use `@Api.bodyCustom(false)` when the endpoint should return the body directly.
+
+Representative pattern:
+
+```typescript
+@Api.bodyCustom(false)
+findOne(): string {
+  return 'Tom';
+}
+```
+
+### Provide a custom wrapper
+
+Use `@Api.bodyCustom(...)` with a wrapper function when the project needs a different response envelope.
+
+Representative pattern:
+
+```typescript
+@Api.bodyCustom(bodySchemaWrapperCustom)
+findOne(): string {
+  return 'Tom';
+}
+```
+
+This is one of the most important response-contract choices because it affects backend OpenAPI output and frontend SDK consumption.
+
+Other response/action metadata patterns can also be expressed at the controller surface, including representative cases such as:
+
+- `contentType`
+- `httpCode`
+- `headers`
+- `setHeaders`
+- `exclude`
+- `tags`
+
+Use those when the runtime behavior and the machine-readable contract should stay aligned in one place.
+
+## Action options
+
+Vona actions can carry additional metadata directly in `@Web.*` options.
+
+Representative pattern:
+
+```typescript
+@Web.get(':id', {
+  tags: ['Student'],
+  description: 'Find a student',
+})
+findOne(@Arg.param('id') id: number): EntityStudent {}
+```
+
+Representative action-option areas include:
+
+- `description`
+- `summary`
+- `httpCode`
+- `contentType`
+- `bodySchema`
+- `bodySchemaWrapper`
+- `exclude`
+- `tags`
+- `operationId`
+- `headers`
+- `setHeaders`
+
+This matters because controller actions are one of the main places where runtime behavior and machine-readable API description meet.
+
+## Controller options
+
+Controllers can also carry higher-level options.
+
+Representative pattern:
+
+```typescript
+@Controller('student', {
+  exclude: false,
+  tags: ['Student'],
+})
+class ControllerStudent {}
+```
+
+Representative controller-option areas include:
+
+- `exclude`
+- `tags`
+- `actions`
+- `enable`
+- `meta`
+
+This is especially important because the controller surface can also be tuned from app config through onion/config override patterns.
+
+## Relationship to the backend contract loop
+
+Read this guide together with:
+
+- [Validation Guide](/backend/validation-guide)
+- [DTO Guide](/backend/dto-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [CRUD Workflow](/backend/crud-workflow)
+- [Unit Testing](/backend/unit-testing)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+
+A practical split is:
+
+- controllers define the route and contract surface
+- validation and DTOs define the request/response schema language
+- OpenAPI emits the machine-readable contract
+- CRUD generation instantiates the thread quickly
+- tests verify the contract through action execution
+
+## Practical implications for controller implementation
+
+When creating or editing a controller, preserve the Vona controller model instead of rewriting it into a generic framework style.
+
+The safest workflow is:
+
+1. use the Vona CLI to create the controller skeleton
+2. inspect the generated module-specific patterns
+3. add `@Web`, `@Arg`, validation, and OpenAPI metadata in the same style
+4. choose deliberately whether response wrapper defaults should stay in place
+5. verify the resulting routes and response conventions