Skip to content

Fondamenti Frappe in FactoryOS ​

Scopo ​

Raccogliere gli elementi Frappe Framework v16 usati da Ez FactoryOS, con mapping al codice reale e link alla documentazione ufficiale. Pagina di riferimento per operatori tecnici e sviluppatori.

Fonti ufficiali: Frappe Framework, User Guide, Bench, REST API.

DocType — unità base ​

Ogni entità FactoryOS è un DocType (DocTypes): metadati JSON + controller Python + viste generate.

ConcettoIn FactoryOSFile reali
DocType masterFactory Customer/Supplier/Product/Line/Machine/Operator/Shift/Work Order…apps/ez_factoryos/ez_factoryos/ez_factoryos/doctype/<name>/<name>.json
Child tableProduct Material/Packaging/Label Item, Line Machine ItemStessa cartella, istable: 1
SingleMachine Connection Profile, Ez FactoryOS Settingsissingle: 1, un solo record
ControllerValidazioni validate / before_savefactory_work_order.py, factory_machine.py
FixturesRuoli, Number Card, Custom HTML Blockhooks.py → fixtures
PatchMigrazioni dati/strutturaapps/ez_factoryos/ez_factoryos/patches/v0_1/ + patches.txt

Regole applicate (da .cursor/rules/frappe-development.mdc): naming anagrafiche Factory <Entità>, codici via naming_series, mai tabelle SQL manuali, mai modifiche al core Frappe, tutto in apps/ez_factoryos/.

Desk: List view, Form view, Workspace ​

Il Desk genera viste dai metadati (Desk).

VistaGenerata daIn FactoryOS
List viewCampi in_list_view, in_standard_filter, sort_field/orderListe WO/macchine/prodotti con filtri ed export CSV (List view)
Form viewfield_order, Section/Column Break, reqd, read_only, uniqueForm anagrafiche con validazioni (Form view)
WorkspaceDocType Workspace + Number Card + Custom HTML Block/desk/ez-factoryos con Entity Cards e 5 Number Card (Workspace)
Awesome BarRicerca globaleAccesso rapido a DocType/record, unico accesso per Machine Command/Event/Data Log (Awesomebar)
Number CardDocType Number Card (function: Count, filters_json)Active Products/Lines/Machines/Operators, Open Work Orders (Number Card)

Naming series ​

Codici univoci via campo naming_series (Naming): autoname: "naming_series:" nei JSON.

DocTypeSerieEsempio
Factory CustomerFC-.YYYY.-FC-2026-00001
Factory SupplierFS-.YYYY.-FS-2026-00001
Factory ProductFPR-.YYYY.-FPR-2026-00001
Factory Raw MaterialFRM-.YYYY.-FRM-2026-00001
Factory PackagingFPK-.YYYY.-FPK-2026-00001
Factory LineFLN-.YYYY.-FLN-2026-00001
Factory MachineFMC-.YYYY.-FMC-2026-00001
Factory OperatorFOP-.YYYY.-FOP-2026-00001
Factory ShiftFSH-.YYYY.-FSH-2026-00001
Factory Work OrderFWO-.YYYY.-FWO-2026-00001
Machine CommandMCMD-.YYYY.-MCMD-2026-00001
Machine EventMEV-.YYYY.-MEV-2026-00001
Machine Data LogMDL-.YYYY.-MDL-2026-00001

Eccezioni (autoname per nome): Factory Product Category (category_name), Factory Product Label (label_name).

Permessi e ruoli ​

Permission engine nativo (Users and Permissions, Permission Types).

  • Permessi per DocType nei JSON (permissions: read/write/create/delete/export/print/email/report/share per ruolo).
  • Visibilità app: has_app_permission (ez_factoryos.ez_factoryos.api.permission) — solo Factory Admin, Production Manager, Line Operator, Warehouse Operator, Administrator.
  • Check in codice: frappe.has_permission(doctype, ptype), frappe.get_roles(), frappe.throw(..., frappe.PermissionError) (vedi integrations/node_red/api.py).
  • Ruoli creati in setup/install.py con desk_access: 1, esportati via fixtures.

API REST e RPC ​

Frappe espone REST per risorse e RPC per metodi whitelist (REST API, API REST).

REST — CRUD su DocType ​

