Conceitos
Entender o modelo de dados do CloudTasks facilita tudo: desde configurar permissões até usar a API. Esta página explica cada entidade e como elas se relacionam.
Hierarquia
Organização
└── Workspace
└── Projeto
└── Issue
└── Sub-issue (filho)Cada nível tem seus próprios membros, papéis e configurações.
Organização
A organização é a unidade de tenant e faturamento. Tudo dentro do CloudTasks pertence a uma organização.
- Tem um slug único global (ex:
acme-corp) usado nas URLs - Tem membros com papéis: owner, admin, member, billing
- Está associada a um plano que define limites (membros, projetos, issues, storage)
- Pode ter múltiplos workspaces
Exemplos: uma empresa, uma equipe freelancer, um projeto pessoal.
Workspace
O workspace é uma subdivisão dentro da organização. Serve para separar contextos: times diferentes, departamentos, produtos.
- Membros do workspace são um subconjunto dos membros da organização
- Papéis de workspace (owner, admin, member, viewer) são independentes dos papéis de organização
- Projetos pertencem a um workspace específico
- Um usuário pode ser membro de vários workspaces dentro da mesma organização com papéis diferentes
Exemplos: "Produto", "Suporte", "Infraestrutura", "Marketing".
Projeto
O projeto agrupa issues com um workflow específico.
- Tem um identificador (ex:
CT,BE,FE) com 2–10 letras maiúsculas - Esse identificador é o prefixo das chaves das issues (
CT-1,CT-2, etc.) - Cada projeto tem seu próprio conjunto de status — podem ser totalmente diferentes entre projetos
- Tem um lead (responsável principal)
- Pode ser arquivado quando não está mais em uso ativo
Issue
A issue é a unidade de trabalho. Equivalente ao ticket no Jira, ao card no Trello, ao item no Linear.
Campos de uma issue:
| Campo | Tipo | Descrição |
|---|---|---|
| key | string | Chave única: PROJ-123 |
| title | string | Título obrigatório |
| description | markdown | Descrição com formatação |
| type | enum | Tarefa, Bug, História, Épico, Subtarefa |
| status | FK | Status atual do projeto |
| priority | enum | Urgente, Alta, Média, Baixa, Nenhuma |
| assignee | FK user | Responsável pela issue |
| labels | array | Etiquetas do workspace |
| parent | FK issue | Issue pai (para sub-issues) |
| start_date | date | Data de início planejada |
| due_date | date | Prazo de entrega |
| estimate | integer | Estimativa em pontos ou horas |
| created_by | FK user | Quem criou |
| created_at | timestamp | Quando foi criada |
Chave da issue (PROJ-123)
A chave é gerada automaticamente e é imutável. Formato: identificador do projeto em maiúsculas + hífen + número sequencial. Exemplos: CT-1, CT-42, BACKEND-99.
Use a chave para referenciar issues em comentários, commits, PRs e na API.
Status
O status representa onde a issue está no workflow. Cada projeto define seus próprios status.
Status padrão criados em todo novo projeto:
| Nome | Cor | Categoria |
|---|---|---|
| Backlog | Cinza | backlog |
| A fazer | Azul | todo |
| Em progresso | Amarelo | in_progress |
| Em revisão | Roxo | review |
| Concluído | Verde | done |
Categorias de status são fixas (backlog, todo, in_progress, review, done, cancelled) e definem o comportamento do sistema — por exemplo, issues em done são consideradas encerradas nos relatórios. O nome e a cor podem ser customizados livremente.
Prioridade
| Nível | Uso recomendado |
|---|---|
| Urgente | Bloqueio crítico em produção |
| Alta | Importante para o ciclo atual |
| Média | Deve ser feito, sem urgência |
| Baixa | Melhoria ou nice-to-have |
| Nenhuma | Ainda não priorizado |
Tipos de issue
| Tipo | Uso |
|---|---|
| Tarefa | Trabalho geral |
| Bug | Defeito ou comportamento incorreto |
| História | User story com valor de negócio |
| Épico | Agrupador de histórias/tarefas relacionadas |
| Subtarefa | Parte de uma issue maior (requer parent) |
Labels (Etiquetas)
Labels são criadas no nível do workspace e podem ser aplicadas em qualquer issue de qualquer projeto dentro desse workspace. Cada label tem nome e cor.
Exemplos: frontend, backend, urgente, v2.0, precisa-de-review.
Relações entre issues
Uma issue pode ter relações com outras issues:
| Tipo | Descrição |
|---|---|
blocks | Esta issue bloqueia outra |
is_blocked_by | Esta issue é bloqueada por outra |
relates_to | Relação genérica entre issues |
duplicates | Esta issue duplica outra |
As relações são bidirecionais: criar CT-1 blocks CT-2 cria automaticamente CT-2 is_blocked_by CT-1.
Sub-issues
Uma issue pode ter issues filhas (sub-issues). O campo parent_id aponta para a issue pai. A issue pai mostra o progresso das filhas (quantas concluídas / total).
Hierarquia típica:
Épico: "Migrar autenticação para OAuth" (BACK-10)
├── História: "Fluxo de login com Google" (BACK-11)
│ ├── Tarefa: "Configurar OAuth app" (BACK-12)
│ └── Tarefa: "Implementar callback" (BACK-13)
└── História: "Fluxo de login com GitHub" (BACK-14)