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