🚀 GUIA COMPLETO: COMO O FRAPPE FUNCIONA

Treinamento Técnico Detalhado - From Frontend to Database

📋 ÍNDICE

🏗️ 1. VISÃO GERAL DA ARQUITETURA {#arquitetura}

Stack Tecnológico:

┌─────────────────────────────────────────────────────────────┐
│                     FRAPPE STACK                            │
├─────────────────────────────────────────────────────────────┤
│ Frontend   │ JavaScript (ES6+) + jQuery + Bootstrap         │
│ Backend    │ Python 3.x + Flask/Werkzeug                    │
│ Database   │ MariaDB/MySQL + SQLAlchemy-like ORM            │
│ Cache      │ Redis (sessões, cache, real-time)              │
│ Queue      │ Redis + RQ (background jobs)                   │
│ WebServer  │ Nginx (proxy) + Gunicorn (WSGI)                │
└─────────────────────────────────────────────────────────────┘

Arquitetura MVC Estendida:

Frontend (View)           Backend (Controller)         Database (Model)
     │                           │                           │
     ├─ form.js                  ├─ document.py              ├─ tabDocType
     ├─ frappe.ui.form.on()      ├─ hooks.py                 ├─ tabSingles
     ├─ triggers/events          ├─ @frappe.whitelist()      ├─ tab[CustomDocType]
     └─ frappe.call()            └─ DocType classes          └─ Child Tables

🎭 2. FRONTEND: FORM SCRIPTS E TRIGGERS {#frontend}

2.1 Como frappe.ui.form.on() Funciona:

// Estrutura básica de um form script
frappe.ui.form.on('DocType Name', {
    // Eventos do documento principal
    refresh: function(frm) {
        // Chamado sempre que o form é carregado/refrescado
        console.log("Form refreshed:", frm.doc);
    },

    validate: function(frm) {
        // Chamado antes de salvar (client-side validation)
        if (!frm.doc.required_field) {
            frappe.throw("Campo obrigatório não preenchido");
        }
    },

    fieldname: function(frm) {
        // Chamado quando 'fieldname' muda
        frm.set_value('dependent_field', frm.doc.fieldname * 2);
    }
});

// Eventos para tabelas filhas
frappe.ui.form.on('Child DocType', {
    fieldname: function(frm, cdt, cdn) {
        // cdt = Child DocType
        // cdn = Child Document Name (unique ID)
        let row = locals[cdt][cdn];
        row.calculated_field = row.qty * row.rate;
        frm.refresh_field('child_table');
    }
});

2.2 Ordem de Execução dos Triggers:

// Sequência cronológica de eventos:
/*
1. setup()           - Primeira vez que o form é criado
2. onload()          - Toda vez que um documento é carregado
3. refresh()         - Após onload, sempre que form atualiza
4. [field_change]()  - Quando campo específico muda
5. validate()        - Antes de salvar (client-side)
6. before_save()     - Antes de enviar para servidor
7. after_save()      - Após salvar com sucesso
*/

frappe.ui.form.on('Nota Fiscal - Servico', {
    setup: function(frm) {
        // Configurações iniciais do form
        frm.set_query('customer', function() {
            return { filters: { disabled: 0 } };
        });
    },

    onload: function(frm) {
        // Executado quando documento é carregado
        if (frm.doc.__islocal) {
            frm.set_value('date', frappe.datetime.now_date());
        }
    },

    refresh: function(frm) {
        // Sempre executado após onload
        frm.toggle_display('section_break', !frm.doc.is_simple);

        // Botões customizados
        if (frm.doc.docstatus === 1) {
            frm.add_custom_button('Custom Action', function() {
                // Ação customizada
            });
        }
    },

    valor_servicos: function(frm) {
        // Trigger específico do campo
        if (frm.doc.valor_servicos) {
            frm.set_value('base_calculo', frm.doc.valor_servicos);

            // Chamar função Python
            frappe.call({
                method: 'nxlite.scripts.calculo_imposto.calculo_imposto_nfse',
                args: { doc: frm.doc },
                callback: function(r) {
                    if (r.message) {
                        frm.set_value(r.message);
                    }
                }
            });
        }
    },

    validate: function(frm) {
        // Validação client-side
        if (frm.doc.valor_servicos <= 0) {
            frappe.throw('Valor dos serviços deve ser maior que zero');
        }
    }
});

2.3 Gerenciamento de Estado no Frontend:

// Como o Frappe gerencia estado
/*
┌─────────────────────────────────────────────────────────────┐
│                     FRONTEND STATE                          │
├─────────────────────────────────────────────────────────────┤
│ cur_frm.doc      │ Documento atual (objeto principal)       │
│ locals           │ Cache de todos os documentos carregados  │
│ frappe.model     │ Funções para manipular documentos        │
│ frm.dirty()      │ Verifica se há mudanças não salvas       │
│ frm.is_new()     │ Documento é novo (__islocal = true)      │
└─────────────────────────────────────────────────────────────┘
*

// Exemplo de manipulação de estado
frappe.ui.form.on('Nota Fiscal - Servico', {
    refresh: function(frm) {
        console.log("Documento:", frm.doc);
        console.log("É novo?", frm.is_new());
        console.log("Está sujo?", frm.is_dirty());
        console.log("Status:", frm.doc.docstatus);

        // Acessar tabela filha
        frm.doc.tab_servicos.forEach(function(row) {
            console.log("Item:", row.item, "Valor:", row.valor_total);
        });
    }
});

🔄 3. COMUNICAÇÃO FRONTEND ↔ BACKEND {#comunicacao}