@hed-hog/operations

1. Visão geral do módulo

O módulo @hed-hog/operations oferece funcionalidades completas para a gestão operacional dentro do ecossistema HedHog. Ele integra-se com módulos de paginação, localização, banco de dados via Prisma, além de módulos de AI, arquivos, integrações e configurações. Disponibiliza uma ampla gama de endpoints para gerenciamento de colaboradores, departamentos, cargos, projetos, tarefas, contratos, folhas de ponto, aprovações, entre outros recursos operacionais.

2. Escopo e responsabilidades

• Gerenciar colaboradores, departamentos e cargos.
• Controlar projetos, tarefas e alocações.
• Administrar contratos e modelos de contratos.
• Gerenciar folhas de ponto (timesheets) e entradas de timesheet.
• Controlar solicitações de folgas e ajustes de agenda.
• Gerenciar processos de aprovação.
• Integrar com sistemas externos via endpoints de integração.
• Garantir controle de acesso baseado em papéis (roles).
• Suportar operações administrativas e operacionais detalhadas.

3. Endpoints

Todos os endpoints requerem autenticação via token JWT e controle de papéis conforme definido no módulo.

| Método | Path | Autenticação | Descrição | Parâmetros / Body | Resposta | Erros Comuns | |--------|----------------------------------------------|--------------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|--------------------------------------------|------------------------------------| | GET | /operations/dashboard | Sim | Retorna dados resumidos do dashboard operacional para o usuário autenticado. | - | JSON com dados do dashboard | 401, 403, 500 | | GET | /operations/collaborators | Sim | Lista colaboradores visíveis para o usuário. | - | Lista JSON de colaboradores | 401, 403, 500 | | GET | /operations/collaborators/me | Sim | Retorna dados do colaborador associado ao usuário autenticado. | - | JSON do colaborador | 401, 403, 500 | | GET | /operations/collaborators/:id | Sim | Retorna detalhes de um colaborador específico pelo ID. | Path param: id (integer) | JSON do colaborador | 401, 403, 404, 500 | | GET | /operations/collaborators/team | Sim | Retorna o time do usuário autenticado. | - | Lista JSON de colaboradores do time | 401, 403, 500 | | POST | /operations/collaborators | Sim | Cria um novo colaborador. | Body: dados do colaborador (não detalhado) | JSON do colaborador criado | 401, 403, 400, 500 | | PATCH | /operations/collaborators/:id | Sim | Atualiza dados de um colaborador existente. | Path param: id (integer), Body: dados para atualização | JSON do colaborador atualizado | 401, 403, 404, 400, 500 | | GET | /operations/departments | Sim | Lista departamentos disponíveis. | - | Lista JSON de departamentos | 401, 403, 500 | | POST | /operations/departments | Sim | Cria um novo departamento. | Body: dados do departamento (não detalhado) | JSON do departamento criado | 401, 403, 400, 500 | | PATCH | /operations/departments/:id | Sim | Atualiza um departamento existente. | Path param: id (integer), Body: dados para atualização | JSON do departamento atualizado | 401, 403, 404, 400, 500 | | GET | /operations/job-titles | Sim | Lista cargos (job titles) disponíveis. | - | Lista JSON de cargos | 401, 403, 500 | | POST | /operations/job-titles | Sim | Cria um novo cargo. | Body: dados do cargo (não detalhado) | JSON do cargo criado | 401, 403, 400, 500 | | GET | /operations/projects/options | Sim | Lista opções de projetos com paginação. | Query params: paginação via ListOperationsProjectOptionsDto | Lista paginada JSON de projetos | 401, 403, 500 | | GET | /operations/projects | Sim | Lista todos os projetos visíveis para o usuário. | - | Lista JSON de projetos | 401, 403, 500 | | GET | /operations/projects/:id | Sim | Retorna detalhes de um projeto específico. | Path param: id (integer) | JSON do projeto | 401, 403, 404, 500 | | POST | /operations/projects | Sim | Cria um novo projeto. | Body: dados do projeto (não detalhado) | JSON do projeto criado | 401, 403, 400, 500 | | PATCH | /operations/projects/:id | Sim | Atualiza um projeto existente. | Path param: id (integer), Body: dados para atualização | JSON do projeto atualizado | 401, 403, 404, 400, 500 | | GET | /operations/tasks | Sim | Lista tarefas com filtros e paginação. | Query params: projectId (int), projectAssignmentId (int), status (active|completed|archived), paginação | Lista paginada JSON de tarefas | 401, 403, 500 | | POST | /operations/tasks | Sim | Cria uma nova tarefa. | Body: CreateOperationsTaskDto | JSON da tarefa criada | 401, 403, 400, 500 | | GET | /operations/contract-templates | Sim | Lista modelos de contratos. | - | Lista JSON de modelos de contratos | 401, 403, 500 | | GET | /operations/contract-templates/:id | Sim | Retorna detalhes de um modelo de contrato. | Path param: id (integer) | JSON do modelo de contrato | 401, 403, 404, 500 | | POST | /operations/contract-templates | Sim | Cria um novo modelo de contrato. | Body: dados do modelo (não detalhado) | JSON do modelo criado | 401, 403, 400, 500 | | PATCH | /operations/contract-templates/:id | Sim | Atualiza um modelo de contrato existente. | Path param: id (integer), Body: dados para atualização | JSON do modelo atualizado | 401, 403, 404, 400, 500 | | GET | /operations/contracts | Sim | Lista contratos. | - | Lista JSON de contratos | 401, 403, 500 | | GET | /operations/contracts/:id | Sim | Retorna detalhes de um contrato específico. | Path param: id (integer) | JSON do contrato | 401, 403, 404, 500 | | POST | /operations/contracts/drafts | Sim | Cria um rascunho de contrato. | Body: dados do rascunho (não detalhado) | JSON do rascunho criado | 401, 403, 400, 500 | | POST | /operations/contracts | Sim | Cria um novo contrato. | Body: dados do contrato (não detalhado) | JSON do contrato criado | 401, 403, 400, 500 | | POST | /operations/contracts/extract-draft | Sim | Extrai dados de um rascunho de contrato. | Body: dados para extração (não detalhado) | JSON com dados extraídos | 401, 403, 400, 500 | | POST | /operations/contracts/:id/extract-source | Sim | Extrai fonte de um contrato existente. | Path param: id (integer), Body: dados para extração | JSON com fonte extraída | 401, 403, 404, 400, 500 | | POST | /operations/contracts/:id/generate-content | Sim | Gera conteúdo do contrato com base em dados. | Path param: id (integer), Body: dados para geração | JSON com conteúdo gerado | 401, 403, 404, 400, 500 | | POST | /operations/contracts/:id/legal-review | Sim | Solicita revisão legal do contrato. | Path param: id (integer), Body: dados para revisão | JSON com status da revisão | 401, 403, 404, 400, 500 | | PATCH | /operations/contracts/:id | Sim | Atualiza um contrato existente. | Path param: id (integer), Body: dados para atualização | JSON do contrato atualizado | 401, 403, 404, 400, 500 | | DELETE | /operations/contracts/:id | Sim | Remove um contrato. | Path param: id (integer) | JSON com confirmação | 401, 403, 404, 500 | | POST | /operations/contracts/:id/generate-pdf | Sim | Gera PDF do contrato especificado. | Path param: id (integer) | PDF ou link para download | 401, 403, 404, 500 | | GET | /operations/timesheets | Sim | Lista folhas de ponto (timesheets). | - | Lista JSON de timesheets | 401, 403, 500 | | GET | /operations/timesheet-entries | Sim | Lista entradas de timesheet com filtros e paginação. | Query params: projectId, projectAssignmentId, taskId, status (draft|submitted|approved|rejected), fromDate, toDate, paginação | Lista paginada JSON de entradas | 401, 403, 500 | | POST | /operations/timesheet-entries | Sim | Cria uma nova entrada de timesheet. | Body: CreateTimesheetEntryDto | JSON da entrada criada | 401, 403, 400, 500 | | DELETE | /operations/timesheet-entries/:id | Sim | Remove uma entrada de timesheet. | Path param: id (integer) | JSON com confirmação | 401, 403, 404, 500 | | POST | /operations/timesheets | Sim | Cria uma nova folha de ponto. | Body: dados da timesheet (não detalhado) | JSON da timesheet criada | 401, 403, 400, 500 | | PATCH | /operations/timesheets/:id | Sim | Atualiza uma folha de ponto existente. | Path param: id (integer), Body: dados para atualização | JSON da timesheet atualizada | 401, 403, 404, 400, 500 | | POST | /operations/timesheets/:id/submit | Sim | Submete uma folha de ponto para aprovação. | Path param: id (integer) | JSON com status da submissão | 401, 403, 404, 500 | | GET | /operations/time-off | Sim | Lista solicitações de folga. | - | Lista JSON de solicitações | 401, 403, 500 | | POST | /operations/time-off | Sim | Cria uma nova solicitação de folga. | Body: dados da solicitação (não detalhado) | JSON da solicitação criada | 401, 403, 400, 500 | | GET | /operations/schedule-adjustments | Sim | Lista solicitações de ajustes de agenda. | - | Lista JSON de solicitações | 401, 403, 500 | | POST | /operations/schedule-adjustments | Sim | Cria uma solicitação de ajuste de agenda. | Body: dados da solicitação (não detalhado) | JSON da solicitação criada | 401, 403, 400, 500 | | GET | /operations/approvals | Sim | Lista processos de aprovação. | - | Lista JSON de aprovações | 401, 403, 500 | | POST | /operations/approvals/:id/approve | Sim | Aprova um processo de aprovação. | Path param: id (integer), Body: dados para aprovação (não detalhado) | JSON com status atualizado | 401, 403, 404, 400, 500 | | POST | /operations/approvals/:id/reject | Sim | Rejeita um processo de aprovação. | Path param: id (integer), Body: dados para rejeição (não detalhado) | JSON com status atualizado | 401, 403, 404, 400, 500 | | POST | /operations/integration/examples/accounts-payable | Sim | Publica referência para contas a pagar (exemplo de integração). | Body: dados da referência (não detalhado) | JSON com resultado da publicação | 401, 403, 400, 500 | | GET | /operations/team | Sim | Retorna o time do supervisor (equivalente a /operations/collaborators/team). | - | Lista JSON de colaboradores do time | 401, 403, 500 |

