chore(deps): update docker/setup-buildx-action action to v2
This commit is contained in:
Rodrigo
parent
bee3f6302b
commit
b2b096d5de
1 changed files with 142 additions and 0 deletions
142
PLANO_FORK_SERVICO.md
Normal file
142
PLANO_FORK_SERVICO.md
Normal file
|
|
@ -0,0 +1,142 @@
|
|||
# Verificação do INSTRUCOES_FORK.md e Plano de Execução
|
||||
|
||||
## 1. Verificação do documento
|
||||
|
||||
### Consistência com o código atual
|
||||
|
||||
O arquivo **INSTRUCOES_FORK.md** foi confrontado com o repositório ConvertX. Resultado:
|
||||
|
||||
| Aspecto | Documento | Código | Status |
|
||||
|--------|-----------|--------|--------|
|
||||
| Stack | Elysia, Bun | `src/index.tsx` usa Elysia, Bun | ✅ |
|
||||
| handleConvert | Acoplado a UI/job/db | `src/converters/main.ts` usa `db`, `jobId`, dirs por user | ✅ |
|
||||
| Assinatura handleConvert | fileNames, dirs, convertTo, converter, jobId | `handleConvert(fileNames, userUploadsDir, userOutputDir, convertTo, converterName, jobId)` | ✅ |
|
||||
| Núcleo de conversão | mainConverter / conversores por engine | `mainConverter()` interno + `properties[].converter` | ✅ |
|
||||
| Upload | multipart em dir user/job | `upload.tsx`: `Bun.write(userUploadsDir + sanitize(name), file)` | ✅ |
|
||||
| Convert | chama handleConvert com body | `convert.tsx`: body.convert_to, file_names, jobId, user | ✅ |
|
||||
| Health | existe algo básico | `healthcheck.tsx`: GET /healthcheck → `{ status: "ok" }` | ✅ (expandir) |
|
||||
| Conversores DOCX→TXT | calibre, libreoffice, markitdown | `calibre`, `libreoffice`, `markitdown` em `main.ts` | ✅ |
|
||||
|
||||
**Conclusão:** O documento está alinhado com o código. A estratégia de extrair uma função pura de conversão e adicionar uma camada `src/api/` sem alterar agressivamente o fluxo web é viável e coerente com a estrutura atual.
|
||||
|
||||
### Pontos de atenção
|
||||
|
||||
1. **mainConverter não é exportado** — a extração pode reutilizar a mesma lógica (normalizeFiletype, properties, escolha de conversor) ou exportar/refatorar `mainConverter` com cuidado para não quebrar a UI.
|
||||
2. **Cookie jobId** — em `handleConvert`, `jobId` só é usado para `query.run(jobId.value, ...)`. Uma função pura não deve receber jobId nem escrever em `file_names`.
|
||||
3. **Rotas Elysia** — O app monta plugins por `.use(user).use(root).use(upload)...`. O modo service-only pode ser um branch no bootstrap: `if (SERVICE_MODE) app.use(apiRoutes); else { ... use(convert) ... }`.
|
||||
4. **JWT / user** — Todas as rotas atuais passam por `userService` e auth. As rotas em `/api/*` devem usar apenas o middleware de token (Bearer), sem JWT de usuário.
|
||||
|
||||
---
|
||||
|
||||
## 2. Plano de execução
|
||||
|
||||
Resumo do plano em **fases e épicos**, seguindo a ordem recomendada no próprio INSTRUCOES_FORK.md (e o checklist técnico).
|
||||
|
||||
---
|
||||
|
||||
### Fase 0 — Preparação (antes de codar)
|
||||
|
||||
| # | Tarefa | Entregável |
|
||||
|---|--------|------------|
|
||||
| 0.1 | Criar fork (se ainda for o repo original) e branch `feat/service-mode-api` | Branch de trabalho |
|
||||
| 0.2 | Documentar hash/tag do upstream usado | README ou doc interno |
|
||||
| 0.3 | Mapear fluxo atual: upload → convert → output (onde está cada passo no código) | Doc “conversion flow map” |
|
||||
|
||||
**Arquivos a inspecionar:** `src/index.tsx`, `src/pages/upload.tsx`, `src/pages/convert.tsx`, `src/converters/main.ts` (já feito na verificação acima).
|
||||
|
||||
---
|
||||
|
||||
### Fase 1 — Desacoplamento (Epic B)
|
||||
|
||||
| # | Tarefa | Entregável |
|
||||
|---|--------|------------|
|
||||
| 1.1 | Extrair função backend pura de conversão (ex.: `convertSingleFile`) em `src/service/convertSingleFile.ts` | Função sem cookie/user/job/db |
|
||||
| 1.2 | Criar `src/service/extractText.ts` com `resolveTextExtractor(inputType, preferredConverter?)` e `extractTextFromFile(...)` | Camada “extração de texto” reutilizável |
|
||||
|
||||
**Critério:** Uma chamada tipo `convertSingleFile({ inputPath, outputDir, target: 'txt', preferredConverter: 'calibre' })` deve converter e retornar `outputPath`, `converterUsed`, `target`, `durationMs`, sem tocar em SQLite nem em cookies.
|
||||
|
||||
---
|
||||
|
||||
### Fase 2 — Modo service-only (Epic C)
|
||||
|
||||
| # | Tarefa | Entregável |
|
||||
|---|--------|------------|
|
||||
| 2.1 | Introduzir `SERVICE_MODE=true|false` e no bootstrap (ex.: `src/index.tsx`) montar só health + API quando true | App sobe sem UI |
|
||||
| 2.2 | Criar `src/api/auth.ts`: middleware que exige `Authorization: Bearer <SERVICE_TOKEN>` em `/api/*`; exceção para `/healthz` | Auth M2M |
|
||||
|
||||
**Variáveis:** `SERVICE_MODE`, `SERVICE_TOKEN`.
|
||||
|
||||
---
|
||||
|
||||
### Fase 3 — API de extração (Epic D)
|
||||
|
||||
| # | Tarefa | Entregável |
|
||||
|---|--------|------------|
|
||||
| 3.1 | GET `/healthz`: ok, service, serviceMode, converters (libreoffice, calibre, pandoc, markitdown) | Health confiável |
|
||||
| 3.2 | POST `/api/extract-text`: multipart `file`, opcionais (filename, mimeType, preferredConverter, formatHint); temp dir → extração → normalização → JSON | MVP consumível pelo n8n |
|
||||
| 3.3 | Módulo `src/api/utils/text.ts`: trim, newline, NUL, whitespace, limites; warnings quando texto vazio ou fallback | Texto estável para RAG |
|
||||
|
||||
**Contrato:** Conforme especificação de endpoints no INSTRUCOES_FORK.md (respostas 200/400/401/413/500 com `ok`, `error.code`, `error.message`).
|
||||
|
||||
---
|
||||
|
||||
### Fase 4 — Robustez (Epic E)
|
||||
|
||||
| # | Tarefa | Entregável |
|
||||
|---|--------|------------|
|
||||
| 4.1 | Temp por request: `/tmp/convertx-service/<requestId>/input|output`, sanitização de nome, cleanup em `finally`, log de falha de cleanup | Zero sujeira por request |
|
||||
| 4.2 | Env: `MAX_UPLOAD_MB`, `REQUEST_TIMEOUT_MS`, `MAX_CONCURRENT_CONVERSIONS`; rejeitar tipos não suportados e payload grande; erros padronizados (PAYLOAD_TOO_LARGE, UNSUPPORTED_INPUT, CONVERSION_TIMEOUT) | Comportamento previsível |
|
||||
|
||||
---
|
||||
|
||||
### Fase 5 — Docker e operação (Epic F)
|
||||
|
||||
| # | Tarefa | Entregável |
|
||||
|---|--------|------------|
|
||||
| 5.1 | Dockerfile (ou adaptar o existente): modo service-only no start, conversores presentes, porta única | Imagem `convertx-service` |
|
||||
| 5.2 | Compose exemplo: bind 127.0.0.1:3010:3000, env SERVICE_MODE, SERVICE_TOKEN, MAX_UPLOAD_MB, REQUEST_TIMEOUT_MS | Deploy repetível |
|
||||
|
||||
---
|
||||
|
||||
### Fase 6 — Integração e testes (Epics G e H)
|
||||
|
||||
| # | Tarefa | Entregável |
|
||||
|---|--------|------------|
|
||||
| 6.1 | Documentar no n8n: HTTP Request POST `/api/extract-text`, Bearer token, multipart, mapping `$json.text` | Handoff para automação |
|
||||
| 6.2 | Testes: DOCX simples/acentos/tabela; arquivo inválido; extensão falsa; timeout; concorrência 2–5; cleanup após sucesso/falha; health sem auth; 401 sem token | Suíte mínima de confiança |
|
||||
|
||||
---
|
||||
|
||||
## 3. Ordem recomendada (build order)
|
||||
|
||||
1. **Extrair/consolidar** função backend de conversão (Fase 1).
|
||||
2. **Criar** `/api/extract-text` (Fase 3.2), usando essa função e temp dir simples.
|
||||
3. **Adicionar** auth + health (Fases 2 e 3.1) e cleanup/limites (Fase 4).
|
||||
4. **Dockerizar** modo service-only (Fase 5).
|
||||
5. **Integrar** no n8n e validar com DOCX reais (Fase 6).
|
||||
6. **Depois** considerar `/api/convert` genérico e `/api/formats` (conforme Sprint 3 do documento).
|
||||
|
||||
---
|
||||
|
||||
## 4. Definição de pronto (MVP)
|
||||
|
||||
O fork estará pronto para uso no n8n quando:
|
||||
|
||||
- [ ] POST `/api/extract-text` aceitar DOCX e devolver texto confiável.
|
||||
- [ ] Token interno obrigatório em `/api/*`.
|
||||
- [ ] Limpeza de temporários garantida.
|
||||
- [ ] GET `/healthz` exposto.
|
||||
- [ ] Container sobe sem UI (`SERVICE_MODE=true`).
|
||||
- [ ] Um único HTTP Request no n8n consome o serviço e usa `$json.text`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Artefatos já presentes no INSTRUCOES_FORK.md
|
||||
|
||||
O próprio documento já inclui os três artefatos pedidos:
|
||||
|
||||
1. **Checklist técnico por tarefa** — EPICs A a H com checklists e entregáveis.
|
||||
2. **ADR curta** — ADR-001 (Fork do ConvertX como serviço interno de extração de texto).
|
||||
3. **Especificação de endpoints** — GET `/healthz`, GET `/api/formats`, POST `/api/extract-text`, POST `/api/convert` (pós-MVP), com payloads e exemplos cURL/n8n.
|
||||
|
||||
Este arquivo (**PLANO_FORK_SERVICO.md**) serve como **verificação + plano de execução** em uma única visão, para seguir fase a fase sem perder o fio do INSTRUCOES_FORK.md.
|
||||
Loading…
Add table
Add a link
Reference in a new issue