# TechXCar — Design Spec
**Data:** 2026-06-16
**Versão:** 1.0

---

## 1. Visão Geral

**TechXCar** é um SaaS multi-tenant de gestão de oficina automóvel. Cada oficina tem o seu espaço isolado com clientes, veículos, ordens de trabalho, faturação, técnicos e relatórios. A plataforma é gerida por um super-admin que cria e convida oficinas manualmente.

**Inspiração:** LubeLogger, mas focado na gestão operacional da oficina (não no diário do proprietário do veículo).

---

## 2. Stack Técnica

| Camada | Tecnologia |
|---|---|
| Frontend | React 19 + TypeScript + Vite |
| Backend | Go + Fiber (framework HTTP) |
| Base de dados | PostgreSQL 16 |
| Cache / Filas | Redis 7 |
| Auth | JWT (access 15min + refresh 30d, httpOnly cookie) |
| Passwords | bcrypt cost 12 |
| PDF | Geração server-side em Go (html/template → PDF) |
| Notificações | Telegram Bot API + SMTP |
| Frontend UI | Tailwind CSS 4 + shadcn/ui |
| Estado cliente | TanStack Query + Zustand |
| Formulários | React Hook Form + Zod |
| Roteamento | React Router v7 |
| Migrations | golang-migrate |
| Deploy | Docker Compose → Coolify |

---

## 3. Arquitectura de Deploy

### Serviços Docker
```
techxcar/
├── frontend/          # React 19 + TypeScript + Vite (servido via Nginx)
├── backend/           # Go + Fiber
├── docker-compose.yml         # Desenvolvimento
└── docker-compose.prod.yml    # Produção (Coolify)
```

Quatro serviços:
- `frontend` — Nginx a servir o build Vite na porta 80
- `backend` — Binário Go na porta 8080
- `postgres` — PostgreSQL 16
- `redis` — Redis 7

### Configuração em dois níveis
1. **`.env`** — valores de arranque imutáveis em runtime: `DATABASE_URL`, `REDIS_URL`, `JWT_SECRET`, `PORT`, `APP_ENV`. Requerem reinício do container para alterar.
2. **`platform_settings` / `tenant_settings` (DB)** — configuração dinâmica gerida pela Web UI sem redeploy: SMTP, Telegram Bot Token, templates de notificação, limites, dados de faturação. Cached em Redis por 5 minutos.

