bmc_hub/fremtidige planer/vareintegration-economic.md

Plan – vareintegration mellem BMC Hub og e-conomic

Status: Implementeret lokalt 12. september 2026. Produktionsaktivering kræver separat, kontrolleret import-preview og gennemgang af e-conomic-forbindelsen. Opdateret: 12. september 2026.

Tillæg 13. september 2026: Ændring af eksisterende kunder og varer er kun tilladt gennem 4-øjne-flowet. Opretteren kan ikke godkende sin egen anmodning; før/efter-data genkontrolleres mod e-conomic umiddelbart før en godkendt PUT. Alle andre opdateringer og sletninger forbliver blokeret.

1. Formål og leverance

Hub er arbejdsfladen for produkter, leverandørdata og priser til tilbud, ordrer, abonnementer og tidsregistrering. e-conomic er autoritativ for økonomiske varereferencer, varegrupper, moms og bogførte dokumenter. Operatøren skal kunne importere, oprette, finde og vedligeholde varer fra Hub uden dobbeltindtastning.

Planen erstatter antagelsen om, at et lokalt SKU automatisk er et e-conomic-varenummer. Alle økonomiske eksportveje skal bruge en verificeret kobling. Eksisterende dokumenter og produktrelationer bevares under indførelsen.

2. Beslutninger

• Bevar eksisterende products.id som integer og eksisterende uuid. Der etableres ikke et parallelt produktkatalog.
• Tilføj economic_product_number som tekst på højst 25 tegn. Nummeret er permanent efter kobling og kan indeholde bogstaver og foranstillede nuller.
• e-conomic ejer det officielle nummer. Det betyder ikke, at API'et automatisk tildeler det: ved produktoprettelse sender integrationen et nummer efter en kontrolleret nummerpolitik.
• Lokale kladder er tilladt. Økonomisk eksport kræver verificeret produktkobling.
• Alle e-conomic-produkter importeres, også spærrede/inaktive. Manglende poster i en delvis import må aldrig udløse deaktivering.
• Navn vedligeholdes i Hub efter første import. Ændringer gemmes kun lokalt og må aldrig sendes som en opdatering til e-conomic.
• Økonomisk varegruppe og ekstern status vedligeholdes i e-conomic i version 1. Redigering af disse fra Hub er en senere udvidelse med særskilte rettigheder.
• Varegruppe og enhed arves ikke blindt fra produkt 1000. De vælges fra synkroniserede værdier eller en eksplicit administrativ mapping.
• Standardpriser er separate: sales_price er Hub-standardpris; economic_sales_price_reference er e-conomics referencepris.
• Ukendte katalogvarer konverteres ikke automatisk til fritekst ved eksport.
• Eksisterende katalogvarer i e-conomic overskrives ikke som følge af en ordreeksport.

3. Ejerskab og konflikter

Felt	Autoritet	Regel
Officielt varenummer	e-conomic	Permanent kobling, ingen almindelig redigering
Navn	Hub efter første import	Lokal ændring forbliver i Hub; ekstern afvigelse kan accepteres lokalt
Økonomisk varegruppe, moms og bogføring	e-conomic	Importeres; Hub-kategorier må ikke ændre dem indirekte
Ekstern aktiv/spærret-status	e-conomic	Blokerer ny eksport, historik bevares
Intern kategori, udfasning, metadata	Hub	Import overskriver ikke lokale værdier
Referencepris	e-conomic	Opdaterer kun referencefeltet
Hub-standardpris og prisregler	Hub	Ændrer ikke allerede gemte dokumentpriser
Leverandørpris og lagerstatus	Leverandør	Gemmes pr. leverandør med kilde og tidspunkt
Bogført faktura	e-conomic	Hub spejler status og reference

Sammenlign lokal værdi, senest synkroniserede værdi og ny ekstern værdi ved import. Gem feltversion og hash, så en forsinket import ikke overskriver en nyere lokal ændring. En ekstern navneændring efter første import kan accepteres ind i Hub. Hub må ikke sende navneændringer tilbage til e-conomic.

4. Datamodel og kompatibilitet

Produkter

