# ⚙️ Fastapp Engine — Produto

> Documento de produto. Define o quê, para quem, e para onde estamos indo sob a filosofia **Anti-Gravity**.

--- 

## O que é?

O **Fastapp** é uma **fábrica de aplicações**. Ele transforma definições JSON em interfaces funcionais completas — CRUD, formulários, tabelas, navegação — sem escrever código repetitivo. A meta básica é a **abstração máxima**: se algo é repetitivo, deve ser automatizado pelo motor; se é específico, deve ser parametrizado.

A primeira aplicação construída sobre o motor (o "carro-chefe") é o **CRM Flux** — o "Modelo 01" que sai da fábrica para validar todos os processos.

```mermaid
graph LR
    subgraph "A Fábrica (Fastapp Engine)"
        ENGINE["⚙️ Motor Dinâmico"]
        BUILDER["🔧 Builder (Admin)"]
        SNAPSHOT["📸 Snapshot"]
        APIV1["🔌 API v1"]
    end

    subgraph "Modelo 01"
        CRM["🏢 CRM Flux"]
    end

    subgraph "Modelo 02...N"
        TICKETS["🎫 Helpdesk"]
        INVENTORY["📦 Inventário"]
        CUSTOM["🧩 Sua App"]
    end

    ENGINE --> CRM
    BUILDER --> ENGINE
    ENGINE -.-> TICKETS
    ENGINE -.-> INVENTORY
    ENGINE -.-> CUSTOM

    style ENGINE fill:#4338ca,color:#fff
    style CRM fill:#f59e0b,color:#000
    style BUILDER fill:#6366f1,color:#fff
    style SNAPSHOT fill:#7c3aed,color:#fff
    style APIV1 fill:#059669,color:#fff
```

---

## Para quem?

| Persona | Necessidade | Como o Fastapp resolve |
|---------|------------|----------------------|
| **Dev solo / startup** | SaaS rápido sem boilerplate | Define o objeto no JSON, motor gera tudo |
| **Equipe comercial** | CRM simples e visual | CRM Flux pronto, Kanban + stats |
| **Gestor técnico** | Customização sem código | Schema Manager v3 edita objetos e props |
| **Dev avançado** | Estender o ecossistema | Camada custom sobre o motor (ex: L3 Orquestração) |

---

## 🗺️ O Mapa de Voo — As 4 Fases do Fastapp

A evolução do Fastapp não é sobre acumular features, mas sobre **mudar onde a inteligência reside**.

```mermaid
graph LR
    F1["🔄 Fase 1<br/>O Intérprete"]
    F2["📸 Fase 2<br/>O Snapshot"]
    F3["🏭 Fase 3<br/>A Forja"]
    F4["🌐 Fase 4<br/>O Ecossistema"]

    F1 ==>|"Otimizar"| F2
    F2 ==>|"Gerar código"| F3
    F3 ==>|"Distribuir"| F4

    style F1 fill:#059669,color:#fff
    style F2 fill:#7c3aed,color:#fff
    style F3 fill:#dc2626,color:#fff
    style F4 fill:#0891b2,color:#fff
```

### Fase 1: O Intérprete ✅ (Base)
O sistema é 100% dinâmico. O motor interpreta o JSON e renderiza componentes genéricos em tempo real.

### Fase 2: O Snapshot ✅ (Performance)
Congelamento do DNA do app em `static-manifest.ts` para evitar consultas ao banco e garantir carregamento instantâneo.

### Fase 3: A Forja 🔮 (Próximo Passo)
O motor lê o manifesto e **escreve arquivos físicos** (`.vue`, `.ts`) no disco, permitindo performance nativa com a flexibilidade do design-time.

### Fase 4: O Ecossistema 🌐 (Visão)
O Fastapp gera infraestrutura distribuída, onde módulos de diferentes apps conversam via contratos semânticos.

---

### Fase 2.5: O Arquiteto & O Gestor ✅ (Concluído)
Implementamos a inteligência de criação. O **Arquiteto IA** projeta sistemas via briefing, e o **Schema Manager v3** permite o ajuste fino técnico 3-pane.

