Formát souboru pro import objednávek do TracePRO

Tento dokument popisuje generický JSON formát pro import výrobních objednávek a veškerých jejich dat (hlavička, výrobní postup, parametry, kusovník) z ERP do TracePRO. Import číselníků (pracovníci, pracoviště, úkony, nástroje, materiál) popisuje Formát souboru pro import číselníků do TracePRO.

Poznámka

Toto je návrh (v1), zatím neimplementováno. Otevřené otázky jsou shrnuty na konci dokumentu.

Zásady

1. Sémantika TracePRO, ne ERP. Mapování polí ERP na pojmy TracePRO je úkolem exportéru na straně ERP (tak, jako to dnes dělá import z Heliosu nebo QAD). JSON už nese hotové hodnoty ve významu TracePRO.

2. Symbolické enumy jako řetězce, ne čísla ("active", ne 1) - kvůli čitelnosti a stabilitě formátu.

3. Každá objednávka v souboru je kompletní snapshot. Import provede sloučení: operace, řádek kusovníku nebo parametr, který v JSON není, se smaže. Ochrany proti nechtěnému přepsání (rozběhnutá objednávka, příznak NO_ERP_UPDATE, koncové stavy) zůstávají v importeru, stejně jako v QAD importu (CanUpdateOrder).

4. Data se strukturovaným významem mají dedikovaná pole (časy, programy). Vše ostatní jde do volných params (klíč/hodnota), které se mapují 1:1 na OperationParam.

Příklad

{
    "format": "tracepro-order",
    "version": 1,
    "source": "HELIOS",
    "generated": "2026-07-09T10:30:00",
    "operation": "update",
    "entities": [
        {
            "erp_ref": "VP-2026-00123",
            "item": "778-3283-001",
            "item_name": "Řídicí deska XYZ",
            "amount": 1200,
            "customer": "COMAP",
            "status": "notstarted",
            "vd": "B.2",
            "cat1": "A",
            "cat2": "",
            "cat3": "",
            "flags": ["loose_ops", "limit_amount"],

            "mptp": "mp_pcb",
            "mpcount": 8,
            "barcode_mp": "^MP[0-9]{8}$",
            "barcode_pcb": "^52-01[0-9]{6}$",

            "params": {
                "INFO": "Poznámka z ERP...",
                "CUSTOMER_ORDER_ID": "OBJ-556677",
                "CLIENT_WARNINGS": "IPC610_CLASS3",
                "SW_VER": "1.4.2",
                "DOKUMENTACE": "https://dms/..."
            },

            "operations": [
                {
                    "op": 10,
                    "act": 2523,
                    "name": "Osazování SMD TOP",
                    "workplace": "SMT1-01",
                    "desc": "Text návodky...",
                    "flags": ["parallel"],
                    "times": {
                        "prep": 1800,
                        "run": 54.5,
                        "end": 0,
                        "between_ops": 0
                    },
                    "program": "778-3283-001_top",
                    "programs": {
                        "SMD": "778-3283-001_top",
                        "SPI": "778-3283-001_spi"
                    },
                    "docs": "https://dms/op10",
                    "box_size": null,
                    "params": {}
                },
                {
                    "op": 90,
                    "act": 3761,
                    "name": "Dělení panelu",
                    "workplace": "CUT-01",
                    "desc": "",
                    "flags": ["splitpanel"],
                    "times": {"run": 12},
                    "params": {}
                },
                {
                    "op": 100,
                    "act": 5000,
                    "name": "Balení",
                    "workplace": "PACK-01",
                    "desc": "",
                    "flags": [],
                    "box_size": 20,
                    "params": {}
                }
            ],

            "bom": [
                {"op": 10, "type": "mat",
                 "item": "R0603-10K", "amount": 74, "comment": "R1-R74"},
                {"op": 10, "type": "mat_prep",
                 "item": "PASTE-SAC3", "amount": 0.1, "comment": ""},
                {"op": 10, "type": "tool",
                 "item": "SITO-778", "amount": 1, "comment": ""},
                {"op": 100, "type": "mat",
                 "item": "BOX-200", "amount": 0.05, "comment": ""}
            ]
        }
    ]
}

Obálka souboru

