@onroad/core 4.0.0-alpha.3 → 4.0.0-alpha.30

package/README.md

@@ -25,6 +25,8 @@
 - [Storage](#storage)
 - [Health Endpoint](#health-endpoint)
 - [Graceful Shutdown](#graceful-shutdown)
+- [Local Development (DevServer)](#local-development-devserver)
+- [Migration CLI](#migration-cli)
 - [Testing](#testing)
 - [Subpath Exports](#subpath-exports)
 - [Known Pitfalls](#known-pitfalls)
@@ -95,72 +97,88 @@ await app.buildServer({ port: 3001 })
 
 ## Architecture Overview
 
-```
-┌──────────────────────────────────────────────────┐
-│                  OnRoadExpress                   │
-│  ┌────────────┐  ┌────────────┐  ┌────────────┐ │
-│  │  Container  │  │ FilterChain│  │  EventBus  │ │
-│  │  (DI + IoC) │  │ (Middleware)│  │ (Sentinel) │ │
-│  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘ │
-│        │               │               │        │
-│  ┌─────▼───────────────▼───────────────▼──────┐ │
-│  │         Request Handler (route)             │ │
-│  │  requestContext.run({ tenant, appToken })   │ │
-│  │  ┌──────────┐ ┌─────────┐ ┌────────────┐   │ │
-│  │  │Controller│→│ Service │→│ Repository │   │ │
-│  │  └──────────┘ └─────────┘ └────────────┘   │ │
-│  └─────────────────────────────────────────────┘ │
-│                                                  │
-│  ┌──────────────────────────────────────────┐   │
-│  │              Providers                    │   │
-│  │  Messaging │ Realtime │ TaskSched │ Socket│   │
-│  └──────────────────────────────────────────┘   │
-│                                                  │
-│  ┌──────────────────────────────────────────┐   │
-│  │           TransportFactory                │   │
-│  │     HttpTransport │ MessagingTransport    │   │
-│  └──────────────────────────────────────────┘   │
-└──────────────────────────────────────────────────┘
+TypeRoad follows a multi-tenant architecture designed for high isolation and developer productivity. The framework orchestrates the request lifecycle using three main internal layers: `RequestContext`, `OnRoadContainer` (DI), and the `Model/Repository` layer.
+
+### The "Matryoshka" Isolation Pattern
+
+Isolation in runtime is achieved through a nested hierarchy that ensures one tenant's request never sees another's data or instances.
+
+1.  **Nível 1: RequestContext (AsyncLocalStorage)**
+    - O `OnRoadExpress` envolve cada execução de rota em um bloco `requestContext.run()`.
+    - Atua como um "envelope" de memória global para a thread lógica atual, armazenando metadados como `tenantId`, `logger` e `appToken`.
+    - Permite que qualquer parte do sistema acesse o estado da requisição via `getRequestContext()` sem precisar de injeção manual.
+
+2.  **Nível 2: OnRoadContainer (RequestScope)**
+    - Dentro do contexto da requisição, o Container cria um objeto `RequestScope`.
+    - Este escopo é um mapa de instâncias isolado por um `UUID` único para aquela chamada HTTP.
+    - Se múltiplos serviços injetarem o mesmo `Repository`, o Container garante que eles recebam a **mesma instância** dentro daquela requisição (reuso de estado), mas instâncias **completamente diferentes** de outras requisições concorrentes.
+
+3.  **Nível 3: Repository & Connection Isolation**
+    - Repositórios são instanciados pelo Container e recebem automaticamente o `tenantId` do escopo atual.
+    - Ao executar uma query (ex: `find()`), o repositório usa seu atributo interno `this.tenant` para solicitar ao `ConnectionManager` o pool de conexões específico daquele banco de dados.
+    - Isso garante que o isolamento chegue até o nível físico do banco de dados (schema ou DB separado).
+
+```mermaid
+graph TD
+    subgraph "Nível 1: RequestContext (AsyncLocalStorage)"
+        direction TB
+        Metadata["{ tenant: 'cliente_a', logger, token }"]
+        
+        subgraph "Nível 2: OnRoadContainer (RequestScope)"
+            direction TB
+            ScopeID["Scope: UUID-123 (Tenant: 'cliente_a')"]
+            Instances["Map { Controller, Service, Repository }"]
+            
+            subgraph "Nível 3: Instância do Repository"
+                direction TB
+                Atributo["this.tenant = 'cliente_a'"]
+                Metodo["getConnection() -> Pede ao ConnectionManager o banco 'onroad_cliente_a'"]
+            end
+        end
+    end
 ```
 
 ---
 
 ## DI Container & Decorators
 
-TypeRoad uses a decorator-based DI container with automatic class scanning.
+TypeRoad uses a decorator-based DI container with automatic class scanning. It manages the lifecycle of your components through defined scopes.
 
 ### Decorators
 
-| Decorator | Scope | Purpose |
-|-----------|-------|---------|
-| `@Injectable()` | Transient (default) | Generic injectable class |
-| `@Controller("/path")` | Request | Express route handler |
-| `@Service()` | Request | Business logic layer |
-| `@Repository()` | Request | Data access layer |
+| Decorator | Scope | Relationship | Purpose |
+|-----------|-------|:---:|---------|
+| `@Controller("/path")` | `REQUEST` | entry-point | Injetado com Services; lida com req/res Express. |
+| `@Service()` | `REQUEST` | logic | Camada de orquestração e regras de negócio. |
+| `@Repository()` | `REQUEST` | data | Camada de acesso ao banco (Sequelize/Mongoose). |
+| `@Injectable()` | `TRANSIENT` | utility | Classes utilitárias instanciadas a cada uso. |
 
 ### Scopes
 
-| Scope | Behavior |
-|-------|----------|
-| `SINGLETON` | One instance for the entire application |
-| `REQUEST` | One instance per request scope |
-| `TRANSIENT` | New instance on every resolve |
+-   **`SINGLETON`**: Uma única instância para toda a aplicação (ex: `EventBus`, `ConnectionManager`).
+-   **`REQUEST`**: Uma instância por requisição HTTP. É o escopo padrão para Controllers e Services, garantindo que o estado do tenant esteja isolado.
+-   **`TRANSIENT`**: Uma nova instância é criada toda vez que a classe é injetada ou resolvida.
 
-### Usage
+### Controller, Service and Repository linkage
+
+The container manages a strict hierarchy: `Controller` -> `Service` -> `Repository`.
+
+-   **Automatic Wiring**: When you register a module via `app.register([MyController, MyService, MyRepository])`, the container scans the metadata and prepares the injection tree.
+-   **Stateful Injection**: A Repository inheriting from `SequelizeRepository` is automatically configured by the container with the current `tenant` and `connectionManager` during its instantiation in the `RequestScope`.
 
 ```ts
-import { Injectable, Scope } from "@onroad/core"
+import { Service, AbstractService } from "@onroad/core"
 
-@Injectable({ scope: Scope.SINGLETON })
-class CacheManager {
-  private store = new Map<string, unknown>()
-  get(key: string) { return this.store.get(key) }
-  set(key: string, value: unknown) { this.store.set(key, value) }
+@Service()
+class OrdemService extends AbstractService<OrdemRepository> {
+  constructor() {
+    // Shared state: the container ensures OrdemRepository
+    // is instantiated within the same RequestScope as this service.
+    super({ repository: OrdemRepository })
+  }
 }
 ```
 
-Register all classes via `app.register([...])` — the container auto-scans metadata.
-
 ---
 
 ## Controllers, Services & Repositories
@@ -601,7 +619,7 @@ await app.shutdown()
 
 ## Testing
 
-TypeRoad uses [Vitest](https://vitest.dev/) with **223 tests** across 9 test files:
+TypeRoad uses [Vitest](https://vitest.dev/) with **242 tests** across 10 test files:
 
 ```bash
 npm test              # Run all tests
@@ -611,7 +629,7 @@ npm run test:coverage # Coverage report
 
 | Test File | Tests | Covers |
 |-----------|-------|--------|
-| `container.test.ts` | 16 | DI Container, decorators, scopes |
+| `container.test.ts` | 19 | DI Container, decorators, scopes |
 | `entity.test.ts` | 14 | Entity, Column, associations |
 | `database.test.ts` | 13 | ConnectionManagers |
 | `filters.test.ts` | 33 | FilterChain, all 5 built-in filters |
@@ -620,6 +638,7 @@ npm run test:coverage # Coverage report
 | `logging.test.ts` | 20 | PinoLogger, OnRoadLogger |
 | `providers.test.ts` | 41 | All 4 providers, graceful-fail, shutdown |
 | `transport.test.ts` | 25 | HttpTransport, MessagingTransport, TransportFactory, RequestContext |
+| `dev.test.ts` | 16 | DevServer, MigrationCLI |
 
 ---
 
@@ -632,21 +651,184 @@ src/
 ├── container/                # DI Container + decorators
 ├── context/                  # RequestContext (AsyncLocalStorage)
 ├── core/                     # AbstractController/Service/Repository, Sentinel, EventBus
+├── database/                 # ConnectionManager abstract + Sequelize/Mongo implementations
+│   └── migrations/           # MigrationRunner (Umzug)
+├── dev/                      # DevServer, MigrationCLI — local dev tools
 ├── entity/                   # @Entity, @Column, @Field, associations
 ├── filters/                  # FilterChain, @Filter, built-in filters (Cors, JWT, Tenant, Role, RequestContext)
-├── security/                 # @Roles, @Public
-├── database/                 # ConnectionManager abstract + Sequelize/Mongo implementations
-├── transport/                # InterServiceTransport, HttpTransport, MessagingTransport, TransportFactory
-├── messaging/                # MatchingObject
-├── providers/                # MessagingProvider, RealtimeProvider, TaskSchedulerProvider, SocketProvider
 ├── logging/                  # OnRoadLogger interface + PinoLogger
+├── messaging/                # MatchingObject
 ├── plugins/                  # OnRoadPlugin interface
+├── providers/                # MessagingProvider, RealtimeProvider, TaskSchedulerProvider, SocketProvider
+├── security/                 # @Roles, @Public
 ├── storage/                  # StorageProvider abstract
+├── transport/                # InterServiceTransport, HttpTransport, MessagingTransport, TransportFactory
 └── types/                    # Express Request augmentation
 ```
 
 ---
 
+## Local Development (DevServer)
+
+TypeRoad includes a `DevServer` that makes local development self-sufficient — it starts database containers, runs migrations, and logs all environment variables your frontend needs.
+
+### Quick Start
+
+```ts
+import "reflect-metadata"
+import { OnRoadExpress } from "@onroad/core"
+import { SequelizeConnectionManager } from "@onroad/core/database"
+import { DevServer } from "@onroad/core/dev"
+
+const app = new OnRoadExpress({
+  connections: [
+    new SequelizeConnectionManager({
+      dialect: "postgres",
+      host: "localhost",
+      port: 5432,
+      user: "typeroad",
+      password: "typeroad_dev",
+      database: "typeroad_dev",
+      migrations: {
+        path: "./src/migrations",
+        runOnConnect: true,
+      },
+    }),
+  ],
+})
+
+// Register your controllers, services, repositories...
+app.register([/* ... */])
+
+const devServer = new DevServer({
+  app,
+  databases: [{ engine: "postgres", port: 5432 }],
+  migrationsPath: "./src/migrations",
+  tenants: ["default"],
+  frontendVars: {
+    REACT_APP_TENANT: "default",
+    REACT_APP_WS_URL: "ws://localhost:3000",
+  },
+})
+
+await devServer.start({ port: 3000 })
+// Press Ctrl+C to stop
+```
+
+### What DevServer Does
+
+1. **Generates `docker-compose.dev.yml`** — PostgreSQL (or MySQL) container with healthcheck, volumes, and sensible defaults
+2. **Starts the container** — `docker compose up -d` automatically
+3. **Waits for readiness** — polls `pg_isready` / `mysqladmin ping` until the DB accepts connections
+4. **Runs migrations** — applies all pending Umzug migrations from your configured path
+5. **Starts the API server** — calls `app.buildServer()` as usual
+6. **Logs frontend env vars** — prints a copy-pasteable block and writes `.env.dev`:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│              FRONTEND ENVIRONMENT VARIABLES                  │
+├──────────────────────────────────────────────────────────────┤
+│  REACT_APP_API_URL=http://localhost:3000
+│  NEXT_PUBLIC_API_URL=http://localhost:3000
+│  VITE_API_URL=http://localhost:3000
+│  DATABASE_URL=postgresql://typeroad:typeroad_dev@localhost:5432/typeroad_dev
+│  REACT_APP_TENANT=default
+└──────────────────────────────────────────────────────────────┘
+```
+
+### DevServer Config
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `app` | `OnRoadExpress` | required | The app instance |
+| `databases` | `DevDatabaseConfig[]` | `[{ engine: "postgres" }]` | Database containers to start |
+| `frontendVars` | `Record<string, string>` | `{}` | Extra vars to log for frontend |
+| `migrationsPath` | `string` | — | Path to migration files |
+| `autoMigrate` | `boolean` | `true` | Run migrations on start |
+| `tenants` | `string[]` | `["default"]` | Tenants to run migrations for |
+| `composeFile` | `string` | `"docker-compose.dev.yml"` | Docker compose filename |
+
+### Database Defaults
+
+| Engine | Image | Port | User | Password | Database |
+|--------|-------|------|------|----------|----------|
+| `postgres` | `postgres:16-alpine` | `5432` | `typeroad` | `typeroad_dev` | `typeroad_dev` |
+| `mysql` | `mysql:8.0` | `3306` | `typeroad` | `typeroad_dev` | `typeroad_dev` |
+
+---
+
+## Migration CLI
+
+The `MigrationCLI` class provides a programmatic API for managing database migrations.
+
+### Usage
+
+```ts
+import { MigrationCLI } from "@onroad/core/dev"
+import { SequelizeConnectionManager } from "@onroad/core/database"
+
+const connection = new SequelizeConnectionManager({
+  dialect: "postgres",
+  host: "localhost",
+  user: "typeroad",
+  password: "typeroad_dev",
+  database: "typeroad_dev",
+  migrations: { path: "./src/migrations" },
+})
+
+const cli = new MigrationCLI({
+  migrationsPath: "./src/migrations",
+  connection,
+  tenant: "default",
+})
+
+// Run from CLI args
+await cli.run()  // reads process.argv
+
+// Or call directly
+cli.create("add-users-table")  // creates timestamped migration file
+await cli.up()                  // apply all pending
+await cli.up(1)                 // apply 1 step
+await cli.down()                // revert last migration
+await cli.status()              // show status table
+```
+
+### CLI Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `create <name>` | Create a new migration file | `cli.run(["create", "add-orders"])` |
+| `up [steps]` | Apply pending migrations | `cli.run(["up"])` or `cli.run(["up", "3"])` |
+| `down [steps]` | Revert migrations (default: 1) | `cli.run(["down", "2"])` |
+| `status` | Show applied/pending status | `cli.run(["status"])` |
+
+### Migration File Format
+
+Generated `.ts` files follow the Umzug/Sequelize pattern:
+
+```ts
+import type { QueryInterface, Sequelize } from "sequelize"
+
+export default {
+  async up(queryInterface: QueryInterface, sequelize: Sequelize): Promise<void> {
+    await queryInterface.createTable("ordens", {
+      id: { type: sequelize.constructor["DataTypes"].UUID, primaryKey: true },
+      descricao: { type: sequelize.constructor["DataTypes"].STRING, allowNull: false },
+      createdAt: sequelize.constructor["DataTypes"].DATE,
+      updatedAt: sequelize.constructor["DataTypes"].DATE,
+    })
+  },
+
+  async down(queryInterface: QueryInterface): Promise<void> {
+    await queryInterface.dropTable("ordens")
+  },
+}
+```
+
+Migration state is tracked in the `__typeroad_migrations` table (configurable via `tableName` in `MigrationConfig`).
+
+---
+
 ## Subpath Exports
 
 Import only what you need:
@@ -662,6 +844,7 @@ import { HttpTransport, TransportFactory } from "@onroad/core/transport" // Tran
 import { MatchingObject } from "@onroad/core/messaging"                // Messaging
 import { PinoLogger } from "@onroad/core/logging"                      // Logging
 import { StorageProvider } from "@onroad/core/storage"                 // Storage
+import { DevServer, MigrationCLI } from "@onroad/core/dev"            // Dev Tools
 ```
 
 ---
@@ -763,6 +946,373 @@ export class UserRepository extends BaseRepository<User> {
 
 ---
 
+### `import type` with relationship decorators
+
+TypeScript's `import type` is erased at compile time. If you use `import type { Foo }` and then reference `Foo` as a **runtime value** inside a decorator like `@HasMany(() => Foo, ...)`, the compiled JavaScript will throw `ReferenceError: Foo is not defined` because the import was stripped.
+
+```ts
+// ❌ Wrong — import type is erased, decorator callback fails at runtime
+import type { CampoDeVerificacao } from "./CampoDeVerificacao.js"
+
+@Entity("caderno", { engine: "sequelize" })
+export class CadernoDeVerificacao {
+  @HasMany(() => CampoDeVerificacao, "cadernoId") // 💥 ReferenceError
+  campos!: CampoDeVerificacao[]
+}
+```
+
+Fix: use a regular `import` for any class referenced inside a decorator callback:
+
+```ts
+// ✅ Correct — regular import keeps the binding at runtime
+import { CampoDeVerificacao } from "./CampoDeVerificacao.js"
+
+@Entity("caderno", { engine: "sequelize" })
+export class CadernoDeVerificacao {
+  @HasMany(() => CampoDeVerificacao, "cadernoId")
+  campos!: CampoDeVerificacao[]
+}
+```
+
+> **Tip:** `import type` is safe for type annotations and generics (`extends AbstractService<Foo>`), but never for decorator arguments, `instanceof`, or any expression evaluated at runtime.
+
+---
+
+### `emitDecoratorMetadata` causes TDZ errors with circular entity imports
+
+When `emitDecoratorMetadata: true` is set in `tsconfig.json`, TypeScript emits `__metadata("design:type", CampoDeVerificacao)` for decorated properties. This accesses the imported class **at class definition time**. If two entities import each other (circular dependency), ESM module evaluation order causes a **Temporal Dead Zone (TDZ)** error:
+
+```
+ReferenceError: Cannot access 'CampoDeVerificacao' before initialization
+```
+
+The `@HasMany(() => Foo, ...)` arrow function is lazy (only called later by `wireSequelizeAssociations`), but `__metadata("design:type", Foo)` is **eager** — it runs during class definition.
+
+```jsonc
+// ❌ Wrong — causes TDZ crash in circular ESM imports
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true  // 💥
+  }
+}
+```
+
+Fix: disable `emitDecoratorMetadata`. @onroad/core uses only custom metadata keys (`METADATA_KEY.ENTITY`, `ENTITY_COLUMNS`, etc.) and does **not** rely on `design:type`, `design:paramtypes`, or `design:returntype`.
+
+```jsonc
+// ✅ Correct — no TDZ, decorators still work
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": false
+  }
+}
+```
+
+---
+
+### Custom route service methods must extract params from `req` — not expect primitive arguments
+
+**`AbstractController` always calls custom service methods with the raw `(req, res)` objects.** It only extracts params for the five default CRUD methods (`create`, `read`, `readAll`, `update`, `delete`). Every method registered under `routes:` in the controller config receives `(req, res)` forwarded directly.
+
+If your service method signature expects primitive parameters (`id: number`, `dataInicio: string`, etc.), it will receive the `req` object instead — causing silent failures (empty queries, NaN ids, wrong SQL filters) because the framework does **not** throw, it just passes the wrong value.
+
+```ts
+// ❌ Wrong — service expects primitives; controller passes (req, res)
+// Controller calls: this.service.findByBetweenDates(req, res)
+async findByBetweenDates(dataInicio: string, dataFim: string) {
+  // dataInicio === req object → Sequelize WHERE clause receives an object → returns []
+  return this.repository.findAll({ where: { dataDeAbertura: { [Op.gte]: dataInicio } } })
+}
+```
+
+```ts
+// ✅ Correct — service extracts its own params from req
+async findByBetweenDates(req: any, res?: any) {
+  const dataInicio: string = req.params.dataInicio
+  const dataFim:    string = req.params.dataFim
+  return this.repository.findAll({ where: { dataDeAbertura: { [Op.gte]: dataInicio, [Op.lte]: dataFim } } })
+}
+```
+
+**Affected params by HTTP position:**
+
+| Source           | How to extract              |
+|------------------|-----------------------------|
+| Route param (`:id`) | `req.params.id`          |
+| Query string     | `req.query.field`           |
+| Request body     | `req.body.field`            |
+| Auth / identity  | `req.decoded.userId`        |
+
+> **Rule of thumb:** In a TypeRoad service, if the method is registered as a custom route, **the first argument is always `req`**. Never write `async myMethod(id: number)` for a method that is called through a route config key — always write `async myMethod(req: any, res?: any)` and extract from `req` internally.
+
+**Scope of impact in `teraprox-api-manutencao` (audit — 2025-04-05):**
+
+The following service methods were found with the wrong signature (primitive params instead of `req`). All calls through their controller routes were silently broken:
+
+| Service | Method | Broken params |
+|---------|--------|---------------|
+| `OrdemDeServicoService` | `findByBetweenDates` | `dataInicio`, `dataFim` — **fixed** |
+| `OrdemDeServicoService` | `findByRecursoBetweenDates` | `recursoId`, `dataInicio`, `dataFim` |
+| `OrdemDeServicoService` | `findByBranchIdBetweenDates` | `branchId`, `dataInicio`, `dataFim` |
+| `OrdemDeServicoService` | `findByRecursoId` | `recursoId` |
+| `OrdemDeServicoService` | `findMonitoramentoByCriticidade` | `criticidade` |
+| `OrdemDeServicoService` | `findByModoDeFalhaId` | `modoDeFalhaId` |
+| `OrdemDeServicoService` | `encerraOS` | `id`, `form` |
+| `OrdemDeServicoService` | `setStatusOs` | `id`, `form` |
+| `OrdemDeServicoService` | `setStatusOsBulk` | `osIds`, `status`, `extraData` |
+| `OrdemDeServicoService` | `iniciarOsBulk` | `osIds`, `status` |
+| `OrdemDeServicoService` | `addTarefaToOrdem` | `osId`, `tarefa` |
+| `OrdemDeServicoService` | `updateDescricaoOs` | `osId`, `descricao` |
+| `OrdemDeServicoService` | `shiftRecursoOs` | `osId`, `recId` |
+| `OrdemDeServicoService` | `findInspecoesBetweenDates` | `recursoId`, `dataInicio`, `dataFim` |
+| `OrdemDeServicoService` | `putAnexos` | `id`, `anexos` |
+| `OrdemDeServicoService` | `findOrdensInBatch` | `ids` |
+| `OrdemDeServicoService` | `loadOsForOcpMigration` | `osIds` |
+| `RecursoService` | `findRecursoFatherByRecursoId` | `recursoId` |
+| `RecursoService` | `findByTagDescription` | `tag` |
+| `RecursoService` | `findRecursoByTagId` | `tagId` |
+| `RecursoService` | `findParadasByRecursoId` | `recursoId` |
+| `RecursoService` | `findSemParadasByRecursoId` | `recursoId` |
+| `TarefaService` | `encerrarTarefa` | `id` |
+| `TarefaService` | `addUnidadeMaterialTarefa` | `tarefaId`, `form` |
+| `TarefaService` | `addObservacaoTarefa` | `tarefaId`, `form` |
+| `TarefaService` | `deleteObservacaoTarefa` | `justificativaId` |
+| `TarefaService` | `loadMultipleIds` | `tarefaIds` |
+| `TarefaService` | `removeAnexo` | `id`, `anexoKey` |
+| `SolicitacaoDeServicoService` | `shiftRecursoSs` | `ssId`, `recId` |
+| `SolicitacaoDeServicoService` | `aprovaSolicitacao` | `id`, `form` |
+| `SolicitacaoDeServicoService` | `reprovaSolicitacao` | `id`, `form` |
+| `SolicitacaoDeServicoService` | `updateDescricaoSs` | `ssId`, `descricao` |
+| `SolicitacaoDeServicoService` | `findByRecursoId` | `recursoId` |
+| `SolicitacaoDeServicoService` | `findBetweenDates` | `start`, `end` |
+| `SolicitacaoDeServicoService` | `putAnexos` | `id`, `anexos` |
+
+---
+
+### Custom route key name must exactly match the service method name
+
+When you register a custom route in the controller config, the key name is used **verbatim** as the service method name to call. If the service was later renamed (e.g. during a refactor), the controller silently returns `null` because the `typeof service[methodName] === 'function'` guard evaluates to `false`.
+
+```ts
+// ❌ Wrong — controller key "addModoDeFalhaOS" but service method is "addModoDeFalha"
+routes: { addModoDeFalhaOS: { method: "post", path: "/..." } }
+// → service.addModoDeFalhaOS is undefined → always returns null (no error thrown)
+```
+
+**Known mismatches in `teraprox-api-manutencao` (audit — 2025-04-05):**
+
+| Controller route key | Expected service method (by key) | Actual service method |
+|----------------------|-----------------------------------|-----------------------|
+| `addModoDeFalhaOS` | `addModoDeFalhaOS` | `addModoDeFalha` |
+| `updateTipoDeOrdem` | `updateTipoDeOrdem` | `setTipoOrdem` |
+| `updateTipoDeOrdemBulk` | `updateTipoDeOrdemBulk` | `setTipoOrdemBulk` |
+| `removeAnexo` | `removeAnexo` | `removeAnexoOs` |
+| `readConcluidasCount` | `readConcluidasCount` | `countTarefasConcluidas` |
+| `findPlanned` | `findPlanned` | `findPlannedOrdensBetweenDatesV2` |
+| `findPlannedV3` | `findPlannedV3` | `findPlannedOrdensBetweenDatesV3` |
+| `findPlannedAgregador` | `findPlannedAgregador` | `findPlannedOrdensWithAgregadores` |
+| `findRecorrenciaPlanned` | `findRecorrenciaPlanned` | `findPlannedOrdensFromRecorrenciaBetweenDates` |
+| `findAgregadorPlanned` | `findAgregadorPlanned` | `findPlannedOrdensFromAgregadorBetweenDates` |
+| `createInBulk` | `createInBulk` | `createInBulkOs` |
+| `findDashByOs` | `findDashByOs` | `findWithDashboardAssociation` |
+
+> Fix: either rename the service method to match the route key, or rename the route key to match the service method. Both sides must be in sync.
+
+---
+
+### `BelongsToMany` association returns `null` (not `[]`) when no records exist
+
+Sequelize's `BelongsToMany` association populates the association property with `null` (not an empty array) when no join-table records exist for a given entity. Any code that iterates over that property with `for...of` or `.forEach()` without a guard will throw `TypeError: x is not iterable`.
+
+```ts
+// ❌ Wrong — crashes with "TypeError: o.tarefas is not iterable" when OS has no tarefas
+for (const tarefa of o.tarefas) { ... }
+o.tarefas.forEach(...)
+o.tarefas.flatMap(...)
+```
+
+```ts
+// ✅ Correct — guard with nullish coalescing
+for (const tarefa of (o.tarefas ?? [])) { ... }
+;(o.tarefas ?? []).forEach(...)
+ordens.flatMap((o) => (o.tarefas ?? []).map(...))
+```
+
+> This was the direct cause of `TypeError: o.tarefas is not iterable` at `OrdemDeServicoService.buildTarefa` (line 235) and `findByBetweenDates`. Apply the same `?? []` guard to **all** `BelongsToMany` associations before iterating.
+
+---
+
+## Migration Guide — Lessons Learned (v3 → v4)
+
+This section documents the key issues found while migrating `teraprox-api-user` from onRoad v3 to TypeRoad v4. Use this as a checklist when migrating other APIs (`api-manutencao`, `api-processo`, etc.).
+
+### 1. Entity Associations — Use Decorators, Not `buildAssociations()`
+
+v3 used `buildAssociations()` inside repositories. v4 uses decorators on entity classes. **Every association must be declared on the entity itself.**
+
+```ts
+// ❌ v3 — Repository-based associations (REMOVE)
+class UserRepository extends BaseRepository {
+  buildAssociations() {
+    this.hasMany(UserRole, "userRole")
+    this.belongsTo(Company, "company")
+  }
+}
+
+// ✅ v4 — Entity decorator associations
+@Entity("user", { engine: "sequelize", timestamps: true })
+class User {
+  @HasMany(() => UserRole, "userId")
+  userRole!: UserRole[]
+
+  @BelongsToMany(() => Company, () => UserCompany, "userId", "companyId")
+  companies!: Company[]
+}
+```
+
+**Checklist per entity:**
+- Join table entities (e.g. `UserRole`, `UserSetor`, `UserCompany`) **must** declare their FK columns with `@Column` AND the `@BelongsTo` back-reference.
+
+```ts
+@Entity("userRole", { engine: "sequelize", timestamps: true })
+class UserRole {
+  @Column({ type: DataType.STRING })
+  userId!: string
+
+  @Column({ type: DataType.STRING })
+  roleId!: string
+
+  @BelongsTo(() => Role, "roleId")
+  role!: Role
+}
+```
+
+### 2. Includes — Use String-Based Associations, Not Model References
+
+v3 used `this.repository.fullAssociation` (injected array of `{ model: SequelizeModel }`).  
+v4 uses **string-based `association` names** that match the decorator property name.
+
+```ts
+// ❌ v3 — model-based includes (CRASH: model is a raw class, not Sequelize model)
+const user = await this.repository.findOne({
+  where: { email },
+  include: this.repository.fullAssociation
+})
+
+// ✅ v4 — string-based association includes
+const USER_FULL_INCLUDE = [
+  { association: "filters" },
+  { association: "tickets" },
+  { association: "userRole" },
+  { association: "userSetor" }
+]
+const user = await this.repository.findOne({
+  where: { email },
+  include: USER_FULL_INCLUDE
+})
+```
+
+**Nested includes follow the same pattern:**
+```ts
+include: [
+  {
+    association: "userRole",
+    include: [{ association: "role", where: { companyId }, required: false }]
+  },
+  {
+    association: "userSetor",
+    include: [{ association: "setor", where: { companyId }, required: false }]
+  }
+]
+```
+
+### 3. Raw Queries — Use `getSequelizeConnection()`
+
+v3 accessed `(this.repository as any).connection.query(...)`.  
+v4 exposes this through `BaseRepository.getSequelizeConnection()`.
+
+```ts
+// ❌ v3
+const [results] = await (this.repository as any).connection.query(sql)
+
+// ✅ v4 — add this method to your BaseRepository
+getSequelizeConnection() { return this.getConnection() }
+
+// Usage in service:
+const [results] = await this.repository.getSequelizeConnection().query(sql)
+```
+
+### 4. Remove `fullAssociation` from BaseRepository
+
+v3 APIs declare `fullAssociation` on `BaseRepository`. **Remove it entirely** — v4 does not use it. Includes are now inline at the query site.
+
+```ts
+// ❌ v3
+export abstract class BaseRepository<T> extends SequelizeRepository<T> {
+  declare readonly fullAssociation: any[]
+}
+
+// ✅ v4
+export abstract class BaseRepository<T> extends SequelizeRepository<T> {
+  // No fullAssociation — define includes where you query
+}
+```
+
+### 5. Controller Return Values Are Auto-Serialized
+
+v4's `OnRoadExpress` automatically calls `res.json(result)` when a controller method returns a value and `res.headersSent` is false. **Do not manually call `res.json()` in controllers if you return a value** — it will cause "headers already sent" errors.
+
+```ts
+// ✅ Just return the value — framework serializes it
+async login(form: any, req: Request, res: Response) {
+  const userData = await this.service.login(form, req, res)
+  return userData // Framework calls res.json(userData)
+}
+```
+
+### 6. `BelongsToMany` Includes — Beware of Query Hangs
+
+Using `BelongsToMany` associations (like `User ↔ Company` through `UserCompany`) in Sequelize `include` can cause queries to hang with large datasets or complex joins. **Avoid including BelongsToMany in default/frequent queries.** Use it only in specific methods that need it, and consider raw SQL queries for performance-critical paths.
+
+### 7. Common Migration Search Patterns
+
+When migrating an API, search for these patterns and replace them:
+
+| Search Pattern | Replace With |
+|---|---|
+| `this.repository.fullAssociation` | Inline `[{ association: "..." }]` array |
+| `(this.xxxRepo as any).model` | `{ association: "aliasName" }` |
+| `(this.xxxRepo as any).xxxRepo` | `{ association: "aliasName" }` |
+| `(this.repository as any).connection` | `this.repository.getSequelizeConnection()` |
+| `buildAssociations()` | `@HasMany`, `@BelongsTo`, `@HasOne`, `@BelongsToMany` on entity |
+| `{ model: SomeClass, as: "..." }` | `{ association: "..." }` |
+
+### 8. `ARRAY` Column Type
+
+For PostgreSQL `varchar[]` columns, use the custom `arrayType` option:
+
+```ts
+@Column({ type: DataType.ARRAY, arrayType: DataType.STRING })
+componentesBloqueados!: string[]
+```
+
+### 9. Env & Local Dev Setup
+
+Each API needs a `.env` at its server root with:
+- `LOCAL_NO_JWT=true` — skips JWT validation for local dev
+- DB connection vars (`DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DBNAME`)
+- `TOKEN_KEY` — any string for local token signing
+- `API_PORT` — local port for the service
+
+Use `cloud-sql-proxy` for connecting to GCP Cloud SQL locally:
+```bash
+./cloud-sql-proxy <PROJECT>:<REGION>:<INSTANCE> --port=5432
+```
+
+---
+
 ## License
 
 UNLICENSED — HashCodeTI-Brasil