@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

GET /operations/contracts HTTP/1.1
Host: api.hed-hog.com
Authorization: Bearer <token_de_acesso>
Accept: application/json

Exemplo de resposta

[
  {
    "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

GET /operations/projects/456 HTTP/1.1
Host: api.hed-hog.com
Authorization: Bearer <token_de_acesso>
Accept: application/json

Exemplo de resposta

{
  "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.