@evertonferreira96/agents 0.0.0-stage → 0.1.0

package/.claude/skills/arch-web/references/services.md

@@ -0,0 +1,297 @@
+# Services e Server Actions
+
+Mecânica da camada `src/modules/<feature>` que a SKILL resume em "Caminhos" e nas regras 1 a 11: anatomia da feature, service de mutação e de leitura, `Action.Result`, fachada `shared/api`, mapper de falha, permissões, revalidate, schemas, entities, listagem, Route Handler e upload. Exemplos com `invoice`/`invoices`; troque pelos nomes do repo.
+
+## Anatomia da feature
+
+| Arquivo | Contém | Quem importa |
+|---|---|---|
+| `index.ts` | leituras `server-only`, schemas de URL, tipos, constantes, mappers puros | servidor (página, bloco, outra feature) |
+| `<feature>.constants.ts` | listas `as const`, limites, regex, whitelist de sort (`satisfies readonly Invoice.Model.ListSort[]`) | todos, inclusive ilhas e `schemas/` |
+| `<feature>.permissions.ts` | `INVOICE_PERMISSIONS` | services, `<rota>.utils.ts` |
+| `<feature>.revalidate.ts` | `revalidateInvoice(options?)` com `import 'server-only'` | services `'use server'` |
+| `<feature>.url-parsers.ts` | parsers de URL das ilhas (sem Zod) | ilhas |
+| `entities/` | `namespace Invoice { Model; DTO }` | todos (`import type`) |
+| `schemas/` | Zod de URL e de escrita | services, página (via `Block.querySchema`) |
+| `mappers/` | regra pura (`<assunto>.mapper.ts`) e falha (`<feature>-failure.mapper.ts`) | services, blocos (só os puros) |
+| `services/` | só `*.service.ts` e seus testes | página, blocos, `<rota>.utils.ts`, outros services, ilhas (só `'use server'`, pelo arquivo) |
+
+Feature é um domínio, não uma tela. A feature nasce com `services` + `entities`; `schemas`, `mappers`, `permissions`, `revalidate` entram com a primeira necessidade real.
+
+## Service de mutação (a Server Action)
+
+```ts
+'use server'
+
+import { authorize } from '@/modules/auth/services/authorize.service'
+import { Action } from '@/shared/action'
+import { type Api, api, upstream } from '@/shared/api'
+import { validationFailure } from '@/shared/api/failure'
+import type { Invoice } from '../entities/invoice.entities'
+import { invoiceFailure } from '../mappers/invoice-failure.mapper'
+import { INVOICE_PERMISSIONS } from '../invoice.permissions'
+import { revalidateInvoice } from '../invoice.revalidate'
+import { createInvoiceSchema, invoiceScopeSchema } from '../schemas/invoice.schemas'
+
+/** `POST /invoices`: nova fatura. 422 `invoice.items_invalid` volta com os itens em `fieldErrors`. */
+export async function createInvoice(
+  _: Action.Result<Invoice.Model.Detail>,
+  input: unknown,
+): Promise<Action.Result<Invoice.Model.Detail>> {
+  const scope = invoiceScopeSchema.safeParse(input)            // só o recorte de que a permissão depende
+  if (!scope.success) return validationFailure(scope.error)
+  const access = await authorize(INVOICE_PERMISSIONS.create, { tenantId: scope.data.tenantId })
+  if (!access.ok) return access.result
+
+  const parsed = createInvoiceSchema.safeParse(input)
+  if (!parsed.success) return validationFailure(parsed.error)
+  const { tenantId, ...body } = parsed.data
+
+  const result = upstream<Api.<Provider>.CreateInvoiceBodyResponse, Api.Common.Error>(
+    await api.<Provider>.methods.createInvoice({
+      ...(await api.<Provider>.session({ tenantId })),
+      body,
+      cache: 'no-store',
+    }),
+  )
+  if (!result.ok) return invoiceFailure.write(result.status, result.error, 'invoices.create')
+
+  revalidateInvoice({ list: true })
+  return Action.result.ok(result.body.data)
+}
+```
+
+- Precisa do estado atual para decidir (versão, transição permitida): componha um service `server-only` de leitura com `cache: 'no-store'`.
+- Regra conferida no web antes de chamar a API devolve `domainFailure('<domínio>.<motivo>', token)`.
+- O JSDoc cita o endpoint e os `code` de 409/422 que a operação devolve.
+
+| Situação | O que muda |
+|---|---|
+| Criar ou cobrar, e a API exige `Idempotency-Key` | a ilha gera `idempotencyKey` (uuid) ao abrir o formulário; o schema valida; o service a tira do body e a envia no header da chamada (`headers: { ...session.headers, 'Idempotency-Key': key }`), nunca no body (o body da API é `.strict()`) |
+| Lote | `z.array(z.uuid()).min(1).max(<teto>)`, permissão própria, resultado parcial em `data` |
+| Operação longa (import, export grande) | A API dispara um job; a tela acompanha o status, fora da Server Action |
+| Escrita vista por outra área | A invalidação cobre os padrões de rota das duas áreas |
+
+## Service de leitura
+
+```ts
+import 'server-only'
+import { z } from 'zod'
+import { getMe } from '@/modules/auth/services/get-me.service'
+import { Action } from '@/shared/action'
+import { type Api, api, upstream } from '@/shared/api'
+import { apiFailure } from '@/shared/api/failure'
+import { requestMemo } from '@/shared/cache/request-memo'
+import type { Invoice } from '../entities/invoice.entities'
+import { invoiceFailure } from '../mappers/invoice-failure.mapper'
+
+/** `GET /invoices/:invoiceId`. Memoizado por request: página, blocos e `authorizeInvoice` leem uma vez. */
+export const getInvoice = requestMemo(async (invoiceId: string): Promise<Action.Result<Invoice.Model.Detail>> => {
+  if (!z.uuid().safeParse(invoiceId).success) return invoiceFailure.read(404, undefined, 'invoices.read')
+  const me = await getMe()                                   // sessão conferida; o alcance quem decide é a API
+  if (me.status !== 'success') return me.status === 'error' ? me : apiFailure(401)
+
+  const result = upstream<Invoice.DTO.DetailResponse, Api.Common.Error>(
+    await api.<Provider>.methods.getInvoiceById({
+      ...(await api.<Provider>.session()),
+      path: { invoiceId },
+      cache: 'no-store',                                     // ou ...cached(perfil, tags): cache.md
+    }),
+  )
+  if (!result.ok) return invoiceFailure.read(result.status, result.error, 'invoices.read')
+  return Action.result.ok(result.body.data)
+})
+```
+
+- Id da URL inválido vira 404 sem ida à API.
+- Alcance que só a API resolve (papel no recurso): o service confere a sessão e deixa a API recusar (403 vira `authorization.forbidden`, 404 vira `<recurso>.not_found`). Permissão que o perfil já traz: `authorize(keys, scope)` antes da chamada, como na listagem.
+- Leitura com recorte: memoize pela string canônica (ver Listagem).
+- Nome diz o caso de uso: `getInvoiceSummary(id)`, não `getInvoice(id, { mode })`.
+
+## `Action.Result`
+
+`Action.Result<T>` (`shared/action`) é `idle` · `success { data, message }` · `error { message, error: { code, fieldErrors?, details? } }`, montado por `Action.result.idle()/ok(data, message?)/fail(code, message, fieldErrors?, details?)`.
+
+- A UI decide por `status`, nunca pela presença de `data`; `idle` é o estado inicial do hook da ilha.
+- `details` leva só o que a tela precisa para reagir (campos faltando, contagem), vindo do envelope de erro da API.
+- `fieldErrors` usa o caminho do campo com ponto (`items.0.quantity`); `_` é o erro sem campo.
+
+## `shared/api`: a fachada do client gerado
+
+| Peça | Papel |
+|---|---|
+| `api.<Provider>.methods` | SDK gerado; o `operationId` do contrato vira o nome do método |
+| `api.<Provider>.types` / `Api.<Provider>.*` | tipos gerados, base das entities |
+| `api.<Provider>.session(options?)` | config autenticada: bearer pelo `auth` do client, headers do navegador e header de contexto do tenant |
+| `api.<Provider>.anonymous(client?)` | config das rotas públicas (login, refresh); o `proxy.ts` passa o contexto do request dele |
+| `<provider>/config.ts` | `baseUrl` = origem do env + prefixo da API; `fetch: instrumentedFetch` |
+| `<provider>/client-context.ts` | repassa `user-agent` e `x-forwarded-for` do navegador (tamanho limitado), para auditoria e rate limit da API verem o usuário, não o servidor Next |
+| `upstream<Body, Error>(result)` | reafirma o tipo do contrato e discrimina por `response.ok` |
+| `Api.Common.Error` | envelope de erro da API: `statusCode`, `message`, `code?`, `errors?`, `traceId?` (e `details` quando a API manda) |
+
+- O porquê de `upstream` decidir por `response.ok` (regra 6 da SKILL): um 204 devolve `data: {}` e um 4xx de corpo ilegível devolve `error: {}`.
+- Correção de tipo do client gerado mora em `upstream`/entities, num lugar só; o teste de `upstream` avisa quando a correção deixa de ser necessária.
+- Sem retry de 401 no transporte; o motivo está em [`auth-session-env.md`](auth-session-env.md).
+- Contrato: `contracts/<provider>.openapi.json` é a cópia do `openapi.json` da API (`openapi:sync`, contrato da API em `arch-api`); `generated/` sai de `openapi:generate` e é commitado; `openapi:check` falha com drift.
+
+## Falha: `shared/api/failure.ts` e o mapper da feature
+
+`apiFailure(status, overrides, { operation, error }, codes)` decide, nesta ordem:
+
+1. 401 é sempre `auth.session_expired`;
+2. `codes`: o `error.code` da API casado com o significado na operação; quando casa, os `details` seguem no `Action.Result`;
+3. `overrides`: o que 400/403/404/409/422 significam nesta operação;
+4. o vocabulário comum.
+
+| status | `code` comum |
+|---|---|
+| 400, 422 | `request.invalid` |
+| 401 | `auth.session_expired` |
+| 403 | `authorization.forbidden` |
+| 404 | `resource.not_found` |
+| 409 | `resource.conflict` |
+| 429 | `request.rate_limited` |
+| 5xx | `upstream.unavailable` |
+| outro | `upstream.failed` |
+
+`apiFailure` loga `operation`, `status`, `code` escolhido, `code` e `message` da API em `warn`; a tela recebe a mensagem traduzida do token. `validationFailure(zodError)` devolve `validation.failed` com `fieldErrors` traduzidos por tipo de issue (a mensagem padrão do Zod nunca chega à tela; `refine` com mensagem em forma de token é traduzido).
+
+```ts
+// mappers/invoice-failure.mapper.ts
+import 'server-only'
+
+const tokens = i18nTokens.invoices.errors
+const CODES: FailureCodes = {
+  'invoice.stale': { code: 'invoice.stale', message: tokens.stale },
+  'invoice.items_invalid': { code: 'invoice.items_invalid', message: tokens.itemsInvalid },
+}
+const notFound = { code: 'invoice.not_found', message: tokens.notFound } as const
+
+export const invoiceFailure = {
+  read: (status: number, error: unknown, operation: string) =>
+    apiFailure(status, { 404: notFound }, { operation, error }, CODES),
+  write: (status: number, error: unknown, operation: string) =>
+    apiFailure(status, { 404: notFound, 409: { code: 'invoice.stale', message: tokens.stale } }, { operation, error }, CODES),
+}
+```
+
+- Duas formas convivem no repo de referência: objeto por operação (`invoiceFailure.write(status, error, operation)`, como acima, quando 404/409 mudam de sentido por operação) e função única (`invoiceFailure(operation, status, error?)`, que chama `apiFailure` com os mesmos `overrides` e `CODES`). Siga a forma do mapper da feature; feature nova escolhe a que cobre os significados dela.
+- Um `CODES` por feature, com todo `code` de 409/422 que a API documenta para ela.
+- 422 com `details` por campo: um `withFieldErrors(result)` no mapper converte `details` em `fieldErrors` mantendo `code` e `details`; o formulário marca cada campo.
+
+## Permissões e autorização
+
+```ts
+// invoice.permissions.ts
+const OVERRIDES = ['invoices:manage', '<admin>:manage'] as const
+export const INVOICE_PERMISSIONS = {
+  read: ['invoices:read', ...OVERRIDES],
+  create: ['invoices:create', ...OVERRIDES],
+} as const satisfies Record<string, readonly Permission[]>
+```
+
+- Cada lista vale por "qualquer uma"; quem passa em todas entra em cada lista.
+- `authorize(keys, scope?)` (helper do módulo de auth do repo) falha com `auth.session_expired` sem sessão e `authorization.forbidden` sem permissão; no sucesso devolve o perfil (`me`).
+- Decisão de apresentação (mostrar botão, aba) usa a regra pura (`authorization.canAny(me, keys, scope)` de `shared/auth`) em `<rota>.utils.ts`; esconder não substitui o `authorize` no service.
+- Permissão por recurso (o perfil não traz o papel no recurso): `services/authorize-<recurso>.service.ts` (`server-only`) lê o recurso memoizado, aceita as permissões do recurso **ou** as do perfil no tenant e devolve o perfil e o recurso no sucesso; a regra pura vai para `mappers/<recurso>-access.mapper.ts`. Na Server Action, o id do recurso é o recorte de escopo da regra 5.
+
+## Revalidate
+
+```ts
+// invoice.revalidate.ts
+import 'server-only'
+import { revalidatePath } from 'next/cache'
+import { invalidate } from '@/shared/cache/invalidate'
+import { CacheTags } from '@/shared/cache/tags'
+import { INVOICE_ROUTE_PATTERNS } from '@/shared/settings/routes'
+
+export function revalidateInvoice(options: { list?: boolean } = {}) {
+  revalidatePath(INVOICE_ROUTE_PATTERNS.detail, 'page')       // padrão da rota: todas as faturas de uma vez
+  if (options.list) revalidatePath(INVOICE_ROUTE_PATTERNS.list, 'page')
+  invalidate.now(CacheTags.invoiceSummary())
+}
+```
+
+O papel de cada chamada e o modo de invalidação: [`cache.md`](cache.md).
+
+## Schemas
+
+```ts
+// URL: lido pela página; .catch() faz link antigo degradar para o padrão
+export const invoicesListQuerySchema = z.object({
+  search: listingParams.search,
+  status: listingParams.oneOf(INVOICE_STATUSES),
+  sort: sortSchema(INVOICE_LIST_SORTS).optional().catch(undefined),
+  page: listingParams.page,
+  pageSize: listingParams.pageSize,
+})
+export type InvoicesListQuery = z.infer<typeof invoicesListQuerySchema>
+
+// Escrita: recorte de escopo + resto, .strict() contra mass assignment
+export const invoiceScopeSchema = z.object({ tenantId: z.uuid() })
+export const createInvoiceSchema = invoiceScopeSchema
+  .extend({ customerId: z.uuid(), notes: z.string().trim().max(INVOICE_NOTES_MAX).optional() })
+  .strict()
+export type CreateInvoiceInput = z.input<typeof createInvoiceSchema>
+```
+
+- Helpers de URL (`listingParams`, `sortSchema`) vêm de `shared/query`; limites e listas, de `<feature>.constants.ts`.
+- O schema traduz para o formato do contrato (`''` vira `null`, data do calendário vira ISO).
+- `z.input` tipa o que a ilha envia; `z.infer`, o que o service usa.
+- Input em `FormData` chega string: número com `z.coerce.number()`, checkbox com `z.literal('on').optional().transform(Boolean)` (`z.coerce.boolean()` faz `'false'` virar `true`).
+
+## Entities
+
+```ts
+import type { Api } from '@/shared/api'
+import type { Page } from '@/shared/query/listing'
+
+export namespace Invoice {
+  export namespace Model {
+    export type Status = Api.<Provider>.InvoiceStatus
+    export type Summary = Api.<Provider>.InvoiceSummary
+    export type Listing = Page<Summary>
+    export type Detail = Api.<Provider>.GetInvoiceByIdBodyResponse['data']
+  }
+  export namespace DTO {
+    export type ListQuery = Api.<Provider>.ListInvoicesQueryParamRequest
+    export type ListResponse = Api.<Provider>.ListInvoicesBodyResponse
+    export type DetailResponse = Api.<Provider>.GetInvoiceByIdBodyResponse
+    export type CreateBody = Api.<Provider>.CreateInvoiceBodyRequest
+  }
+}
+```
+
+Tipo que o service monta por conta própria (composição de duas leituras) mora em `Model` com JSDoc.
+
+## Listagem
+
+```ts
+const fetchInvoices = requestMemo(async (key: string): Promise<Action.Result<Invoice.Model.Listing>> => {
+  const { tenantId, ...query } = JSON.parse(key) as InvoicesListQuery & { tenantId: string }
+  const access = await authorize(INVOICE_PERMISSIONS.read, { tenantId })
+  if (!access.ok) return access.result
+  const result = upstream<Invoice.DTO.ListResponse, Api.Common.Error>(
+    await api.<Provider>.methods.listInvoices({ ...(await api.<Provider>.session({ tenantId })), query, cache: 'no-store' }),
+  )
+  if (!result.ok) return invoiceFailure.read(result.status, result.error, 'invoices.list')
+  return Action.result.ok(toPage(result.body))
+})
+
+export function listInvoices(tenantId: string, input: Partial<InvoicesListQuery>) {
+  return fetchInvoices(requestMemoKey({ tenantId, ...invoicesListQuerySchema.parse(input) }))
+}
+```
+
+- O service revalida o recorte: a URL é do usuário, mesmo depois do parse da página.
+- `requestMemoKey` monta a chave canônica (chaves ordenadas, vazio fora), e dois blocos com o mesmo recorte dividem uma ida à API.
+- `toPage` normaliza o envelope paginado da API para `Page<T>`.
+- O lado da página está em [`blocks.md`](blocks.md); o da ilha de filtro, em [`ui-forms.md`](ui-forms.md).
+
+## Route Handler
+
+Server Action é o caminho da mutação da UI. Route Handler entra para webhook ou callback externo, endpoint consumido por outro sistema, download/streaming/export, upload grande com progresso, ou protocolo que Server Action não atende.
+
+Webhook, nesta ordem: corpo cru (`request.text()`) → assinatura conferida (401 se falha) → payload pelo Zod → service `server-only` → `invalidate.background(CacheTags.*)` (ninguém espera a própria escrita) → log em `after()` → `Response.json`. Route Handler chama services `server-only`, nunca um `'use server'`; o que lê para o navegador autentica e autoriza como qualquer leitura.
+
+**Upload:** arquivo pequeno de formulário vai por Server Action com `serverActions.bodySizeLimit` no `next.config` acima do limite de produto (o multipart soma bytes); grande, múltiplo, com progresso ou retomada vai por Route Handler ou URL assinada do storage. Tipo e tamanho validados no servidor; `accept` do `<input>` é conveniência.