bash
# Lista (con filtri)
curl -sS "https://factoryos.ezbit.it/api/resource/Factory%20Work%20Order?filters=[[\"status\",\"in\",[\"To Plan\",\"Planned\"]]]&limit_page_length=20" \
  -H "Authorization: token <api_key>:<api_secret>"

# Singolo documento
curl -sS "https://factoryos.ezbit.it/api/resource/Factory%20Machine/FMC-2026-00001" \
  -H "Authorization: token <api_key>:<api_secret>"

# Creazione
curl -sS -X POST "https://factoryos.ezbit.it/api/resource/Factory%20Work%20Order" \
  -H "Authorization: token <api_key>:<api_secret>" \
  -H "Content-Type: application/json" \
  -d '{"product":"FPR-2026-00001","quantity":100,"status":"To Plan"}'

API key/secret: Desk → avatar → My Settings → API Access → Generate Keys (solo utenti con ruolo abilitato).

RPC — metodi whitelist FactoryOS ​

Funzioni decorate @frappe.whitelist() (frappe.call), chiamabili via /api/method/<dotted.path> (GET per letture, POST per scritture).

MetodoPathEffetto
get_entity_cardsez_factoryos.ez_factoryos.api.dashboard.get_entity_cardsConteggi workspace
list_node_red_machinesez_factoryos.integrations.node_red.api.list_node_red_machinesInventario gateway
sync_machine_from_node_red...api.sync_machine_from_node_redUpsert Factory Machine
read_machine_data...api.read_machine_dataLettura + Machine Data Log
request_machine_command...api.request_machine_commandComando in Pending Approval
approve_machine_command / reject_machine_command...api.approve_machine_commandApprovazione
get_machine_commands...api.get_machine_commandsComandi ammessi dall'inventario Node-RED
ingest_machine_event / ingest_machine_telemetry...api.ingest_machine_eventCallback gateway (token X-FactoryOS-Gateway-Token)

Esempio RPC:

bash
curl -sS -X POST https://factoryos.ezbit.it/api/method/ez_factoryos.integrations.node_red.api.read_machine_data \
  -H "Authorization: token <api_key>:<api_secret>" \
  -H "Content-Type: application/json" \
  -d '{"machine":"FMC-2026-00001","keys":["weight","speed"]}'

Da client Desk (JS): frappe.call({ method: "ez_factoryos.integrations.node_red.api.list_node_red_machines" }).

Sicurezza: i metodi controllano i ruoli (_require_roles) o il gateway token (_require_roles_or_gateway). Unici endpoint guest: ingest_machine_event e ingest_machine_telemetry (solo POST), che senza token gateway valido respingono Guest (ADR-0005).

Bench CLI e site config ​

Bench è il tool di gestione siti Frappe (Bench). In FactoryOS si usa dentro Docker via ./scripts/bench-exec.sh o make.

ComandoUso
bench --site factory.local list-appsApp installate (atteso: frappe + ez_factoryos)
bench --site factory.local migrateApplica DocType JSON + patch (make migrate)
bench --site factory.local consoleConsole Python con frappe caricato
bench --site factory.local run-tests --app ez_factoryosTest app (make test)
bench --site factory.local get-config mute_emailsLegge site config
bench --site factory.local set-config mute_emails 1Scrive site config
bench versionVersioni frappe/bench
bench execute <dotted.method>Esegue metodo server (bench execute)

Config sito (site_config.json, mai in git): node_red_gateway_token / node_red_api_token, mute_emails, disable_external_webhooks, business_cube_api_url (svuotato su staging). Accesso in codice: frappe.conf.get("...").

Scheduler, job e hook ​

  • hooks.py: app_name/title, app_logo_url (/assets/ez_factoryos/images/Ez_FactoryOS_Logo.png, varianti _Height e _Wide), add_to_apps_screen (route /desk/ez-factoryos), fixtures, after_install.
  • Nessuno scheduler_events / doc_events attivi nel codice (sezioni commentate in hooks.py).
  • Queue RQ/Redis disponibili via runtime ma senza job FactoryOS schedulati: letture/comandi sono on-demand da Desk/API o callback gateway.

Riferimenti ufficiali ​

Ez FactoryOS — MES per Ortobellina / OP Raggio di Sole · App Frappe v16 ez_factoryos