npm package: @hed-hog/operations
Description: O módulo `@hed-hog/operations` é responsável por fornecer funcionalidades relacionadas à gestão operacional dentro do ecossistema HedHog. Ele integra-se com módulos de paginação, localização e acesso a banco de dados via Prisma, oferecendo endpoints para 
Latest version: 0.0.303

# @hed-hog/operations

## 1. Visão geral do módulo

O módulo `@hed-hog/operations` é responsável por fornecer funcionalidades relacionadas à gestão operacional dentro do ecossistema HedHog. Ele integra-se com módulos de paginação, localização e acesso a banco de dados via Prisma, oferecendo endpoints para consulta de operações, contratos, projetos, alocações, tarefas, folhas de ponto e aprovações.

## 2. Escopo e responsabilidades

- Disponibilizar endpoints para consulta de dados operacionais.
- Garantir controle de acesso baseado em papéis (roles) específicos.
- Integrar-se com módulos de configuração, paginação, localização e banco de dados.
- Suportar operações administrativas relacionadas a contratos, projetos, alocações, tarefas, timesheets e aprovações.

## 3. Endpoints

Todos os endpoints são protegidos e requerem autenticação com papéis específicos (`admin` ou `admin-operations`).

| Método | Path                      | Autenticação | Descrição                                      |
|--------|---------------------------|--------------|------------------------------------------------|
| GET    | `/operations`             | Sim          | Retorna lista geral de operações.              |
| GET    | `/operations/contracts`   | Sim          | Retorna lista de contratos.                     |
| GET    | `/operations/contracts/:id` | Sim        | Retorna detalhes de um contrato específico.    |
| GET    | `/operations/projects`    | Sim          | Retorna lista de projetos.                      |
| GET    | `/operations/projects/:id` | Sim         | Retorna detalhes de um projeto específico.     |
| GET    | `/operations/allocations` | Sim          | Retorna lista de alocações.                     |
| GET    | `/operations/tasks`       | Sim          | Retorna lista de tarefas.                        |
| GET    | `/operations/timesheets`  | Sim          | Retorna lista de folhas de ponto (timesheets). |
| GET    | `/operations/approvals`   | Sim          | Retorna lista de aprovações.                     |

### Parâmetros e Respostas

- **Parâmetros Path:** Para endpoints com `:id`, espera-se um identificador único do recurso.
- **Query Parameters:** Possível suporte a paginação e filtros via módulos integrados (não detalhado no código fornecido).
- **Body:** Não aplicável para os endpoints GET listados.
- **Resposta:** Listas ou objetos JSON representando os recursos solicitados.
- **Erros:** Autorização negada, recurso não encontrado, erros internos do servidor.

## 4. Regras de autenticação e autorização

- Todos os endpoints são protegidos e requerem autenticação.
- O acesso é restrito a usuários com os papéis (`roles`) `admin` ou `admin-operations`.
- A verificação de papéis é feita via relações definidas no arquivo `route.yaml`.

## 5. Estruturas de request/response

Não há definições explícitas de estruturas de request ou response no código fornecido, pois todos os endpoints são do tipo GET e não recebem corpo. Espera-se que as respostas sejam JSON contendo listas ou objetos dos recursos solicitados.

## 6. Erros comuns

- **401 Unauthorized:** Usuário não autenticado.
- **403 Forbidden:** Usuário autenticado, mas sem os papéis necessários (`admin` ou `admin-operations`).
- **404 Not Found:** Recurso com o `id` especificado não encontrado.
- **500 Internal Server Error:** Erro inesperado no servidor.

## 7. Banco de dados (tabelas YAML)

Não foram fornecidos arquivos YAML de tabelas específicas para o módulo `operations`. O módulo depende do `PrismaModule` para acesso ao banco de dados, mas detalhes das tabelas não estão disponíveis no código fornecido.

## 8. Regras de negócio relevantes

- O módulo é destinado exclusivamente para uso administrativo, conforme papéis definidos.
- O papel `admin-operations` é descrito como "Administrador com acesso total à gestão de operações".
- O acesso aos dados operacionais é restrito e controlado via papéis.
- Integração com módulos de paginação e localização sugere suporte a consultas paginadas e internacionalizadas, embora não detalhado.

## 9. Guia rápido de uso (exemplos)

### Exemplo de requisição para listar contratos

```http
GET /operations/contracts HTTP/1.1
Host: api.hed-hog.com
Authorization: Bearer <token_de_acesso>
Accept: application/json
```

### Exemplo de resposta

```json
[
  {
    "id": "123",
    "name": "Contrato A",
    "startDate": "2023-01-01",
    "endDate": "2023-12-31",
    "status": "ativo"
  },
  {
    "id": "124",
    "name": "Contrato B",
    "startDate": "2023-02-01",
    "endDate": "2023-11-30",
    "status": "ativo"
  }
]
```

### Exemplo de requisição para obter detalhes de um projeto

```http
GET /operations/projects/456 HTTP/1.1
Host: api.hed-hog.com
Authorization: Bearer <token_de_acesso>
Accept: application/json
```

### Exemplo de resposta

```json
{
  "id": "456",
  "name": "Projeto X",
  "description": "Descrição detalhada do projeto X",
  "startDate": "2023-03-01",
  "endDate": "2023-09-30",
  "status": "em andamento"
}
```

---

**Nota:** Para utilizar os endpoints, o token JWT deve conter os papéis `admin` ou `admin-operations` para garantir acesso autorizado.