Udvid eksisterende tabel og genbrug eksisterende felter, hvor betydningen passer:

• id, uuid, navn, korte/lange beskrivelser, producent og producent-SKU.
• economic_connection_id, economic_product_number, economic_product_group_number.
• economic_sales_price_reference, separat referencevaluta, ekstern enhedsreference.
• Eksisterende sales_price, cost_price, samt eksplicit valuta og kilde for disse beløb.
• Intern kategori og underkategori; eksisterende metadata og tekniske JSON-felter.
• is_active_in_economic, intern aktiv-status og separat lifecycle_status: kladde, aktiv, udfases, inaktiv.
• sync_status: ikke koblet, afventer, synkroniserer, synkroniseret, konflikt, fejl.
• Seneste eksterne snapshot/hash, lokal versionsværdi, tidspunkt for import og vellykket afsendelse. Eksternt ændringstidspunkt gemmes kun, hvis API'et faktisk leverer det.

Den eksterne kobling er unik inden for en e-conomic-forbindelse/aftale. Indekset omfatter også soft-deaktiverede produkter, så nummeret ikke genbruges ved en fejl. En ændring af aftalens credentials må ikke lydløst koble eksisterende produkter til en anden aftale.

er_number undersøges før migration. Kun værdier, der kan verificeres mod den rigtige aftale, overføres. sku_internal, EAN og navne er kandidater til manuel afklaring, aldrig automatisk bevis. Bevar bagudkompatibel læsning af gamle felter under overgangen og stop divergerende dobbeltredigering.

Leverandører og kategorier

Ét Hub-produkt kan have flere leverandørtilbud. Brug en relation med produkt, leverandør, leverandør-SKU, kost, valuta, gyldighed, lagerstatus og seneste opdatering. Eksisterende enkeltleverandørfelter bevares som kompatibel visning af primær leverandør.

Microsoft- og distributøridentiteter skal kunne skelne mellem produkt, variant, licensperiode, betalingsinterval og marked. Samme varenavn er ikke tilstrækkeligt til at slå tilbud sammen.

Genbrug Hub-kategorier og udvid med hierarki efter behov. Varegrupper caches separat pr. e-conomic-forbindelse med nummer, navn, økonomiske referencer og Hub-mapping. Interne flag som »må bruges til nye varer« og »udfases« holdes adskilt fra API-felter; antag ikke, at e-conomic har et aktiv-flag på alle gruppetyper.

Integration og audit

Gem synkroniseringsjobs, dokumenteksportforsøg og audit separat fra produkter. Hvert job har mål, operation, lokal version, integrationsnøgle, forsøg, næste forsøg, låseudløb, resultat og korrelations-id. Genbrug eksisterende audit- og jobkomponenter efter en konkret gennemgang.

Varenummerlåsen håndhæves i backend og database. Særskilt administrativ omkobling kræver årsag, verificeret mål og audit; den omskriver aldrig historiske dokumentlinjer eller forsøger automatisk at omnummerere varen i e-conomic.

5. Produktimport og oprettelse

Første import

1. Kontrollér den tilsluttede aftale og hent varegrupper samt enheder.
2. Hent alle produktpages uden et filter, der skjuler spærrede varer.
3. Vis import-preview med nye, opdaterede, uændrede og konfliktfyldte poster.
4. Match på verificeret ekstern kobling. Eksisterende ukoblede Hub-varer behandles i en afklaringsliste.
5. Gem checkpoint pr. page og afsluttende rapport. Genkørsel skal give samme resultat.

Løbende sync

Standardinterval er 15 minutter, administrativt konfigurerbart. Brug ændringsmarkør, hvis API'et understøtter en egnet markør; ellers pagineret sammenligning med hashes. Fuld gensync kan startes manuelt og deler samme lås som almindelig import. Et fuldt gennemløb skal være afsluttet, før fravær af en tidligere vare behandles som mulig ekstern sletning.

Opret fra Hub

