API e Dados

A camada pública da aplicação importa api de src/lib/api.ts. Na versão documentada, esse arquivo reexporta src/lib/demo-api.ts.

Grupos da API

Grupo	Métodos
subprojects	list()
projects	list(), get(id), create(body), update(id, body), remove(id)
collections	list(params), get(id)
documents	list(params), updateMetadata(id, body), reprocess(ids)
samples	get(id), createAnnotation(id, body), updateOverride(id, body), deleteOverride(id)
review	samples(params)
search	text(body), pos(body), annotation(body), semantic(body)
analysis	frequency, ngrams, collocations, diachronic, compare, clitics, geodistribution
ingest	status(), startLocal()
export	corpus(format, body)

Payload principal

O JSON público do corpus segue a forma geral:

type CorpusPayload = {
  summary: Record<string, unknown>
  overrides?: { samples: number; documents: number }
  collections: Collection[]
  documents: CorpusDocument[]
  samples: Sample[]
}

Coleção

Campo	Tipo	Descrição
id	string	Identificador estável.
name	string	Nome público da coleção.
genre	string	Gênero agregado.
support	string	Suporte, como impresso ou manuscrito.
access_form	string	Forma de acesso ou transcrição.
century	`XVIII	XIX
half_century	`1	2`
state	string	UF.
city	string	Cidade quando disponível.
bibliographic_ref	string	Referência editorial.
sample_count	number	Total de amostras.
token_count	number	Total de tokens.
status	`pending	processing

Documento

CorpusDocument representa o arquivo de origem ou documento consolidado.

Campo	Descrição
collection_id	Vínculo com coleção.
title	Título exibido.
filename	Nome do arquivo.
source_path	Caminho de origem no payload sanitizado.
origin	local ou upload.
metadata	Metadados editoriais herdados da coleção e do arquivo.
sample_count	Quantidade de amostras associadas.
token_count	Soma de tokens.

Amostra

Sample é a unidade exibida na leitura e na busca.

Campo	Descrição
id	Identificador da amostra.
collection_id	Coleção de origem.
position	Ordem dentro da coleção.
raw_text	Texto consultável.
source_label	Rótulo da fonte.
metadata	Metadados livres.
parser	Parser de segmentação usado no pipeline de preparação.
status	auto, partial ou review.
granularidade	Nível de segmentação.
categoria, subgenero, tipo	Campos editoriais para filtros.
periodo	Século, metade e intervalo.
local	UF, cidade ou outros dados geográficos.

Busca

Payload de busca:

type SearchBody = {
  query?: string
  filters?: {
    century?: string
    state?: string
    genre?: string
    status?: string
    parser?: string
    granularidade?: string
  }
  limit?: number
}

Retorno principal:

Campo	Descrição
total	Quantidade de resultados.
results	Lista de KwicResult.

Análises

Método	Payload principal	Retorno
frequency	pos, period, tipo, mode	FrequencyItem[]
ngrams	n, period, tipo	NgramItem[]
collocations	node, period, tipo	CollocationItem[]
diachronic	terms, tipo	Séries por termo.
compare	filter_a, filter_b	Listas características de A e B.
clitics	tipo, granularidade	Distribuição e tabela por documento.
geodistribution	scope	GeoItem[]

Exportação

Formatos aceitos:

Formato	MIME	Extensão
json	application/json;charset=utf-8	.json
csv	text/csv;charset=utf-8	.csv
tsv	text/tab-separated-values;charset=utf-8	.tsv
conllu	text/plain;charset=utf-8	.conllu
tei	application/xml;charset=utf-8	.xml
analysis	text/csv;charset=utf-8	.csv

O nome padrão é phpb-export.{ext}.

Persistência local

Chave	Origem
phpb-demo-projects:{tenant}:v1	demo-api.ts
phpb-demo-annotations:{tenant}:v1	demo-api.ts
phpb-demo-ingest:{tenant}:v1	demo-api.ts
phpb-corpus-overrides:{tenant}:v1	corpus-loader.ts

Sanitização de build

O script scripts/check-public-build.mjs é executado após build:hub e build:sc. Ele deve bloquear artefatos sensíveis no diretório dist.