Visão geral
Requisitos, relatos de erro e pedidos de melhoria chegavam à equipa de desenvolvimento por e-mail, folhas de cálculo e conversas de corredor, pelo que nada tinha responsável, prioridade ou histórico fiáveis. Esta plataforma dá a cada pedido um registo único, a partir do qual a equipa trabalha e que a gestão consegue ler sem andar a perguntar. Os utilizadores são os programadores, testadores e responsáveis de uma equipa de TI que acompanha vários produtos ao mesmo tempo.
A minha contribuição
Construí a API REST em Python com FastAPI, desenhei o modelo relacional em PostgreSQL e implementei a interface web e as vistas de relatório. Isso inclui o ciclo de vida do pedido e a sua máquina de estados, as regras de perfis e permissões, o agrupamento em lotes, o fluxo de comentários e anexos, a tarefa agendada de notificações e as consultas do painel e do ranking.
O código é privado e pertence à organização, por isso esta página descreve comportamento e decisões em vez de apontar para o repositório. As capturas de ecrã abaixo vêm da aplicação em funcionamento.
O que muda no dia a dia
- Rastreabilidade: cada pedido fica registado com responsável, prazos e evolução, pelo que a informação vive num único sítio que se encontra.
- Entrada controlada: criar uma demanda é reservado aos perfis de gestão e administração — regra explícita do produto que corta filas informais e mantém a equipa no que foi acordado.
- Quadro e indicadores: uma vista Kanban para quem executa, resumos e gráficos para quem decide, com painéis que a administração pode adaptar, incluindo que blocos aparecem na página inicial.
- Trabalho agrupado: os lotes reúnem demandas do mesmo tema ou entrega, para serem planeadas e comunicadas em bloco.
- Conversa junto do pedido: comentários e anexos ficam ligados à demanda, e as notificações e o e-mail avisam quem precisa de agir.
- Esforço visível: o ranking e o registo de atividades tornam legíveis o esforço e o ritmo da equipa ao longo do tempo.
Arquitetura
Um front end estático e uma API REST servidos a partir de uma única origem, atrás de um proxy reverso, com o PostgreSQL como única fonte de verdade. A API está dividida em routers, serviços e repositórios; ao lado dela corre uma tarefa agendada que envia notificações de prazo e de atribuição.
Stack
- Backend: API REST em Python com FastAPI; serviços e repositórios separados; tarefas agendadas para notificações.
- Front end: páginas modulares escritas em TypeScript, Bootstrap para o layout e gráficos interativos para os indicadores.
- Dados: PostgreSQL — modelo relacional com integridade referencial entre demandas, lotes, utilizadores, comentários e histórico.
Como o trabalho flui
- Quadro Kanban por estado — mover um cartão reflete o avanço real do pedido.
- Lotes agrupam demandas da mesma entrega ou tema.
- Entrada formal reservada aos perfis de gestão e administração, para que prioridade e prazo fiquem explícitos desde o registo.
- Painel e ranking traduzem esforço e ritmo em números que a liderança pode acompanhar.
Entrega
- Autenticação: JWT em cookie HttpOnly para o cliente web; a API também aceita cabeçalho Bearer para integrações. Tentativas de entrada falhadas em série são limitadas.
- Contrato da API: endpoints REST documentados, com o explorador interativo OpenAPI/Swagger ativo nos ambientes adequados.
- Implantação: instalação passo a passo num servidor novo — PostgreSQL, build, proxy reverso — cobrindo hosts Windows e Linux.
Decisões de engenharia
1. Restringir a criação de demandas aos perfis de gestão
- Decisão:
- apenas os perfis de gestão e administração podem abrir uma demanda; programadores e testadores trabalham sobre o que já existe.
- Alternativa:
- deixar qualquer pessoa abrir uma demanda e confiar numa triagem posterior para definir prioridade.
- Motivo:
- o problema a resolver era precisamente a fila de entrada informal. Aplicar a regra na camada de permissões, e não num documento de processo, é o que a elimina de facto.
- Limitação:
- quem deteta um problema mas não pode abrir uma demanda tem de passar por alguém que possa, o que acrescenta um passo.
2. JWT em cookie HttpOnly, com Bearer como segundo caminho
- Decisão:
- o browser recebe o token num cookie HttpOnly; a mesma API aceita um cabeçalho
Authorization: Bearerpara integrações. - Alternativa:
- guardar o token em
localStorage, o que é mais simples de tratar no front end. - Motivo:
- um cookie HttpOnly não é legível pelos scripts da página, o que elimina a forma mais comum de um token vazar; servir o front end e a API na mesma origem evita lidar com cookies entre origens.
- Limitação:
- a autenticação por cookie exige proteção própria contra pedidos entre sites, e o caminho Bearer tem de ficar reservado a integrações, sem se tornar uma segunda rota de entrada para o browser.
3. Manter o histórico no modelo relacional
- Decisão:
- mudanças de estado, comentários e atribuições ficam registados como linhas em PostgreSQL, com integridade referencial para a demanda.
- Alternativa:
- registos de aplicação, ou um armazenamento de documentos para eventos de atividade.
- Motivo:
- "quem mudou o quê e quando" tem de ser consultável junto da própria demanda, e os relatórios filtram os mesmos dados por intervalo de datas, estado, sistema e responsável.
- Limitação:
- as tabelas de histórico crescem com a atividade e exigem manutenção de índices e uma política de arquivo ao longo do tempo.
Resultados e limitações
O que o sistema entrega está descrito acima e visível nas capturas: um registo único por pedido, um quadro que reflete o estado real, agrupamento em lotes, relatórios filtrados por intervalo de datas, estado, sistema e responsável, e painéis para a liderança. O catálogo de sistemas é administrável, o que importa quando uma equipa acompanha vários produtos no mesmo quadro.
Limitações declaradas
- Sem métricas publicadas. Não fiz uma medição controlada de antes e depois, por isso não se alega aqui qualquer ganho percentual, redução de tempo de ciclo ou número de adoção.
- O código é privado. O repositório pertence à organização e não é público, pelo que o código por trás desta página não pode ser revisto. Só estão disponíveis as capturas e esta descrição.
- Sem demonstração pública. O sistema corre dentro da rede da organização; não há instância hospedada para experimentar.
- Interface em português. A aplicação foi construída para utilizadores de língua portuguesa; as capturas refletem isso.
Galeria
Capturas de ecrã da aplicação em uso — selecione uma imagem para ampliar e percorrer a galeria.
Entrada e sessão.
Painel para a gestão.
Lista de demandas e detalhe do pedido.
Lotes e entregas agrupadas.
Ranking e atividade da equipa.
Estimativa de esforço e prioridade.
Quadro Kanban por estado.