Operatøren vælger »Opret i e-conomic« på produktet eller i eksportens kontrolvindue. Navn, varegruppe, enhed og nummerforslag vises samlet. En administrativt valgt nummersekvens reserveres lokalt med unik nøgle; ved konflikt med e-conomic reserveres et nyt nummer før ny oprettelse. Brug ikke max(varenummer)+1 uden samtidighedskontrol.

API-kontrakten kræver et eksplicit produktnummer. Ved succes verificeres nummeret i svaret og koblingen gemmes. Ved timeout bliver oprettelsen »Uafklaret«; slå det reserverede nummer op og sammenlign forventede data, før der forsøges igen. Et eksisterende nummer med andre data er en konflikt, ikke en tilladelse til at overtage varen.

Kun de valgte varer oprettes; import af en hel leverandørs katalog må ikke automatisk oprette alle varer i e-conomic. Automatisk oprettelse kan senere aktiveres for godkendte kategorier med komplet mapping. Version 1 bruger kontrolleret oprettelse i samme arbejdsflow.

6. Gemning og baggrundsjob

Gem produktændring og audit i samme database-transaktion. Lokale navne- og metadataændringer får status local_only og opretter ikke et eksternt skrivejob. Outbox bruges kun til de tre tilladte oprettelser: kunder, varer og ordrekladder.

Oprettelsesjobs behandles versionssikkert; et forældet job må ikke ændre en nyere lokal kobling. Eksisterende e-conomic-objekter opdateres aldrig fra Hub.

Retry gælder midlertidige fejl med eksponentiel ventetid, jitter og respekt for Retry-After. Standard er højst fem automatiske forsøg. Valideringsfejl kræver rettelse; credentialfejl pauser forbindelsens skrivninger. Uafklarede oprettelser genafstemmes før retry. Worker-låse har udløb, så jobs kan genoptages efter nedbrud.

7. Prisberegning og historik

Prioriteten er:

1. Eksplicit, rettighedsgodkendt manuel linjepris.
2. Aftalt kundespecifik produktpris.
3. Kundens prisregel.
4. Produktregel, derefter nærmeste kategoriregel.
5. Hub-standardpris.
6. e-conomic-referencepris, hvis valuta og enhed er kompatible.
7. Blokering og krav om pris, hvis ingen gyldig pris findes.

Inden for samme niveau bruges regelprioritet og specificitet. Identiske prioriteringer med overlappende gyldighed afvises eller vises som konflikt; databaserækkefølge afgør aldrig prisen. Version 1 understøtter fast pris, procentvis rabat og tillæg på kost. Dækningsgrad og tillæg på kost er forskellige beregninger og skal navngives særskilt.

Brug Decimal/NUMERIC, dokumenteret afrunding og beløb eksklusive moms. Nulpris er en gyldig eksplicit værdi, ikke et manglende beløb. Valutakonvertering kræver kurs, kilde og dato; samme tal må aldrig blot ommærkes med en anden valuta. Negative priser, kreditnotaer og negative mængder skal have egne dokumentregler.

Gem snapshot på eksisterende dokumentlinjer: produkt-id, ekstern kobling, navn, beskrivelse, mængde, enhed, kost hvor relevant, pris, rabat, momsgrundlag/moms, valuta, total, prisregelversion, beregningsforklaring og tidspunkt. Genbrug de eksisterende linjetabeller frem for en parallel dokumentmodel.

Gemte kladder genberegnes kun ved en eksplicit handling med før/efter-visning. Bogførte dokumenter er uforanderlige. Tilbud-til-ordre-overførsel bevarer den aftalte pris. Abonnementer skelner mellem fast aftalepris og pris beregnet ved næste periode; hver faktureret periode får sit eget snapshot. En produktprisændring regulerer ikke automatisk alle eksisterende aftaler.

8. Eksport af ordrer

Version 1 understøtter kun oprettelse af ordrekladder. Hub må ikke oprette eller ændre fakturakladder, bogføre, sende eller slette dokumenter. En ordrekladde i e-conomic er en rigtig ekstern skrivning og er ikke det samme som dry-run.

