# Tique — Manual Completo de Contexto & Arquitetura (https://tique.ia.br)

## 1. Identidade e Filosofia do Tique
O Tique (https://tique.ia.br) é uma aplicação web e mobile brasileira concebida para redefinir o relacionamento das pessoas com o tempo. 
Diferente de sistemas corporativos de "timesheet" que impõem controle por vigilância (monitoramento de cliques, gravação de tela ou verificação de atividade), o Tique parte do princípio de que **produtividade real nasce da clareza e da autonomia**.

### Slogan Oficial
"Seu tempo. Mais seu."

### Cores Oficiais da Marca
- Tinta Profunda (Ink): `#262133`
- Roxo Brand: `#6340c7`
- Lilás Suave: `#eae2fa`
- Neon Lima: `#dcf59e`
- Creme Calmo: `#fbfaf7`

---

## 2. Princípios de Engenharia e Modelo Matemático do Tempo

### 2.1 Intervalos Semiabertos [startedAt, endedAt)
Todas as sessões de tempo são armazenadas no banco de dados como intervalos matemáticos semiabertos:
- O momento inicial `startedAt` é inclusivo.
- O momento final `endedAt` é exclusivo.
- Para qualquer sessão concluída, a duração exata é calculada por `endedAt - startedAt` em milissegundos inteiros.
- Não existem sobreposições permitidas para um mesmo usuário no mesmo espaço de trabalho: se uma nova tarefa for iniciada, a anterior é pausada de forma transacional e atômica.

### 2.2 Integridade Concorrente em MySQL InnoDB
O Tique utiliza transações `REPEATABLE READ` com bloqueio explícito de linha via `SELECT ... FOR UPDATE` no estado ativo do usuário. Isso assegura que:
- Mesmo que o usuário abra múltiplos navegadores, abas ou celulares simultaneamente, nunca haverá duas sessões ativas concorrentes.
- Requisições com o mesmo `idempotencyKey` são tratadas com segurança idempotente.

### 2.3 Preservação Absoluta do Histórico
- A reabertura de uma tarefa ou projeto concluído nunca apaga nem zera o tempo anteriormente registrado.
- A exclusão de tarefas que possuem sessões registradas é bloqueada; o usuário pode apenas arquivá-las, garantindo a integridade dos relatórios passados e presentes.
- Qualquer revisão de horário (`PATCH /api/v1/time-sessions/:id/correct`) ou anulação (`POST /api/v1/time-sessions/:id/void`) gera um registro imutável na tabela `audit_events`.

---

## 3. Módulos Funcionais

### 3.1 Painel Hoje (Today Dashboard)
- **Saudação e Status:** Exibição do status em tempo real com indicador luminoso da sessão ativa.
- **Hero Card do Cronômetro:** Mostrador grande com tempo acumulado em formato tabular (`HH:MM:SS`), projeto, etapa associada e controles de Pausar e Concluir.
- **3 Cartões Métricos:** Tempo Registrado Hoje, Tarefas Concluídas no Dia e Ciclo de Foco / Pomodoro.
- **Criação Rápida:** Entrada de tarefas com estimativa em minutos e opção de planejamento imediato.
- **Filtros em Pílula:** Todas, Planejadas, Atrasadas e Sem Data.

### 3.2 Projetos & Etapas (Projects & Stages)
- Estruturação hierárquica em Etapas ordenadas (01, 02, 03...).
- Alternador de visualização entre **Lista Hierárquica** e **Quadro Kanban**.
- Modelos prontos sem horas fictícias: Estudos, Trabalho e Vida Pessoal.

### 3.3 Foco Inteligente (Pomodoro)
- Ciclos customizáveis de foco (padrão 25m), pausa curta (5m) e pausa longa (15m).
- O cronômetro do Pomodoro encerra automaticamente ao fim do bloco planejado.
- O tempo das pausas é rastreado para saúde mental, mas nunca é somado como tempo de trabalho.

### 3.4 Relatórios & Inteligência Analítica
- Agrupamento flexível por períodos (Hoje, 7 dias, 30 dias ou personalizado).
- Particionamento rigoroso no fuso horário do usuário: sessões que cruzam a meia-noite são divididas exatamente na virada do dia do fuso consultado.
- Comparação lado a lado entre **Tempo Estimado** e **Tempo Registrado**, sem inferências artificiais.
- Exportação instantânea em formato CSV.

### 3.5 Espaços de Trabalho e Equipes (Workspaces)
- Suporte a múltiplos espaços por usuário (Pessoal ou Equipe).
- Papéis e permissões granulares:
  - `OWNER`: Dono do espaço, controle total e encerramento.
  - `ADMIN`: Gerencia membros, projetos e relatórios.
  - `MEMBER`: Cria e gerencia suas próprias tarefas e projetos.
  - `VIEWER`: Acesso de leitura aos projetos e relatórios.

---

## 4. Endpoints Principais da API (Fastify)
- `POST /api/v1/auth/register` — Cadastro de usuário com fuso horário
- `POST /api/v1/auth/login` — Autenticação com sessão segura e CSRF token
- `GET /api/v1/today` — Painel consolidado do dia
- `POST /api/v1/timer/start` — Início/troca atômica de cronômetro
- `POST /api/v1/timer/pause` — Pausa da sessão ativa
- `POST /api/v1/tasks/:id/complete` — Conclusão de tarefa e sessão em uma única transação
- `GET /api/v1/projects` — Listagem e métricas de projetos
- `GET /api/v1/reports/time` — Relatório de tempo no fuso horário
- `GET /api/v1/reports/time/export.csv` — Download de planilha de horas
- `GET /api/v1/workspaces/:id/members` — Listagem de equipe

---

## 5. Informações Corporativas
- **Site Oficial:** https://tique.ia.br
- **País:** Brasil
- **Idioma:** Português do Brasil (pt-BR)
- **Licenciamento / Acesso:** Plataforma SaaS Freemium com recursos avançados de equipe.