TaskFlow OS | UNBOX FOR YOU

📝 Resumo do Projeto

O TaskFlow OS é um sistema pessoal de gestão de tempo e tarefas que vive em dois lugares ao mesmo tempo: o WhatsApp captura e executa — adicionar tarefas, iniciar cronómetros, concluir trabalho —, enquanto o Dashboard no PC oferece a visão estratégica — Kanban, análise de produtividade e relatórios para clientes. Ambos partilham a mesma base de dados local (SQLite), sem sincronizações, sem cloud, sem custos de subscrição. O objetivo: zero fricção para registar, profundidade total para decidir.

💬 Como se Interage (Modo "Mão na Massa")

Você (no metro) add Consultoria Acme: Preparar proposta #urgente

🤖 TaskFlow OS ✅ Tarefa adicionada em Consultoria Acme → lista Caixa de Entrada.

Você iniciar Documentar API

🤖 TaskFlow OS ⏱️ Timer iniciado em Documentar API.
⏸️ Pausei automaticamente "Reunião de alinhamento" (0h42m guardadas). Foco total!

Você status

🤖 TaskFlow OS 🔵 Documentar API — 1h15m rodando
📅 Hoje: 4h20m trabalhadas · 3 tarefas pendentes
🎯 Meta diária: 6h de trabalho profundo

Você hoje

🤖 TaskFlow OS 📊 Relatório do dia:
▪ Consultoria Acme: 3h10m (2 tarefas fechadas)
▪ Site Cliente X: 1h10m
▪ Tempo ocioso entre tarefas: 22min
🔗 Relatório completo: localhost:3000/relatorio/2026-01-15

* Exemplos ilustrativos da experiência de conversação — todos os dados são registados na base local em tempo real.

⚙️ O Que o Sistema Faz

Capacidade	Descrição Funcional
🗂 Hierarquia Projeto → Lista → Tarefa	Cada projeto tem metadados próprios (cliente, cor, orçamento de horas, prazo) e listas personalizáveis (Urgente, Backlog, Em Espera, Revisão). Cada tarefa guarda título, tags, prioridade, checklist e histórico completo de execuções.
⏱️ Time-Tracking Inteligente	Regista tempo estimado vs. tempo real por tarefa. Ao iniciar um novo cronómetro, pausa automaticamente o que estava a correr — nunca perde nem duplica tempo.
📋 Kanban por Comando	Move tarefas entre listas diretamente no chat (ex: `mover Documentar API para Revisão`). O mesmo drag-and-drop existe no Dashboard, em sincronia permanente.
🔔 Lembretes que Pensam	Se uma tarefa ficar pausada há 30 minutos sem retorno, o bot pergunta: "Vai continuar com [Tarefa] ou registo o tempo?" — nenhuma hora de trabalho cai no esquecimento.
📊 Visão Semanal (Heatmap)	Blocos de tempo coloridos por projeto no calendário — mostra onde o tempo realmente foi, e não onde deveria ter ido.
🧮 Análise de Estimativas	Mede quanto erra as suas previsões de tempo ao longo do histórico — aprende com si próprio para estimar cada vez melhor.
🚨 Projetos em Risco	Alerta visual no Dashboard quando um projeto se aproxima de estourar o orçamento de horas definido com o cliente.
📄 Relatórios para Clientes	Exporta PDFs com logotipo, tempo detalhado por tarefa e totais por período — faturação transparente, pronta a enviar.

⌨️ Comandos Essenciais do WhatsApp

Comando	Função	Inteligência Embutida
`add [projeto]: [tarefa] #[tag]`	Adiciona tarefa ao projeto	Sem projeto definido, vai para a Caixa de Entrada
`iniciar [tarefa]`	Inicia o cronómetro	Pausa timers anteriores e avisa
`check`	Conclui a última tarefa trabalhada	Atalho sem digitar o nome completo
`mover [tarefa] para [lista]`	Kanban via texto	Equivalente ao arrastar no Dashboard
`status`	Resumo em 3 linhas	Timer atual + tempo de hoje + pendentes
`hoje`	Relatório do dia em texto	Inclui tempo ocioso e link para o relatório web
`contexto @[nome]`	Filtra tarefas por contexto	`@escritorio` no PC, `@ligacao` no telemóvel

🎛️ Funcionalidades Avançadas (O "Plus")

