Atta Star web

O que faz

1. 01

   To do (por fazer)

   A página de negócio abre com uma só lista do que está à minha espera: uma importação do e-Fatura com mais de 35 dias, uma linha do e-Fatura sem documento por trás, uma fotografia cujo código não foi possível ler, uma encomenda online sem fatura, um pedido de quem trata da contabilidade, um extrato de uma conta que não conhece. O número na barra lateral conta-os, e tudo o que for anterior à data em que as contas foram fechadas sai da lista.

   

2. 02

   Faturas lidas pelo código QR

   Todas as faturas e recibos que a empresa recebe são arquivados pelo código QR fiscal português, quer tenham chegado pela caixa de correio das faturas, por carregamento ou pela câmara do telemóvel, que lê o código e depois tira uma fotografia para recortar. O leitor lida com códigos desenhados como imagem, como formas vetoriais ou numa fonte de código de barras, com um segundo descodificador de reserva. Cada documento diz o que é (um custo, uma venda, não é fatura), pode ser marcado como pago do meu bolso e segue para o programa de contabilidade.

   

3. 03

   e-Fatura

   A lista das faturas do mês, recebidas e emitidas, que a Autoridade Tributária tem fica ao lado dos documentos. Cada linha é associada ao seu documento ou marcada como Missing (em falta), e pode ser ligada à mão ou dispensada.

   

4. 04

   Banco

   As contas são lidas através de open banking (PSD2), só de leitura, com o consentimento dado no próprio banco: uma vez por dia em segundo plano, ou a pedido quando estou presente. A associação aplica apenas os casos certos (comissões bancárias, transferências entre as minhas próprias contas, um montante exato a menos de dez dias de uma fatura) e propõe os prováveis para confirmar com um clique. Os extratos em PDF completam o histórico mais antigo, e um extrato cujos saldos correntes não batem certo é recusado por inteiro. Uma secção à parte guarda o saldo corrente entre mim e a empresa.

   

5. 05

   Visão geral

   O ano em termos contabilísticos ao lado do dinheiro no banco: quem deve o quê, meses e trimestres com IVA, uma estimativa do IRC, o que aí vem e os anos lado a lado. O relatório anual imprime-se em inglês ou em português.

6. 06

   Folha de horas

   Ninguém escreve horas. Um pequeno programa em cada um dos meus computadores lê as sessões de programação e o estado do git e envia blocos de trabalho. A folha de horas mostra-os por dia, semana ou mês, como registo, como calendário, por cliente ou como fatura. Um bloco pode ter a hora corrigida, ser dividido, passar para outro projeto, ser excluído ou ser marcado como faturável, e cada cliente tem uma data de "faturado até". Exporta para CSV, Excel e PDF.

   

7. 07

   A contabilidade e os clientes

   Quem trata da contabilidade tem uma vista só de leitura em português (documentos, e-Fatura, banco e visão geral) e descarrega um período em zip, em folha de cálculo ou num pacote mensal. Pode ser pedido um documento em falta, e o pedido cai no meu To do. Um cliente vê apenas as suas próprias horas faturáveis, sem horas de início e de fim nem montantes, e pode sugerir uma alteração ou comentar uma linha. As sugestões esperam em Approvals (aprovações) até eu as aceitar ou recusar.

   

8. 08

   Projetos e wikis

   Um cartão por projeto com o branch, as alterações ainda sem commit, o último commit e as tarefas em aberto, e ligações para o editor, para o site em produção e para a sua wiki. A base de conhecimento partilhada e a wiki de cada projeto podem ser lidas aqui, com índice e pesquisa.

   

9. 09

   Notificações

   Notificações no telemóvel só para o que pede ação: uma fatura que chega aos 30 dias por pagar (uma vez, e nunca antes das nove da manhã), um bloqueio depois de várias tentativas falhadas de início de sessão, uma cópia de segurança externa que não chegou em 36 horas, e o lembrete diário de cada aplicação ligada.

   

Como funciona

