e488ae3342
- Created ExampleTest and RoutesTest for basic application response and route testing. - Implemented IsolatedDatabaseTestCase for isolated database testing. - Added unit tests for various models and services including Contract, CPE, and LeadDetail. - Developed request validation tests for CreateClientRequest, UpdateClientRequest, and ContractRequest. - Introduced Vite configuration for asset management in the Laravel application.
132 lines
7.0 KiB
Markdown
132 lines
7.0 KiB
Markdown
# API da aplicacao
|
|
|
|
## Arquitetura
|
|
|
|
Web e API usam os mesmos servicos em `app/Services`, com as mesmas regras de
|
|
negocio e acesso aos dados. A web mantem as vistas Blade e os redirecionamentos.
|
|
A API devolve JSON, exceto a exportacao Excel e o diagnostico HTML `phpinfo`.
|
|
Os controllers nao fazem chamadas HTTP a propria aplicacao. `APP_API_URL` ou
|
|
`app.api_url` deixam de ser necessarios para o login e a sessao web.
|
|
|
|
O bootstrap Laravel regista `routes/api.php` com o prefixo `/api`.
|
|
|
|
## Autenticacao
|
|
|
|
`POST /api/login` recebe `email` e `password` e devolve `token` e `user`.
|
|
Os tokens Sanctum expiram apos 20 minutos. Use estes cabecalhos nos pedidos:
|
|
|
|
```http
|
|
Authorization: Bearer <token>
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
```
|
|
|
|
`POST /api/refresh` prolonga um token ainda valido por 20 minutos.
|
|
`POST /api/logout` revoga o token atual. A recuperacao de senha revoga todos
|
|
os tokens do utilizador. Contas com `can_login=false` nao podem autenticar-se
|
|
nem usar tokens existentes. O login web usa o mesmo servico, regenera a sessao
|
|
e valida/renova o token localmente em cada pedido autenticado.
|
|
|
|
Login e verificacao de PIN permitem 10 tentativas por minuto; pedidos publicos
|
|
de recuperacao de senha e envio de email de teste permitem 5 por minuto.
|
|
|
|
## Endpoints
|
|
|
|
Todos os caminhos abaixo sao relativos a `/api`.
|
|
`CRUD /recurso` significa `GET /recurso`, `POST /recurso`,
|
|
`GET /recurso/{id}`, `PUT` ou `PATCH /recurso/{id}` e `DELETE /recurso/{id}`.
|
|
As rotas `/resources` aceitam `PUT`, nao `PATCH`.
|
|
|
|
| Operacao | Endpoint | Acesso |
|
|
| --- | --- | --- |
|
|
| Login | `POST /login` | Publico |
|
|
| Pedir recuperacao de senha | `POST /password/email` | Publico |
|
|
| Redefinir senha | `POST /password/reset` | Publico |
|
|
| Sair / renovar / verificar token | `POST /logout`, `POST /refresh`, `GET /check-token` | Autenticado |
|
|
| Utilizador atual e permissoes | `GET /me` | Autenticado |
|
|
| Dashboard | `GET /dashboard` | Autenticado |
|
|
| Analises | `GET /analytics` | Role `administracao` |
|
|
| Guardar / verificar PIN | `POST /user/pin`, `POST /user/check-pin` | Autenticado |
|
|
| Clientes | CRUD `/clients` | Autenticado |
|
|
| Opcoes de clientes | `GET /clients/options?type={client_type_id}` | Autenticado |
|
|
| Detalhe e contratos de cliente | `GET /clients/{id}/detail` | Autenticado |
|
|
| Pesquisa por nome | `GET /clients/search/name?term=...` | Autenticado |
|
|
| Pesquisa por ID | `POST /clients/search/id`, corpo `{"id":1}` | Autenticado |
|
|
| Leads | CRUD `/leads` | Autenticado |
|
|
| Estados de leads | `GET /leads/options` | Autenticado |
|
|
| Converter lead | `PUT /leads/{id}/convert` | Autenticado |
|
|
| Contratos | CRUD `/contracts` | Autenticado |
|
|
| Opcoes de contratos | `GET /contracts/options?client_id=...` | Autenticado |
|
|
| Dados de edicao | `GET /contracts/{id}/edit` | Autenticado |
|
|
| Opcoes / executar renovacao | `GET /contracts/{id}/renew`, `POST /contracts/{id}/renew` | Autenticado |
|
|
| Historico | `GET /contracts/{id}/history` | Autenticado |
|
|
| Ler / editar / eliminar historico | `GET`, `PUT`, `DELETE /contracts/{id}/history/{historyId}` | Autenticado |
|
|
| Eliminar contratos em lote | `DELETE /contracts/bulk`, corpo `{"ids":[1,2]}` | Autenticado |
|
|
| Exportar contratos | `GET /contracts/export` | Permissao `view_contract_summary` |
|
|
| Utilizadores | CRUD `/users` | Role `admin` |
|
|
| Roles para criar utilizador | `GET /users/options` | Role `admin` |
|
|
| Enviar recuperacao de senha a utilizador | `POST /users/{user}/password-reset` | Role `admin` |
|
|
| Roles e permissoes | `GET /admin/access/roles-permissions` | Role `admin` |
|
|
| Atualizar permissoes de role | `POST /admin/access/roles/{role}/permissions` | Role `admin` |
|
|
| Utilizadores e roles | `GET /admin/access/users` | Role `admin` |
|
|
| Atualizar roles de utilizador | `POST /admin/access/users/{user}/roles` | Role `admin` |
|
|
| Recursos auxiliares | CRUD `/resources/{resource}` | Permissao `manage_resources` |
|
|
| Informacao do sistema | `GET /admin/info` | Role `admin` |
|
|
| Diagnostico PHP (HTML) | `GET /admin/phpinfo` | Role `admin` |
|
|
| Executar migrations | `POST /admin/runMigrations` | Role `admin` |
|
|
| Email de teste | `POST /admin/testEmail`, corpo `{"email":"destino@example.com"}` | Role `admin` |
|
|
|
|
Recursos permitidos: `power_tiers`, `contract_types`, `payment_methods`,
|
|
`typologies`, `cui_tiers`, `suppliers`, `contract-statuses`.
|
|
Roles e permissoes sao enviadas como listas de nomes nos campos `roles` e
|
|
`permissions`. Os campos de negocio e datas seguem os FormRequests existentes,
|
|
incluindo o formato `d/m/Y` nos formularios de contratos. As operacoes de
|
|
senha recebem `email`; a redefinicao tambem recebe `token`, `password` e
|
|
`password_confirmation`.
|
|
|
|
## Respostas e compatibilidade
|
|
|
|
Criacao: `201`; operacao concluida: `200`; nao autenticado: `401`;
|
|
acesso negado: `403`; registo inexistente: `404`; validacao: `422`;
|
|
limite de tentativas: `429`. Erros de validacao incluem `message` e `errors`.
|
|
Os erros API sao JSON mesmo sem o cabecalho `Accept`.
|
|
|
|
Clientes mantem a listagem antiga `{"clients":[...]}` quando `per_page` nao e
|
|
enviado. Com `per_page`, devolvem um paginador em `clients`, com `data`,
|
|
`current_page`, `last_page`, `per_page`, `total` e links. Clientes e contratos
|
|
limitam `per_page` ao intervalo 1-100. A listagem paginada de clientes filtra
|
|
`type=client`, tal como a web; a listagem antiga conserva o comportamento
|
|
anterior de devolver os registos ativos. Filtros de nome, NIF, email, tipo e
|
|
codigo de contrato sao partilhados. Contratos incluem os totais da pagina atual.
|
|
|
|
IDs de clientes passam a ser incluidos nas respostas. Passwords, hashes de PIN
|
|
e remember tokens nao sao serializados. Dados financeiros e snapshots de
|
|
contratos sao omitidos das respostas de negocio sem `view_contract_summary`.
|
|
Atualizacoes sem essa permissao preservam os valores financeiros e parcelas.
|
|
Exportacoes exigem essa permissao, tambem na web.
|
|
|
|
As antigas operacoes administrativas `GET /admin/runMigrations` e
|
|
`GET /admin/testEmail` passam a `POST`, exigem a role `admin`, e o email de
|
|
destino passa a ser obrigatorio. Nenhuma migration foi executada durante esta
|
|
refatoracao. Estes endpoints devem ser restritos tambem ao nivel de rede em
|
|
producao, especialmente `phpinfo` e a execucao de migrations.
|
|
|
|
## Verificacao
|
|
|
|
Os testes unitarios de regras ficam em `tests/Unit`. Os testes HTTP da API ficam
|
|
em `tests/Api`, e os fluxos web destinados ao browser ficam em `tests/Browser`.
|
|
Ambos usam uma base SQLite em memoria, com o esquema oficial de permissoes do
|
|
Spatie e tabelas minimas; nao usam nem alteram a base de dados da aplicacao.
|
|
Os testes Browser verificam a resposta HTTP, vistas, CSRF, redirecionamentos e
|
|
sessoes Laravel; nao executam JavaScript num Chromium real.
|
|
|
|
```bash
|
|
APP_ENV=testing DB_CONNECTION=sqlite DB_DATABASE=:memory: CACHE_STORE=array SESSION_DRIVER=array \
|
|
vendor/bin/phpunit tests/Unit tests/Api tests/Browser
|
|
```
|
|
|
|
Cada grupo tambem pode ser executado isoladamente com `vendor/bin/phpunit
|
|
--testsuite API` ou `vendor/bin/phpunit --testsuite Browser`. O PHP CLI necessita
|
|
da extensao `pdo_sqlite`. Os testes Feature legados que dependem de dados
|
|
preexistentes nao estao incluidos no comando acima.
|