### Fase 2.75: Architect Tool Chain & Sovereign Navigation ✅ (Concluído)
Implementamos a **cadeia completa de ferramentas do arquiteto** e a **navegação soberana**:
- **Builder Hub**: Top bar contextual com seleção de contexto e acesso às ferramentas
- **FastApp Architect** (🟣 Indigo): Schema Studio v3 com editor 3-pane
- **FastApp Flow** (🔵 Blue): Visualização de metadados via Vue Flow (ER e Process)
- **FastApp Agent** (💜 Purple): AI Copilot com streaming e Domain-Aware Gap Analysis
- **Sidebar colapsável**: 15rem → 4rem com tooltips, estado persistido
- **Separação de contextos**: Navegação (rota) vs Builder (`selectedAppId`)
- **Ontologia v3**: Semântica expandida com `semantic`, `topology`, e campos enriquecidos

---

### Fase 3: A Forja 🔮 (Próximo Passo)

**O que é:** O nível "Pro". O sistema lê o manifesto e **escreve arquivos físicos** (`.vue`, `.ts`, `.prisma`) no disco.

**Fluxo:** `Manifesto → Engine lê → Gera pages/leads/index.vue de verdade`

**Vantagem:** Performance de código nativo + liberdade para customizar sem limitações do dinâmico.

**Impacto da Taxonomia:**
- `category: transactional` → gera automaticamente rotas de relatório/stats
- `category: master` → gera caches e dropdowns globais
- `category: configuration` → gera "Settings Page" simplificada
- `relations` → gera includes/joins automáticos nas queries

**Preparação (fazer agora):**
- Manter os componentes de Lead **muito bem organizados** — são os **Arquétipos**
- Documentar padrões de código nos componentes Lead/CRM
- Separar lógica de presentation vs logic nos componentes

**O que construir quando chegar aqui:**
- [ ] Template engine (Handlebars/EJS para .vue templates)
- [ ] CLI: `fastapp generate --app crm-flux`
- [ ] Diffing: detectar customizações do dev antes de re-gerar
- [ ] Scaffold: gerar `schema.prisma` a partir do manifesto + taxonomy

---

### Fase 4: O Ecossistema 🌐 (Visão)

**O que é:** O Fastapp gera não só código, mas **infraestrutura**.

**Fluxo:** `Módulo Financeiro → AWS A / Módulo CRM → AWS B / Micro-frontends conversam`

**Preparação (fazer agora):**
- [x] APIs padronizadas com `v1/data/` para roteamento futuro
- [ ] Pensar em namespaces por app no banco
- [ ] Design de API gateway

**Impacto da Taxonomia:**
- Objetos `master` (User) → serviço de Autenticação Central
- Objetos `transactional` → bancos de alta escrita
- Objetos `configuration` → config service com cache distribuído

---

## Features Implementadas

### Motor Dinâmico (Core)
- **CoreDynamicCRUD** — Orquestrador: modal, page, ou inline
- **CoreDynamicTable** — DataTable com colunas por `show_in_list`
- **CoreDynamicList** — List view com edição in-place
- **CoreDynamicForm** — Zod runtime + VeeValidate
- **CoreDynamicFields** — Recursivo para inner_collection
- **CoreFieldRenderer** — type → PrimeVue component
- **CoreDynamicFilter** — Filtro universal URL-driven com inputs adaptativos por tipo
- **CoreAppMenu** — Sidebar dinâmica por App/Module

### Schema Manager v3 (Novo) 🏗️
- **Arquitetura 3-Pane** — Navegação ágil e edição profunda simultânea
- **Editor Visual** — Drag & drop reordering, cards interativos
- **Deep Editor** — Controle total sobre metadados (labels, icons, types)
- **Live Sync** — Edições refletem imediatamente no Arquiteto IA

### Inteligência Artificial (Arquiteto) 🧠
- **Heuristic Parser** — Interpretação resiliente de outputs variados (JSON, Markdown)
- **Contexto Silencioso** — Handshake técnico invisível ao usuário
- **Taxonomy Aware** — Sugere e valida tipos, naturezas e categorias automaticamente

### API Dinâmica
- **Endpoints v1** — GET, POST, PATCH, DELETE genéricos
- **Hybrid Strategy** — Prisma model nativo ou tabela Record
- **Meta-validation** — Valida body contra manifest properties
- **Query Parser** — 9 operadores de filtro + sort, coerção de tipos
- **URL-Driven Sync** — URL ↔ Filter ↔ API ↔ Table (bookmarkável)

### Taxonomia
- **Category** — master, transactional, configuration (semântica do dado)
- **Nature** — physical, embedded, virtual (onde mora o dado)
- **Relations** — belongs_to, has_one, has_many, associates_with + storage strategy
- **Super-Seed** — App Gestão de Ativos com 6 objetos validando toda a taxonomia