### Coolify
- Secrets geridos pelo Coolify (injectados como variáveis de ambiente)
- HTTPS automático via Coolify (Let's Encrypt)
- Health checks em `/api/v1/health`

---

## 4. Multi-tenancy

### Estratégia: Schema-per-tenant no PostgreSQL
- Schema `public`: tabelas globais (`tenants`, `invites`, `super_admins`, `platform_settings`)
- Schema `tenant_<uuid>`: dados isolados de cada oficina
- Middleware no backend define `SET search_path = tenant_<uuid>` por request, com base no JWT

### Onboarding de oficinas
**Via convite:** Super-admin gera token assinado com expiração configurável. Oficina clica no link, preenche nome, NIF, email, password → schema PostgreSQL provisionado automaticamente via migrations.

**Via criação manual:** Super-admin cria a oficina no painel `/admin`, define credenciais iniciais, envia email de boas-vindas.

---

## 5. Autenticação & Autorização

### Níveis de acesso
```
super_admin           — gestão da plataforma, todos os tenants
tenant_admin          — dono/gestor principal da oficina
manager               — gestor operacional, sem acesso a settings financeiras
technician            — técnico interno, acesso a OTs atribuídas
external_technician   — sem login; apenas para atribuição e registo de custos
```

### Fluxo JWT
- `POST /api/v1/auth/login` → devolve `access_token` (body) + `refresh_token` (httpOnly cookie)
- `POST /api/v1/auth/refresh` → renova access token usando refresh token do cookie
- `POST /api/v1/auth/logout` → invalida refresh token
- Rate limiting: 10 tentativas/min por IP nas rotas de auth (Redis)

---

## 6. Módulos de Negócio

### 6.1 Clientes & Veículos
- **Cliente**: nome, NIF, telefone, email, morada, notas
- **Veículo**: pertence a um cliente (opcional), matrícula, marca, modelo, ano, VIN, km actual
- Um cliente pode ter N veículos
- OT pode ser criada sem cliente nem veículo (cliente temporário)

### 6.2 Ordens de Trabalho (OT)

**Estados e transições:**
```
Aberta → Em Progresso → Concluída → Faturada
                    ↓
                Cancelada (de qualquer estado excepto Faturada)
```

**Conteúdo de uma OT:**
- Cliente + Veículo (ambos opcionais)
- Items: serviços/peças do catálogo (qty, preço unitário, desconto por item)
- Técnico(s) atribuído(s) + registo de horas (horas × custo/hora)
- Notas internas (não visíveis ao cliente)
- Notas para o cliente (aparecem no PDF)
- Log de estados: timestamp + utilizador responsável por cada transição
- Total calculado: soma de items + mão de obra

### 6.3 Catálogo de Serviços & Peças
- Item: código, nome, categoria, unidade (un/hora/litro/kg), preço base, activo/inactivo
- Categorias livres (criadas pela oficina)
- Ao adicionar a OT: preço copiado do catálogo mas editável por OT
- Pesquisa por código ou nome no momento de adição à OT

### 6.4 Faturação & Orçamentos
- **Orçamento**: gerado a partir de OT em estado "Aberta", PDF com logo e dados da oficina
- **Fatura**: gerada quando OT passa a "Faturada", numeração sequencial por oficina
- PDFs gerados server-side em Go com **`chromedp`** (render HTML → PDF via Chrome headless); armazenados localmente (volume Docker) ou S3-compatible (configurável nas Settings)
- Dados da oficina para PDF: logo, nome, NIF, morada, IBAN — configuráveis nas Settings da Web UI

### 6.5 Técnicos (Staff)
- **Interno**: tem conta no sistema (role `technician`), aparece na atribuição de OTs
- **Externo**: registo simplificado (nome, contacto, custo/hora), sem login
- Registo de horas por OT: horas trabalhadas × custo/hora = custo de mão de obra
- Listagem com estado activo/inactivo

### 6.6 Combustíveis & Despesas da Oficina
- Registo: data, tipo (combustível / peças / ferramentas / outros), valor, descrição, veículo (opcional)
- Filtros por período e tipo
- Totais agregados no dashboard e relatórios

### 6.7 Notificações ao Cliente
- **Telegram**: token do bot configurável nas Settings; envia mensagem quando OT muda para "Concluída" ou "Faturada"
- **Email**: SMTP configurável nas Settings; template HTML editável na Web UI
- Configurável por oficina: quais eventos disparam notificação e qual canal
- Envio assíncrono: o handler HTTP publica um job numa lista Redis; uma goroutine dedicada consome a lista e envia as notificações (não bloqueia o request HTTP)

### 6.8 Dashboard & Relatórios
**Dashboard (tempo real):**
- Receita do mês actual vs mês anterior
- Nº de OTs por estado (cards)
- OTs abertas recentes (tabela)
- Serviços mais realizados (top 5)

**Relatórios (com filtro de período):**
- Receita por período (dia/semana/mês)
- OTs por estado e por técnico
- Despesas vs Receita
- Exportação em PDF e CSV

---

## 7. Estrutura do Backend Go

```
backend/
├── cmd/server/main.go
├── internal/
│   ├── auth/           # JWT, middleware, bcrypt
│   ├── tenant/         # Gestão tenants, schema provisioning
│   ├── workorder/      # Ordens de trabalho
│   ├── client/         # Clientes & veículos
│   ├── catalog/        # Serviços & peças
│   ├── invoice/        # Faturação, geração PDF
│   ├── staff/          # Técnicos
│   ├── expense/        # Combustíveis & despesas
│   ├── notification/   # Telegram + Email (worker assíncrono)
│   ├── report/         # Relatórios & exportações
│   └── settings/       # Settings dinâmicas (DB + cache Redis)
├── pkg/
│   ├── database/       # Pool PostgreSQL, migrations
│   ├── redis/          # Cliente Redis
│   └── pdf/            # Geração PDF
└── migrations/
    ├── public/         # Schema público
    └── tenant/         # Schema tenant (aplicado no provisionamento)
```

### API
- Base: `/api/v1/`
- Autenticação: Bearer token no header `Authorization`
- Tenant resolvido via claim `tenant_id` no JWT
- Respostas: `{ "data": ..., "error": null, "meta": { "page": ..., "total": ... } }`
- Paginação cursor-based

---

## 8. Estrutura do Frontend React

```
frontend/
├── src/
│   ├── pages/
│   │   ├── auth/           # Login
│   │   ├── admin/          # Super-admin (dashboard, tenants, settings)
│   │   └── app/            # Área da oficina
│   │       ├── dashboard/
│   │       ├── work-orders/
│   │       ├── clients/
│   │       ├── vehicles/
│   │       ├── catalog/
│   │       ├── staff/
│   │       ├── expenses/
│   │       ├── reports/
│   │       └── settings/
│   ├── components/
│   │   ├── ui/             # shadcn/ui base components
│   │   └── shared/         # Componentes reutilizáveis da app
│   ├── hooks/              # Custom hooks (useAuth, useTenant, etc.)
│   ├── lib/
│   │   ├── api.ts          # Cliente HTTP (fetch + interceptors)
│   │   └── queryClient.ts  # TanStack Query config
│   ├── store/              # Zustand stores
│   └── i18n/               # Estrutura i18n (PT por defeito, EN preparado)
```

### Rotas protegidas
- `/login` — público
- `/admin/*` — requer role `super_admin`
- `/app/*` — requer role `tenant_admin`, `manager` ou `technician`
- Guards no React Router v7 redireccionam para `/login` se JWT expirado

---

## 9. Base de Dados — Schemas

### Schema `public`
```sql
tenants           (id uuid PK, slug text UNIQUE, name text, status, plan, created_at)
invites           (id uuid PK, tenant_id uuid FK, token text UNIQUE, expires_at, used_at nullable)
super_admins      (id uuid PK, email text UNIQUE, password_hash text, created_at)
platform_settings (key text PK, value text, updated_at)
```

### Schema `tenant_<uuid>` (por oficina)
```sql
users             (id uuid PK, email, password_hash, role, name, active)
clients           (id uuid PK, name, nif, phone, email, address, notes, created_at)
vehicles          (id uuid PK, client_id uuid nullable FK, plate, brand, model, year, vin, mileage, notes)
work_orders       (id uuid PK, number serial, client_id nullable, vehicle_id nullable, status, internal_notes, client_notes, created_by, created_at, updated_at)
wo_items          (id uuid PK, work_order_id FK, catalog_item_id nullable FK, description, qty, unit_price, discount_pct, total)
wo_staff_hours    (id uuid PK, work_order_id FK, staff_id FK, hours, cost_per_hour, total)
wo_status_log     (id uuid PK, work_order_id FK, from_status, to_status, changed_by FK, changed_at)
catalog_items     (id uuid PK, code, name, category, unit, base_price, active)
invoices          (id uuid PK, work_order_id FK, type: quote|invoice, number serial, pdf_path, issued_at)
staff             (id uuid PK, user_id nullable FK, name, email, phone, type: internal|external, hourly_rate, active)
expenses          (id uuid PK, vehicle_id nullable FK, type, amount, description, date)
tenant_settings   (key text PK, value text, updated_at)
```

---

## 10. Internacionalização (i18n)

- Estrutura i18n no frontend desde o início (ficheiros JSON por locale em `src/i18n/`)
- Idioma padrão e único no MVP: **Português de Portugal (pt-PT)**
- Inglês (en) preparado na estrutura mas não traduzido no MVP
- Datas, moeda e números formatados com `Intl` API (locale `pt-PT`, moeda `EUR`)

---

## 11. Segurança

- HTTPS obrigatório em produção (Coolify / Let's Encrypt)
- JWT com expiração curta + refresh token rotativo em httpOnly cookie
- Passwords com bcrypt cost 12
- Rate limiting em todas as rotas de auth (Redis)
- Row-level isolation via PostgreSQL `search_path` por tenant
- Headers de segurança: CSP, HSTS, X-Frame-Options (middleware Fiber)
- Inputs validados com Zod (frontend) e struct validation em Go (backend)
- Ficheiros PDF armazenados fora do webroot, servidos via endpoint autenticado

---

## 12. Fora de Âmbito (MVP)

- Billing automático / Stripe
- App mobile nativa
- Integração com sistemas de diagnóstico OBD
- Portal self-service para clientes da oficina
- Multi-idioma completo (EN traduzido)
- Backups automáticos (responsabilidade do Coolify/infra)