4. Regras de autenticação e autorização

• Todos os endpoints requerem autenticação via token JWT.
• O acesso é restrito a usuários com papéis (roles) definidos, geralmente admin ou admin-operations.
• A verificação de papéis é realizada via decoradores e configurações no arquivo route.yaml.
• Usuários sem os papéis necessários recebem erro 403 Forbidden.
• Usuários não autenticados recebem erro 401 Unauthorized.

5. Estruturas de request/response

DTOs principais para criação e listagem

• CreateOperationsTaskDto

{
  projectId?: number; // opcional, inteiro
  projectAssignmentId?: number; // opcional, inteiro
  name: string; // obrigatório, string, máximo 180 caracteres
  description?: string; // opcional, string, máximo 500 caracteres
  status?: 'active' | 'completed' | 'archived'; // opcional, string enum
}

• CreateTimesheetEntryDto

{
  projectId?: number; // opcional, inteiro
  projectAssignmentId?: number; // opcional, inteiro
  taskId?: number; // opcional, inteiro
  taskName?: string; // opcional, string, máximo 180 caracteres
  activityLabel?: string; // opcional, string, máximo 180 caracteres
  workDate: string; // obrigatório, string ISO date
  duration: number; // obrigatório, número > 0
  unit?: 'hours' | 'minutes'; // opcional, string enum
  description?: string; // opcional, string, máximo 500 caracteres
}