Pole	Popis
format	Vždy "tracepro-order".
version	Verze formátu, aktuálně 1.
source	Identifikace zdrojového ERP (volný text, např. "HELIOS", "QAD").
generated	Datum a čas vygenerování souboru (ISO 8601, lokální čas).
operation	"create" | "update" | "delete", společná pro celý soubor. Systém nemusí rozlišovat mezi create a update - obojí provede sloučení. Při delete stačí, aby každá objednávka obsahovala jen erp_ref.
entities	Seznam objednávek.

Objednávka

Pole bez hodnoty ve sloupci Povinné/Default jsou volitelná s defaultem (prázdný řetězec / 0 / prázdný seznam).

Pole	Cíl v TracePRO	Povinné/Default	Popis
erp_ref	ProductionOrder.erp_ref	ano	Jedinečný identifikátor objednávky v ERP. Klíč pro sloučení.
item	ProductionOrder.item	ano	Označení vyráběné položky.
item_name	ProductionOrder.item_name		Název / popis vyráběné položky.
amount	ProductionOrder.amount	ano	Objednané množství.
customer	ProductionOrder.customer		Název zákazníka.
status	ProductionOrder.status	ano	"notstarted" | "active" | "finished" | "cancelled".
vd	ProductionOrder.vd		Verze dokumentace.
cat1, cat2, cat3	ProductionOrder.cat1 - cat3		Kategorie (např. cat1: "A" = automotive, "N" = normální).
flags	ProductionOrder.flags		Seznam symbolických příznaků, viz níže.
mptp	ProductionOrder.mptp	single pokud mpcount == 1, jinak mp_pcb	Typ panelizace a značení, viz níže.
mpcount	ProductionOrder.mpcount	1	Počet PCB v multipanelu.
barcode_mp	ProductionOrder.barcode_mp		Regulární výraz pro barkód multipanelu.
barcode_pcb	ProductionOrder.barcode_pcb		Regulární výraz pro barkód PCB.
params	OperationParam (op = NULL)		Volné parametry objednávky, klíč/hodnota.
operations	Operation	ano	Výrobní postup.
bom	OrderBOM		Kusovník.

Příznaky objednávky (flags):

JSON	defs.py
loose_ops	PRODORDER_FLAG_LOOSE_OPS - Systém povolí vložení očíslované operace mimo postup.
limit_amount	PRODORDER_FLAG_LIMIT_AMOUNT - Systém nepovolí založit více položek, než je amount.
block_production	PRODORDER_FLAG_BLOCK_PRODUCTION - Blokovat výrobu - na pracovištích Práce nepůjdou načíst operace.

Pole dt0 / dt1 v JSON nejsou - nastavuje je TracePRO při přechodech stavů objednávky.

Hodnoty mptp:

JSON	defs.py	Popis
single	PRODORDER_MPTP_SINGLE	Jednotlivé PCB s barkódy.
mp_pcb	PRODORDER_MPTP_MPPCB	Multipanel i PCB s barkódy (nejběžnější).
mp_only	PRODORDER_MPTP_MPBC_PCBNOBC	Multipanel s barkódem, PCB bez.
pcb_only	PRODORDER_MPTP_MPNOBC_PCBBC	Multipanel bez barkódu, barkódy jen na PCB.
none	PRODORDER_MPTP_NO_BARCODE	Bez barkódů.
mp_late_pcb	PRODORDER_MPTP_MP_LATEPCB	Nejprve multipanel, později v procesu i PCB.

Operace

Přirozený klíč pro sloučení je op.

Pole	Cíl v TracePRO	Povinné/Default	Popis
op	Operation.op	ano, číslo větší než 0	Číslo operace.
act	Operation.act	ano, číslo	Číslo úkonu.
name	Operation.name		Název operace.
workplace	Operation.workplace		erp_ref pracoviště nebo skupiny pracovišť.
desc	Operation.desc		Text operace - návodka - prostý text.
flags	Operation.flags		Seznam symbolických příznaků, viz níže.
times	parametry tm_*		Výrobní časy, viz níže.
program	param PROGRAM		Název hlavního programu operace.
programs	param PROGRAM_<klíč>		Další programy; klíč objektu je přípona parametru.
docs	param stddocs		Odkaz na dokumentaci operace.
box_size	param BOX_SIZE		Počet kusů v krabici, pokud je operace balení. Hodnota > 0 zároveň nastaví PRODORDER_FLAG_BOXES na objednávce.
params	OperationParam (op = číslo operace)		Volné parametry operace, klíč/hodnota.

