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, sukūrimas, tipai, dialogas — 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).

Pažymėtos detalios eilutės — checkedLinesIds[]. Iš dokumento arba ataskaitos paleistai automatizacijai kartu su initial kontekstu perduodamas varnelėmis pažymėtų eilučių identifikatorių masyvas checkedLinesIds[]. Dokumente tai yra detalių eilučių identifikatoriai; initial.ids naudojamas sąraše pažymėtiems įrašams.

Masyve pateikiamas automatizacijos paleidimo metu aktualus pasirinkimas: viena, kelios arba visos pažymėtos eilutės. Pakeitus pažymėjimą ir pakartotinai paleidus automatizaciją, perduodamas atnaujintas pasirinkimas. Automatizacijos logikoje šiuos identifikatorius galima naudoti, pavyzdžiui, tik pasirinktų eilučių kainoms perskaičiuoti arba neatitikčių kortelėms kurti. Veiksmų taikymą pasirinktoms eilutėms turi numatyti pati automatizacijos logika.

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.