• ListOperationsProjectOptionsDto, ListOperationsTasksDto e ListTimesheetEntriesDto suportam paginação e filtros opcionais conforme descrito nos parâmetros dos endpoints.

Respostas

• Respostas são JSON contendo listas ou objetos dos recursos solicitados.
• Para geração de PDF, a resposta pode ser um arquivo binário ou link para download.

6. Erros comuns

• 401 Unauthorized: Usuário não autenticado.
• 403 Forbidden: Usuário autenticado, mas sem os papéis necessários.
• 404 Not Found: Recurso com o id especificado não encontrado.
• 400 Bad Request: Dados inválidos ou incompletos no corpo da requisição.
• 500 Internal Server Error: Erro inesperado no servidor.

7. Banco de dados (tabelas YAML)

Não foram fornecidos arquivos YAML específicos para as tabelas do módulo operations. O acesso ao banco é realizado via Prisma, e as entidades envolvidas incluem:

• Colaboradores: informações pessoais, cargos, departamentos, times.
• Departamentos: nome, descricao, hierarquia.
• Cargos (Job Titles): nome, descricao, nível.
• Projetos: nome, descricao, datas, status.
• Tarefas: associadas a projetos e alocações, status, descricao.
• Modelos de Contratos: templates para contratos.
• Contratos: dados contratuais, status, datas, conteúdo gerado.
• Folhas de Ponto (Timesheets): períodos, status, entradas.
• Entradas de Timesheet: data, duração, tarefa, descricao.
• Solicitações de Folga: datas, tipo, status.
• Ajustes de Agenda: datas, motivo, status.
• Processos de Aprovação: tipo, status, histórico.

