21 lines
4.7 KiB
Markdown
21 lines
4.7 KiB
Markdown
# API interna de assistência — v1
|
|
|
|
Base `/api/v1/ai`. Autenticação por sessão Laravel, email verificado, `manage-portal`, feature flag e CSRF do middleware web. Não é API OAuth/OIDC para terceiros. Enviar `Accept: application/json`; o React usa as rotas equivalentes `/management/ai` via Inertia.
|
|
|
|
| Método / recurso | Entrada | Resultado |
|
|
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
| POST `/runs` | capability, purpose, language; query para assistant/search; source_id para summary; interest_id para classify; sector_id/province/maturity_level opcionais para recommend; source_id/nature opcionais para search | 201 com UUID; finalidade verificada também pelo gateway |
|
|
| GET `/runs/{uuid}` | UUID | Metadados e resultado, ou resultado nulo quando fonte/consentimento revogados ou capacidade suspensa |
|
|
| POST `/runs/{uuid}/feedback` | rating: helpful/unhelpful/unsafe; review_requested boolean | Feedback idempotente por utilizador/resultado; unsafe suspende a capacidade |
|
|
| POST `/runs/{uuid}/review` | status: accepted/rejected; version_no | Revisão independente, conflito 409 em versão antiga; nenhum envio externo |
|
|
| POST `/documents` | Multipart file texto simples, authorised=true | 201 document_id canónico; não torna a fonte pesquisável |
|
|
| POST `/sources` | document_id, title, language pt/en, nature, source_url HTTPS, source_owner, evidence_reference, source_date, valid_until, authorised=true | Fonte pendente e fragmentos indexados, ainda inelegíveis |
|
|
| POST `/sources/{uuid}/review` | status: approved/revoked; expected_status | Confirmação por outra pessoa para aprovar; conflito se estado mudou |
|
|
| POST `/controls/{capability}` | suspended boolean | Suspensão imediata no armazenamento partilhado; fora do limite de consultas, mantendo autorização/CSRF |
|
|
|
|
Capacidades: assistant, search, recommend, classify, quality, sla, summary. Finalidades: investment_information para pesquisa/recomendação/excertos; interest_triage para triagem; data_quality e execution_monitoring para monitores.
|
|
|
|
Limite das consultas e alterações comuns: 20 pedidos/minuto por identidade de throttling Laravel. Erros: 401/redirect para sessão ausente conforme Accept; 403 autorização, 404 desactivação/ID inválido, 409 conflito, 422 validação/consentimento/fonte, 429 limite, 503 suspensão. Sem streaming, tools de modelos, chamadas directas do React a inferência ou contrato externo de sincronização.
|
|
|
|
Resultados de pesquisa são limitados a cinco fragmentos; pré-visualização a três; oportunidades a dez; monitores têm limites explícitos por regra. Listagens administrativas mostram até 50 fontes, 100 documentos e 20 execuções; paginação completa fica pendente. A interface identifica que resultados não são exaustivos.
|