Adicionar app front

[gitnnolabs]

Descrição da tarefa

Criar um endpoint REST para marcar o front do artigo, no mesmo padrão do endpoint de referências (POST /api/v1/reference/).

O cliente envia o texto do front (título, autores, afiliações, resumo, palavras-chave, datas, DOI, etc.). A API usa LLM para extrair elementos estruturados e devolve JSON ou XML JATS/SPS.

---

Endpoints

Método	Caminho	Auth	Descrição
POST	/api/v1/front/	Sim (JWT)	Marcar front a partir de texto
POST	/api/v1/front/docx/	Sim (JWT)	Upload .docx, extrair texto e marcar (opcional nesta issue)

Prefixo: /api/v1/
Auth: Authorization: Bearer <access_token> (IsAuthenticated)
Content-Type: application/json (texto) ou multipart/form-data (DOCX)

---

POST /api/v1/front/

Campos do request

Campo	Tipo	Default	Obrigatório	Descrição
front	string	—	sim	Texto do front do artigo a marcar
type	json | xml	json	não	Formato de saída
language	string (ex.: pt, en, es)	—	não	Idioma fallback quando a IA não devolver idioma

Exemplo A — saída JSON

curl -s -X POST "${BASE_URL}/api/v1/front/" \
  -H "Authorization: Bearer ${ACCESS}" \
  -H "Content-Type: application/json" \
  -d '{
    "front": "Título de teste\nAna Silva\nUniversidade Exemplo, São Paulo, Brasil\nResumo: Texto do resumo.\nPalavras-chave: ciência; dados\nDOI: 10.1590/example",
    "type": "json",
    "language": "pt"
  }'

200

{
  "data": {
    "doi": "10.1590/example",
    "titles": [
      {
        "text": "Título de teste",
        "language": "pt",
        "kind": "main"
      }
    ],
    "authors": [
      {
        "given_names": "Ana",
        "surname": "Silva",
        "orcid": "",
        "affiliations": ["aff1"],
        "display": "Ana Silva"
      }
    ],
    "affiliations": [
      {
        "id": "aff1",
        "text": "Universidade Exemplo, São Paulo, Brasil",
        "orgname": "Universidade Exemplo",
        "city": "São Paulo",
        "country": "Brasil",
        "country_code": "BR"
      }
    ],
    "dates": [],
    "abstracts": [
      {
        "title": "Resumo",
        "text": "Texto do resumo.",
        "language": "pt"
      }
    ],
    "keywords": [
      {
        "language": "pt",
        "keywords": ["ciência", "dados"]
      }
    ]
  }
}

Exemplo B — saída XML

curl -s -X POST "${BASE_URL}/api/v1/front/" \
  -H "Authorization: Bearer ${ACCESS}" \
  -H "Content-Type: application/json" \
  -d '{
    "front": "Título de teste\nAna Silva\nUniversidade Exemplo\nResumo: Texto do resumo.",
    "type": "xml",
    "language": "pt"
  }'

200

{
  "data": "<article-meta>...</article-meta>"
}

O XML deve usar tags SPS/JATS do front (article-id, article-title, trans-title, contrib, aff, abstract, kwd-group, datas received/accepted, etc.).

---

POST /api/v1/front/docx/ (opcional)

Upload de .docx; a API extrai o texto do documento (ou da secção de front) e aplica a mesma marcação de /api/v1/front/.

curl -s -X POST "${BASE_URL}/api/v1/front/docx/" \
  -H "Authorization: Bearer ${ACCESS}" \
  -F "file=@/caminho/artigo.docx" \
  -F "type=json" \
  -F "language=pt"

Resposta no mesmo formato de /api/v1/front/.

---

Schema do payload marcado (data quando type=json)

Campo	Tipo	Descrição
doi	string | null	DOI do artigo
titles	array	{ text, language, kind } com kind ∈ main | translated
authors	array	{ given_names, surname, orcid, affiliations[], display }
affiliations	array	{ id, text, orgname, orgdiv1, orgdiv2, city, state, country, country_code, symbol }
dates	array	{ type, date } com type ∈ received | accepted
abstracts	array	{ title, text, language }
keywords	array	{ language, keywords[] }

---

Códigos HTTP

Código	Quando
200	Marcação concluída
400	Validação (ex.: front ausente/vazio; type inválido; DOCX inválido)
401 / 403	Sem autenticação ou token inválido
503	LLM indisponível / desligado / mal configurado

---

Comportamento esperado

• Autenticação JWT igual à de /api/v1/reference/.
• Cache por checksum do texto normalizado: o mesmo front não deve reenviar à LLM se já existir marcação persistida.
• type=json (default) devolve objeto estruturado em data.
• type=xml devolve string XML JATS do front em data.
• Em falha de LLM, responder 503 sem persistir resultado inválido como sucesso.

---

Critérios de aceite

• POST /api/v1/front/ autenticado com texto válido devolve 200 e data no schema acima (type=json).
• POST /api/v1/front/ com type=xml devolve XML JATS do front em data.
• Request sem front (ou vazio) devolve 400.
• Request sem token devolve 401/403.
• LLM indisponível devolve 503.
• Mesmo texto reenviado reutiliza cache (checksum) sem nova chamada à LLM.
• Documentação em docs/wiki/api-rest.md inclui o endpoint.

---