Příznaky operace (flags):

JSON	defs.py	Popis
unscanned	OP_FLAG_UNSCANNED	Operace nemusí být načtena.
parallel	OP_FLAG_PARALLEL	Nekontrolovat předchozí operace.
splitpanel	OP_FLAG_SPLITPANEL	Na této operaci se panel dělí na jednotlivá PCB.
notify	OP_FLAG_NOTIFY	Upozornit uživatele při prvním odvedení operace.

Úkon

Co je Úkon? Některá ERP (např. Infor) mají zabudovaný koncept úkonu. Je to typové označení operace, které má fixní číslo a fixní jméno (titulek, text). Pokud úkon v ERP není, zpravidla se místo něj používá pracoviště. Vztah mezi úkonem a pracovištěm ale nemusí být 1:1. Např. pokud jsou pracoviště v ERP detailně specifikována, např. jako SMD linka 1, SMD linka 2, SMD linka 3, tak úkon, který se dělá na kterékoliv lince může být SMD osazování.

TracePRO podle čísla úkonu rozhoduje, jakým způsobem se pro operaci počítají statistiky. TracePRO podporuje také sadu speciálních úkonů, pro operace, které nejsou v technologickém postupu. Např. Kontrola 1.ks, Oprava, Poznámka.

Pokud v ERP koncept úkonu není, použije se míst něj nějaká forma pracoviště.

Sekce times

Všechny časy jsou v sekundách, desetinná čísla jsou povolena. Chybějící klíč znamená 0. Klíče odpovídají parametrům tm_* (viz Integrace s ERP - detaily importu), jen bez prefixu tm_:

prep, run, end, between_ops.

Pozn.: v dřívějších verzích TracePRO se rozlišovalo mezi časem operátora a časem stroje. Skutečnost ale je taková, že při sledování výroby se prostě sleduje čas na výrobu jednoho kusu, a nezáleží na tom, na kolika strojích nebo kolik lidí vyrábělo. Pokud bylo na operaci nahlášeno více pracovníků, odvede se jim všem celý čas. A to je všechno.

TracePRO čas potřebuje jen pro to zobrazování normy na pracovišti - tam chceme znát takt - a na výpočet OEE, využitelnosti, nebo dalších přehledů.

Kusovník (bom)

Pole	Cíl v TracePRO	Povinné/Default	Popis
op	OrderBOM.op		Číslo operace, ke které materiál patří.
type	OrderBOM.tp	ano	Typ řádku, viz níže.
item	OrderBOM.mat_item	ano	Artikl.
amount	OrderBOM.amount		Množství na 1 kus výrobku.
comment	OrderBOM.comment		Poznámka / reference.

Typy řádků (type):

JSON	defs.py	Popis
mat	ORDER_BOM_TP_MAT	Materiál bez zvláštního zacházení (nenačítá se).
mat_prep	ORDER_BOM_TP_MAT_PREP	Materiál, který se musí načíst v rámci přípravy.
tool	ORDER_BOM_TP_TOOL	Nástroj / přípravek.
part	ORDER_BOM_TP_PART	Díl - vyráběná položka použitá na této pozici.

Otevřené otázky

1. Barkódy: jen hotové regexy, nebo i masky/prefixy? Návrh počítá s tím, že ERP dodá rovnou regexy barcode_mp / barcode_pcb. QAD ale posílá prefixy a masky (pre_desk, mask_dps, …) a regexy se generují zákaznickou logikou. Má formát podporovat i sekci barcode_hints (prefix/suffix/maska/min/max pro panel i PCB) s tím, že generování regexů zůstane na straně TracePRO?

2. Identita řádků při sloučení. Operace mají přirozený klíč op, kusovník ale ne - QAD to řeší přes externí id (NVGQADIds). Stačí klíčovat kusovník přes (op, type, item), nebo přidat volitelné pole erp_id na operaci / řádek kusovníku?

3. Transport a potvrzení. Soubory v adresáři (drop dir + periodické čtení, jako QAD), nebo JSON-RPC/HTTP endpoint s okamžitou odpovědí s validačními chybami? Ovlivňuje, zda je potřeba navrhnout i formát odpovědi / error reportu.