Cada entidade possui integridade referencial e índices para otimizar consultas, conforme modelagem Prisma interna.

8. Regras de negócio relevantes

• O módulo é destinado a uso administrativo e operacional, com acesso controlado por papéis.
• Colaboradores podem ser gerenciados, incluindo criação, atualização e consulta.
• Projetos e tarefas possuem status e podem ser filtrados e paginados.
• Contratos suportam rascunhos, extração de conteúdo, geração de PDF e revisão legal.
• Folhas de ponto e entradas de timesheet suportam criação, atualização, submissão e listagem com filtros.
• Solicitações de folga e ajustes de agenda são gerenciadas via endpoints específicos.
• Processos de aprovação podem ser aprovados ou rejeitados via endpoints dedicados.
• Integrações externas são suportadas por endpoints específicos para publicação de dados.
• Paginação e localização são integradas para melhor experiência e performance.

9. Guia rápido de uso (exemplos)

Listar contratos

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

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"
  }
]

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

Resposta:

{
  "id": 456,
  "name": "Projeto X",
  "description": "Descrição detalhada do projeto X",
  "startDate": "2023-03-01",
  "endDate": "2023-09-30",
  "status": "em andamento"
}

Criar uma tarefa

POST /operations/tasks HTTP/1.1
Host: api.hed-hog.com
Authorization: Bearer <token_de_acesso>
Content-Type: application/json

{
  "projectId": 456,
  "name": "Desenvolvimento Backend",
  "description": "Implementar API REST",
  "status": "active"
}

Resposta:

{
  "id": 789,
  "projectId": 456,
  "name": "Desenvolvimento Backend",
  "description": "Implementar API REST",
  "status": "active"
}

Criar uma entrada de timesheet

POST /operations/timesheet-entries HTTP/1.1
Host: api.hed-hog.com
Authorization: Bearer <token_de_acesso>
Content-Type: application/json

{
  "projectId": 456,
  "taskId": 789,
  "workDate": "2024-05-20",
  "duration": 4,
  "unit": "hours",
  "description": "Desenvolvimento de endpoints"
}

Resposta:

{
  "id": 1011,
  "projectId": 456,
  "taskId": 789,
  "workDate": "2024-05-20",
  "duration": 4,
  "unit": "hours",
  "description": "Desenvolvimento de endpoints",
  "status": "draft"
}

Nota: Para acessar os endpoints, o token JWT deve conter os papéis admin ou admin-operations. Utilize os parâmetros de paginação e filtros conforme necessário para otimizar consultas.