# Impl: Falas longas entram no acervo sem estourar o limite do texto normalizado Status: aprovado Atualizado em: 2026-09-25 Issue: #1337 Intenção: `docs/plans/falas-web-texto-normalizado-limite.md` Appetite restante: ~0,5 dia; alteração de validação coberta por regressões de persistência, retry e busca Impeccable: A — N/A Design UI: N/A ## Leitura da intenção - **Outcome:** uma transcrição longa, inclusive uma fala web de aproximadamente três horas, entra inteira no acervo, continua pesquisável do começo ao fim e pode ser reingerida sem duplicar registros. - **O que não negociar:** não truncar; não rejeitar por tamanho de transcrição; não esconder falhas físicas; não alterar busca, facetas, paginação, rotas ou contrato público; não alterar access, segurança ou Consent. - **O que reavaliar:** a hipótese de que bastariam os cinco `searchText`; a segurança de elevar o default global; a extensão dos campos brutos; a ausência de migration SQL. - **Decisão de escopo:** corrigir os campos de texto que participam da transcrição do acervo. Reutilizar a normalização, o upsert transacional, o relatório e os loaders existentes. ## Estado técnico confirmado - `normalizeForSearch` em `src/lib/speechSearch.ts:8-15` normaliza acentos, caixa e espaços sem cortar ou resumir. - O Payload usa `defaultMaxTextLength = 40000` para `text`/`textarea` sem `maxLength`; um `maxLength` explícito substitui esse default (`node_modules/payload/dist/config/defaults.js:48` e `node_modules/payload/dist/fields/validations.js:24-35`). - O upsert de Câmara/web em `src/utilities/speech/speechImport.ts:226-320` deriva o texto normalizado dos segmentos e grava fala e segmentos na mesma transação. - O caminho de recordings grava `Recording.searchText` e cria `RecordingSegment` em `src/utilities/recordings/recordingJob.ts:294-332`. - `ContentPiece` deriva `searchText` no hook em `src/collections/ContentPiece.ts:171-237`. - A busca de Speech usa `searchText` com `LIKE` em `src/utilities/speech/speechListFilters.ts:65-108` e já usa o índice GIN trigram; não precisa mudar. - As colunas PostgreSQL relevantes são `varchar` sem comprimento declarado, então a correção é de validação da aplicação, não de SQL. - Os testes existentes de `speechImport` e `speechAcervo` cobrem persistência e busca com textos curtos, mas não atravessam o limite de 40 000. ## Abordagem recomendada ```mermaid flowchart LR A[ASR ou texto bruto] --> B[normalizeForSearch sem corte] B --> C[upsertSpeechBundle] C --> D[(speech + speechSegment)] C --> E[RecordingSegment ou ContentPiece] D --> F[searchText completo] E --> F F --> G[LIKE + índice GIN existente] G --> H[Termo do fim encontra a fala] C --> I[Retry com o mesmo sourceKey] I --> J[Atualização idempotente] C --> K[Falha física ou de provider] K --> L[Falha visível no relatório] ``` **Opções consideradas:** A | B | C | D **Recomendação:** **C — declarar um `maxLength` explícito e efetivamente ilimitado nos campos brutos de transcrição e nos cinco `searchText`; manter o default global em 40 000.** O valor deve ser uma constante compartilhada, `TRANSCRIPT_TEXT_MAX_LENGTH = Number.MAX_SAFE_INTEGER`, no owner existente `src/lib/speechSearch.ts`. O valor funciona como sentinel de validação, não como uma nova política de negócio: não cria uma fronteira artificial para transcrições, continua deixado ao limite físico do runtime/banco/storage, e falhas físicas continuam passando pelo relatório existente. **Alternativas rejeitadas:** - **A — elevar `defaultMaxTextLength`:** alteraria todos os `text`/`textarea` sem limite explícito, globs e formulários, ampliaria demais o risco de payloads enormes e mascararia limites de outros domínios. - **B — elevar somente os cinco `searchText`:** deixaria os campos brutos com o teto de 40 000; uma transcrição longa ainda poderia ser rejeitada antes do texto derivado. - **D — corrigir apenas o import web ou um hook condicional por origem:** os owners são compartilhados por Câmara/web, recordings e Central; a validação do schema mantém o mesmo teto e os caminhos divergem. ### Matriz de campos | Collection | Campo | Tipo | Motivo | | ------------------ | -------------------- | ---------- | --------------------------------- | | `speech` | `officialTranscript` | `textarea` | Transcrição bruta do catálogo. | | `speech` | `searchText` | `textarea` | Concatenação pesquisável da fala. | | `speechSegment` | `text` | `textarea` | Texto bruto de um segmento. | | `speechSegment` | `searchText` | `text` | Derivado normalizado do segmento. | | `recording` | `searchText` | `textarea` | Texto agregado pesquisável. | | `recordingSegment` | `text` | `textarea` | Texto bruto do segmento. | | `recordingSegment` | `searchText` | `text` | Derivado normalizado do segmento. | | `contentPiece` | `transcript` | `textarea` | Texto/transcrição da peça. | | `contentPiece` | `searchText` | `textarea` | Haystack derivado da peça. | Campos de resumo, erro, palavras-chave, Consent, Reel e demais formulários permanecem intocados: não são a transcrição pesquisável do acervo e devem conservar seus limites atuais. ## Componentes / mudanças - **`src/lib/speechSearch.ts`:** adicionar `TRANSCRIPT_TEXT_MAX_LENGTH`; não alterar a normalização. - **`src/collections/Speech.ts`:** aplicar a constante a `officialTranscript` e `searchText`. - **`src/collections/SpeechSegment.ts`:** aplicar a constante a `text` e `searchText`. - **`src/collections/Recording.ts`:** aplicar a constante a `searchText`. - **`src/collections/RecordingSegment.ts`:** aplicar a constante a `text` e `searchText`. - **`src/collections/ContentPiece.ts`:** aplicar a constante a `transcript` e `searchText`. - **`src/lib/schemas/contentPiece.ts`:** usar a mesma constante no schema da ficha, para que a action não mantenha um teto de 200 000 caracteres diferente do campo. - **`src/utilities/speech/speechImport.ts`, `webSpeechIngest.ts` e `speechListFilters.ts`:** sem mudança de comportamento; o upsert, o relatório e a busca existentes são reutilizados. - **Migration:** nenhuma alteração SQL esperada; as colunas já são `varchar` sem limite. Não editar migrations, `payload-types.ts` ou `importMap.js`. Se a verificação de migration indicar alteração de banco, parar e revisar antes de prosseguir. - **Access / Consent:** nenhuma alteração. - **UI:** Impeccable A — nenhuma tela, componente, rota ou designer. ## Fases verificáveis 1. **Contrato e regressão principal:** criar teste de integração no caminho web com três segmentos individuais abaixo de 40 000 cujo agregado ultrapasse 40 000, incluindo um marcador apenas no último segmento. O teste deve provar persistência completa e nova execução com o mesmo `sourceKey` sem duplicar fala, segmentos ou mídia. 2. **Busca e campos irmãos:** provar no loader do acervo que o marcador final encontra a fala; adicionar cobertura de persistência para `officialTranscript`, `SpeechSegment.text`, `RecordingSegment.text`, `Recording.searchText`, `ContentPiece.transcript` e `ContentPiece.searchText` quando o teste existente permitir. Fixar que `defaultMaxTextLength` continua 40 000 e que os campos não relacionados mantêm seus limites. 3. **Configuração mínima:** aplicar a constante somente aos nove campos da matriz e rodar os testes alterados, `pnpm gate:fast` e os demais gates do repositório. 4. **E2E local afetado:** rodar os specs de `campaignSpeechAcervo`/superfície web que o classificador considerar afetados, se houver benefício além dos testes de integração. 5. **Changelog e fechamento:** registrar `docs/changelog/2026-09-25-c223.md`, revisar o diff, usar `pnpm push` e abrir PR Ready com `Closes #1337`; não executar o lote de produção nesta entrega. ## Rabbit holes / Não escopo de engenharia - Subir apenas o default global. - Truncar em 40 000, mesmo com registro. - Alterar `speechListFilters`, GIN, facetas, ordenação ou URL. - Criar collection, campo, relatório, tela ou status `truncated`. - Reindexar dados históricos; a falha impedia a criação, portanto o retry do lote pendente basta. - Alterar access, overrideAccess, segurança ou Consent. - Ampliar campos de resumo/erro ou domínios sem relação com transcrição. - Adicionar limite concreto sem evidência operacional; se surgir, deve ser issue separada com contagem e motivo no relatório. ## Riscos e mitigação - **Volume de memória, payload e índice:** os textos já são normalizados e persistidos uma vez; manter os processamentos e índices existentes e observar o lote real antes de criar nova estratégia. - **Limite físico residual:** Node, PostgreSQL, storage ou provider podem falhar; não truncar e deixar o fluxo existente reportar `sourceKey`, estágio e erro. - **Campo esquecido:** a matriz de nove campos e os testes de persistência impedem uma segunda barreira de 40 000. - **Retry:** reutilizar a transação e o `sourceKey` atuais; o teste prova identidade e contagem de segmentos. - **Divergência com escopo:** revisar que busca, facetas, URLs, access, migrations e UI não foram alterados. ## Aceite de engenharia - [ ] A fala de teste tem segmentos individuais abaixo de 40 000 e `searchText` agregado acima de 40 000. - [ ] A transcrição e o marcador final são persistidos integralmente. - [ ] A busca pelo marcador final retorna a fala. - [ ] O retry com o mesmo `sourceKey` não duplica registros nem artefatos. - [ ] Os nove campos da matriz aceitam o texto completo; campos não relacionados mantêm seus limites. - [ ] `defaultMaxTextLength` continua 40 000. - [ ] Nenhum texto é truncado; falhas físicas continuam visíveis no relatório. - [ ] Nenhuma migration, alteração de tipos/importMap, busca, rota ou UI é introduzida. - [ ] Testes relevantes, `pnpm gate:fast`, gates completos e build estão verdes. ## Triagem pós-simplify ### Já resolvido no simplify (não reabrir) - P2: pin explícito do default `40 000` e de campo não relacionado. - P2: comparação exacta de todos os segmentos, `searchText` e preservação de conteúdo/mídia no retry. - P2: schema da ficha de `ContentPiece` alinhado à constante dos campos de transcrição. ### Explicitamente fora - P3: assertion de `excerpt` no teste de busca foi removida por ser redundante e acoplada ao view model; o marcador e a presença da fala já provam o contrato. - Nenhum novo lote, Issue ou follow-up deferido: não há débito caro remanescente. ## Self-score — decision-quality | Critério | Nota | Justificativa | | -------------------------------- | ---: | ------------------------------------------------------------------------------------------- | | Decisões caras têm rejeitadas? | 5/5 | Global, cinco campos, escopo por origem e truncamento foram comparados. | | A abordagem cabe no appetite? | 5/5 | É configuração de nove campos mais regressões focadas, sem pipeline novo. | | Rabbit holes nomeados? | 5/5 | Busca, migration, relatório, reindexação, UI e domínios não relacionados foram delimitados. | | Depth check: reusa donos? | 5/5 | Reutiliza a constante de busca, upsert, hooks, loaders, índice e relatório existentes. | | A intenção permanece satisfeita? | 5/5 | Texto inteiro, busca ponta a ponta, retry e falhas honestas permanecem cobertos. | **Self-score total: 25/25 — 5/5. Gate `>= 4/5`: aprovado.**