Sistema de Contextos (GTD Aprilimorado): defina contextos no Dashboard (@escritorio, @ligacao, @casa) e o WhatsApp mostra apenas as tarefas executáveis onde você está agora.
Modos de Time-Tracking por Perfil: Free Running para trabalho criativo · Pomodoro (25/5, o bot avisa quando acaba) · Time-Boxing (define "2h nesta tarefa" e o bot avisa 15min antes do fim).
Modo Foco: ao iniciar uma tarefa, o bot pode disparar a mensagem automática "Estou focado em [X], volto em 50min" — protege a sua atenção sem rudeza.
Atualização em Tempo Real: inicia uma tarefa pelo telemóvel e o Dashboard aberto no PC reflete a mudança instantaneamente (WebSocket/polling leve).
Templates de Projeto: crie um "Cliente Novo" e ele nasce já com as listas padrão, metas de horas e checklist inicial definidos.
Metas Diárias: configure "mínimo 6h de trabalho profundo" e acompanhe o progresso a cada comando status.

🚀 Benefícios para a Produtividade

Captura sem fricção: regista uma tarefa em 5 segundos, na fila do café, sem abrir nenhuma app nova — usa o WhatsApp que já está sempre aberto.
Privacidade e soberania total: 100% dos dados vivem na sua máquina (SQLite local). Sem cloud, sem subscrições, sem vazamento de dados de clientes.
Fim das horas "fantasma": o registo automático de pausa/retoma e os lembretes inteligentes capturam o tempo que hoje se perde entre tarefas.
Estimativas que melhoram sozinhas: ao medir o desvio entre previsto e real, o sistema treina a sua própria capacidade de planear.
Profissionalismo na faturação: relatórios em PDF com detalhe hora-a-hora justificam cada cobrança ao cliente.
Uma só fonte de verdade: WhatsApp e Dashboard leem o mesmo ficheiro — nunca existem versões contraditórias da mesma tarefa.

⏱️ Agilidade e Fiabilidade na Execução

Aspeto	Como é Garantido
⚡ Resposta Imediata	Comandos processados em milissegundos (FastAPI local); sem latência de internet, sem login, sem espera de carregamento.
🔗 Zero Sincronização	As duas interfaces leem o mesmo ficheiro `.db` no mesmo PC — arquitetura que elimina por design o problema dos sistemas duplos.
🕒 Vigilância Contínua	O `APScheduler` corre em segundo plano monitorizando a última atividade — é ele quem dispara os lembretes de tarefa pausada.
🛡️ Nenhum Timer Perdido	A regra "iniciar novo ⇒ pausar atual" mais os lembretes de retoma garantem que cada minuto de trabalho fica associado à tarefa certa.
📶 Independência de Rede	O Dashboard e a base de dados funcionam offline (localhost); apenas a camada WhatsApp precisa de conexão.

📦 Arquitetura e Tecnologias (Traduzidas para Valor)

Componente	Função no Sistema (Explicação Simples)
`FastAPI (Python)`	"O motor central": serve simultaneamente a API do Dashboard e a gestão dos comandos — um único backend para as duas interfaces.
`SQLAlchemy + SQLite`	"O cofre local": base de dados leve num único ficheiro — robusta para uso pessoal, zero configuração de servidor, backup = copiar um ficheiro.
`Playwright / Evolution API`	"A ponte com o WhatsApp": lê e responde mensagens; a Evolution API (via Docker) oferece estabilidade industrial e interface REST amigável.
`HTMX + Tailwind`	"A vitrine do comandante": interface web leve e rápida para o Kanban, heatmap e análises — sem a complexidade de frameworks pesados.
`APScheduler`	"O assistente silencioso": verifica continuamente o estado dos timers e dispara lembretes, avisos de Pomodoro e relatórios de fim de dia.
`Processador de Comandos (NLP simples)`	"O tradutor": interpreta linguagem natural curta (`iniciar Documentar API`) e converte-a em ações concretas na base de dados.
`WebSocket / Polling leve`	"O telepata": propaga mudanças de estado entre WhatsApp e Dashboard em tempo real, sem manuais de refresh.
`Gestor de Estado do Timer`	"O cronómetro único": garante que só existe um timer ativo, guardando sempre hora de início, pausas e duração por tarefa.

      💡 A Filosofia em Uma Frase: o WhatsApp é onde o trabalho acontece; o Dashboard é onde o trabalho faz sentido. A mesma base de dados garante que nunca se contradizem.
    