Início de sessão e papéis

À frente da aplicação, que não tem porta própria, está uma página de início de sessão único com autenticação de dois fatores. Um só módulo de acesso decide cada rota e recusa tudo o que não permite. Há quatro papéis: dono, colaborador, cliente e contabilista. A quem não for o dono, uma escrita é recusada antes de o pedido ser sequer lido, e cada alteração tem de levar um cabeçalho próprio contra pedidos entre sites. Posso ver o site como outro utilizador, só de leitura e com registo de auditoria. O registo de auditoria guarda durante 90 dias cada exportação, decisão, alteração de fatura e leitura feita por quem trata da contabilidade.

Segredos

As chaves vêm de uma lista fixa e verificada, ficam em ficheiros a que só o dono acede e nunca chegam a uma página. Uma página só vê os últimos quatro dígitos de um IBAN. As chamadas ao banco são assinadas com tokens de curta duração. A palavra-passe do Portal das Finanças nunca é guardada: uma skill do Atta vai buscar o ficheiro do e-Fatura do mês num navegador onde sou eu a iniciar sessão.

Os programas em cada computador

Cada computador recebe o seu próprio token, mostrado uma só vez. Só é guardado o seu hash; é comparado em tempo constante, pode ser revogado e abre as rotas que recebem dados e mais nenhuma. As transcrições das sessões nunca saem do computador, só os blocos de trabalho com pequenos excertos de cada prompt. Uma edição feita enquanto o servidor não está acessível fica à espera numa caixa de saída local.

A aplicação de finanças da casa

A aplicação de finanças da casa lê dois valores do Atta Star através de uma única ponte só de leitura, de servidor para servidor: as faturas da empresa que paguei com um cartão pessoal e o saldo corrente que a empresa me deve. O seu token abre esse único caminho, a resposta tem um tamanho máximo e cada leitura fica registada na auditoria. O Atta Star não pede nada em troca. Outras aplicações podem mostrar um pequeno cartão de estado na página Projects, com três linhas no máximo, sem que o Atta Star saiba o que significam os números.

Armazenamento

Não há base de dados: os dados são ficheiros JSON, escritos num ficheiro temporário e depois renomeados para o seu lugar. Um ficheiro que não se consegue ler trava a rota em vez de ser escrito por cima. As páginas abertas recebem as alterações por um único fluxo de eventos e recarregam só a parte que mudou.

Como foi feito e testado

Testes

Cerca de 2500 testes unitários e seis conjuntos de testes em Playwright: verificações de acessibilidade com axe, execuções com a largura de um telemóvel e os fluxos de negócio, aprovações, cliente e documentos. Cada teste foi provado partindo o código de propósito e vendo-o falhar. PDFs de faturas falsas com códigos QR válidos, extratos falsos, um banco falso e um Google falso fazem as vezes dos verdadeiros.

Versões

Cada pull request corre a verificação de tipos, o lint, os testes, a build e o empacotamento. Integrar um pull request publica um arquivo da versão com o seu checksum. Nada no GitHub consegue chegar ao servidor: é o servidor que vai buscar a versão, verifica o hash e o conteúdo, e testa a nova configuração do proxy antes de recarregar. O servidor é empacotado num só ficheiro, sem node_modules.

Como o Atta ajudou

• Cada pull request passou pelo atta-critic, um revisor independente que não guarda memória da sessão que escreveu o código. Na primeira utilização a sério, apanhou duas afirmações falsas na descrição de um PR.
• As decisões em aberto foram fechadas antes do código com o /atta-grill, uma pergunta de cada vez, e o raciocínio ficou guardado na wiki do projeto.
• O que aprendeu sobre bancos, extratos e faturas ficou escrito na wiki partilhada, e a aplicação de finanças da casa partiu daí em vez de começar do zero.
• A regra do repositório é não ter valores reais: os testes usam montantes e nomes inventados, e uma verificação antes de cada commit recusa tudo o que tenha a forma de um NIF ou de um IBAN.