Guia completo

O que vem na app (grátis, MIT)

Tudo o que uma oficina usa no dia a dia, sem subscrição nem limites:

Três formas de instalar

O OficinaOS é sempre o mesmo programa — a diferença está em como é arrancado no PC da loja. Há três caminhos:

OficinaOS-Setup.exe (recomendado) — um instalador Windows normal, sem Docker: corre como serviço, arranca com o PC, cria a regra de firewall, faz backup diário automático e deixa um ícone na bandeja. É o caminho certo para o PC da loja.

Modo portátil — um pacote único com tudo embutido (a app, a base de dados PostgreSQL e o runtime), sem instalação e sem serviços Windows. Existe para as situações em que o instalador não serve: PCs onde não tens a password de administrador, quem prefere não instalar nada no sistema, e como fallback se o instalador falhar numa máquina concreta (antivírus, políticas da empresa).

Docker — para um NAS, um servidor dedicado, Linux ou macOS, ou para quem já usa Docker.

Instalação — OficinaOS-Setup.exe (uma vez, ~10 minutos)

Descarregue o OficinaOS-Setup.exe na página de releases e faça duplo clique. Se o Windows Defender SmartScreen avisar: «Mais informações» → «Executar mesmo assim».

Pede administrador uma só vez (serviços, firewall e a tarefa de backup) e faz tudo sozinho. No fim o browser abre em http://localhost:4000. Primeiro login: utilizador admin, palavra-passe braindead — a app obriga a mudar ambos.

Fica um ícone na bandeja junto ao relógio: abrir a app, ver o estado, parar/arrancar, fazer backup. Noutros aparelhos da loja: http://oficinaos.local:4000 — ou o QR code na página Ajuda.

Em Linux ou macOS não há instalador — usa-se o Docker manualmente:

            git clone https://github.com/braindeadpt/OficinaOS.git
cd OficinaOS && cp .env.example .env
docker compose up -d
docker compose exec app bun run db:seed
          

Modo portátil — sem admin, sem instalar nada

Para quando o instalador não é opção: não tens a password de administrador do PC, não queres que nada fique instalado no sistema, ou o instalador/serviços foram bloqueados naquela máquina (antivírus, políticas da empresa).

Descarrega oficinaos-portable.zip, extrai para uma pasta e corre INICIAR.bat. A app é exatamente a mesma — mesmo código, mesma base de dados PostgreSQL, mesmas funcionalidades — e também tem o botão «Atualizar» dentro da app.

Duas diferenças práticas face ao Setup.exe: o arranque automático é uma tarefa agendada opcional (o INICIAR.bat pergunta na 1ª execução) em vez de um serviço; e como ninguém abre a firewall por ti, o Windows pergunta uma vez se permite a ligação — escolhe «Permitir» para os tablets da loja ligarem.

Se chegaste aqui por causa do erro «virtualization support not detected» do caminho Docker, o portátil resolve — mas nesse caso o Setup.exe é ainda mais simples, porque também não precisa de Docker.

Dia a dia — ligar, desligar, ficheiros

Depois de instalado, o dia a dia resume-se a duplo clique num ficheiro. Os nomes são iguais nos dois modos — só muda a pasta onde estão:

• Instalação por Setup.exe: o serviço corre sozinho — parar/arrancar e backup manual pelo ícone na bandeja.
• Modo Docker: na pasta onde extraiu o instalador.
• Modo portátil: dentro da pasta oficinaos-portable — os dados vivem em data\, os backups em app\uploads\backups.
• Outros dispositivos da loja (tablet, telemóvel, outro PC) não instalam nada — abrem http://<IP-do-PC>:4000 no browser.

Backups e restauro

Os backups são ficheiros comprimidos (.sql.gz) com a base de dados inteira. A app mostra o estado do último backup em Definições → Loja → Backups — funciona igual em todos os modos.

Na instalação por Setup.exe uma tarefa agendada faz backup diário às 03:30 para C:\ProgramData\OficinaOS\backups. No modo Docker um serviço dedicado faz um backup a cada 24 horas, guarda 14 dias, e opcionalmente copia para armazenamento externo (S3, Backblaze, etc.) e testa o restauro automaticamente.

No modo portátil o backup corre a cada arranque e com BACKUP.bat. Restaurar é com RESTAURAR.bat (repor um ficheiro de backups). Como não há cópia fora do PC automática, copie a pasta app\uploads\backups para um disco externo ou pen — backups no mesmo disco não protegem contra avaria, roubo ou ransomware.