package/.claude/skills/arch-web/references/tests.md

@@ -0,0 +1,159 @@
+# Testes
+
+O que testar em cada camada, onde o teste mora e como mockar a fronteira. Runner, ambiente e setup são os do repo (`vitest.config.*`, `vitest.setup.ts`); esta reference não prescreve setup novo.
+
+---
+
+## Onde mora
+
+- Ao lado do código que testa: `create-invoice.service.test.ts` ao lado do service, `invoice.schemas.test.ts` ao lado do schema, `invoices-table-block.test.tsx` ao lado do bloco.
+- Um arquivo pode cobrir vários services da mesma família (`invoice-mutations.service.test.ts`).
+- Fixtures, fábricas e helpers compartilhados em `src/test/`.
+- Os guards (`scripts/check-*.mjs`) fazem parte do gate: estrutura errada falha no `guard`, não na revisão.
+
+## Por camada
+
+| Camada | Teste | Cobre |
+|---|---|---|
+| `mappers/<assunto>.mapper.ts` | unit, sem React/Next | regra pura, casos de borda |
+| `mappers/<feature>-failure.mapper.ts` | unit | `code` por `error.code` da API, `overrides` por status, `withFieldErrors` |
+| `schemas/` | unit | válido, inválido, normalização, `.catch()` da URL, `.strict()` |
+| `blocks/<rota>.utils.ts` | unit | cada estado do resolver, permissões, links |
+| Service `'use server'` | unit com a fronteira mockada | validação, forbidden, falha upstream com `code`, sucesso, invalidação |
+| Service `server-only` | unit com a fronteira mockada | 404 por id inválido, sessão, falha mapeada, `cached` vs `no-store` |
+| Bloco server | RSC chamado como função | os três `status`, fallback degradável |
+| Ilha | Testing Library | interação, `fieldErrors` no campo, pendência, a11y |
+| `shared/` | unit | `upstream`, `apiFailure`, `requestMemoKey`, logger (redaction) |
+| Catálogo de páginas | contrato, se o repo tem | toda rota do catálogo tem `page.tsx` e key em `pages.ts` |
+| Bug | o nível mais baixo que reproduz | regressão |
+
+---
+
+## Service `'use server'`
+
+```ts
+vi.mock('@/shared/api', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@/shared/api')>()),
+  api: { <Provider>: { session: vi.fn(async () => ({})), methods: { createInvoice: vi.fn() } } },
+}))
+vi.mock('@/modules/auth/services/authorize.service', () => ({ authorize: vi.fn() }))
+vi.mock('next/cache', () => ({ revalidatePath: vi.fn(), updateTag: vi.fn(), revalidateTag: vi.fn() }))
+
+const idle = Action.result.idle<Invoice.Model.Detail>()
+const generated = (status: number, body: unknown) =>
+  status < 400
+    ? { data: body, response: new Response(null, { status }) }
+    : { error: body, response: new Response(null, { status }) }
+
+it('recorte inválido: validation.failed sem autorizar nem chamar a API', async () => {
+  const result = await createInvoice(idle, { tenantId: 'x' })
+  expect(result.status === 'error' && result.error.code).toBe('validation.failed')
+  expect(authorize).not.toHaveBeenCalled()
+})
+
+it('sem permissão: authorization.forbidden antes de validar o body', async () => {
+  vi.mocked(authorize).mockResolvedValue({ ok: false, result: Action.result.fail('authorization.forbidden', 'forbidden') })
+  const result = await createInvoice(idle, { tenantId: TENANT, customerId: 'inválido' })
+  expect(result.status === 'error' && result.error.code).toBe('authorization.forbidden')
+})
+
+it('422 da API vira o code da operação, com details', async () => {
+  vi.mocked(authorize).mockResolvedValue({ ok: true, me })
+  vi.mocked(api.<Provider>.methods.createInvoice).mockResolvedValue(
+    generated(422, { statusCode: 422, code: 'invoice.items_invalid', message: 'raw', details: { items: [0] } }),
+  )
+  const result = await createInvoice(idle, validInput)
+  expect(result.status === 'error' && result.error).toMatchObject({ code: 'invoice.items_invalid', details: { items: [0] } })
+  expect(result.message).not.toContain('raw')                // mensagem crua da API só no log
+})
+
+it('sucesso invalida as telas e as tags', async () => {
+  vi.mocked(authorize).mockResolvedValue({ ok: true, me })
+  vi.mocked(api.<Provider>.methods.createInvoice).mockResolvedValue(generated(201, { data: invoice }))
+  const result = await createInvoice(idle, validInput)
+  expect(result).toMatchObject({ status: 'success', data: invoice })
+  expect(revalidatePath).toHaveBeenCalledWith(INVOICE_ROUTE_PATTERNS.list, 'page')
+  expect(updateTag).toHaveBeenCalledWith(CacheTags.invoiceSummary())
+})
+```
+
+- O mock atinge a fronteira (`shared/api`, o service de autorização, `next/cache`); o service roda de verdade.
+- Afirme por `code` e `status`, nunca pela mensagem traduzida.
+- Teste a tag declarada e as tags invalidadas, não se o framework cacheou.
+- `notFound()`, `redirect()`, `forbidden()` lançam por design; o mock de `next/navigation` lança e o teste espera o lançamento.
+- Tradução no teste (se o repo tem i18n): siga o setup do repo (mock de `getTranslation` ou locale carregado); a asserção continua por `code`.
+
+## Schema de URL
+
+```ts
+it('coage e limita o que vem da URL', () => {
+  expect(invoicesListQuerySchema.parse({ page: '-3', pageSize: '99999', status: 'inexistente' }))
+    .toMatchObject({ page: 1, status: undefined })          // .catch() em ação: link antigo degrada
+})
+
+it('body com campo extra é recusado', () => {
+  expect(createInvoiceSchema.safeParse({ ...validInput, admin: true }).success).toBe(false)
+})
+```
+
+## Bloco server: chame como função
+
+`render()` da Testing Library não lida com componente que retorna Promise. Chame, `await`, renderize o resultado.
+
+```tsx
+vi.mock('@/modules/invoice', () => ({ getInvoiceSummary: vi.fn() }))
+
+it('mostra o erro na moldura quando a leitura falha', async () => {
+  vi.mocked(getInvoiceSummary).mockResolvedValue(Action.result.fail('upstream.unavailable', 'indisponível'))
+  render(await InvoiceSummaryComponent({ invoiceId: INVOICE }))
+  expect(screen.getByRole('region', { name: /resumo/i })).toBeInTheDocument()
+  expect(screen.getByText('indisponível')).toBeInTheDocument()
+})
+```
+
+| Funciona | Vai para E2E |
+|---|---|
+| bloco que retorna elementos e ilhas, os três `status`, fallback | RSC async aninhado (vira Promise no meio da árvore) |
+| conferir a chamada ao service | streaming real de `<Suspense>`, ordem de chegada |
+
+## Ilha
+
+- Localize pelo que o usuário vê: `getByRole` com `name`; test id só quando não há papel.
+- Mocke a Server Action importada pelo arquivo e o provider de feedback.
+- Cubra: submit com valores válidos chama a action com o objeto certo; `fieldErrors` aparecem no campo e não em toast; erro sem campo vira toast/`formError`; botão pendente.
+- `axe` nos componentes do DS e em ilhas com formulário, se o repo usa.
+
+---
+
+## E2E (se o repo tiver)
+
+Sem Playwright ou equivalente configurado, registre a lacuna e não crie setup novo dentro da tarefa. Mock de rede (MSW) idem: só se o repo já usa; o padrão é mockar `shared/api`. Com setup:
+
+| Mudança | E2E |
+|---|---|
+| Fluxo com carregamento em etapas (moldura antes, blocos em streaming) | afirme a ordem observável, nunca o esqueleto |
+| Boundary nova ou movida, `prefetch={true}` | sim |
+| Mutação com otimista e reconciliação | sim, no fluxo principal |
+| Regra, schema, invalidação de tag, composição de bloco | não: unit |
+
+- Nome acessível vem do locale importado no teste, não de string repetida no spec.
+- Rotas visitadas podem continuar montadas e ocultas: `filter({ visible: true })` ou escopo de container.
+- Suíte que escreve: um worker, backend semeado, servidor subido do zero (leitura cacheada sobrevive ao re-seed).
+- Sem permissão: o controle some (E2E) **e** a chamada direta à Server Action falha (unit).
+
+Load test e relatórios (k6, Allure): só se o repo já tem; mantenha alvos e labels existentes.
+
+---
+
+## Checklist
+
+```txt
+[ ] mapper puro e failure mapper com teste ao lado
+[ ] schema: válido, inválido, .catch() da URL, .strict() do body
+[ ] Server Action nova: os cinco casos da linha `'use server'` em "Por camada"
+[ ] leitura nova: id inválido, sessão, falha mapeada
+[ ] <rota>.utils.ts: cada estado do resolver
+[ ] bloco degradável: fallback com o erro do Action.Result
+[ ] ilha com formulário: fieldErrors no campo
+[ ] guard, lint, check-types e test verdes
+```

