From 044fb078b04943902c4e6973c67eb0326c628f6d Mon Sep 17 00:00:00 2001 From: Matheus Freire | Backend & Infra Date: Fri, 10 Jul 2026 07:14:49 -0300 Subject: [PATCH 1/6] Translate README to English --- README.md | 154 +++++++++++++++++++++++++++--------------------------- 1 file changed, 77 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index 38b16bf..395d514 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,54 @@ # Central de Chamados -Central de Chamados é uma plataforma full stack para gestão de atendimento interno e suporte técnico, construída com FastAPI, PostgreSQL, React, Docker e ferramentas de observabilidade. +Central de Chamados is a full-stack platform for internal service desk and technical support management, built with FastAPI, PostgreSQL, React, Docker, and observability tooling. -O sistema organiza a abertura, atribuição e acompanhamento de chamados, aplica controle de acesso por perfil e mantém uma trilha de auditoria das operações. +The system structures ticket creation, assignment, and tracking, enforces role-based access control, and maintains an audit trail of operational changes. -## Tecnologias +## Technology Stack -| Área | Tecnologias | +| Area | Technologies | | --- | --- | | Backend | Python, FastAPI, SQLAlchemy, Alembic, Pydantic, Pytest | | Frontend | React, TypeScript, Vite, React Router | -| Dados | PostgreSQL | -| Segurança | JWT, RBAC | -| Observabilidade | Prometheus, Grafana, logs estruturados | -| Infraestrutura | Docker Compose, Nginx, GitHub Actions | +| Data | PostgreSQL | +| Security | JWT, RBAC | +| Observability | Prometheus, Grafana, structured logs | +| Infrastructure | Docker Compose, Nginx, GitHub Actions | -## Problema +## Problem -Solicitações internas tratadas por mensagens e conversas isoladas perdem contexto, responsáveis e histórico. A Central de Chamados estrutura esse fluxo em uma aplicação única, com estados definidos, atribuição técnica, comentários, anexos e auditoria. +Internal requests handled through isolated messages and conversations lose context, ownership, and history. Central de Chamados structures this process in a single application with defined states, technical assignment, comments, attachments, and auditing. -## Funcionalidades +## Features -- Abertura e acompanhamento de chamados. -- Atribuição e atendimento por técnicos. -- Fluxo de status operacional. -- Comentários e anexos. -- Histórico e trilha de auditoria. -- Gestão de usuários, categorias, setores e áreas de suporte. -- Filtros e dashboard operacional. -- Autenticação JWT e controle de acesso por perfil. -- Métricas Prometheus e dashboard Grafana. -- Proxy reverso com Nginx. -- Testes automatizados de backend. -- CI com testes, typecheck e build. +- Ticket creation and tracking. +- Assignment and handling by technicians. +- Operational status workflow. +- Comments and attachments. +- History and audit trail. +- Management of users, categories, departments, and support areas. +- Filters and operational dashboard. +- JWT authentication and role-based access control. +- Prometheus metrics and Grafana dashboard. +- Nginx reverse proxy. +- Automated backend tests. +- CI pipeline with tests, type checking, and build validation. -## Arquitetura +## Architecture ```text -Usuário -> Nginx -> React - -> FastAPI -> PostgreSQL - | - +-> Anexos persistentes +User -> Nginx -> React + -> FastAPI -> PostgreSQL + | + +-> Persistent attachments Prometheus -> FastAPI Grafana -> Prometheus ``` -## Fluxo dos chamados +## Ticket Workflow -Estados suportados: +Supported states: - `ABERTO` - `EM_ANDAMENTO` @@ -57,76 +57,76 @@ Estados suportados: - `CONCLUIDO` - `CANCELADO` -As alterações relevantes são registradas na trilha de auditoria. +Relevant changes are recorded in the audit trail. -## Perfis de acesso +## Access Roles -| Perfil | Permissões | +| Role | Permissions | | --- | --- | -| `ADMIN` | Gerencia usuários, cadastros auxiliares e todos os chamados | -| `TECNICO` | Assume chamados, atualiza status, comenta e conclui atendimentos | -| `SOLICITANTE` | Abre chamados e acompanha as próprias solicitações | +| `ADMIN` | Manages users, reference data, and all tickets | +| `TECNICO` | Claims tickets, updates status, comments, and completes requests | +| `SOLICITANTE` | Creates tickets and tracks their own requests | -## Como executar +## Running Locally ```bash cp .env.example .env docker compose up -d --build ``` -URLs principais: +Main URLs: -- Aplicação: http://localhost +- Application: http://localhost - API: http://localhost/api -- Swagger: http://localhost/docs +- Swagger UI: http://localhost/docs - Health check: http://localhost/api/health -- Métricas: http://localhost/metrics +- Metrics: http://localhost/metrics - Prometheus: http://localhost:9090 - Grafana: http://localhost:3000 ## Endpoints -| Método | Endpoint | Descrição | +| Method | Endpoint | Description | | --- | --- | --- | -| `POST` | `/api/auth/login` | Autentica o usuário | -| `POST` | `/api/auth/register` | Cadastra um solicitante | -| `GET` | `/api/auth/me` | Retorna o usuário autenticado | -| `GET` | `/api/tickets` | Lista os chamados permitidos ao perfil | -| `POST` | `/api/tickets` | Abre um chamado | -| `GET` | `/api/tickets/{id}` | Detalha um chamado | -| `PUT` | `/api/tickets/{id}` | Atualiza um chamado | -| `POST` | `/api/tickets/{id}/comments` | Adiciona um comentário | -| `POST` | `/api/tickets/{id}/attachments` | Envia um anexo | -| `GET` | `/api/users` | Lista usuários | -| `POST` | `/api/users` | Cria um usuário | -| `GET` | `/api/categories` | Lista categorias | -| `GET` | `/api/sectors` | Lista setores | -| `GET` | `/api/dashboard/metrics` | Retorna métricas operacionais | -| `GET` | `/api/health` | Verifica a saúde da API | -| `GET` | `/metrics` | Expõe métricas Prometheus | - -## Estrutura +| `POST` | `/api/auth/login` | Authenticates a user | +| `POST` | `/api/auth/register` | Registers a requester | +| `GET` | `/api/auth/me` | Returns the authenticated user | +| `GET` | `/api/tickets` | Lists tickets visible to the current role | +| `POST` | `/api/tickets` | Creates a ticket | +| `GET` | `/api/tickets/{id}` | Returns ticket details | +| `PUT` | `/api/tickets/{id}` | Updates a ticket | +| `POST` | `/api/tickets/{id}/comments` | Adds a comment | +| `POST` | `/api/tickets/{id}/attachments` | Uploads an attachment | +| `GET` | `/api/users` | Lists users | +| `POST` | `/api/users` | Creates a user | +| `GET` | `/api/categories` | Lists categories | +| `GET` | `/api/sectors` | Lists departments | +| `GET` | `/api/dashboard/metrics` | Returns operational metrics | +| `GET` | `/api/health` | Checks API health | +| `GET` | `/metrics` | Exposes Prometheus metrics | + +## Project Structure ```text -backend/ API, regras de negócio, persistência e testes -frontend/ Interface web em React -nginx/ Proxy reverso -prometheus/ Coleta de métricas -grafana/ Datasource e dashboard provisionados -.github/ Pipeline de integração contínua +backend/ API, business rules, persistence, and tests +frontend/ React web interface +nginx/ Reverse proxy +prometheus/ Metrics collection +grafana/ Provisioned data source and dashboard +.github/ Continuous integration pipeline ``` -## Documentação +## Documentation -| Documento | Conteúdo | +| Document | Coverage | | --- | --- | -| [Arquitetura](docs/architecture.md) | Componentes, domínio, persistência e limitações | -| [API](docs/api.md) | Endpoints, filtros, anexos e erros | -| [Autenticação e RBAC](docs/authentication-and-rbac.md) | JWT, visibilidade e matriz de permissões | -| [Fluxo de chamados](docs/ticket-workflow.md) | Criação, estados, atribuição e auditoria | -| [Observabilidade](docs/observability.md) | Métricas, logs, health checks e lacunas | +| [Architecture](docs/architecture.md) | Components, domain model, persistence, and limitations | +| [API](docs/api.md) | Endpoints, filters, attachments, and errors | +| [Authentication and RBAC](docs/authentication-and-rbac.md) | JWT, visibility rules, and permission matrix | +| [Ticket workflow](docs/ticket-workflow.md) | Creation, states, assignment, and auditing | +| [Observability](docs/observability.md) | Metrics, logs, health checks, and current gaps | -## Validação +## Validation ```bash cd backend @@ -139,10 +139,10 @@ npm run typecheck npm run build ``` -O pipeline executa automaticamente os testes do backend, o typecheck e o build do frontend. +The CI pipeline automatically runs backend tests, frontend type checking, and the frontend build. ## Status -**MVP concluído.** +**MVP complete.** -O primeiro escopo cobre autenticação, RBAC, fluxo completo de chamados, comentários, anexos, auditoria, dashboard, observabilidade e execução containerizada. SLA, notificações em tempo real e deploy automatizado permanecem como evoluções futuras. +The initial scope covers authentication, RBAC, the complete ticket workflow, comments, attachments, auditing, the operational dashboard, observability, and containerized execution. SLAs, real-time notifications, and automated deployment remain planned improvements. From 13c1dd8aa6b44625826b6da2c16c25d8a7addc47 Mon Sep 17 00:00:00 2001 From: Matheus Freire | Backend & Infra Date: Fri, 10 Jul 2026 07:15:07 -0300 Subject: [PATCH 2/6] Translate architecture documentation to English --- docs/architecture.md | 84 ++++++++++++++++++++++---------------------- 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index d1895f9..afeb128 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,59 +1,59 @@ -# Arquitetura +# Architecture -## Visão geral +## Overview -A Central de Chamados é uma aplicação full stack containerizada. O Nginx publica a interface e encaminha requisições para a API. A API FastAPI aplica autenticação, autorização e regras do fluxo de chamados, persistindo os dados no PostgreSQL. +Central de Chamados is a containerized full-stack application. Nginx serves the interface and forwards requests to the API. The FastAPI backend enforces authentication, authorization, and ticket workflow rules while persisting data in PostgreSQL. ```text -Cliente -> Nginx -> Frontend React - -> API FastAPI -> PostgreSQL - | - +-> volume de anexos +Client -> Nginx -> React frontend + -> FastAPI API -> PostgreSQL + | + +-> attachment volume Prometheus -> API Grafana -> Prometheus ``` -## Componentes +## Components -| Componente | Responsabilidade | +| Component | Responsibility | | --- | --- | -| Frontend | Interface de solicitantes, técnicos e administradores | -| Nginx | Entrada única e proxy reverso | -| FastAPI | API, RBAC, regras de chamados, auditoria e uploads | -| PostgreSQL | Dados relacionais e histórico | -| Volume `ticket_uploads` | Arquivos enviados aos chamados | -| Prometheus | Coleta das métricas HTTP | -| Grafana | Visualização das métricas | +| Frontend | Interface for requesters, technicians, and administrators | +| Nginx | Single entry point and reverse proxy | +| FastAPI | API, RBAC, ticket rules, auditing, and uploads | +| PostgreSQL | Relational data and history | +| `ticket_uploads` volume | Files attached to tickets | +| Prometheus | HTTP metrics collection | +| Grafana | Metrics visualization | -## Organização do backend +## Backend Organization ```text app/ - api/routes/ Endpoints por domínio - core/ Configuração, banco, segurança, enums e erros - models/ Entidades SQLAlchemy - repositories/ Consultas, filtros e regras de visibilidade - schemas/ Contratos Pydantic - services/ Regras de negócio e transações + api/routes/ Domain-specific endpoints + core/ Configuration, database, security, enums, and errors + models/ SQLAlchemy entities + repositories/ Queries, filters, and visibility rules + schemas/ Pydantic contracts + services/ Business rules and transactions ``` -As rotas tratam HTTP e dependências; repositories constroem consultas e visibilidade; services validam regras, persistem alterações e criam registros de auditoria. +Routes handle HTTP concerns and dependencies; repositories build queries and enforce visibility; services validate rules, persist changes, and create audit records. -## Inicialização +## Initialization -No startup, a aplicação cria dados iniciais quando ausentes: +At startup, the application creates initial data when missing: -- categorias; -- setores; -- áreas e tipos de suporte; -- administrador inicial. +- categories; +- departments; +- support areas and types; +- initial administrator. -As migrações são aplicadas pelo comando do container antes do Uvicorn. +The container applies migrations before starting Uvicorn. -## Modelo de domínio +## Domain Model -Principais entidades: +Main entities: - `User`; - `Ticket`; @@ -65,16 +65,16 @@ Principais entidades: - `TicketAttachment`; - `TicketAudit`. -O chamado referencia solicitante, técnico responsável, categoria, setor, área e tipo de suporte. Comentários, anexos e auditorias pertencem ao chamado. +A ticket references its requester, assigned technician, category, department, support area, and support type. Comments, attachments, and audit records belong to the ticket. -## Persistência de anexos +## Attachment Persistence -Os metadados ficam no PostgreSQL. Os bytes são salvos no volume local com nome interno UUID, preservando o nome original apenas como metadado. +Metadata is stored in PostgreSQL. File contents are saved in the local volume under an internal UUID-based name, while the original filename is preserved only as metadata. -## Limitações atuais +## Current Limitations -- Os anexos dependem de filesystem compartilhado e não suportam múltiplas réplicas sem storage externo. -- Seed e API compartilham o mesmo processo de inicialização. -- Não há processamento assíncrono nem notificações em tempo real. -- Não há SLA automatizado. -- O ambiente atual é Docker Compose, sem infraestrutura cloud declarada. +- Attachments depend on a shared filesystem and do not support multiple replicas without external storage. +- Seed operations and the API share the same initialization process. +- There is no asynchronous processing or real-time notification mechanism. +- SLAs are not automated. +- The current environment uses Docker Compose and has no declared cloud infrastructure. From b0ec0b488b975a67bc870b26005fe6c1b3d2ddc7 Mon Sep 17 00:00:00 2001 From: Matheus Freire | Backend & Infra Date: Fri, 10 Jul 2026 07:15:26 -0300 Subject: [PATCH 3/6] Translate API documentation to English --- docs/api.md | 86 ++++++++++++++++++++++++++--------------------------- 1 file changed, 43 insertions(+), 43 deletions(-) diff --git a/docs/api.md b/docs/api.md index 2eb4a8c..249e06e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,36 +1,36 @@ # API -A API usa o prefixo `/api`. O login utiliza formulário OAuth2 e retorna um Bearer token. +The API uses the `/api` prefix. Login follows the OAuth2 form flow and returns a Bearer token. -## Autenticação +## Authentication -| Método | Endpoint | Acesso | Descrição | +| Method | Endpoint | Access | Description | | --- | --- | --- | --- | -| POST | `/api/auth/login` | Público | Autentica por usuário e senha | -| POST | `/api/auth/register` | Público | Registra um `SOLICITANTE` | -| GET | `/api/auth/me` | Autenticado | Retorna usuário atual | +| POST | `/api/auth/login` | Public | Authenticates with username and password | +| POST | `/api/auth/register` | Public | Registers a `SOLICITANTE` | +| GET | `/api/auth/me` | Authenticated | Returns the current user | -O registro público força o perfil `SOLICITANTE`, ignorando um perfil diferente enviado pelo cliente. +Public registration always enforces the `SOLICITANTE` role, ignoring any different role submitted by the client. -## Chamados +## Tickets -| Método | Endpoint | Descrição | -| --- | --- | -| GET | `/api/tickets` | Lista chamados visíveis com filtros e paginação | -| POST | `/api/tickets` | Abre chamado | -| GET | `/api/tickets/{ticket_id}` | Retorna detalhes | -| PUT | `/api/tickets/{ticket_id}` | Atualiza conforme o perfil | -| POST | `/api/tickets/{ticket_id}/comments` | Adiciona comentário | -| POST | `/api/tickets/{ticket_id}/attachments` | Envia anexos | -| GET | `/api/tickets/{ticket_id}/attachments/{attachment_id}` | Baixa anexo | +| Method | Endpoint | Description | +| --- | --- | --- | +| GET | `/api/tickets` | Lists visible tickets with filters and pagination | +| POST | `/api/tickets` | Creates a ticket | +| GET | `/api/tickets/{ticket_id}` | Returns ticket details | +| PUT | `/api/tickets/{ticket_id}` | Updates a ticket according to the current role | +| POST | `/api/tickets/{ticket_id}/comments` | Adds a comment | +| POST | `/api/tickets/{ticket_id}/attachments` | Uploads attachments | +| GET | `/api/tickets/{ticket_id}/attachments/{attachment_id}` | Downloads an attachment | -Filtros disponíveis: status, categoria, setor, área, tipo, prioridade, responsável, solicitante, texto e intervalo de criação. A paginação aceita até 100 itens por página. +Available filters include status, category, department, support area, support type, priority, assignee, requester, free text, and creation date range. Pagination accepts up to 100 items per page. -## Administração +## Administration -Usuários, categorias, setores, áreas e tipos possuem operações administrativas. Consultas auxiliares exigem autenticação; criação, atualização e desativação exigem `ADMIN`. +Users, categories, departments, support areas, and support types expose administrative operations. Reference-data queries require authentication; creation, updates, and deactivation require the `ADMIN` role. -Principais grupos: +Main route groups: - `/api/users`; - `/api/categories`; @@ -38,32 +38,32 @@ Principais grupos: - `/api/support-areas`; - `/api/support-types`. -Exclusões administrativas são desativações lógicas por `is_active=false`. +Administrative deletions are implemented as logical deactivation with `is_active=false`. -## Dashboard e saúde +## Dashboard and Health -| Método | Endpoint | Descrição | -| --- | --- | -| GET | `/api/dashboard/metrics` | Métricas respeitando a visibilidade do usuário | -| GET | `/api/health` | Saúde do processo | -| GET | `/api/health/db` | Valida conexão com o banco | -| GET | `/metrics` | Métricas Prometheus | +| Method | Endpoint | Description | +| --- | --- | --- | +| GET | `/api/dashboard/metrics` | Returns metrics under the current user's visibility rules | +| GET | `/api/health` | Checks process health | +| GET | `/api/health/db` | Validates the database connection | +| GET | `/metrics` | Exposes Prometheus metrics | -O dashboard agrega total, estados, chamados sem responsável e distribuições por categoria, setor, área, tipo e prioridade. +The dashboard aggregates totals, states, unassigned tickets, and distributions by category, department, support area, support type, and priority. -## Anexos +## Attachments -- somente imagens e vídeos; -- limite configurável, padrão de 25 MB por arquivo; -- arquivos vazios são rejeitados; -- o download verifica se o anexo pertence ao chamado visível; -- nomes internos são UUIDs. +- only images and videos are accepted; +- the configurable default limit is 25 MB per file; +- empty files are rejected; +- downloads verify that the attachment belongs to a ticket visible to the current user; +- internal filenames are UUIDs. -## Erros +## Errors -- `400`: regra de negócio ou cadastro inativo; -- `401`: token inválido ou usuário inativo; -- `403`: operação incompatível com o perfil; -- `404`: recurso não encontrado; -- `413`: anexo acima do limite; -- `422`: payload inválido. +- `400`: business rule violation or inactive reference data; +- `401`: invalid token or inactive user; +- `403`: operation not allowed for the current role; +- `404`: resource not found; +- `413`: attachment exceeds the size limit; +- `422`: invalid payload. From 8b142a78dfb88bb5a6305fa37e03d4e7d98bcec4 Mon Sep 17 00:00:00 2001 From: Matheus Freire | Backend & Infra Date: Fri, 10 Jul 2026 07:15:45 -0300 Subject: [PATCH 4/6] Translate authentication documentation to English --- docs/authentication-and-rbac.md | 74 ++++++++++++++++----------------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/docs/authentication-and-rbac.md b/docs/authentication-and-rbac.md index a2c9e2f..ba5d07c 100644 --- a/docs/authentication-and-rbac.md +++ b/docs/authentication-and-rbac.md @@ -1,52 +1,52 @@ -# Autenticação e RBAC +# Authentication and RBAC -## Autenticação +## Authentication -1. O cliente envia formulário OAuth2 para `POST /api/auth/login`. -2. A API valida as credenciais. -3. Um JWT HS256 é emitido com expiração configurável. -4. O token é enviado como `Authorization: Bearer `. -5. A API decodifica o token e carrega o usuário pelo `sub`. -6. Usuários ausentes ou inativos recebem `401`. +1. The client submits an OAuth2 form to `POST /api/auth/login`. +2. The API validates the credentials. +3. An HS256 JWT is issued with a configurable expiration. +4. The token is sent as `Authorization: Bearer `. +5. The API decodes the token and loads the user identified by `sub`. +6. Missing or inactive users receive `401`. -As senhas são armazenadas com bcrypt por meio do Passlib. +Passwords are hashed with bcrypt through Passlib. -## Perfis +## Roles -| Capacidade | ADMIN | TECNICO | SOLICITANTE | +| Capability | ADMIN | TECNICO | SOLICITANTE | | --- | :---: | :---: | :---: | -| Gerenciar usuários e cadastros | Sim | Não | Não | -| Visualizar todos os chamados | Sim | Não | Não | -| Visualizar chamados atribuídos ou livres | Sim | Sim | Não | -| Visualizar os próprios chamados | Sim | Não | Sim | -| Criar chamados | Sim | Não | Sim | -| Assumir chamado livre | Sim | Sim | Não | -| Alterar status | Sim | Sim | Não | -| Alterar dados descritivos | Sim | Não | Sim, nos próprios | -| Comentar e anexar em chamado visível | Sim | Sim | Sim | +| Manage users and reference data | Yes | No | No | +| View all tickets | Yes | No | No | +| View assigned or unassigned tickets | Yes | Yes | No | +| View own tickets | Yes | No | Yes | +| Create tickets | Yes | No | Yes | +| Claim an unassigned ticket | Yes | Yes | No | +| Change status | Yes | Yes | No | +| Change descriptive fields | Yes | No | Yes, on own tickets | +| Comment and attach files to visible tickets | Yes | Yes | Yes | -## Visibilidade +## Visibility -- `ADMIN`: todos os chamados; -- `TECNICO`: chamados atribuídos a ele ou sem responsável; -- `SOLICITANTE`: somente chamados criados por ele. +- `ADMIN`: all tickets; +- `TECNICO`: tickets assigned to the technician or currently unassigned; +- `SOLICITANTE`: only tickets created by the requester. -A mesma consulta de visibilidade é reutilizada na listagem, detalhes e dashboard. +The same visibility query is reused for ticket lists, details, and dashboard metrics. -## Regras de atualização +## Update Rules -- Solicitantes só alteram campos descritivos e de classificação. -- Técnicos só alteram status e responsável. -- Um técnico só pode assumir para si um chamado ainda sem responsável. -- O responsável precisa existir, estar ativo e possuir perfil `TECNICO`. -- Administradores não sofrem essas restrições específicas de campo. +- Requesters may change only descriptive and classification fields. +- Technicians may change only status and assignee. +- A technician may claim only an unassigned ticket and only for themselves. +- The assignee must exist, be active, and have the `TECNICO` role. +- Administrators are not subject to these role-specific field restrictions. -## Registro público +## Public Registration -`POST /api/auth/register` sempre cria `SOLICITANTE`. Perfis privilegiados são criados pela administração. +`POST /api/auth/register` always creates a `SOLICITANTE`. Privileged roles are created through administrative operations. -## Limitações atuais +## Current Limitations -- Não há refresh token, MFA ou revogação individual. -- Tokens válidos continuam utilizáveis até expirar, salvo se o usuário for desativado. -- TLS depende do ambiente de implantação. +- There are no refresh tokens, MFA, or per-token revocation. +- Valid tokens remain usable until expiration unless the user is deactivated. +- TLS depends on the deployment environment. From 7951542beef697a4412f93884a7928d01a22c7af Mon Sep 17 00:00:00 2001 From: Matheus Freire | Backend & Infra Date: Fri, 10 Jul 2026 07:16:06 -0300 Subject: [PATCH 5/6] Translate ticket workflow documentation to English --- docs/ticket-workflow.md | 78 ++++++++++++++++++++--------------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/docs/ticket-workflow.md b/docs/ticket-workflow.md index 4d667e8..4887307 100644 --- a/docs/ticket-workflow.md +++ b/docs/ticket-workflow.md @@ -1,20 +1,20 @@ -# Fluxo de chamados +# Ticket Workflow -## Criação +## Creation -`ADMIN` e `SOLICITANTE` podem abrir chamados. O perfil `TECNICO` é bloqueado nessa operação. +`ADMIN` and `SOLICITANTE` users may create tickets. The `TECNICO` role is not allowed to perform this operation. -A criação valida: +Ticket creation validates: -- categoria ativa; -- setor ativo; -- área de suporte ativa; -- tipo de suporte ativo e pertencente à área; -- prioridade e descrição. +- active category; +- active department; +- active support area; +- active support type belonging to the selected area; +- priority and description. -Quando a categoria não é informada, a aplicação utiliza `OUTROS`. O status inicial é `ABERTO` e a auditoria registra `CHAMADO_CRIADO`. +When no category is provided, the application uses `OUTROS`. The initial status is `ABERTO`, and the audit trail records `CHAMADO_CRIADO`. -## Estados +## States - `ABERTO`; - `EM_ANDAMENTO`; @@ -23,46 +23,46 @@ Quando a categoria não é informada, a aplicação utiliza `OUTROS`. O status i - `CONCLUIDO`; - `CANCELADO`. -O serviço aceita alterações de status conforme a permissão do perfil. Não existe, nesta versão, uma máquina de estados que restrinja formalmente cada transição entre esses valores. +The service accepts status changes according to role permissions. This version does not implement a formal state machine that restricts each transition between these values. -Ao chegar em `CONCLUIDO`, `resolved_at` é preenchido. Em `CONCLUIDO` ou `CANCELADO`, `closed_at` é preenchido. Esses horários não são recalculados depois de definidos. +When a ticket reaches `CONCLUIDO`, `resolved_at` is populated. When it reaches `CONCLUIDO` or `CANCELADO`, `closed_at` is populated. These timestamps are not recalculated after being set. -## Atribuição +## Assignment -- O responsável deve ser um técnico ativo. -- Técnicos visualizam chamados livres ou atribuídos a eles. -- Um técnico só pode assumir um chamado livre e somente para si. -- Administradores podem administrar a atribuição. +- The assignee must be an active technician. +- Technicians can view unassigned tickets and tickets assigned to them. +- A technician may claim only an unassigned ticket and only for themselves. +- Administrators may manage assignments without those restrictions. -## Comentários +## Comments -Qualquer usuário com acesso ao chamado pode comentar. A operação cria `TicketComment` e auditoria `COMENTARIO_ADICIONADO`. +Any user with access to a ticket may add comments. The operation creates a `TicketComment` and the `COMENTARIO_ADICIONADO` audit event. -## Anexos +## Attachments -Qualquer usuário com acesso ao chamado pode enviar imagens ou vídeos. Cada arquivo: +Any user with access to a ticket may upload images or videos. Each file: -1. é validado por content type e tamanho; -2. recebe nome interno UUID; -3. é salvo no volume de uploads; -4. tem metadados persistidos no banco. +1. is validated by content type and size; +2. receives an internal UUID-based name; +3. is stored in the uploads volume; +4. has its metadata persisted in the database. -A operação gera auditoria `ANEXO_ADICIONADO`. +The operation creates the `ANEXO_ADICIONADO` audit event. -## Auditoria +## Auditing -A tabela `ticket_audits` registra: +The `ticket_audits` table records: -- chamado; -- ator; -- ação; -- campo alterado; -- valor anterior; -- valor novo; -- data. +- ticket; +- actor; +- action; +- changed field; +- previous value; +- new value; +- timestamp. -Alterações de status usam `STATUS_ALTERADO`; outras alterações usam `CAMPO_ATUALIZADO`. +Status changes use `STATUS_ALTERADO`; other changes use `CAMPO_ATUALIZADO`. -## Busca e dashboard +## Search and Dashboard -A listagem suporta filtros combináveis e paginação. O dashboard utiliza a mesma regra de visibilidade, evitando apresentar agregações de chamados que o usuário não poderia consultar. +Ticket lists support combinable filters and pagination. The dashboard uses the same visibility rules, preventing users from seeing aggregates for tickets they would not be allowed to query. From 32d41d05dddc776ef4c8c660693faf8517c749aa Mon Sep 17 00:00:00 2001 From: Matheus Freire | Backend & Infra Date: Fri, 10 Jul 2026 07:16:18 -0300 Subject: [PATCH 6/6] Translate observability documentation to English --- docs/observability.md | 66 +++++++++++++++++++++---------------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/observability.md b/docs/observability.md index 82769b4..80528e8 100644 --- a/docs/observability.md +++ b/docs/observability.md @@ -1,52 +1,52 @@ -# Observabilidade +# Observability -## Métricas +## Metrics -A API usa `prometheus-fastapi-instrumentator` e expõe métricas em `/metrics`. +The API uses `prometheus-fastapi-instrumentator` and exposes metrics at `/metrics`. -O Prometheus coleta o backend e permite acompanhar métricas HTTP como volume, status e latência. O Grafana é iniciado com datasource e dashboard provisionados. +Prometheus scrapes the backend and tracks HTTP metrics such as request volume, response status, and latency. Grafana starts with a provisioned data source and dashboard. ## Logs -O backend usa logging da biblioteca padrão com timestamp, nível, logger e mensagem. +The backend uses Python's standard logging library with timestamp, level, logger, and message fields. -Eventos relevantes incluem: +Relevant events include: -- criação e atualização de chamado; -- comentários e anexos; -- tentativas de operações proibidas; -- criação do administrador inicial. +- ticket creation and updates; +- comments and attachments; +- attempts to perform forbidden operations; +- initial administrator creation. -Alguns registros incluem contexto adicional, como `ticket_id`, `actor_id`, campos alterados e quantidade de anexos. +Some records include additional context such as `ticket_id`, `actor_id`, changed fields, and attachment count. -## Health checks +## Health Checks -| Endpoint | Verificação | +| Endpoint | Check | | --- | --- | -| `/api/health` | Processo da API respondendo | -| `/api/health/db` | Execução de `SELECT 1` no banco | -| `/metrics` | Exposição das métricas | +| `/api/health` | API process is responding | +| `/api/health/db` | Executes `SELECT 1` against the database | +| `/metrics` | Metrics endpoint is available | -No Docker Compose: +In Docker Compose: -- PostgreSQL usa `pg_isready`; -- backend consulta seu health endpoint; -- Nginx aguarda backend saudável; -- Prometheus inicia após o backend estar saudável. +- PostgreSQL uses `pg_isready`; +- the backend calls its health endpoint; +- Nginx waits for the backend to become healthy; +- Prometheus starts after the backend is healthy. -## Persistência +## Persistence -Volumes preservam: +Volumes preserve: -- PostgreSQL; -- anexos; -- dados do Prometheus; -- configuração e estado do Grafana. +- PostgreSQL data; +- attachments; +- Prometheus data; +- Grafana configuration and state. -## Limitações +## Limitations -- Não há agregação de logs com Loki. -- Não há tracing distribuído. -- Não há Alertmanager nem regras de alerta. -- Não há métricas de negócio específicas além do dashboard da aplicação. -- Não há definição formal de SLOs. +- Logs are not aggregated with Loki. +- Distributed tracing is not implemented. +- Alertmanager and alerting rules are not configured. +- There are no dedicated business metrics beyond the application dashboard. +- SLOs are not formally defined.