Preflight kontrollerer debitor, produktkoblinger, ekstern status, varegruppe, enhed, dokumentvaluta, linjepris, rabat, momszone, betalingsbetingelser, layout og tidligere eksport. Kundens eksterne standarder bruges som udgangspunkt. Et eksplicit layoutvalg skal valideres og respekteres eller afvises tydeligt.

Eksporten sender det verificerede varenummer og linjens snapshotpris som unitNetPrice. Der skiftes aldrig lydløst til e-conomics standardpris eller en anden valuta. Produktreference og pris holdes adskilt.

Manglende produktkobling åbner »Knyt eksisterende vare«, »Opret i e-conomic« eller »Ret senere«. Manuelle prisbærende linjer kræver ligeledes en valgt gyldig økonomisk vare. Rene overskrifter/kommentarer kan undtages, hvis dokument-API'et understøtter dem. Fritekstfallback fra v2.8.6 udfases ved aktivering af dette flow.

Dubletter og uafklarede svar

Tilstande: afventer → sender → oprettet → verificeret. Fejl deles i afvist og uafklaret. Gem integrationsnøgle før afsendelse og brug lås pr. dokumentrevision. Gem returneret dokumentnummer straks og atomisk med lokal eksportstatus.

En lokal nøgle er ikke i sig selv ekstern idempotens. Ved timeout eller mistet svar søges via en stabil Hub-reference i et understøttet e-conomic-referencefelt, før nyt POST tillades. Beløb/kunde/dato er kun supplerende kontrol, ikke sikkert match alene. Nul eller flere tvetydige resultater kræver manuel afklaring. Hvis den aktuelle API-kontrakt tilbyder egentlig idempotens, anvendes den også.

Gentagne klik og samtidige workers må ikke sende samme revision to gange. Et eksternt dokument oprettet før et lokalt nedbrud skal kunne genfindes. Vareoprettelse og dokumentoprettelse har separate resultater: en korrekt oprettet vare genbruges, hvis den efterfølgende ordre fejler.

9. Brugerflader og rettigheder

Produktoversigten er en kompakt tabel med varenummer, navn, økonomisk gruppe, intern kategori, Hub-pris, referencepris, status og sync-status. Inaktive/udfasende produkter skjules normalt ved nyvalg og findes via et filter. Detaljesiden viser låst ekstern reference, navn, metadata, leverandører, priser og historik.

Settings → e-conomic samler Forbindelse, Produktsync, Varegrupper, Eksport og Fejl/log. Vis aftaleidentitet uden credentials, sidste/næste kørsel, import-preview, fuld sync, mapping og læsbare fejl med korrelations-id. »Markér som behandlet« ændrer aldrig faktisk sync-/eksportstatus.

Rettigheder skelner mellem læsning, kost/DB, produktredigering, eksterne navneændringer, produktoprettelse, prisregler, manuel pris og eksport/integrationsadministration. De håndhæves både i UI og API. Kostfelter udelades server-side for brugere uden adgang.

Read-only og dry-run kontrolleres ved hver ekstern skrivning, også i workers og produktjobs. Konfigurationen viser effektiv tilstand og eventuelle moduloverrides. Dry-run udfører ingen produktoprettelse, navneopdatering eller dokumentoprettelse. Miljø og aftale er entydigt adskilt mellem test og produktion.

10. API og driftskrav

Udvid eksisterende /api/v1/products og eksisterende dokumentruter bagudkompatibelt. Nye operationer omfatter produktkobling, ekstern oprettelse, sync-status, import-preview/kørsel, varegruppemapping, prisberegning, eksportvalidering og afklaring af uafklarede eksportforsøg. Langvarige handlinger returnerer job-id og en statusressource.

Mål antal afventende/fejlede jobs, ældste ventetid, konflikter, seneste komplette sync og uafklarede oprettelser. Log kun nødvendige feltændringer og fejl; tokens, headers og komplette følsomme payloads må ikke logges. Audit registrerer bruger/systemaktør, før/efter, årsag, objekt, tidspunkt og korrelations-id. Adgang og retention fastlægges sammen med eksisterende auditpraksis.

11. Leveringsrækkefølge

Fase 0 – datakortlægning