package/.claude/skills/arch-web/references/ui-forms.md

@@ -0,0 +1,143 @@
+# UI e formulários
+
+O lado client que a SKILL resume nas regras 8, 9, 18 e 19: o que a ilha importa, a receita de formulário com `useServerAction`, feedback único, pendência e otimista, ação destrutiva, ação que desmonta a própria ilha, busca e filtro, componentes do DS, tokens e texto em ilha. Estética e escolhas visuais: `/ui`; o README do DS do repo vence esta reference.
+
+**Feedback não se duplica.** Cada resultado tem um único sinal: o item que mudou, o status inline, o campo com erro ou um toast. Nunca dois.
+
+---
+
+## O que a ilha importa
+
+Além das regras 8 e 9 da SKILL (Server Action pelo arquivo; vocabulário sem Zod):
+
+| Importa | Fica no servidor |
+|---|---|
+| tipos de `entities/` por `import type` (somem do bundle) | `shared/api`, `shared/environment`, o logger do servidor, qualquer `server-only` |
+| `useServerAction` de `shared/feedback` | o objeto de tokens de i18n completo (a ilha usa a fatia) |
+| componentes do DS pelo index (`@/shared/ui/components/<nome>`) | arquivo interno de componente (`.../atoms/...`) |
+| blueprint pelo arquivo | barril de blueprint |
+
+## Formulário: React Hook Form + `useServerAction`
+
+```tsx
+'use client'
+
+import { useForm } from 'react-hook-form'
+import { INVOICE_NOTES_MAX } from '@/modules/invoice/invoice.constants'
+import { createInvoice } from '@/modules/invoice/services/create-invoice.service'
+import { useServerAction } from '@/shared/feedback'
+
+type Values = { tenantId: string; customerId: string; notes: string }
+
+export const CreateInvoiceForm: FC<{ tenantId: string; onDone: () => void }> = ({ tenantId, onDone }) => {
+  const { t } = useTranslation(['invoices', 'common'])
+  const form = useForm<Values>({ defaultValues: { tenantId, customerId: '', notes: '' } })
+  const create = useServerAction(createInvoice, {
+    closeLabel: t(commonTokens.actions.close),
+    successMessage: t(invoicesTokens.create.success),
+    onSuccess: () => { form.reset(); onDone() },
+    setError: (field, error) => form.setError(field as keyof Values, error),
+  })
+
+  return (
+    <form onSubmit={form.handleSubmit((values) => create.run(values))} noValidate>
+      <TextField.Field
+        label={t(invoicesTokens.create.notes)}
+        error={form.formState.errors.notes?.message}
+        {...form.register('notes', { maxLength: { value: INVOICE_NOTES_MAX, message: t(validationTokens.tooLong, { max: INVOICE_NOTES_MAX }) } })}
+      />
+      <Button.Root type="submit" disabled={create.pending}>{t(invoicesTokens.create.submit)}</Button.Root>
+    </form>
+  )
+}
+```
+
+- O client valida com as **regras nativas** do React Hook Form (`required`, `maxLength`, `pattern` com as constantes da feature); o Zod fica no service, que é a validação que conta.
+- `useServerAction(action, { closeLabel, successMessage?, onSuccess?, onError?, setError? })` devolve `{ state, run, pending, fieldErrors, formError }`: `run(input)` dispara em transição com o objeto validado; `pending` vem do `useActionState`.
+- Sucesso: toast se `successMessage` (sem ele, o sucesso é silencioso porque o dado novo já aparece) + `onSuccess` (fechar dialog, resetar).
+- Erro **com** `fieldErrors`: cada campo volta ao formulário por `setError`, sem toast. Erro **sem** `fieldErrors`: toast com a mensagem já traduzida pelo service (ou `formError` dentro do dialog).
+- Formulário em dialog: `FormDialog` do DS.
+- Rascunho sobrevive à rejeição: confira no navegador que um `status: 'error'` não limpa o que o usuário digitou.
+- Ação que muda a tarefa do usuário (cadastro concluído) troca o formulário pela confirmação, em vez de toast.
+
+## Ação destrutiva
+
+- Confirmação com `AlertDialog` do DS: ícone + rótulo + consequência, `tone="danger"`, `pending` e `error={action.formError}` vindos do hook; o botão de confirmar é dono da pendência.
+- `onSuccess` fecha o diálogo; navegue só depois de `status: 'success'`.
+- Sem `redirect()` no service quando o chamador precisa fechar diálogo ou dar toast: retorne sucesso e navegue no client.
+- Texto do diálogo que depende de contagem guarda o valor na hora de abrir (depois do sucesso a lista encolhe e o texto mudaria fechando).
+
+## Ação que desmonta a própria ilha
+
+Quando o sucesso remove a linha, o item ou o botão que disparou a ação (encerrar, remover da lista, moderar e sair da fila), um `useServerAction` no botão desmontaria antes de anunciar o resultado e fechar o diálogo. Duas saídas:
+
+1. **Provider de ações que fica montado:** a ilha `<bloco>-actions.client.tsx` envolve a lista, guarda o alvo e os `AlertDialog`, e chama `useServerAction`; cada linha só abre a confirmação pelo contexto (`askRemove({ id, name })`).
+2. **Hook de ação destacada** (`useDetachedAction` na referência): o aviso vai para o provider de feedback global, que sobrevive à ilha.
+
+Fora desse caso, `useServerAction` na própria ilha.
+
+---
+
+## Pendência e otimista
+
+| Situação | Use | Regra |
+|---|---|---|
+| Mutação que quase nunca falha (favoritar, alternar) | `useOptimistic` | atualiza já, reverte no erro; dentro da mesma transição do `run` |
+| Sem encaixe otimista (filtro, ordenação, navegação) | `useTransition` + `data-pending` | o nó pendente marca `data-pending`; ancestrais reagem por CSS (`group-has-data-pending:`) |
+| Erro que só o servidor encontra | `useServerAction` | erro no campo com `aria-invalid` + `role="alert"` |
+| Seleção que vive na URL | `useOptimistic(draft)` + `router.replace` em `startTransition` | a URL é a fonte; o rascunho mantém o controle responsivo |
+
+- Todo clique que inicia escrita ou navegação mostra a pendência **no que foi clicado**, sem mexer no layout (indicador de tamanho fixo).
+- Mais de uma fonte de pendência na mesma subárvore: nomeie o sinal (`data-filtering`, `data-saving`).
+- Lista com criar, editar e excluir: um reducer otimista por lista, com nome do domínio, em vez de pendências espalhadas.
+- Controle deriva do valor otimista; moldura ao redor, do valor confirmado.
+- Falha esperada é inline, na linha de status; toast é para falha sem lugar no layout.
+
+## Toast
+
+| Caso | Toast? |
+|---|---|
+| UI otimista ou dado revalidado já mostra o resultado | só no erro |
+| Efeito sem resultado visível (e-mail enviado, link copiado, export iniciado) | sim, no sucesso |
+| Navegação | não: a troca de página é o feedback |
+| Dentro do service ou em render server | nunca: o service retorna `Action.Result`, o toast é do hook |
+
+## Busca e filtro
+
+- O recorte vive na URL; filtro não é motivo para `'use client'` na página, só o controle é ilha.
+- Default vem da URL (o estado de URL do repo: nuqs ou `URLSearchParams`); o `<form>` de busca vive na moldura, fora da boundary do `searchParams`, com `key={params.toString()}`.
+- Submit em transição: `startTransition(() => router.replace(href, { scroll: false }))`; `replace`, não `push`; trocar filtro reseta a página.
+- Resultado atual esmaece (`data-pending` + `transition-opacity`); o `key` do `<Suspense>` da lista evita mostrar dado velho como novo.
+- Filtros em diálogo entram por `<bloco>.loader.tsx` (`next/dynamic`), montados só quando abrem.
+- Seleção de linhas é estado local; "selecionar todos" envia o **filtro**, não os ids.
+- Cinco estados: carregando · vazio · sem resultado de filtro (texto diferente de vazio) · erro · sem permissão.
+
+---
+
+## Componentes do DS
+
+- Componente de `shared/ui/components/<nome>/` é um **namespace de átomos**: `index.tsx` (só agrupa e reexporta, nunca `'use client'`) + `props.ts` (`data-tag`) + `atoms/<grupo>/<parte>.tsx` + `hooks/`. O consumidor compõe (`<Chip.Root>`, `<PageHeader.Title>`) importando do index.
+- `className` mescla com `cn()`; variantes por CVA (forma do componente na tabela Nomes da SKILL).
+- `'use client'` só no átomo que chama hook, cria handler ou importa biblioteca client; átomo que só repassa props fica sem diretiva (a proporção de arquivos client entra no orçamento de bundle).
+- Peça pré-composta (`TextField.Field`, `AlertDialog.Dialog`, `FormDialog`) só existe com repetição real; o resto é composição no consumidor.
+- Campo que o DS já resolve (escolha com busca, dinheiro, nota) vem do DS; o consumidor não monta à mão.
+- Componente do DS não conhece feature: não importa Server Action. Quando coordena uma mutação (otimista, pendência), recebe a prop `action`/`<x>Action` e o bloco passa a Server Action; `onChange`/`onClick` é callback comum.
+- Norma, anatomia do átomo e checklist: README do DS do repo.
+
+## Tokens semânticos
+
+- A regra 18 da SKILL vale para todo `className`, inclusive valor arbitrário (`bg-[#…]`); o guard de cor crua confere.
+- Par de contraste vem do DS (`bg-accent` com `text-content-onaccent`); não sobrescreva localmente.
+- Valor dinâmico de runtime entra como custom property no `style` e a classe lê a variável; valor estático é classe.
+
+## Texto em ilha (se o repo tem i18n)
+
+- A regra 19 da SKILL vale também para `aria-label`, placeholder e nome acessível.
+- Por que a fatia (`token-slices/<ns>`) em todo código alcançável de `'use client'`: o objeto completo não sofre tree-shaking por propriedade e pesa em toda rota. `import type` do tipo do token é livre.
+- Ilhas com texto ficam sob `<I18nScope namespaces={…}>`, e a página passa só os namespaces dela.
+- Erro da API chega traduzido pelo service; a ilha não traduz mensagem de API.
+- `Intl` com locale explícito (helpers de formatação do i18n do repo).
+
+## Estado global client
+
+Provider `'use client'` só para estado efêmero de UI (menu aberto, drawer, rascunho otimista), com `children` server. Dado do servidor nunca entra em contexto client; store global só para estado de fato compartilhado.