Skip to content

Translate project documentation to English #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Matheus-TecDev merged 6 commits into from
Jul 10, 2026
Merged

Translate project documentation to English #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
044fb07
Translate README to English
Matheus-TecDev Jul 10, 2026
13c1dd8
Translate architecture documentation to English
Matheus-TecDev Jul 10, 2026
b0ec0b4
Translate API documentation to English
Matheus-TecDev Jul 10, 2026
8b142a7
Translate authentication documentation to English
Matheus-TecDev Jul 10, 2026
7951542
Translate ticket workflow documentation to English
Matheus-TecDev Jul 10, 2026
32d41d0
Translate observability documentation to English
Matheus-TecDev Jul 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 77 additions & 77 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`
Expand All @@ -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
Expand All @@ -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.
86 changes: 43 additions & 43 deletions docs/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,69 +1,69 @@
# 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`;
- `/api/sectors`;
- `/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.
Loading
Loading