funifier-mcp 0.2.25 → 0.2.27

package/datasource-funifier-docs/knowledge/modules/story.md

@@ -1,42 +1,578 @@
-# Story (História)
+# `story`
 
-**Acesso Studio:** `/studio/story`
-**API Endpoint:** `/v3/story`
+**Acesso Studio:** `/studio/story` _(convenção de frontend — **não há nenhuma referência a `/studio/story` no `funifier-service`**; a tela é servida por outro repositório)_
+**API Endpoint:** `/v3/story/*` (apenas endpoints especiais de IA + cascade delete) **+** CRUD genérico via `/v3/database/{story|story_character|story_scene}`
+**Coleções MongoDB:** `story`, `story_character`, `story_scene` (+ gravação derivada na coleção `upload`)
 
-## O que é
+> **Origem desta documentação:** engenharia reversa de `com.funifier.rest.v3.rest.StoryRest` (`src/main/java/com/funifier/rest/v3/rest/StoryRest.java`, 1380 linhas) e da referência cruzada em `AIRest.buildStory`. Todo comportamento descrito foi confirmado lendo o código-fonte real. Quando algo **não foi encontrado**, isso está dito explicitamente.
 
-Criação de histórias interativas com múltiplos caminhos e finais. Permite criar narrativas gamificadas nas quais o jogador faz escolhas que afetam o desenrolar da trama. Cenários, personagens, imagens e vídeos podem ser utilizados para enriquecer a experiência.
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Para treinamentos baseados em storytelling
-- Para campanhas de marketing com desfechos alternativos
-- Para jogos educacionais interativos
-- Para experiências de role-playing
+O módulo `story` é uma **camada fina de aumento por IA** sobre três coleções MongoDB **sem schema no servidor**: `story`, `story_character` e `story_scene`. Ele implementa o backend de um editor de **histórias visuais interativas** (visual novel / branching story): cenas encadeadas, cenas de decisão com pontuação, finais alternativos, personagens com voz, e mídia (imagem/vídeo/áudio) gerada por IA.
 
-## Checklist de Configuração no Studio
+Papel arquitetural — **atípico** em relação aos demais módulos da plataforma:
 
-- [ ] Definir título e descrição da história
-- [ ] Criar cenários/cenas com textos e mídias
-- [ ] Definir ramificações e escolhas
-- [ ] Configurar finais alternativos
+- **Não existe entidade, manager, service ou repository dedicados.** Não há classe `Story`, `StoryManager`, `StoryService` nem `StoryDao`/`StoryRepository` no projeto. Confirmado por busca (`grep -r 'class Story|StoryManager|StoryService' src/`): o único arquivo com `Story` no nome é `StoryRest.java`.
+- **O CRUD (criar/ler/atualizar) dos documentos é feito pelo endpoint genérico** `/v3/database/{collection}` (`com.funifier.rest.v3.rest.DatabaseRest`), exatamente como qualquer coleção custom da plataforma. `StoryRest` **não** expõe `POST /v3/story` nem `GET /v3/story`.
+- `StoryRest` adiciona **apenas** operações que não cabem no CRUD genérico: cascade delete e geração de conteúdo por IA (imagem de cena, retrato de personagem, capa, áudio TTS de diálogo, prévia de voz, estrutura de cenas via GPT e vídeo via Sora/Freepik).
+- As coleções são **schema-less**: os documentos são gravados pelo frontend via `/v3/database/*` com a forma que o frontend quiser. O backend só **lê campos específicos** (ver seção 3) e, em pontos pontuais, **escreve** apenas os campos `video`, `media`, `media_mode` e `dialogues[i].word_timestamps` em `story_scene`.
 
-## API Endpoints
+Problemas que resolve:
 
-### Listar Stories
-**Método:** GET
-**Endpoint:** `/v3/story`
+- Persistir e versionar uma história ramificada (cenas, decisões, finais) sem precisar de schema rígido.
+- Orquestrar chamadas a APIs externas de IA (OpenAI Images, OpenAI TTS, OpenAI Whisper, OpenAI Sora 2 e — desabilitado — Freepik) e **persistir o resultado** no storage do tenant (S3/Azure/Google) e nos documentos de cena.
+- Gerar automaticamente a estrutura narrativa (cenas + decisões + finais) a partir de um objetivo, via function-calling do GPT.
 
-### Criar Story
-**Método:** POST
-**Endpoint:** `/v3/story`
+Relação com outros componentes:
 
-### Deletar Story
-**Método:** DELETE
-**Endpoint:** `/v3/story/:id`
+- `AIService` (`com.funifier.engine.system.ai.AIService`) — token e helpers OpenAI (`generateImage`, `chatCompletionWithFunction`, constante `CHATGPT_TOKEN`, `MODEL_GPT_IMAGE_1`).
+- `S3Service` / `AzureService` / `GoogleService` — destino do upload conforme `Configuration.getCurrentConfiguration().getCloud()`.
+- Coleção `upload` (`Entity.UPLOAD.collection`) — `saveImageUpload` grava um registro de upload **apenas para imagens** (não para áudio nem vídeo).
+- `DatabaseRest` (`/v3/database`) — caminho real de CRUD das três coleções.
+- `AIRest.buildStory` (`/v3/ai/build/story`) — helper **legado** que gera uma história em **formato de objeto totalmente diferente** (ver seções 4 e 7); **não** compartilha schema com `StoryRest`.
+- **Não dispara triggers nem webhooks.** Nenhuma chamada a `Trigger`, `before_*`/`after_*` ou notificação foi encontrada em `StoryRest`.
 
