Backend e domínio / 2025

Scheduling API

Modelar entregas é mais que guardar datas: disponibilidade, permissões e conflitos em uma API Go.

contexto: Projeto de API, código público
atuação: Desenvolvimento da API em Go
estado: Protótipo; build bloqueado
stack: Go / Gin / GORM / PostgreSQL

o que é

A API modela agendamentos entre fornecedores e funcionários. O repositório contém autenticação JWT, modelos de operação e produto, serviços de validação e consultas GORM.

o problema

Antes de aceitar uma entrega, é preciso conferir as entidades, a janela da operação e a sobreposição na agenda de funcionário e fornecedor. Uma consulta de disponibilidade isolada não garante exclusividade sob concorrência.

as restrições

Validação antes da escrita: O serviço verifica entidades e horários; o repositório verifica conflitos antes de criar o agendamento.
Dois calendários: HasConflict consulta funcionário e fornecedor, desconsiderando agendamentos cancelados.

a arquitetura

Camadas identificáveis no código do protótipo.

HTTP
internal/api
Gin, handlers e middleware JWT/RBAC.
Serviço
internal/service
Entidades, janela de operação e estado do agendamento.
Repositório
internal/repository
Consultas de conflito e escrita com GORM.
Domínio
internal/models
Agendamento, funcionário, fornecedor e operação.

Este é um mapa do código, não evidência de um serviço em produção. Há trechos truncados e o clone não compila.

decisões técnicas

Separar transporte, regra e dados
por quê
Handlers delegam ao serviço; consultas ficam no repositório. Isso explicita onde cada validação ocorre.
em vez de
Concentrar acesso a dados e regras nos handlers HTTP.
o preço
A separação ainda não tem testes que protejam seus contratos.
Consultar conflito antes de inserir
por quê
HasConflict consulta sobreposições sem carregar a agenda inteira em memória.
em vez de
Garantir exclusividade com uma constraint de exclusão no PostgreSQL.
o preço
A checagem ocorre antes da transação de escrita. Requisições simultâneas podem passar pela mesma checagem.

limites e aprendizados

O clone não compila

go.sum contém comentários inválidos. Além disso, arquivos de repositório e serviço têm trechos truncados e declarações duplicadas. O primeiro erro de build está transcrito abaixo.

Regra sem testes

O repositório não contém arquivos _test.go. A regra central precisa de casos para bordas, sobreposição, cancelamento e concorrência.

estado atual

O artefato disponível é um protótipo de backend e seu modelo de domínio. Não há evidência de implantação, uso ou desempenho. A verificação de 1 de outubro de 2026 reproduziu a falha inicial de build.

próximas questões

Restaurar os arquivos e o go.sum antes de ampliar o domínio.
Testar intervalos e concorrência; avaliar exclusão de sobreposição no banco.

evidência

go build ./... · 2026-10-01estado

malformed go.sum:
go.sum:1: wrong number of fields 7

Saída do clone; caminho absoluto omitido. Nenhum arquivo do projeto foi reparado nesta auditoria.

internal/repository/appointment_repository.go

hasConflict, err := r.HasConflict(appointment)
// ...
err = r.db.Transaction(func(tx *gorm.DB) error {
    if err := tx.Create(appointment).Error; err != nil {
        return err
    }
    return nil
})

Trecho de Create: a consulta de conflito antecede a transação. As chamadas são mostradas como excerto, não como arquivo completo.

fontes e revisão

Código revisado em 2026-10-01

Scheduling API@1b54796

a seguir: PsyPredict