### Snapshot System
- **Geração** — Endpoint converte DB → static-manifest.ts
- **Smart Store** — Prioriza estático em prod, fallback API
- **is_frozen** — Flag por App para forçar modo estático

### Dashboard de Ecossistema 🔗
- **Propostas Estratégicas** — Componentes visuais de alto impacto para pré-venda e roadmap.
- **SosPlantao**: Foco em Gestão Médica e Kit de Sucesso.
- **Central Filtros**: Foco em Manutenção Industrial e Automação Preventiva.
- **Technical Exploration** — Dashboard técnico gerado automaticamente com contagem de objetos, módulos e navegação rápida.
- **Custom Pages Routing** — Suporte a rotas hardcoded integradas dinamicamente ao menu do App.

### CRM Flux (Modelo 01)
- **Dashboard** com stats em tempo real
- **Kanban** com drag & drop + optimistic updates
- **Formulário inline** e modo página
- **Offline-first** com persistência localStorage
- **WebSocket** para sync multi-tab

### Admin Panel
- **App Management** — CRUD de Apps, Modules, Objects
- **Snapshot** — Botão gerar + badge STATIC/LIVE
- **Seed System** — Popula definições base

### Builder Hub & Sovereign Navigation 🛣️
- **Builder Hub** — Top bar contextual (`h-14`, `bg-[#0a0d14]`) com pill buttons segmentados
- **Sidebar Colapsável** — `15rem` expandida, `4rem` colapsada, estado persistido
- **App Switcher** — OverlayPanel com ícones gradiente e animações hover
- **2 Contextos Independentes** — Navegação (baseada em rota) vs Builder (baseado em selectedAppId)
- **Design DNA Consistente** — Mesmo padrão visual do Architect/Flow/Agent

### Ontologia v3 (Semântica Expandida) 🧠
- **Semantic Fields** — `asset`, `money`, `percentage`, `phone`, `email`, `url`
- **Topology** — `focal`, `connected`, `hierarchical` (governa a navegação)
- **Spatial Types** — `point`, `polygon` (ativa inteligência GIS)
- **Routing Types** — `waypoint`, `route` (ativa logística)

### Logística & Mapa 🗺️
- **CoreMapRenderer** — Renderização de pins com gradiente por status
- **CoreMapExplorer** — Mapa explorativo com Leaflet/Google Maps
- **Flow de Logística** — Vue Flow com topologia de rotas/atendimentos
- **Seed Automático** — Scripts `seed-[app-slug]-data.ts` para população

---

## Definições e Termos

| Termo | Significado |
|-------|-----------|
| **App** | Aplicação completa (CRM Flux, Helpdesk) |
| **Module** | Agrupamento lógico dentro do App (CRM, Financeiro) |
| **Object** | Entidade de dados (Lead, Tarefa, Contato) |
| **Property** | Campo do Object (nome, email, status) |
| **Manifest** | Estrutura JSON que define App → Module → Object → Property |
| **Static Manifest** | Snapshot: versão "congelada" do manifest em `.ts` |
| **Native Model** | Object com tabela Prisma dedicada (Lead) |
| **Generic Record** | Object dinâmico na tabela `Record` (data: Json) |
| **Builder** | Interface admin para criar/editar Objects e Properties (Schema Manager v3) |
| **Builder Hub** | Top bar contextual que conecta as ferramentas do Arquiteto |
| **Architect Tool Chain** | Conjunto: Agent + Architect + Flow, acessados pelo Builder Hub |
| **Query Parser** | Converte query params da URL em cláusulas `where`/`orderBy` do Prisma |
| **URL-Driven** | A URL é a fonte única de verdade para filtros (bookmarkável) |
| **Category** | Classificação semântica: master, transactional, configuration |
| **Nature** | Onde o dado mora: physical (tabela), embedded (JSON), virtual (calculado) |
| **Semantic** | Natureza semântica do campo: asset, money, phone, email, url |
| **Topology** | Dinâmica de navegação: focal (dashboard), connected, hierarchical |
| **Relation** | Vínculo tipado entre objects: belongs_to, has_many, etc. |
| **Storage Strategy** | Como a relação persiste: reference_id, document_embed, pivot |
| **Super-Seed** | Seed com taxonomia completa para validar a arquitetura |
| **Arquétipo** | Componente hardcoded (Lead) que serve de molde para o gerador futuro |
| **Motor / Engine** | Conjunto de componentes Core que interpretam o manifest |
| **Forja** | (Futuro) Gerador de código que escreve arquivos físicos |
| **Auto-Evolução** | Capacidade do motor de usar suas próprias ferramentas para evoluir |