-## Validações e Testes
+---
 
-- [ ] História aparece na lista
-- [ ] Navegação entre cenários funciona
-- [ ] Escolhas do jogador são registradas
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe / arquivo | Papel |
+|---|---|
+| `com.funifier.rest.v3.rest.StoryRest` | **Único** controller do módulo (`@Path("v3/story")`). Cascade delete + 10 endpoints de IA/diagnóstico. |
+| `com.funifier.rest.v3.rest.DatabaseRest` (`@Path("v3/database")`) | CRUD genérico real das coleções `story`, `story_character`, `story_scene`. |
+| `com.funifier.engine.system.ai.AIService` | Integração OpenAI (token, geração de imagem, chat com function-calling). |
+| `S3Service` / `AzureService` / `GoogleService` | Persistência de binários (imagem/áudio/vídeo) por tenant. |
+| `com.funifier.engine.guid.Guid` | Geração de `_id`/nome de arquivo (`newShortGuid`). |
+| `com.funifier.rest.v3.rest.AIRest` (`@Path` em `/v3/ai`) | Endpoint legado `buildStory` (`/build/story`) — formato distinto. |
+
+> **Ausências confirmadas (não fitar no template à força):** não há `Story` (entidade/POJO), `StoryManager`, `StoryService`, `StoryRepository`/`StoryDao`, scheduler/job dedicado, enum `Entity.STORY`, nem pipeline MongoDB pré-cadastrado. A manipulação Mongo é feita **inline via Jongo** dentro de `StoryRest`, sempre com queries parametrizadas (`"{_id: #}"`, `"{story_id: #}"`).
+
+### 2.2 Modelo de persistência
+
+```mermaid
+erDiagram
+    story ||--o{ story_character : "story_id"
+    story ||--o{ story_scene : "story_id"
+    story_scene }o--|| upload : "imagens geram registro em upload"
+    story {
+        string _id
+        string title
+        string genre
+        string synopsis
+        string aspect_ratio
+        bool   subtitle_karaoke
+    }
+    story_character {
+        string _id
+        string story_id
+        string name
+        string description
+        string voice_profile
+    }
+```
+
+- Conexão é resolvida por tenant: `FrontController.getInstance(authBean.getApiKey()).getManagerFactory().getJongoConnection()`. **O isolamento multi-tenant é pela API key → conexão Jongo do tenant** (cada tenant tem seu próprio banco). Não há campo de tenant dentro do documento.
+- `story_character.story_id` e `story_scene.story_id` são **strings que referenciam `story._id`**. A integridade é mantida apenas pelo cascade delete (seção 2.7) — não há foreign key real.
+
+### 2.3 Pipeline — geração de estrutura de cenas (`generateSceneStructure`)
+
+`POST /v3/story/{id}/scene/structure`. Síncrono. Usa GPT com function-calling.
+
+```
+[1] Lê story (title, synopsis, genre) e todos os story_character do story_id.
+[2] Lê parâmetros: mode (full|continue), objective, num_scenes (def 6),
+    num_decisions (def 2), num_endings (def 1*), continuation_prompt.
+    (* o JavaDoc diz "num_endings: 2", mas o código usa default 1 — linha 571)
+[3] buildStructureSystemPrompt(...) monta o prompt-sistema com as REGRAS de ref/type.
+[4] buildStructureUserPrompt(...) monta o pedido conforme o mode.
+[5] Declara a Function 'generate_story_structure' com UM único parâmetro
+    'scenes_json' do tipo STRING (não array — ver "Comportamento real" abaixo).
+[6] Aumenta o socket timeout do Unirest para 8 min (480_000ms) só nesta chamada,
+    restaurando 180_000ms no finally.
+[7] AIService.chatCompletionWithFunction(system, user, function) → argsJson.
+[8] Faz parse de argsJson; extrai scenes_json. Se vier String → reparseia como List;
+    senão usa como List direto (tolera ambas as formas).
+[9] Retorna { "scenes": [...] }. NÃO PERSISTE nada — apenas devolve a estrutura.
+```
+
+**Comportamento real:** o parâmetro da function é declarado como `type("string")` de propósito — comentário no código (linha 577-578): _"type:array is not properly serialized by ChatCompletionRequest.Parameter builder"_. Por isso o GPT devolve um JSON-string que precisa ser reparseado.
+
+Forma de cada cena retornada (definida no `description` da property — linha 586):
+
+- `ref` (string, ex.: `C0`, `C1`, `C2A`) — identificador único da cena
+- `title` (string)
+- `type`: `scene` | `decision` | `end`
+- `description` (string)
+- `next_scene_ref` (string) — **apenas** `type=scene`
+- `end_label` (string), `end_score` (number) — **apenas** `type=end`
+- `decision` (object `{ prompt, options[] }`) — **apenas** `type=decision`; cada `option` = `{ label, score (number), next_scene_ref }`
+
+### 2.4 Pipeline — geração de vídeo (assíncrono, 2 etapas)
+
+Etapa 1 — disparo (`generateSceneVideo`, `POST .../generate-video`):
+
+```mermaid
+flowchart LR
+    A[POST generate-video] --> B{Resolve image_url}
+    B -->|1. request.image_url| C[image_url ok]
+    B -->|2. scene.image_url| C
+    B -->|3. scene.media.url se media.type=image| C
+    B -->|nenhum| E[400 image_url is required]
+    C --> F{model == sora-2 ?}
+    F -->|nao e FREEPIK_ENABLED=false| G[400 requer Freepik]
+    F -->|sora-2| H[dispatchSoraVideo]
+    F -->|outro e Freepik ON| I[dispatchFreepikVideo]
+    H --> J[salva scene.video = pending]
+    I --> J
+    J --> K[retorna job_id + status pending]
+```
+
+```
+[1] Carrega story_scene por sceneId (404 se ausente).
+[2] Resolve image_url por prioridade: request.image_url → scene.image_url
+    → scene.media.url (somente se scene.media.type == "image").
+    Se nenhum → 400 "image_url is required. Generate or upload a scene image first."
+[3] Lê story.aspect_ratio (def "16:9").
+[4] Lê model (def "veo-3-fast"), quality (def "high"), prompt (def ""),
+    end_image_url, duration_sec (def 6), generate_audio (def true*).
+    (* generate_audio só é false se vier explicitamente Boolean.FALSE)
+[5] SE model != "sora-2" E FREEPIK_ENABLED == false → 400 (Freepik desabilitado).
+    -> Na prática, com o default "veo-3-fast", a chamada SEM informar model FALHA.
+[6] sora-2 → dispatchSoraVideo(...); senão → dispatchFreepikVideo(...).
+[7] Grava em scene.video = { job_id, status:"pending", model, quality, has_native_audio }
+    e salva o documento.
+[8] Retorna { job_id, status:"pending", model } imediatamente (não bloqueia).
+```
+
+Etapa 2 — polling (`checkSceneVideoJob`, `GET .../video-job`):
+
+```mermaid
+stateDiagram-v2
+    [*] --> none: scene.video ausente
+    none --> pending: generate-video dispara job
+    pending --> pending: API ainda processando
+    pending --> completed: API devolve completed
+    pending --> failed: API devolve failed/errored
+    completed --> completed: estado em cache (nao reconsulta)
+    failed --> failed: estado em cache (nao reconsulta)
+```
+
+```
+[1] Carrega scene (404 se ausente).
+[2] Se scene.video ausente → { status:"none" }.
+[3] Se status já é completed/failed OU job_id == null → retorna estado em cache
+    (não reconsulta a API externa).
+[4] Senão consulta a API: sora-2 → checkSoraVideo(jobId); outro → checkFreepikVideo.
+[5] SE completed:
+      videoUrl = checkResult.video_url
+      SE videoUrl vazio (caso Sora) → downloadAndSaveSoraVideo(jobId) baixa de
+        /v1/videos/{id}/content e salva no CDN (URL da OpenAI expira em ~1h).
+      Atualiza scene.video.url/status/duration_sec,
+      scene.media_mode = "video",
+      scene.media = { type:"video", url, duration } e SALVA.
+    SE failed: grava scene.video.status = "failed" e salva.
+    SENÃO: { status:"pending" } (sem persistir).
+```
+
+Pseudocódigo da cadeia de fallback de URL do Sora (`checkSoraVideo`, linhas 1127-1147) — a resposta da OpenAI varia entre versões:
+
+```
+videoUrl = json.url
+se vazio: videoUrl = json.data[0].url
+se vazio: videoUrl = json.result.url
+se vazio: videoUrl = json.output[0].url
+se vazio: videoUrl = json.video.url
+se ainda vazio: (etapa 2) baixa o binário de /v1/videos/{id}/content e salva no CDN
+```
+
+### 2.5 Pipeline — TTS de diálogo + Whisper karaokê (`generateDialogueTts`)
+
+`POST /v3/story/{storyId}/scene/{sceneId}/dialogue/{dialogueIndex}/tts`. Síncrono.
+
+```
+[1] Lê text (obrigatório → 400 se vazio) e voice (def "alloy").
+[2] POST OpenAI /v1/audio/speech { model:"tts-1", input:text, voice, response_format:"mp3" }.
+    (atenção: o comentário do método diz "tts-1-hd", mas o código envia "tts-1")
+[3] Se HTTP != 200 → RuntimeException com corpo do erro.
+[4] Lê os bytes do MP3.
+[5] SE story.subtitle_karaoke == true → callWhisperWordTimestamps(mp3Bytes)
+    (best-effort: qualquer exceção é capturada e logada em stderr; NÃO falha o request).
+[6] Salva o MP3 no storage do tenant (session "story_audio") via S3/Azure/Google.
+[7] SE houve word_timestamps → updateDialogueWordTimestamps grava
+    scene.dialogues[dialogueIndex].word_timestamps (re-lê a cena, muta e salva).
+[8] Retorna { url, word_timestamps? }.
+```
+
+`callWhisperWordTimestamps`: `POST /v1/audio/transcriptions` com `model=whisper-1`, `response_format=verbose_json`, `timestamp_granularities[]=word`, `language=pt`. Retorna lista de `{ word, start, end }`.
+
+### 2.6 Pipeline — geração de imagem (cena / personagem / capa)
+
+Três endpoints (`generateSceneImage`, `generateCharacterImage`, `generateStoryCover`) seguem o mesmo padrão, variando apenas o prompt e o `aspect_ratio`:
+
+```
+[1] Lê documentos de contexto (story e/ou story_character).
+[2] Monta prompt em PT-BR concatenando título/gênero/sinopse/personagens + prompt do usuário.
+[3] generateImageBytes(prompt, reference_image_urls, aspectRatio):
+      SE não há reference_image_urls → AIService.generateImage(prompt, sizeGenerations)
+        (OpenAI /v1/images/generations, modelo padrão do AIService)
+      SENÃO → baixa cada imagem de referência (fetchImageBytes) e chama
+        /v1/images/edits (multipart, model = gpt-image-1, n=1) usando-as como referência.
+        Se o download de TODAS as refs falhar → cai no caminho text-only.
+[4] saveImageUpload(bytes, prefix, session): salva o PNG no storage E cria um
+    registro na coleção `upload` (_id, filename, content_type, size, time + campos do cloud).
+[5] Retorna { url, upload }.
+```
+
+| Endpoint | `aspect_ratio` usado | session de storage | prefixo do arquivo |
+|---|---|---|---|
+| `generateSceneImage` | `story.aspect_ratio` (def 16:9) | `story_scenes` | `story-scene-` |
+| `generateCharacterImage` | **fixo `1:1`** | `story_characters` | `story-char-` |
+| `generateStoryCover` | `story.aspect_ratio` (def 16:9) | `story_covers` | `story-cover-` |
+
+Tabelas de tamanho (helpers em `StoryRest`):
+
+| aspect_ratio | `/images/generations` e `/edits` | Sora `high` | Sora `light` | Freepik enum |
+|---|---|---|---|---|
+| `16:9` | `1536x1024` | `1920x1080` | `1280x720` | `widescreen_16_9` |
+| `9:16` | `1024x1536` | `1080x1920` | `720x1280` | `social_story_9_16` |
+| `1:1`  | `1024x1024` | `1080x1080` | `720x720` | `square_1_1` |
+
+### 2.7 Cascade delete (`deleteStory`)
+
+`DELETE /v3/story/{id}` executa, **em ordem**, três `remove` Jongo parametrizados:
+
+```
+db.story_character.remove({ story_id: id })
+db.story_scene.remove({ story_id: id })
+db.story.remove({ _id: id })
+→ 204 No Content
+```
+
+Sem transação (Mongo standalone): se falhar no meio, pode deixar órfãos. As subcoleções são apagadas **antes** do documento raiz.
+
+### 2.8 Diagnóstico OpenAI
+
+- `probeOpenAiVideo` (`POST /v3/story/openai/video-probe`): tenta `POST` em `https://api.openai.com/v1/videos` e `/v1/video/generations` com um corpo de teste; para no primeiro retorno != 404; devolve status+body bruto de cada tentativa.
+- `listOpenAiModels` (`GET /v3/story/openai/models`): lista modelos da conta filtrando por `sora`/`video`/`dall`; retorna `sora_accessible` e contagem total.
+
+Ambos servem para diagnosticar acesso da API key da OpenAI — não tocam nas coleções.
+
+---
+
+## 3. Estrutura dos Objetos
+
+> **Aviso crítico:** **não existe schema no servidor.** As tabelas abaixo são **inferidas dos campos que o código realmente lê/escreve** em runtime. Qualquer outro campo gravado pelo frontend via `/v3/database/*` é persistido tal qual e **ignorado pelo backend**. A coluna **Acesso backend** indica se `StoryRest` apenas lê (R) ou também escreve (W) o campo.
+
+### 3.1 `story` — documento raiz
+
+| Campo | Tipo | Padrão (no read) | Acesso backend | Descrição |
+|---|---|---|---|---|
+| `_id` | String | gerado pelo cliente / `/v3/database` | R | Id da história. Referenciado por `story_id` nas subcoleções. |
+| `title` | String | `""` | R | Título; entra nos prompts de imagem e de estrutura. |
+| `genre` | String | `""` | R | Gênero; entra nos prompts. |
+| `synopsis` | String | `""` | R | Sinopse; entra no prompt de capa e de estrutura. |
+| `aspect_ratio` | String | `"16:9"` | R | `16:9` \| `9:16` \| `1:1`. Define o tamanho de imagem/vídeo de cena e capa. |
+| `subtitle_karaoke` | Boolean | `false` | R | Se `true`, o TTS de diálogo chama o Whisper para gerar `word_timestamps`. |
+
+Demais campos (capa, descrição, etc.) que o frontend persista **não são lidos** pelo backend.
+
+### 3.2 `story_character`
+
+| Campo | Tipo | Padrão (no read) | Acesso backend | Descrição |
+|---|---|---|---|---|
+| `_id` | String | cliente | R | Id do personagem. |
+| `story_id` | String | — | R | FK lógica para `story._id` (usada no cascade delete e na geração de estrutura). |
+| `name` | String | `""` / `"Personagem"` | R | Nome; entra no prompt de retrato e na prévia de voz. |
+| `description` | String | `""` | R | Descrição visual/narrativa; entra nos prompts. Na prévia de voz é truncada em 120 chars. |
+| `voice_profile` | String | `"alloy"` | R | Voz OpenAI padrão do personagem (fallback da prévia de voz). |
+
+### 3.3 `story_scene`
+
+| Campo | Tipo | Padrão | Acesso backend | Descrição |
+|---|---|---|---|---|
+| `_id` | String | cliente | R | Id da cena. |
+| `story_id` | String | — | R | FK lógica para `story._id` (cascade delete). |
+| `image_url` | String | — | R | URL da imagem da cena; pré-requisito para gerar vídeo. |
+| `media` | Object | — | R/**W** | `{ type, url, duration }`. **Escrito** quando o vídeo conclui (`type:"video"`). Também lido (`type:"image"`) para resolver `image_url` no vídeo. |
+| `media_mode` | String | — | **W** | Definido como `"video"` quando o vídeo conclui. |
+| `video` | Object | — | R/**W** | Estado do job de vídeo (ver 3.4). **Escrito** no disparo e no polling. |
+| `dialogues` | Array | — | R/**W** | Lista de diálogos da cena. O backend só escreve `dialogues[i].word_timestamps`. |
+
+Campos da **estrutura narrativa** (`ref`, `type`, `next_scene_ref`, `decision`, `end_label`, `end_score`, `title`, `description`) são **gravados pelo frontend** a partir do retorno de `generateSceneStructure` (seção 2.3) — o backend **não os lê nem valida** nos fluxos de mídia. Ver formato em 2.3.
+
+### 3.4 Subobjeto `story_scene.video`
+
+| Campo | Tipo | Origem | Descrição |
+|---|---|---|---|
+| `job_id` | String | dispatch | Id do job na API externa (Sora `id`, Freepik `task_id`). |
+| `status` | String | dispatch/polling | `pending` \| `completed` \| `failed`. (`none` é retornado quando o subobjeto não existe.) |
+| `model` | String | request | `sora-2` (único operacional) \| `veo-3-fast` \| `kling-3.0`. |
+| `quality` | String | request | `high` \| `light` (afeta o tamanho do vídeo Sora). |
+| `has_native_audio` | Boolean | dispatch | Se o modelo gera áudio nativo. |
+| `url` | String | polling | URL final (CDN, após download do Sora). |
+| `duration_sec` | Number | polling | Duração efetiva, quando informada. |
+
+### 3.5 Subobjeto `story_scene.media`
+
+`{ "type": "image"|"video", "url": "...", "duration": <number opcional> }`. O backend escreve este objeto na conclusão do vídeo; lê quando precisa achar a imagem de início do vídeo.
+
+### 3.6 `story_scene.dialogues[i].word_timestamps`
+
+Lista de `{ "word": String, "start": Number, "end": Number }`, em segundos, produzida pelo Whisper. Gravada **somente** quando `story.subtitle_karaoke == true` e o Whisper respondeu com sucesso.
+
+> **Não há enums numéricos nem "técnicas de jogo (GT)" neste módulo** — diferentemente de `achievement`/`challenge`. Os únicos conjuntos fechados de valores são strings: `type` da cena (`scene|decision|end`), `aspect_ratio` (`16:9|9:16|1:1`), `status` do vídeo (`pending|completed|failed`), vozes TTS (`alloy|echo|fable|onyx|nova|shimmer`) e `model` de vídeo.
+
+---
+
+## 4. Endpoints
+
+> Todos os endpoints exigem `Authorization: Bearer <token>` (via `@BeanParam AuthBean`). **Nenhum endpoint de `StoryRest` verifica scope ou role** — ver seção 8. Erros são sempre devolvidos como `{ "errorMessage": "..." }` (o handler nunca propaga exceção).
+
+### 4.0 CRUD (não é `StoryRest`)
+
+Criar/ler/atualizar `story`, `story_character`, `story_scene` usa o endpoint **genérico**:
+
+```
+GET    /v3/database/{collection}/{id}
+GET    /v3/database/{collection}?... (query/aggregate)
+POST   /v3/database/{collection}     (insert/save)
+PUT    /v3/database/{collection}/{id}
+DELETE /v3/database/{collection}/{id}
+```
+
+`DatabaseRest.find` exige o scope `SCOPE_DATABASE` e `collection.length() > 3` (todas as três coleções qualificam). É **full replace** no padrão do Funifier (o `save` substitui o documento).
+
+### 4.1 `DELETE /v3/story/{id}` — cascade delete
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Apagar a história e tudo que a referencia (`story_character`, `story_scene`). |
+| Autenticação | Bearer token (resolve o tenant). **Sem checagem de scope/role.** |
+| Tipo | Deleção em cascata, 3 `remove` sequenciais, sem transação. |
+| Resposta | `204 No Content`. |
+
+### 4.2 `POST /v3/story/{id}/scene/generate` — imagem de cena
+
+Body: `{ "scene_id": "...", "prompt": "...", "characters": [{name, description}], "reference_image_urls": ["url"] }`
+Resposta: `{ "url": "...", "upload": { ... } }`. Usa `story.aspect_ratio`. Com `reference_image_urls` → `/v1/images/edits`; sem → `/v1/images/generations`.
+
+### 4.3 `POST /v3/story/{storyId}/character/{charId}/generate-image` — retrato
+
+Body: `{ "prompt": "...", "reference_image_urls": ["url"] }`. **Aspect ratio fixo `1:1`.** 404 se o personagem não existe. Resposta `{ url, upload }`.
+
+### 4.4 `POST /v3/story/{id}/cover/generate` — capa
+
+Body: `{ "prompt": "...", "reference_image_urls": ["url"] }`. Usa `story.aspect_ratio`. Resposta `{ url, upload }`.
+
+### 4.5 `POST /v3/story/{storyId}/scene/{sceneId}/dialogue/{dialogueIndex}/tts` — áudio do diálogo
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `storyId` | path | Usado só para checar `subtitle_karaoke`. |
+| `sceneId` | path | Cena cujo diálogo recebe `word_timestamps`. |
+| `dialogueIndex` | path (int) | Índice em `scene.dialogues`. |
+
+Body: `{ "text": "...", "voice": "alloy|echo|fable|onyx|nova|shimmer" }`. `text` obrigatório (400 se vazio). Resposta: `{ "url": "...", "word_timestamps"?: [...] }`. **Comportamento real:** envia `model:"tts-1"` (o comentário do método cita `tts-1-hd`, mas não é o que roda).
+
+### 4.6 `POST /v3/story/{storyId}/character/{charId}/voice-preview` — prévia de voz
+
+Body: `{ "voice": "nova" }` (opcional; cai em `character.voice_profile`, depois `"alloy"`). Gera uma autoapresentação curta (`"Olá! Meu nome é {name}. {description[:120]}"`) e devolve `{ url }`. 404 se o personagem não existe.
+
+### 4.7 `POST /v3/story/{id}/scene/structure` — estrutura por GPT
+
+Body:
+```json
+{
+  "mode": "full",
+  "objective": "...",
+  "num_scenes": 6,
+  "num_decisions": 2,
+  "num_endings": 1,
+  "continuation_prompt": "...",
+  "from_scene_id": "..."
+}
+```
+Resposta: `{ "scenes": [ { "ref":"C0", "type":"scene|decision|end", ... } ] }`. **Não persiste** — o frontend é quem grava as cenas. Timeout estendido para 8 min nesta chamada. **Atenção:** `from_scene_id` aparece no JavaDoc mas **não é lido** no código (ignorado silenciosamente).
+
+### 4.8 `POST /v3/story/{storyId}/scene/{sceneId}/generate-video` — disparo de vídeo
+
+Body: `{ "model":"sora-2", "quality":"high|light", "duration_sec":6, "prompt":"...", "image_url":"...", "end_image_url":"...", "generate_audio":true }`. Async: devolve `{ job_id, status:"pending", model }`. **Requer uma imagem de início** (ver prioridade em 2.4). **Trap:** o default de `model` é `veo-3-fast`, que com `FREEPIK_ENABLED=false` retorna **400** — só `sora-2` funciona (informe-o explicitamente).
+
+### 4.9 `GET /v3/story/{storyId}/scene/{sceneId}/video-job` — polling
+
+Resposta: `{ status: "none|pending|completed|failed", video_url?, duration_sec?, error? }`. Em `completed`, persiste `scene.video.url`, `scene.media`, `scene.media_mode="video"`. Estados `completed`/`failed` ficam em cache (não reconsultam a API).
+
+### 4.10 Diagnóstico
+
+- `POST /v3/story/openai/video-probe` → `{ probes: [{url, http_status, response_body}] }`.
+- `GET /v3/story/openai/models` → `{ models: [...], total_models_in_account, sora_accessible }`.
+
+### 4.11 Legado — `POST /v3/ai/build/story` (em `AIRest`, **não** em `StoryRest`)
+
+Body: `{ "content": "<pedido em texto>", "current": <objeto opcional> }`. Usa GPT-3.5 + function `build_story` e devolve um JSON em **formato totalmente diferente** do `StoryRest` (objeto-mapa de cenas com `next_scenes[]`, personagens como objeto-mapa). **Não persiste nada.** Ver seção 7.
+
+---
+
+## 5. Regras de Negócio
+
+Regras que existem **no código** e não em nenhum schema:
+
+- **Pré-requisito de imagem para vídeo:** sem `image_url` resolvível → 400. A imagem do Sora é **redimensionada para o tamanho exato** do vídeo e enviada como `input_reference.image_url` (data URL base64).
+- **Snap de duração do Sora:** `seconds = min(duration_sec, 20)`, depois `snapSoraSeconds`: `<=6 → "4"`, `<=10 → "8"`, senão `"12"`. O `duration_sec` do cliente é **reescrito silenciosamente**.
+- **Áudio "silencioso":** se `generate_audio=false`, o backend **anexa ao prompt** o texto `" Silent video, no audio track."` (não desliga o áudio via parâmetro de API).
+- **Freepik desabilitado:** `FREEPIK_ENABLED=false` (constante). Qualquer `model != sora-2` → 400. Os caminhos `veo-3-1-fast`/`kling-v2-6-pro` são **código morto** no estado atual.
+- **Karaokê condicional:** Whisper só roda se `story.subtitle_karaoke==true`; falha de Whisper **não** quebra o TTS (best-effort, capturada).
+- **Voz default `alloy`** em TTS e prévia de voz quando não informada / `voice_profile` ausente.
+- **Multi-tenant por API key:** todo acesso resolve a conexão Jongo do tenant via `FrontController.getInstance(apiKey)`. Não há `_id` global cruzando tenants.
+- **`num_endings` default = 1** no código (apesar do JavaDoc dizer 2).
+- **Consistência eventual de mídia:** o vídeo só "existe" no documento após um `GET .../video-job` retornar `completed`; antes disso, `scene.video.status="pending"`.
+- **Imagens geram registro em `upload`; áudio e vídeo não.** Áudio (`story_audio`) e vídeo (`story_videos`) são salvos no storage mas **sem** documento na coleção `upload`.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Conclusão de vídeo atualiza a cena | `GET .../video-job` retorna `completed` | Escreve `scene.video.{url,status,duration_sec}`, `scene.media_mode="video"`, `scene.media={type:video,url,duration}` | `story_scene` |
+| Download do vídeo Sora para o CDN | `video-job completed` e URL ausente na resposta | Baixa `/v1/videos/{id}/content` e salva em `story_videos`; usa URL permanente do CDN | storage (sem doc `upload`) |
+| Word timestamps de karaokê | TTS com `story.subtitle_karaoke==true` | Escreve `scene.dialogues[i].word_timestamps` | `story_scene` |
+| Registro de upload de imagem | Qualquer geração de imagem (cena/personagem/capa) | Cria documento na coleção `upload` | `upload` |
+| Auto-cadastro do prompt legado | 1ª chamada a `/v3/ai/build/story` sem `intro_build_story` | Insere o `Prompt` `intro_build_story` no sistema | coleção de prompts |
+| Cascade delete | `DELETE /v3/story/{id}` | Remove `story_character` + `story_scene` + `story` | 3 coleções |
+
+> **Não há triggers (`before_*`/`after_*`) nem webhooks** disparados por `StoryRest`. Nenhum evento de gamificação é emitido por este módulo.
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD das três coleções via `/v3/database/*` (schema-less).
+- Cascade delete via `DELETE /v3/story/{id}`.
+- Geração de imagem (cena, personagem, capa) com ou sem imagens de referência.
+- TTS de diálogo (`tts-1`) e prévia de voz de personagem.
+- Karaokê (word timestamps Whisper) quando `subtitle_karaoke=true`.
+- Geração de estrutura narrativa por GPT (function-calling).
+- Geração de vídeo **apenas via Sora 2** (disparo + polling + download para CDN).
+- Diagnóstico de acesso OpenAI (`/openai/video-probe`, `/openai/models`).
+
+### ❌ NÃO Suportado / armadilhas
+
+- **Modelos de vídeo Freepik (`veo-3-fast`, `kling-3.0`):** desabilitados (`FREEPIK_ENABLED=false`) — código morto; chamada retorna 400. **O default de `model` (`veo-3-fast`) falha** — é obrigatório passar `sora-2`.
+- **`tts-1-hd`:** citado no comentário, **não** usado — o código envia `tts-1`.
+- **`from_scene_id`** (estrutura, `mode=continue`): documentado no JavaDoc, **não** é lido pelo código.
+- **CRUD dedicado em `/v3/story`:** não existe (`POST`/`GET /v3/story` não estão implementados).
+- **Triggers/webhooks/notificações:** não disparados por este módulo.
+- **`AIRest.buildStory` (`/v3/ai/build/story`) — formato legado/incompatível:** gera história em **objeto-mapa** (`scenes:{ "start": {..., next_scenes:[{scene,text}]} }`, `characters:{...}`) com GPT-3.5, **sem persistir**. **Não** é o schema usado por `StoryRest` (que trabalha com cenas em array, `ref`/`type`/`next_scene_ref`, e personagens/cenas como documentos separados). Tratar como recurso legado.
+- **Transação no cascade delete:** inexistente — falha parcial deixa órfãos.
+- **Validação de schema dos documentos:** inexistente — qualquer campo extra é aceito e ignorado.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** todo endpoint recebe `@BeanParam AuthBean` e usa `authBean.getApiKey()` para resolver a conexão do tenant. Um token Bearer válido é necessário para resolver o tenant.
+- **Sem autorização por endpoint:** **nenhum** método de `StoryRest` chama `getScope()`, `SCOPE_*`, `getRole()` ou similar (confirmado por grep — 0 ocorrências). Isso contrasta com `DatabaseRest.find`, que exige `SCOPE_DATABASE`. **Consequência:** qualquer token válido do tenant pode chamar qualquer endpoint de `StoryRest`, **inclusive o `DELETE` em cascata** — que apaga história, personagens e cenas sem checagem de papel/scope.
+- **Isolamento multi-tenant:** garantido pela conexão Jongo por tenant (`FrontController.getInstance(apiKey)`); não há campo de tenant nos documentos.
+- **Segredo hardcoded:** `FREEPIK_API_KEY = "FPSX69b6861d3b45e4591f8e8d354ebf3ec0"` está **literalmente no código-fonte** (linha 630). Mesmo com `FREEPIK_ENABLED=false`, é um vazamento de credencial versionado — deve ser rotacionado e movido para configuração.
+- **Superfície de SSRF:** `fetchImageBytes(url)` faz `GET` em **URLs arbitrárias** vindas do request (`reference_image_urls`, `image_url`, `end_image_url`) sem allowlist. Um chamador pode induzir o servidor a buscar URLs internas. Mitigado parcialmente apenas por reencode de URL (não por validação de destino).
+- **Injeção MongoDB:** **não há** — todas as queries usam placeholders Jongo parametrizados (`"{_id: #}"`, `"{story_id: #}"`). Não há concatenação de query crua.
+- **Token OpenAI compartilhado:** `AIService.CHATGPT_TOKEN` é global do servidor (não por tenant) — custo/uso de IA não é isolado por tenant no nível da credencial.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+**Diagnóstico rápido**
+
+- Verificar acesso à OpenAI/Sora: `GET /v3/story/openai/models` (cheque `sora_accessible:true`) e `POST /v3/story/openai/video-probe`.
+- Logs vão para **stderr** com prefixos `StoryRest...` — ex.: `StoryRest | Whisper word timestamps failed (non-fatal): ...`, `StoryRest.generateImageBytes | failed to fetch ref image: ...`, `StoryRest.updateDialogueWordTimestamps | error: ...`.
+
+**Queries úteis (via `/v3/database`)**
+
+```
+GET /v3/database/story/<storyId>
+GET /v3/database/story_character/<charId>
+GET /v3/database/story_scene/<sceneId>
+# todas as cenas de uma história (aggregate/find por story_id):
+POST /v3/database/story_scene/aggregate
+[ { "$match": { "story_id": "<storyId>" } } ]
+```
+
+**Erros comuns e causas**
+
+| Sintoma | Causa provável |
+|---|---|
+| 400 `image_url is required` no `generate-video` | Cena sem imagem (gere/anexe a imagem antes). |
+| 400 `Modelo '...' requer integração Freepik` | `model != sora-2` com Freepik desabilitado — use `sora-2`. |
+| `video-job` preso em `pending` | Job ainda processando, ou Sora não devolveu URL (cai no download via `/content`). |
+| Vídeo "some" após ~1h | URL temporária da OpenAI expirou — o download para CDN só ocorre no `video-job completed`. |
+| TTS funciona mas sem karaokê | `story.subtitle_karaoke != true`, ou Whisper falhou (cheque stderr). |
+| 404 `Character/Scene not found` | `_id` inexistente no tenant atual. |
+
+**O que verificar quando algo não funciona**
+
+1. Token Bearer válido e tenant correto (a coleção é por tenant).
+2. `story.aspect_ratio` válido (`16:9|9:16|1:1`) — valores fora disso caem em 16:9.
+3. Para vídeo: `model:"sora-2"` explícito e imagem de início presente.
+4. Acesso da conta OpenAI ao Sora (`/openai/models`).
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Mínimo funcional — gerar estrutura e capa
+
+```http
+POST /v3/story/STORY123/scene/structure
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{ "mode": "full", "objective": "Treinamento de segurança no trabalho", "num_scenes": 5, "num_decisions": 2, "num_endings": 2 }
+```
+```http
+POST /v3/story/STORY123/cover/generate
+{ "prompt": "estilo cartoon corporativo" }
+```
+
+### 10.2 Avançado — vídeo de cena via Sora com áudio
+
+```http
+POST /v3/story/STORY123/scene/SCENE9/generate-video
+{ "model": "sora-2", "quality": "high", "duration_sec": 8, "prompt": "câmera lenta aproximando do personagem", "generate_audio": true }
+→ { "job_id": "video_abc", "status": "pending", "model": "sora-2" }
+```
+Polling até concluir:
+```http
+GET /v3/story/STORY123/scene/SCENE9/video-job
+→ { "status": "completed", "video_url": "https://cdn.../story-video-xyz.mp4", "duration_sec": 8 }
+```
+
+### 10.3 Anti-pattern (o que NÃO fazer)
+
+- **Disparar vídeo sem informar `model`** → usa `veo-3-fast` por default → **400** (Freepik desabilitado). Sempre passe `"model":"sora-2"`.
+- **Pedir `duration_sec: 6` esperando 6s** → o Sora **snap** para `"4"`. Use a tabela do snap (`<=6→4`, `<=10→8`, senão 12) para escolher conscientemente.
+- **Confiar na URL retornada direto pela OpenAI** → ela expira em ~1h; só persiste no CDN após `video-job` retornar `completed`.
+- **Chamar o `DELETE /v3/story/{id}` sem cuidado** → não há checagem de scope/role e não há transação: apaga história + personagens + cenas de forma irreversível.
+- **Misturar `/v3/ai/build/story` com o editor novo** → formatos de história incompatíveis (objeto-mapa vs. array de cenas com `ref`).
+
+---
+
+## Checklist de Configuração
+
+- [ ] Token Bearer válido do tenant em todas as chamadas.
+- [ ] Conta OpenAI com acesso ao **Sora 2** (`GET /v3/story/openai/models` → `sora_accessible:true`).
+- [ ] `story.aspect_ratio` definido (`16:9|9:16|1:1`) antes de gerar imagem/vídeo.
+- [ ] **Imagem de cena gerada/anexada antes** de `generate-video` (pré-requisito).
+- [ ] `"model":"sora-2"` **explícito** no `generate-video` (default falha).
+- [ ] `story.subtitle_karaoke=true` se quiser word timestamps no TTS.
+- [ ] `voice_profile` definido no personagem para prévia de voz consistente.
+- [ ] Armadilha: `duration_sec` é **reescrito** (snap 4/8/12) no Sora.
+- [ ] Armadilha: omitir `generate_audio` ⇒ `true`; `false` apenas injeta texto "silent" no prompt.
+- [ ] Lembrar: cascade `DELETE` é **irreversível e sem autorização por role**.