Visão geral do Aedifica

O que é

O Aedifica é uma plataforma web de gestão para empresas de construção e remodelação (empreiteiros gerais, instaladores, pequenas e médias equipas de obra). Junta num só sítio o que normalmente está espalhado entre folhas de cálculo, Word e WhatsApp: contactos, orçamentos, obras, planeamento de equipas, registo de horas, relatórios de obra e faturação.

A interface está em português (pt-PT por omissão) com espanhol, inglês e francês. Os dados de cada empresa vivem numa organização isolada (organizations/{orgId} no Firestore).

Para quem

Perfil	Papel no sistema	O que faz
Gerência / dono	`owner`	Tudo, incluindo gerir membros e papéis
Administração	`admin`	Definições, séries de numeração, modelos, faturação
Escritório / orçamentista	`office`	Contactos, catálogo, orçamentos, faturas, projetos
Equipa de obra	`worker`	Vê projetos e planeamento, regista as suas horas e relatórios

Fluxo principal: do pedido à fatura

Contacto/lead ──► Orçamento (offer) ──► Aprovação ──► Obra (projeto)
      │                 │                                │
      │           catálogo (materiais,             planificador (fases,
      │           serviços, Datanorm)              equipas, membros)
      │                                                  │
      └──────────────────────────────► horas + relatórios de obra
                                                         │
                       fatura parcial / final ◄──────────┘
                                │
                   pagamentos, lembretes, notas de crédito

Lead → contacto. O pedido chega (telefone, email, formulário) e é criado um contacto organisation ou person, com o papel customer.
Projeto (obra). Cria-se um projeto (Folder, ex.: BL-OBR-001) ligado ao cliente (folderRecipient) e à morada da obra (folderAddress).
Orçamento. No projeto cria-se um documento offer. O editor usa blocos: capítulos (block-group), partidas (block-position) vindas do catálogo, textos, imagens, tabelas e subtotais. A calculação (pcCosts) divide material, mão de obra, equipamento, serviços externos e outros.
Finalizar. Ao finalizar, a Cloud Function allocateDocumentNumber atribui o número da série (ex.: P-26-00102) numa transação, e o documento fica published e imutável. Cada gravação gera uma versão em documentVersions ({id}--vN).
Obra e planeamento. O planificador regista fases do projeto (folderAllocation) e alocações de membros (memberAllocation).
Horas e relatórios. A equipa regista horas (times) por projeto e relatórios de obra (reports) com secções de materiais, serviços e horas. As horas de um relatório podem passar para o registo de horas.
Fatura. A partir do orçamento ou do relatório geram-se faturas (invoice, partialInvoice, finalInvoice). Pagamentos ficam em invoicePayments. A função diária paymentReminders cria notificações internas de vencimento. Cancelamentos e notas de crédito (invoiceCancellation, creditNote) usam a série FR.
Controlo. O painel e as estatísticas do projeto comparam orçamentado, faturado, horas e custos (margem).

Arquitetura atual

Componente	Tecnologia
Frontend	React + Vite (duas SPAs: `apps/app`, `apps/setup`), react-router, styled-components + Tailwind v4, Slate/TipTap, Jotai, zod, axios + swr, i18next, pdf-lib/pdf.js
Dados	Cloud Firestore `(default)`, `europe-west1`, regras em `firestore.rules`
Ficheiros	Cloud Storage, `organizations/{orgId}/{area}/…`, máx. 10 MiB por ficheiro
Lógica de servidor	Cloud Functions v2, `europe-west1`; superfícies L1 descritas em `docs/plans/l1-api.md`, deploy pendente
Pesquisa	Typesense (coleções `projects`, `documents`, `contacts`, `catalog_items`)
Alojamento do frontend	nginx em Docker, publicado pelo Coolify

Cloud Functions existentes:

Função	Tipo	Uso
`allocateDocumentNumber`	callable	Finaliza documento e atribui número
`mintSearchKey`	callable	Chave Typesense limitada à organização (55 min)
`exportProjectZip`	callable	ZIP dos ficheiros de um projeto (≤500 ficheiros, ≤100 MiB)
`syncProjects`, `syncDocuments`, `syncContacts`, `syncCatalog`	trigger Firestore	Indexação Typesense
`paymentReminders`	agendada 08:00 Lisboa	Notificações de faturas vencidas
`expireInvitations`	agendada 03:00 Lisboa	Limpa convites expirados
`storageFinalized`, `storageDeleted`	trigger Storage	Quotas, miniaturas, metadados

Onde encaixa a API

A API REST /v1 é uma camada fina por cima do que já existe, não um segundo backend:

Integração / ERP / assistente IA
        │  Authorization: Bearer aed_live_…
        ▼
Gateway REST (proposto: Cloud Function HTTP `api`, europe-west1)
  • valida chave (hash SHA-256 em apiKeys) e scopes
  • valida corpo com os schemas zod partilhados
  • aplica as mesmas regras de papel que firestore.rules
        │ Admin SDK
        ▼
Firestore · Storage · Typesense · funções existentes (numeração, ZIP)

Casos de uso: importar clientes de um CRM, criar orçamentos a partir de um configurador web, exportar faturas para contabilidade, sincronizar horas com processamento salarial, e deixar um assistente de IA preparar rascunhos de orçamentos que um humano revê e finaliza.

Limites atuais conhecidos

Não há emissão fiscal certificada nem comunicação AT/AEAT (Verifactu). A numeração é sequencial por série, sem certificação.
O PDF dos documentos é hoje gerado no browser (apps/app/src/document-pdf.ts, pdf-lib). A geração de PDF no servidor para a API é proposta.
Ferramentas e equipamentos não existem como entidades (só como tipo de custo equipment). Ver Catálogo.

O que é​

Para quem​

Fluxo principal: do pedido à fatura​

Arquitetura atual​

Onde encaixa a API​

Limites atuais conhecidos​