Atualizações

A app avisa no topo quando existe versão nova. Nas instalações por Setup.exe e no modo portátil, o dono da loja tem um botão «Atualizar» no aviso — descarrega só a parte da app (~100 MB) com verificação SHA-256, faz backup da base de dados antes e repõe a versão anterior sozinho se a nova não arrancar. A app fica offline ~1-2 minutos durante a troca.

À mão também funciona: o Setup.exe da versão nova por cima, ou ATUALIZAR.bat no portátil e no Docker. No Docker pode ainda ativar-se atualização 100% automática (Watchtower) — as migrações da base de dados correm sempre sozinhas.

Na loja — telemóveis, tablets e PCs

Qualquer aparelho ligado à Wi-Fi da loja abre a app no browser — sem instalar nada. Basta escrever o endereço que a instalação dá e fazer login:

Funciona sem internet para o uso do dia a dia. Guarde o endereço nos favoritos — é sempre o mesmo.

            http://192.168.1.33:4000   # o endereço do PC-servidor
          

Ícone no ecrã do telemóvel

Para abrir com um toque, como uma app normal — demora 10 segundos:

• iPhone/iPad: Safari → botão Partilhar → «Adicionar ao ecrã principal»
• Android: Chrome → menu ⋮ → «Adicionar ao ecrã principal»
• Com acesso remoto ligado, o Android chega a oferecer «Instalar aplicação» — instalação real

Fora da loja — acesso remoto

Com o PC da loja ligado, um Cloudflare Tunnel gratuito dá à loja um endereço https:// próprio — sem mexer no router, funciona com qualquer operadora, mesmo as que bloqueiam portas (CGNAT).

Serve para a equipa consultar a app fora da loja e para os links dos clientes — tracking, orçamentos, QR de garantia — abrirem em qualquer lado.

• Criar conta grátis na Cloudflare + um domínio (~10 €/ano)
• No painel Zero Trust: criar o túnel e copiar o token
• Duas linhas no ficheiro .env e reiniciar a app
• Na app: Definições → Loja → URL base de tracking → o endereço público

Privado por defeito

O túnel é opcional: a app funciona a 100% na rede local mesmo sem internet. Os dados dos clientes ficam na loja — a Cloudflare apenas transporta o tráfego encriptado quando o túnel está ligado.

Quem quiser uma barreira extra pode ativar o Cloudflare Access (grátis): email + código antes do login, mantendo as páginas públicas dos clientes abertas.

Impressão — talões e etiquetas

O OficinaOS imprime os três documentos do dia a dia diretamente da ficha ou do ecrã de venda: o talão da reparação para o cliente, o talão de venda do POS e a etiqueta que se cola no equipamento.

Tudo se configura em Definições → Loja → Impressão — as escolhas aplicam-se a todos os documentos a partir desse momento:

Dois métodos de impressão

Caixa de diálogo Imprimir (predefinição): o documento abre num separador novo e usa o diálogo de impressão do sistema. Funciona com qualquer impressora instalada — USB, rede, Bluetooth — e até com «Guardar como PDF». As etiquetas seguem sempre este caminho: as etiqueteiras falam outras linguagens (ZPL/TSPL) e o browser trata do driver.

Impressora térmica de rede (ESC/POS): a app envia o talão diretamente para a impressora pela rede da loja — um clique e sai o talão, sem diálogo. Serve para térmicas ligadas por cabo ou Wi-Fi (Epson TM, Star, Xprinter e compatíveis ESC/POS). O texto usa a página de código CP850 — acentos corretos — e o QR de tracking é impresso pelos comandos nativos da impressora, sem drivers.

• Ativar (uma vez): Definições → Loja → Impressão → Método «Impressora térmica de rede» → indicar IP e porta (quase sempre 9100) → «Enviar ticket de teste»
• Descobrir o IP: na maioria das térmicas, ligar com o botão FEED premido imprime um autoteste com o IP; também aparece na lista de dispositivos do router
• Fixar o IP no router (reserva DHCP) — sem isso a impressora pode mudar de endereço e deixar de imprimir
• Com papel A4 configurado ou impressora só USB, o caminho é a caixa de diálogo — ESC/POS é só para rolos térmicos na rede

Impressão — problemas comuns

As situações mais frequentes:

Módulos Pro — como funcionam

