Tema 6 · Automation skriptai

Naujokams: scenarijaus sutartis ir tikri scripts/*.json pavyzdžiai

Po redagavimo ir TypeScript konteksto čia sutariame kaip tas pats kodas saugomas JSON eksporte (scripts/ kataloge). Bendras ERP objekto lauko tipų ir datų skaitymas — Tema 2. Laukai, forma, initial, output, log.*, tada — tikri repo failai su fragmentais. Išvedimas, šaltiniai ir rql — Tema 3, UI — Tema 4; pilna API linija — Tema 7.

1. Naujokams: JSON eksportas ir scenarijaus sutartis

Repozitorijos kataloge scripts/ saugomi automatizavimo apibrėžimų eksportai (JSON). Vykdomas JavaScript — lauke values.scriptContent; vartotojo forma (kai įjungta) — paramsFormSchema ir paramsFormEnabled; bandomasis kontekstas — exampleData. Tai leidžia laikyti tą pačią logiką versijų kontrolėje ir kartu su technine dokumentacija.

Žemiau — tas pats turinys, kurį anksčiau rasdavote tik gilintis į readme.html : sutraukta, su paaiškinimais ir kodo pavyzdžiais. Pilnos lentelės, papildomos pastabos ir „santrauka pagal failus“ toliau atnaujinamos žinyne — čia laikome vedėjo ir naujoko įėjimo sluoksnį.

1.1. Kas patenka į scenarijų kaip initial

Paleidus veiksmą iš UI, platforma suformuoja objektą initial. Dažni laukai:

  • Sąrašas: initial.ids (pažymėtų įrašų ID masyvas), initial.id (vienas įrašas), initial.filterString, initial.sortString.
  • Forma (kai paramsFormEnabled: true): laukai pagal paramsFormSchema — pvz. initial.departmentIn arba initial.fileName / initial.fileName.publicLink po FILEUPLOAD.
  • Kita: pvz. initial.acceptLanguage vertimams (žr. ss-ocr-read-email JSON žinyne).

Formos fragmentas (vienas failo laukas — kaip c-001):

[
  {
    "blockType": "FILEUPLOAD",
    "meta": { "fieldName": "fileName", "accept": ".xlsx" }
  }
]

Scenarijuje dažnai skaitote initial.fileName arba viešą nuorodą: initial.fileName?.publicLink ?? initial.fileName.

1.2. JSON laukai, kurie „sujungia“ UI ir kodą

Laukas Paskirtis
paramsFormSchema Formos blokai: blockType, meta.fieldName, required, accept, RQL getItems ir pan.
exampleData JSON eilutė su pavyzdiniu initial testui, pvz. ids + departmentIn (aa260126).
placeId Kur sistemoje rodomas veiksmas (clients-list, inventory-adjustments-list, …).
triggerTypeId / cronExpression Trigerio tipas; 0 — dažnai rankinis / kontekstinis; suplanuotiems — CRON eilutė (žr. ss-ocr-read-email žinyne).

1.3. Klaidos: verslas (UserError) ir technika (try / catch)

Verslo taisyklė (niekas nepažymėta, trūksta privalomo lauko) — throw new UserError("…"): vartotojui aiški žinutė, be stack trace „baimės“.

if (initial?.ids?.length < 1) {
  throw new UserError("Nepažymėtas nei vienas dokumentas");
}

Techninė klaida aplink mutate, rql, fetchData — tipinis šablonas:

try {
  const result = await mutate("updateClient", { /* … */ });
} catch (error) {
  await log.error("Klaida: " + (error?.message ?? error));
  throw error;
}

Cikle per dokumentus vienam nepavykus — galima kaupti failed ir tęsti (continue) — žr. aa260126 repo faile. c-001 naudoja logException(tag, exception) su message / stack / name serializacija į log.error.

Antipavyzdys iš repo: catch (execption) neatitinka exception kintamojo vardo — tikroji klaida gali būti paslėpta. Laikykitės vieno vardo (error arba exception) visame faile.

1.4. Pabaiga scenoriaus — output

Pabaigoje priskiriate output (objektas) — matoma UI ir istorijoje. Tipiniai laukai iš šio projekto pavyzdžių:

  • message — trumpas tekstas vartotojui (pvz. c-001: „Veiksmas atliktas“).
  • created / struktūrizuota santrauka — kas sukurta (aa260126).
  • failed, failedCount — dalinis nesėkmės atvejis.
  • Papildomai API: executionStatus (SUCCESS / WARNING / CANCELED), documentsCount — žr. Automatizavimo scenarijų API.

1.5. Žurnalas — log.* ir kada rašyti

Situacija Ką daryti Pavyzdys faile
Sėkmingas žingsnis await log.info(…) su santrauka aa260126 po sėkmingo mutate
Diagnostika / payload log.trace (atsargiai gamyboje) Įvesties objektai prieš sunkią operaciją
Įspėjimas, bet ne stabdymas log.warn ss-ocr-read-email
Klaida log.error su kontekstu (docRef, functionName, …) aa260126, c-001 per logException

Jei API dokumente log.* yra asinchroniniai, saugiau await log.info(…), kad įrašas spėtų užsirašyti prieš baigiant sesiją.

1.6. Nuo ko pradėti skaitant scripts/*.json

Failas Ką pamatysite
c-001 FILEUPLOAD, fetchData, Excel, lygiagretumas, logException, output.message
aa260126 initial.ids, forma departmentIn, UserError, ciklas, mutate, output su santrauka
jm16750 initial.fileName.publicLink, eilutės, output su dideliu JSON (atsargiai gamyboje)
ss-ocr-read-email CRON, parametrai, try/catch el. paštui, vertimų helperiai

Pilnas žinynas (scripts/readme.html) — visos pastabos, papildomos lentelės ir nuorodos į docs/ bei 24 verslo scenarijus.

2. Praktika: tikri automatizavimo skriptai (scripts/)

Čia naudojami eksportuoti apibrėžimai (JSON): vykdomas kodas — values.scriptContent, forma — paramsFormSchema, bandymui — exampleData. Teoriją, lenteles ir bendrus šablonus žr. skyriuje 1; pilną indeksuotą žinyną — scripts/readme.html .

Kodo fragmentas iš `c-001` (failo nuskaitymas) 
const fileDataResponse = await fetchData(undefined, {
  url: initial.fileName,
  method: "GET",
  raw: false,
});
const clientsFileData = await dataParser.excelSheetToJson(
  fileDataResponse.body,
  0,
  5
);
Kodo fragmentas iš `aa260126` (`initial` ir `UserError`) 

const ids = initial?.ids;
if (initial?.ids?.length

Teorijos santrauka

  • JSON sutartis: scriptContent, initial, UserError, output, log.* — skyrius 1; išplėtimas — scripts/readme.html .
  • Repo failai c-001 ir aa260126 — tipiniai šablonai failui iš sąrašo ir sąrašo pažymėjimams.

Praktika salėje

Atverkite vieną iš nuorodų į JSON ir IDE raskite scriptContent — trumpai paaiškinkite kolegai vieną matomą šabloną (fetchData arba UserError).

Savarankiškas darbas

  1. Pakartokite skyrių 1 su vienu repo JSON (c-001 arba aa260126); tada žinyne readme.html peržvelkite tą patį failą pagal „santrauką pagal failus“.
  2. Užfiksuokite vieną lauką iš exampleData, kuris atitinka initial bandyme.