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.
| Concetto | In FactoryOS | File reali |
|---|---|---|
| DocType master | Factory Customer/Supplier/Product/Line/Machine/Operator/Shift/Work Order… | apps/ez_factoryos/ez_factoryos/ez_factoryos/doctype/<name>/<name>.json |
| Child table | Product Material/Packaging/Label Item, Line Machine Item | Stessa cartella, istable: 1 |
| Single | Machine Connection Profile, Ez FactoryOS Settings | issingle: 1, un solo record |
| Controller | Validazioni validate / before_save | factory_work_order.py, factory_machine.py |
| Fixtures | Ruoli, Number Card, Custom HTML Block | hooks.py → fixtures |
| Patch | Migrazioni dati/struttura | apps/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).
| Vista | Generata da | In FactoryOS |
|---|---|---|
| List view | Campi in_list_view, in_standard_filter, sort_field/order | Liste WO/macchine/prodotti con filtri ed export CSV (List view) |
| Form view | field_order, Section/Column Break, reqd, read_only, unique | Form anagrafiche con validazioni (Form view) |
| Workspace | DocType Workspace + Number Card + Custom HTML Block | /desk/ez-factoryos con Entity Cards e 5 Number Card (Workspace) |
| Awesome Bar | Ricerca globale | Accesso rapido a DocType/record, unico accesso per Machine Command/Event/Data Log (Awesomebar) |
| Number Card | DocType 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.
| DocType | Serie | Esempio |
|---|---|---|
| Factory Customer | FC-.YYYY.- | FC-2026-00001 |
| Factory Supplier | FS-.YYYY.- | FS-2026-00001 |
| Factory Product | FPR-.YYYY.- | FPR-2026-00001 |
| Factory Raw Material | FRM-.YYYY.- | FRM-2026-00001 |
| Factory Packaging | FPK-.YYYY.- | FPK-2026-00001 |
| Factory Line | FLN-.YYYY.- | FLN-2026-00001 |
| Factory Machine | FMC-.YYYY.- | FMC-2026-00001 |
| Factory Operator | FOP-.YYYY.- | FOP-2026-00001 |
| Factory Shift | FSH-.YYYY.- | FSH-2026-00001 |
| Factory Work Order | FWO-.YYYY.- | FWO-2026-00001 |
| Machine Command | MCMD-.YYYY.- | MCMD-2026-00001 |
| Machine Event | MEV-.YYYY.- | MEV-2026-00001 |
| Machine Data Log | MDL-.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/shareper 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)(vediintegrations/node_red/api.py). - Ruoli creati in
setup/install.pycondesk_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
# 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).
| Metodo | Path | Effetto |
|---|---|---|
get_entity_cards | ez_factoryos.ez_factoryos.api.dashboard.get_entity_cards | Conteggi workspace |
list_node_red_machines | ez_factoryos.integrations.node_red.api.list_node_red_machines | Inventario gateway |
sync_machine_from_node_red | ...api.sync_machine_from_node_red | Upsert Factory Machine |
read_machine_data | ...api.read_machine_data | Lettura + Machine Data Log |
request_machine_command | ...api.request_machine_command | Comando in Pending Approval |
approve_machine_command / reject_machine_command | ...api.approve_machine_command | Approvazione |
get_machine_commands | ...api.get_machine_commands | Comandi ammessi dall'inventario Node-RED |
ingest_machine_event / ingest_machine_telemetry | ...api.ingest_machine_event | Callback gateway (token X-FactoryOS-Gateway-Token) |
Esempio RPC:
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.
| Comando | Uso |
|---|---|
bench --site factory.local list-apps | App installate (atteso: frappe + ez_factoryos) |
bench --site factory.local migrate | Applica DocType JSON + patch (make migrate) |
bench --site factory.local console | Console Python con frappe caricato |
bench --site factory.local run-tests --app ez_factoryos | Test app (make test) |
bench --site factory.local get-config mute_emails | Legge site config |
bench --site factory.local set-config mute_emails 1 | Scrive site config |
bench version | Versioni 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_Heighte_Wide),add_to_apps_screen(route/desk/ez-factoryos),fixtures,after_install.- Nessuno
scheduler_events/doc_eventsattivi nel codice (sezioni commentate inhooks.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
- Frappe Framework — home documentazione.
- DocTypes — metadati, campi, naming.
- Desk — Awesome Bar, List/Form, Workspace.
- Users and Permissions — ruoli e permessi.
- REST API — REST + RPC,
frappe.call. - Bench — CLI siti/app.
- Hooks —
hooks.py, fixtures, scheduler.
