Controllers e ciclo de vida de documentos

Todo documento em execução é uma instância de Document. É no controller que regras de negócio, validações e efeitos colaterais são consolidados.

Acesso básico com neo.get_doc

import neo

doc = neo.get_doc("Task", "TASK-0001")
doc.status = "Closed"
doc.save()

Criação em memória:

doc = neo.get_doc({
    "doctype": "Task",
    "title": "Revisar documentação NEO",
    "status": "Open"
})
doc.insert()

Métodos úteis

Método	Uso
neo.get_doc()	Carrega ou instancia documento
neo.new_doc()	Cria documento vazio
doc.insert()	Insere novo registro
doc.save()	Persiste alterações
doc.submit()	Submete documento
doc.cancel()	Cancela documento
doc.append()	Adiciona linha em child table

Exemplo de controller

from neo.model.document import Document
import neo

class LibraryMember(Document):
    def before_save(self):
        parts = [self.first_name or "", self.last_name or ""]
        self.full_name = " ".join(p for p in parts if p).strip()

    def validate(self):
        if self.email and neo.db.exists("Library Member", {
            "email": self.email,
            "name": ["!=", self.name]
        }):
            neo.throw("Já existe um associado com este e-mail.")

Eventos comuns do ciclo de vida

• before_insert

• after_insert

• validate

• before_save

• on_update

• before_submit

• on_submit

• before_cancel

• on_cancel

Cada evento deve ser usado com intenção clara.

Estratégia para distribuir lógica

validate

Consistência do documento antes da gravação.

before_save

Cálculo de derivados e ajustes internos.

on_submit

Ações que só fazem sentido após confirmação formal.

Serviços auxiliares

Quando a lógica atravessa vários DocTypes ou precisa ser reutilizada.

Relação entre controller e front-end

O front-end pode disparar uma ação, mas o controller continua sendo a fonte da verdade. Isso vale para:

• botões do formulário;

• chamadas RPC;

• portal;

• importações;

• jobs.

Exemplo de botão no front-end chamando backend

Cliente:

neo.ui.form.on("Library Membership", {
    refresh(frm) {
        if (!frm.is_new()) {
            frm.add_custom_button("Ativar", () => {
                neo.call({
                    method: "biblioteca.membership.api.activate_membership",
                    args: { membership_name: frm.doc.name },
                    callback() {
                        frm.reload_doc();
                    }
                });
            });
        }
    }
});

Servidor:

import neo

@neo.whitelist()
def activate_membership(membership_name):
    doc = neo.get_doc("Library Membership", membership_name)
    doc.status = "Active"
    doc.save()
    return {"name": doc.name, "status": doc.status}

Erros comuns

• lógica crítica apenas em Client Script;

• uso excessivo de ignore_permissions=True;

• consultas pesadas em validate;

• integração externa antes do commit.