Kortlæg reelle tabeller, migrationshistorik, alle eksportveje, produktreferencer, prisberegning, jobs og audit. Undersøg er_number og dubletter. Kontrollér API-kontrakter og aftaleidentitet med read-only kald. Lever mappingrapport, import-preview og migrationsplan. Produktionsdata ændres ikke som led i kortlægningen.

Fase 1 – fundament og import

Additive migrationer, ekstern kobling, grupper/enheder, read-only import og produktvisning. Bevar eksisterende integerrelationer. Importér i batches og verificér antal samt konflikter. Aktivering af streng eksportkontrol afventer, at relevante eksisterende produkter er koblet eller står i en synlig afklaringsliste.

Fase 2 – varer fra Hub og korrekt ordreeksport

Kontrolleret produktoprettelse, nummerreservation, koblingslås, preflight og brug af economic_product_number på ordreeksport. Fjern SKU-antagelsen og lydløs fritekstfallback. Lever dette før den udvidede prismotor, så den aktuelle eksportfejl bliver løst tidligt.

Fase 3 – lokal navneadministration

Versionskontrol, konflikter, manuel lokal afklaring og varegruppemapping. Der aktiveres ingen ekstern navnesync.

Fase 4 – priser og ordrekladder

Fælles prisberegning, snapshots, kunderegler, abonnementspolitik og kostrettigheder. Eksportjournal og reconciliation gælder kun ordrekladder.

Fase 5 – drift og overgang

Overvågning, driftsvejledning, valideret fuld genkørsel og endelig udfasning af gamle referencefelters skriveadgang. Migrerede data beholdes ved applikationsrollback; dokumenter og eksterne varer slettes ikke automatisk som rollback.

12. Acceptkriterier og tests

• Førstesync og fuld gensync kan genkøres og genoptages uden dubletter; inaktive varer bevares.
• Afbrudt paginering deaktiverer ikke varer og præsenteres ikke som gennemført import.
• Foranstillede nuller/alfanumeriske numre bevares; samme nummer i en anden aftale blandes ikke sammen.
• En lokal navneændring bliver i Hub og opretter ingen ekstern skrivning; eksterne samtidige ændringer testes ved import.
• Nummerkollision, dobbeltklik og timeout efter vellykket produktoprettelse giver ingen ukontrolleret genoprettelse.
• Ingen almindelig produktopdatering kan ændre ekstern kobling; administrativ omkobling bevarer snapshots.
• Hub-linjepris, nulpris, valuta, rabat, afrunding og prisregelkonflikt testes med konkrete forventede beløb.
• Kundeaftaler og allerede fakturerede abonnementsperioder ændres ikke ved nye produktpriser.
• Eksport med manglende, spærret eller ugyldigt koblet produkt blokeres med en brugbar rettehandling.
• Manglende layout, betalingsbetingelser og momszone afvises inden dokumentoprettelse, hvor oplysningerne kan valideres.
• To samtidige eksportforsøg og timeout efter ekstern succes testes; uafklaret status kræver reconciliation før retry.
• Kun POST customers, POST products og POST orders/drafts kan passere den centrale allowlist; alle andre eksterne writes er blokeret. Read-only/dry-run blokerer også de tre tilladte oprettelser.
• Kostrettigheder kontrolleres ved direkte API-adgang, og logs testes for credentiallæk.
• End-to-end-test gennemføres på separat testaftale. Produktion testes med read-only preview før kontrolleret aktivering.

13. Dokumentationsgrundlag

Oprindelig brugerplan: »Plan – vareintegration mellem BMC Hub og e-conomic«, indsendt 12. september 2026. Denne plan samler den med de besluttede tilpasninger til eksisterende Hub.

Kodegrundlag: migrations/106_products.sql, eksisterende produkt-API, produkt-audit og ordreeksport. Databasens aktuelle indhold og alle senere migrationer verificeres i fase 0.

API-reference: https://restdocs.e-conomic.com/ – især produkter, varegrupper, kunder, ordrekladder og fakturakladder. Nummerkrav, længder, opdateringssemantik, paging og understøttede referencefelter skal verificeres mod de aktuelle skemaer under implementeringen.