Os módulos Pro são funcionalidades que precisam de «chegar à internet». A app continua 100% local e gratuita; quando a loja quer alcance remoto, emparelha a app com a OficinaOS Cloud — o nosso serviço que faz de ponte entre a app da loja e o exterior, sem expor o PC da loja.

A loja cria uma conta na Cloud e emparelha a app com um código (uma vez). Cada módulo é ativado do lado do servidor — sem ficheiros de licença. A app sincroniza com a Cloud a cada ~2 minutos para enviar e receber.

Sem emparelhamento, tudo continua a funcionar na rede local — os módulos Pro simplesmente não aparecem.

Preços

A app completa é gratuita e open source (MIT) — sem limites, sem contas, sem período de teste. Para sempre.

Os módulos Pro estão em beta: durante este período, as lojas piloto usam-nos gratuitamente enquanto medimos o valor real que trazem ao balcão. Quando os preços forem anunciados serão subscrições mensais simples — sem fidelização e sem custos escondidos.

* Nota WhatsApp: responder a clientes dentro da janela de 24h é grátis. Para notificações proativas («está pronta») fora dessa janela, a Meta cobra pequenos valores por mensagem modelo — custo da Meta, não nosso.

Portal do cliente (Pro)

Com o módulo ativo, cada reparação ganha um botão «Public link» na página de detalhe. Ao clicar, a app publica na Cloud um snapshot redigido do trabalho — estado, dispositivo, orçamento, prazo e timeline — e copia o link.

O link é segredo por trabalho (um código aleatório de 16 caracteres): quem o tem vê a página. Envia-se ao cliente por SMS, WhatsApp ou impresso no registo. A página atualiza sozinha quando o estado muda na app.

Se houver um orçamento pendente, o cliente aceita ou recusa diretamente na página — a resposta entra na app pelo fluxo normal de orçamentos, com notificação ao staff.

Bot de WhatsApp (Pro)

O cliente escreve para o número de WhatsApp da loja e o bot responde com dados reais da ficha — sem ninguém pegar no telemóvel. Funciona com o próprio número da loja (o WhatsApp Business do telemóvel continua a funcionar em paralelo).

Notas honestas: a resposta pode demorar até ~2 minutos (ciclo de sincronização); o setup usa a WhatsApp Business Platform oficial da Meta e é assistido por nós na primeira loja.

Canal SMS (grátis no core)

O mesmo assistente automático, mas por SMS — para lojas que não querem (ou ainda não têm) a conta empresarial da Meta. Um telemóvel Android com SIM fica na loja a fazer de ponte: a app envia e recebe SMS através dele, pela rede móvel normal. É gratuito e não precisa de Cloud — tudo acontece na rede da loja.

Sem contas Meta, sem aprovações de modelos e sem custo por mensagem — só o tarifário do SIM da loja (cartões com SMS incluídos tornam o custo marginal zero). O setup são ~5 minutos e está explicado passo a passo no guia.

Diagnósticos enviados por clientes (Pro)

A ferramenta oficinaos-diag é gratuita para qualquer pessoa: o cliente descarrega, liga o telemóvel ao PC por cabo e o programa lê bateria, ecrã, sensores e armazenamento.

Com o módulo ativo, a loja recebe esses diagnósticos diretamente na app (fila de pedidos), prontos a converter em reparação — o cliente só precisa do código da loja. O módulo de relatórios IA transforma os dados técnicos num texto simples para entregar ao cliente.

Faturação certificada (Pro)

A app emite documentos fiscais legais diretamente da venda ou da reparação — fatura-recibo quando o cliente tem NIF, fatura simplificada quando não tem. A emissão é feita via InvoiceXpress com a conta da própria loja: a chave API fica guardada encriptada no PC da loja e a app fala diretamente com o InvoiceXpress — a OficinaOS Cloud só controla o acesso ao módulo, nunca vê os documentos. Só para lojas em Portugal.

Montra, procuro-peça, preços, multi-loja e remarketing (Pro)

Mais cinco módulos Pro, todos em beta e ativados na conta OficinaOS Cloud. Cada um tem um guia curto:

Problemas comuns

As situações mais frequentes e a resolução de cada uma:

Perguntas frequentes

As dúvidas que ouvimos mais vezes:

Documentação completa

Este guia cobre o essencial. O repositório no GitHub tem a documentação técnica completa — instalação detalhada, acesso remoto, telemóveis, backups com cópia externa e o funcionamento interno do pacote portátil: