@etus/bhono-app 0.1.4 → 0.1.6

package/dist/cli.js

@@ -13,7 +13,7 @@ function buildProgram() {
     return new Command()
         .name('bhono-app')
         .description('Create a new project from the Etus boilerplate')
-        .version('0.1.4')
+        .version('0.1.5')
         .argument('<project-name>', 'Name of the project')
         .option('-d, --domain <domain>', 'Production domain')
         .option('-m, --modules <modules>', 'Comma-separated modules to include')

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@etus/bhono-app",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/etusdigital/bhono"
+  },
   "files": [
     "dist",
     "templates"

package/templates/base/.husky/pre-push

@@ -0,0 +1,26 @@
+#!/usr/bin/env sh
+
+echo "🔍 Running pre-push checks..."
+
+# Type checking
+echo "📝 Type checking..."
+pnpm typecheck || {
+  echo "❌ Type check failed. Push aborted."
+  exit 1
+}
+
+# Server unit tests only (faster, more reliable)
+echo "🧪 Running server unit tests..."
+pnpm test:unit:server || {
+  echo "❌ Server unit tests failed. Push aborted."
+  exit 1
+}
+
+# Build verification
+echo "🏗️ Verifying build..."
+pnpm build || {
+  echo "❌ Build failed. Push aborted."
+  exit 1
+}
+
+echo "✅ All pre-push checks passed!"

package/templates/base/CLAUDE.md

@@ -5,7 +5,7 @@ Production-ready multi-tenant SaaS boilerplate with Hono.js backend and React fr
 ## Tech Stack
 
 - **Runtime**: Cloudflare Workers (D1 database, KV sessions, R2 storage)
-- **Backend**: Hono.js 4.6 + Drizzle ORM + Zod validation
+- **Backend**: Hono.js 4.6 + SQL (D1) + Zod validation
 - **Frontend**: React 19 + TanStack Router + Tailwind CSS 4.0
 - **Testing**: Vitest (unit/integration) + Playwright (E2E)
 - **Auth**: Google OAuth 2.0 with session-based cookies
@@ -33,7 +33,7 @@ Production-ready multi-tenant SaaS boilerplate with Hono.js backend and React fr
 │   │   │   └── health/         # Health check
 │   │   ├── services/           # Business logic layer
 │   │   ├── middleware/         # Auth, CORS, logging, rate-limit
-│   │   ├── db/schema/          # Drizzle table definitions
+│   │   ├── db/records.ts       # DB record types for SQL mapping
 │   │   ├── lib/                # Utilities (oauth, session, tokens)
 │   │   └── auth/               # Roles, permissions, guards
 │   │
@@ -213,6 +213,6 @@ Defined in `config/wrangler.json`:
 
 ### Database Changes
 
-1. Modify schema in `src/server/db/schema/`
-2. Run `pnpm drizzle-kit generate` to create migration
-3. Apply with `pnpm db:migrate:local`
+1. Update `schema.sql`
+2. Apply with `pnpm db:schema:local`
+3. (Optional) Seed with `pnpm db:seed:local`

package/templates/base/README.md

@@ -52,7 +52,7 @@ This boilerplate provides everything you need to build a modern, secure, and sca
 - Rate limiting middleware (in-memory with lazy cleanup)
 - CSRF protection via SameSite cookies
 - XSS prevention with secure headers
-- SQL injection protection via Drizzle ORM
+- SQL injection protection via parameterized queries
 
 ### Testing
 - Unit tests with Vitest (94%+ coverage)
@@ -73,7 +73,7 @@ This boilerplate provides everything you need to build a modern, secure, and sca
 | **Backend** | Hono.js 4.6 |
 | **Frontend** | React 19 + TanStack Router |
 | **Database** | Cloudflare D1 (SQLite) |
-| **ORM** | Drizzle ORM |
+| **Data Access** | SQL helpers (D1) |
 | **Sessions** | Cloudflare KV |
 | **Storage** | Cloudflare R2 |
 | **Styling** | Tailwind CSS 4.0 |
@@ -105,11 +105,11 @@ pnpm install
 # Copy environment variables
 cp .env.example .env
 
-# Apply database migrations
-pnpm db:migrate:local
+# Apply database schema
+pnpm db:schema:local
 
 # Seed test data (optional)
-pnpm db:seed
+pnpm db:seed:local
 
 # Start development server
 pnpm dev
@@ -152,7 +152,6 @@ LOG_LEVEL=info
 ├── config/                     # Configuration files
 │   ├── eslint.config.js        # ESLint configuration
 │   ├── wrangler.json           # Cloudflare Workers config
-│   ├── drizzle.config.ts       # Drizzle ORM config
 │   └── ...
 │
 ├── src/
@@ -166,8 +165,11 @@ LOG_LEVEL=info
 │   │   │   └── storage/        # File storage (R2)
 │   │   ├── services/           # Business logic
 │   │   ├── middleware/         # Request middleware
-│   │   ├── db/                 # Database (Drizzle ORM)
-│   │   │   └── schema/         # Table definitions
+│   │   ├── db/                 # Database (SQL helpers)
+│   │   │   ├── client.ts       # D1 client wrapper
+│   │   │   ├── records.ts      # Record typings (SQL results)
+│   │   │   ├── sql.ts          # Query helpers (queryOne/queryAll/execute)
+│   │   │   └── seed.ts         # Seed generator (seed.sql)
 │   │   ├── auth/               # Roles, permissions, guards
 │   │   └── lib/                # Utilities
 │   │
@@ -209,7 +211,8 @@ LOG_LEVEL=info
 ├── docs/                       # Documentation
 │   └── testing.md              # Testing guide
 │
-└── migrations/                 # D1 SQL migrations
+├── schema.sql                  # D1 schema (source of truth)
+└── seed.sql                    # Generated seed data
 ```
 
 ---
@@ -300,14 +303,20 @@ invitations (
 )
 ```
 
-### Migrations
+### Database Schema
 
 ```bash
-# Apply migrations locally
-pnpm db:migrate:local
+# Apply schema.sql locally
+pnpm db:schema:local
 
-# Apply migrations to production
-pnpm db:migrate:remote
+# Apply schema.sql to production (optional)
+pnpm db:schema:remote
+
+# Generate + seed locally
+pnpm db:seed:local
+
+# Full reset (schema + seed)
+pnpm db:reset:local
 
 # Generate Cloudflare types
 pnpm cf-typegen
@@ -556,7 +565,7 @@ Client (React SPA)
 │              │                    │
 │              ▼                    │
 │  ┌─────────────────────────────┐  │
-│  │      Drizzle ORM            │  │
+│  │      SQL Helpers            │  │
 │  └─────────────────────────────┘  │
 │              │                    │
 └──────────────┼────────────────────┘
@@ -586,9 +595,11 @@ import { createUser } from '@server/services/users'  // Server
 | `pnpm lint` | Run ESLint |
 | `pnpm typecheck` | Run TypeScript checks |
 | **Database** | |
-| `pnpm db:migrate:local` | Apply local migrations |
-| `pnpm db:migrate:remote` | Apply remote migrations |
-| `pnpm db:seed` | Seed database |
+| `pnpm db:schema:local` | Apply schema.sql locally |
+| `pnpm db:schema:remote` | Apply schema.sql remotely |
+| `pnpm db:seed` | Generate seed.sql |
+| `pnpm db:seed:local` | Generate + seed locally |
+| `pnpm db:reset:local` | Apply schema + seed locally |
 | `pnpm cf-typegen` | Generate Cloudflare types |
 | **API** | |
 | `pnpm api:spec` | Generate OpenAPI spec (docs/openapi.json) |
@@ -614,7 +625,7 @@ import { createUser } from '@server/services/users'  // Server
 - **CSRF**: SameSite cookies + CORS validation
 - **XSS**: Secure headers + React's built-in escaping
 - **Session Hijacking**: httpOnly cookies, secure flag in production
-- **SQL Injection**: Parameterized queries via Drizzle ORM
+- **SQL Injection**: Parameterized queries via SQL helpers
 - **Rate Limiting**: In-memory store with configurable limits per route
 - **Fingerprint Validation**: User-agent validation for sessions
 
@@ -663,7 +674,7 @@ MIT License - see [LICENSE](LICENSE) for details.
 ## Acknowledgments
 
 - [Hono.js](https://hono.dev/) - Ultrafast web framework
-- [Drizzle ORM](https://orm.drizzle.team/) - TypeScript ORM
+- [Cloudflare D1](https://developers.cloudflare.com/d1/) - Serverless SQLite
 - [TanStack Router](https://tanstack.com/router) - Type-safe routing
 - [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS
 - [Cloudflare Workers](https://workers.cloudflare.com/) - Edge computing platform

package/templates/base/docs/app_spec.txt

@@ -42,12 +42,12 @@
 
     <backend>
       <framework>Hono.js 4.6</framework>
-      <orm>Drizzle ORM</orm>
+      <orm>SQL (D1/SQLite)</orm>
       <validation>Zod</validation>
       <documentation>OpenAPI 3.0 / Swagger UI</documentation>
       <description>
         Type-safe API development with automatic schema generation.
-        Drizzle provides compile-time SQL safety with SQLite dialect.
+        SQL-first access with Cloudflare D1 (SQLite under the hood).
         OpenAPI spec and TypeScript types can be generated locally (api:spec, api:types).
       </description>
     </backend>
@@ -120,7 +120,7 @@
         → Fetch API
         → Hono Routes
         → Services
-        → Drizzle ORM
+        → SQL (D1/SQLite)
         → D1 Database
     </data_flow>
   </architecture>
@@ -769,9 +769,11 @@
       npm run build            # Build for production
       npm run deploy           # Deploy to Cloudflare Workers
 
-      npm run db:migrate:local   # Apply migrations locally
-      npm run db:migrate:remote  # Apply migrations to production
-      npm run db:seed            # Seed test data
+      npm run db:schema:local    # Apply schema.sql locally
+      npm run db:schema:remote   # Apply schema.sql to production (optional)
+      npm run db:seed            # Generate seed.sql
+      npm run db:seed:local      # Generate + seed locally
+      npm run db:reset:local     # Apply schema.sql + seed (local)
 
       npm run test:unit:server   # Backend unit tests
       npm run test:unit:client   # Frontend tests
@@ -813,8 +815,8 @@
     │   ├── services/               # Business logic
     │   ├── middleware/             # Auth, CORS, logging
     │   ├── db/
-    │   │   ├── schema/             # Drizzle table definitions
-    │   │   └── migrations/         # SQL migrations
+    │   │   ├── records.ts          # DB record types for SQL mapping
+    │   │   └── seed.ts             # Seed generator (outputs seed.sql)
     │   ├── lib/                    # Utilities
     │   └── auth/                   # RBAC guards
     │
@@ -836,11 +838,12 @@
   <key_files>
     src/server/index.ts              # Hono app entry
     src/server/routes/index.ts       # API router
-    src/server/db/schema/            # Database schema
+    src/server/db/records.ts         # Database record types
     src/client/routes/__root.tsx     # React app root
     src/client/routes/_authenticated.tsx  # Auth layout
     wrangler.json                    # Cloudflare config
-    drizzle.config.ts                # Drizzle ORM config
+    schema.sql                        # SQL schema (source of truth)
+    seed.sql                          # Generated seed data (output)
     playwright.config.ts             # E2E test config
     vitest.config.ts                 # Unit test config
   </key_files>

package/templates/base/docs/architecture/README.md

@@ -6,3 +6,6 @@ Indice rapido dos documentos de arquitetura.
 
 - `docs/architecture/erd.md` - ERD e dicionario de dados.
 - `docs/architecture/data-requirements.md` - Data Requirements Document (DRD).
+- `docs/architecture/db-bootstrap.md` - Bootstrap do schema.sql e seed.
+- `docs/architecture/drizzle-migration-plan.md` - Mapeamento do Drizzle e plano de migracao para SQL puro.
+- `docs/architecture/sql-standards.md` - Padrao de SQL puro e mapeamento de resultados.

package/templates/base/docs/architecture/data-requirements.md

@@ -1,7 +1,7 @@
 # Data Requirements Document (DRD)
 
 ## 1. Objetivo e escopo
-Este documento define os requisitos de dados do projeto, cobrindo o modelo relacional (D1/SQLite), armazenamento de sessao (KV) e objetos (R2). Serve como referencia para manutencao, auditoria e eventual migracao para SQL puro.
+Este documento define os requisitos de dados do projeto, cobrindo o modelo relacional (D1/SQLite), armazenamento de sessao (KV) e objetos (R2). Serve como referencia para manutencao, auditoria e evolucao do SQL puro.
 
 ## 2. Componentes de armazenamento
 - D1 (SQLite): armazenamento relacional principal.
@@ -102,8 +102,9 @@ Principais entidades:
 - Requisito: manter procedimento de backup/restore do D1 (ex.: exportacao periodica) e verificar restauracao.
 - KV e R2 devem ter estrategia de recuperacao alinhada com RPO/RTO desejados.
 
-## 12. Consideracoes para migracao para SQL puro
+## 12. Consideracoes para SQL puro (sem migrations)
 - Todas as queries devem ser parametrizadas para evitar SQL injection.
 - Manter mapeadores de resultado (ex.: validacao via Zod) para preservar contratos tipados.
 - Centralizar SQL em um modulo `db` e reutilizar modelos do ERD.
-- Implementar migracoes em SQL (ou manter ferramenta atual apenas para migrar schema).
+- `schema.sql` e a fonte de verdade do schema e deve ser aplicado via `wrangler d1 execute`.
+- `seed.sql` e gerado a partir de `src/server/db/seed.ts` e aplicado apos o bootstrap quando necessario.

package/templates/base/docs/architecture/db-bootstrap.md

@@ -0,0 +1,39 @@
+# Database Bootstrap (schema.sql)
+
+## Objetivo
+O boilerplate nao usa migrations. O schema do D1 e versionado em `schema.sql` e aplicado via `wrangler d1 execute`. O seed e gerado em `seed.sql` a partir de `src/server/db/seed.ts`.
+
+## Arquivos
+- `schema.sql` - fonte de verdade do schema
+- `src/server/db/seed.ts` - gerador de seed
+- `seed.sql` - output do seed (gerado)
+
+## Fluxos recomendados
+### Local
+```bash
+# aplicar schema
+pnpm db:schema:local
+
+# gerar e aplicar seed
+pnpm db:seed:local
+
+# reset completo (schema + seed)
+pnpm db:reset:local
+```
+
+### Remoto (opcional)
+```bash
+# aplicar schema
+pnpm db:schema:remote
+
+# gerar e aplicar seed
+pnpm db:seed:remote
+
+# reset completo (schema + seed)
+pnpm db:reset:remote
+```
+
+## Notas
+- `schema.sql` deve ser atualizado a cada mudanca estrutural.
+- `seed.sql` deve ser re-gerado apos alteracoes em `seed.ts`.
+- As migrations nao sao usadas neste boilerplate para manter o fluxo simples.

package/templates/base/docs/architecture/drizzle-migration-plan.md

@@ -0,0 +1,125 @@
+# Mapeamento do Drizzle e plano de migracao para SQL puro
+
+> Status: Drizzle removido (PDB-823, Jan 2026). Este documento permanece como historico do plano.
+
+Contexto canonico: `docs/app_spec.txt`.
+
+## Objetivo
+
+Documentar onde o Drizzle e utilizado hoje e propor uma sequencia de migracao para SQL puro (D1/SQLite) com menor risco.
+
+## Inventario de uso do Drizzle
+
+### Tooling e configuracao
+
+- `config/drizzle.config.ts`
+- `package.json` (scripts `db:push`, `db:generate`, `db:studio`; dependencias `drizzle-orm`, `drizzle-kit`)
+- `packages/bhono-app/templates/base/config/drizzle.config.ts`
+- `packages/bhono-app/templates/base/package.json` (mesmos scripts/dependencias)
+
+### Schema e helpers
+
+- `src/server/db/schema/index.ts`
+- `src/server/db/schema/*.ts` (users, accounts, user-accounts, invitations, refresh-tokens, audit-logs)
+- `src/server/lib/schema-helpers.ts`
+- `packages/bhono-app/templates/base/src/server/db/schema/*`
+- `packages/bhono-app/templates/base/src/server/lib/schema-helpers.ts`
+
+### Client e cross-cutting
+
+- `src/server/db/client.ts` (createDb com `drizzle-orm/d1`)
+- `src/server/lib/transaction.ts` (types baseados em `Database['transaction']`)
+- `src/server/lib/audited-db.ts` (Table/SQL do Drizzle, `.returning()`)
+- `src/server/lib/audit.ts` (grava em `audit_logs` usando `db.insert`)
+- `packages/bhono-app/templates/base/src/server/db/client.ts`
+- `packages/bhono-app/templates/base/src/server/lib/transaction.ts`
+- `packages/bhono-app/templates/base/src/server/lib/audited-db.ts`
+- `packages/bhono-app/templates/base/src/server/lib/audit.ts`
+
+### Services (queries principais)
+
+- `src/server/services/auth.ts` (insert/update/returning, tokens, refresh)
+- `src/server/services/users.ts` (filtros, subquery IN, soft delete, paginacao)
+- `src/server/services/accounts.ts` (filtros, subquery IN, soft delete, paginacao)
+- `src/server/services/invitations.ts` (joins, expiracao, create/accept)
+- `src/server/services/audits.ts` (filtros, paginacao)
+- `packages/bhono-app/templates/base/src/server/services/*` (espelho)
+
+### Middleware e rotas
+
+- `src/server/middleware/auth.ts` (select por id + soft delete)
+- `src/server/middleware/account.ts` (select por membership)
+- `src/server/routes/health/handlers.ts` (db.run com `sql` do Drizzle)
+- `src/server/routes/auth/test-login.ts` (select simples)
+- `packages/bhono-app/templates/base/src/server/middleware/*`
+- `packages/bhono-app/templates/base/src/server/routes/*`
+
+### Testes
+
+- `tests/integration/setup.ts` (drizzle + better-sqlite3, schema SQL inline)
+- `packages/bhono-app/templates/base/tests/integration/*` (espelho com drizzle)
+- `packages/bhono-app/templates/base/tests/integration/security/*.test.ts` (comentarios e wrappers de drizzle)
+
+## Padroes de query usados hoje
+
+- Select simples por id + soft delete (`deleted_at IS NULL`).
+- Select com join (`invitations` + `users`/`accounts`).
+- Subquery com `IN` (multi-tenancy em users/accounts).
+- Paginacao com `LIMIT/OFFSET` + `count(*)`.
+- `LIKE` para filtros por nome/email/dominio.
+- Inserts/updates com `returning()`.
+- Soft delete (update de `deleted_at` e audit).
+- Transacoes (create user + account + membership; depende de `db.transaction`).
+- Uso pontual de SQL raw (`sql\`SELECT 1\`` na healthcheck).
+
+## Sequencia recomendada de migracao
+
+1) Padroes e convencoes de SQL puro (PDB-813)
+- Definir placeholders, naming, soft delete, mapeamento/validacao, tratamento de erros.
+
+2) Helper SQL para D1 (PDB-814)
+- API de execucao (queryOne/queryAll/exec), bind de parametros e typing.
+- Confirmar comportamento de transacoes no D1 (ex.: `batch`) antes de migrar flows criticos.
+
+3) Camadas cross-cutting (PDB-815)
+- Reimplementar `audited-db` e `audit` com SQL puro.
+- Ajustar `transaction.ts` para o novo helper.
+
+4) Modulos de negocio (PDB-816 a PDB-821)
+- Auth -> Users -> Accounts -> Invitations -> Audits -> Middleware.
+- Sempre migrar junto com testes afetados.
+
+5) Estrategia sem migrations (PDB-822)
+- Consolidar `schema.sql` versionado e bootstrap/reset com `wrangler d1 execute`.
+- Alinhar `tests/integration/setup.ts` com `schema.sql`.
+
+6) Remocao de Drizzle (PDB-823)
+- Limpar dependencias, scripts e tipos remanescentes.
+
+## Riscos e mitigacoes
+
+- Consistencia multi-tenant: garantir `account_id` em todas as queries.
+  - Mitigacao: helper com scoping obrigatorio e testes de autorizacao.
+
+- Perda de audit trail: `audited-*` depende de `returning()`.
+  - Mitigacao: selecionar estado anterior antes do update e usar `RETURNING` quando suportado.
+
+- SQL injection: migracao aumenta risco manual.
+  - Mitigacao: prepared statements, helpers obrigatorios e proibicao de string interpolation.
+
+- Diferencas de comportamento entre D1 e sqlite local.
+  - Mitigacao: alinhar `schema.sql` e tests com D1 (usar `wrangler d1` para smoke tests).
+
+- Quebra de testes e mocks.
+  - Mitigacao: atualizar `tests/integration/setup.ts` e mocks ao mesmo tempo que cada modulo.
+
+## Entregaveis desta etapa (PDB-812)
+
+- Inventario de arquivos e padroes de query.
+- Sequencia recomendada e dependencias entre modulos.
+- Riscos e mitigacoes para orientar as proximas issues.
+
+## Notas
+
+- Tudo que for alterado no `src/` deve ser espelhado em `packages/bhono-app/templates/base/`.
+- O seed ja gera SQL puro; pode ser mantido e ajustado conforme o `schema.sql`.

package/templates/base/docs/architecture/erd.md

@@ -1,7 +1,7 @@
 # ERD - Hono Boilerplate (D1/SQLite)
 
 ## Visao geral
-Este documento descreve o modelo relacional atual utilizado no banco D1 (SQLite) do projeto. Ele foi derivado diretamente dos schemas em `src/server/db/schema`.
+Este documento descreve o modelo relacional atual utilizado no banco D1 (SQLite) do projeto. Ele foi derivado diretamente de `schema.sql`.
 
 ## Diagrama (Mermaid)
 ```mermaid

package/templates/base/docs/architecture/sql-standards.md

@@ -0,0 +1,100 @@
+# Padrao de SQL puro e mapeamento de resultados
+
+Contexto canonico: `docs/app_spec.txt`.
+
+## Objetivo
+
+Definir convencoes para SQL puro no D1/SQLite, incluindo bind de parametros,
+mapa de resultados e tratamento de erros para manter consistencia e seguranca.
+
+## Escopo
+
+- SQL usado no backend (services, middleware, lib).
+- Mapeamento de resultados para tipos de dominio.
+- Soft delete, multi-tenancy, auditoria e paginacao.
+
+## Convencoes de SQL
+
+### Estilo
+
+- Keywords em UPPERCASE (SELECT, FROM, WHERE).
+- Tabelas e colunas em snake_case (como no schema atual).
+- Evitar `SELECT *`: listar colunas para mapear explicitamente.
+- Preferir alias curtos (`users u`, `accounts a`) quando houver join.
+
+### Parametros e seguranca
+
+- Nunca interpolar strings diretamente em SQL.
+- Usar placeholders posicionais `?` com `stmt.bind(...)`.
+- Proibir concatenacao de SQL com valores de usuario.
+
+### Soft delete
+
+- Queries de leitura devem sempre filtrar `deleted_at IS NULL` quando aplicavel.
+- Remocoes devem ser soft delete (update de `deleted_at`, `deleted_by_id`, `updated_at`).
+- Restauracao deve limpar `deleted_at` e `deleted_by_id`.
+
+### Multi-tenancy
+
+- Toda query de dados multi-tenant deve filtrar `account_id`.
+- Para super-admin, permitir bypass explicito em query (flag de contexto).
+
+### Paginacao e filtros
+
+- Paginacao via `LIMIT`/`OFFSET`.
+- Contagem total via `SELECT count(*)`.
+- Filtros textuais com `LIKE` e `%`.
+
+### Datas e tipos
+
+- Datas em TEXT ISO (ex.: `created_at`) ou INTEGER unix (ex.: `refresh_tokens`).
+- Mapear `INTEGER` para boolean quando necessario (0/1).
+- Campos JSON em TEXT devem ser parseados ao ler.
+
+## Mapeamento de resultados
+
+### Regra geral
+
+- Toda query deve ter um mapper explicito (funcao ou schema) que:
+  - valida shape (preferencialmente com Zod),
+  - converte tipos (INTEGER -> boolean, TEXT JSON -> objeto),
+  - normaliza campos opcionais.
+
+### Exemplo (conceitual)
+
+- Query retorna `is_super_admin` (INTEGER).
+- Mapper converte para boolean e retorna `isSuperAdmin`.
+- Campo `provider_ids` (TEXT JSON) vira `string[]`.
+
+## Erros e tratamento
+
+- `NotFoundError` quando `SELECT` nao retorna registros esperados.
+- `ConflictError` quando violar unicidade (dominio/email/token).
+- `ForbiddenError` para acesso indevido a `account_id`.
+- Propagar erro de SQL com mensagem generica (evitar leak de detalhes).
+
+## Transacoes
+
+- D1 nao oferece transacoes nativas. Operacoes multi-step devem ser planejadas
+  para serem idempotentes ou dividir em `batch` quando possivel.
+- Para fluxos criticos, validar resultados intermediarios e registrar auditoria
+  com `transaction_id` compartilhado.
+
+## Auditoria
+
+- Toda mutacao relevante deve registrar `audit_logs`.
+- Usar `transaction_id` comum para agrupar operacoes.
+- Registrar `changes` apenas com campos relevantes.
+
+## Checklist de migracao por modulo
+
+- Listar queries atuais.
+- Reescrever SQL com bind e filtros `account_id`/`deleted_at`.
+- Adicionar mapper/validator.
+- Atualizar testes afetados.
+
+## Referencias
+
+- `docs/architecture/erd.md`
+- `docs/architecture/data-requirements.md`
+- `docs/architecture/drizzle-migration-plan.md`