DEV Community

Cover image for Byg en materialekontrol til tømrerprojekter med JavaScript
Tømrerfirmaet Cronberg ApS
Tømrerfirmaet Cronberg ApS

Posted on

Byg en materialekontrol til tømrerprojekter med JavaScript

En materialeliste kan se enkel ud.

Et produktnavn, et antal og måske en måleenhed.

Men når flere materialer indgår i et tømrerprojekt, bliver det hurtigt vigtigt, at oplysningerne er ensartede.

Hvad betyder tallet 12?

Er det 12 brædder, 12 meter eller 12 kvadratmeter?

Og hvad gør man, hvis to linjer har samme ID, eller hvis producentens produktkode mangler?

Den slags problemer er interessante for udviklere, fordi de handler om datakvalitet.

Vi bygger derfor et lille Node.js-værktøj, som gennemgår en materialeliste og finder fejl, før oplysningerne bliver brugt i et andet system.

Vi kommer til at arbejde med:

  • JavaScript-objekter og arrays.
  • Validering af strukturerede data.
  • Måleenheder og obligatoriske felter.
  • Dubletkontrol.
  • Fejlrapporter i JSON.
  • Automatiske tests.

Projektet er et programmeringseksempel. Det beregner ikke konstruktioners bæreevne, materialeforbrug eller indkøbsbehov.

1. Problemet: Materialelister indeholder ofte forskellige typer data

Forestil dig et projekt med træbeklædning og forskellige komponenter.

Vi har måske følgende oplysninger:

Produkt Antal Enhed
Træbrædder 18 stk
Liste 12 m
Plademateriale 8 m²

Tallene kan ikke sammenlignes direkte.

18 styk er ikke det samme som 18 meter.

Derfor skal vores datamodel beskrive både værdien og måleenheden.

Vi vil også kunne identificere hver linje og registrere en produktkode.

Produktkoden kan være nyttig, når man senere skal finde dokumentation om et bestemt produkt.

Men vores program kommer ikke til at kontrollere, om produktkoden faktisk findes hos en producent.

Det kan kun kontrollere, om oplysningerne er indtastet i det format, vi forventer.

2. Definer vores datamodel

Vi bruger JSON-lignende JavaScript-objekter.

Et materiale kan beskrives sådan:

const material = {
  lineId: "MAT-001",
  name: "Træbrædder",
  quantity: 18,
  unit: "stk",
  productCode: "DEMO-T01"
};
Enter fullscreen mode Exit fullscreen mode

Felterne betyder:

  • lineId: Unik identifikator for materialelinjen.
  • name: Et beskrivende produktnavn.
  • quantity: Den registrerede mængde.
  • unit: Måleenheden.
  • productCode: En reference til det valgte produkt.

Vi tillader følgende måleenheder i eksemplet:

const allowedUnits = ["stk", "m", "m2"];
Enter fullscreen mode Exit fullscreen mode

Vi bruger m2 i datasættet i stedet for m², så værdien er enkel at behandle som en maskinlæsbar kode.

Den betyder stadig kvadratmeter.

I en rigtig applikation kunne vi naturligvis understøtte flere enheder.

3. Hvilke fejl skal vi kunne finde?

Vi definerer seks typer problemer.

Manglende ID

Hver materialelinje skal have et ID.

Dublet-ID

To forskellige linjer må ikke have samme ID.

Manglende navn

En materialelinje uden produktnavn er vanskelig at forstå.

Ugyldig mængde

Mængden skal være et positivt, endeligt tal.

Ukendt måleenhed

Enheden skal findes på vores tilladte liste.

Manglende produktkode

Vi kræver en produktkode for at gøre materialeregistret mere ensartet.

Det er regler, vi har valgt til demonstrationsprogrammet.

De er ikke officielle krav til alle danske tømrerprojekter.

4. Opret en materialekontrol i Node.js

Opret en fil med navnet material-audit.js.

Indsæt følgende komplette kode:

"use strict";

const fs = require("node:fs");

const allowedUnits = new Set([
  "stk",
  "m",
  "m2"
]);

const exampleMaterials = [
  {
    lineId: "MAT-001",
    name: "Træbrædder",
    quantity: 18,
    unit: "stk",
    productCode: "DEMO-T01"
  },
  {
    lineId: "MAT-002",
    name: "Træliste",
    quantity: 12,
    unit: "m",
    productCode: "DEMO-L02"
  },
  {
    lineId: "MAT-003",
    name: "Plademateriale",
    quantity: 8,
    unit: "m2",
    productCode: ""
  },
  {
    lineId: "MAT-002",
    name: "Ekstra liste",
    quantity: -3,
    unit: "meter",
    productCode: "DEMO-L03"
  }
];

function hasText(value) {
  return (
    typeof value === "string" &&
    value.trim().length > 0
  );
}

function addIssue(issues, index, code, message) {
  issues.push({
    line: index + 1,
    code,
    message
  });
}

function validateMaterials(materials) {
  if (!Array.isArray(materials)) {
    throw new TypeError(
      "Materialelisten skal være et array."
    );
  }

  const issues = [];
  const seenIds = new Set();

  materials.forEach((material, index) => {
    if (
      material === null ||
      typeof material !== "object" ||
      Array.isArray(material)
    ) {
      addIssue(
        issues,
        index,
        "INVALID_RECORD",
        "Linjen skal være et objekt."
      );

      return;
    }

    if (!hasText(material.lineId)) {
      addIssue(
        issues,
        index,
        "MISSING_ID",
        "Materialelinjen mangler et ID."
      );
    } else {
      const id = material.lineId.trim();

      if (seenIds.has(id)) {
        addIssue(
          issues,
          index,
          "DUPLICATE_ID",
          `ID ${id} findes flere gange.`
        );
      } else {
        seenIds.add(id);
      }
    }

    if (!hasText(material.name)) {
      addIssue(
        issues,
        index,
        "MISSING_NAME",
        "Materialelinjen mangler et navn."
      );
    }

    if (
      typeof material.quantity !== "number" ||
      !Number.isFinite(material.quantity) ||
      material.quantity <= 0
    ) {
      addIssue(
        issues,
        index,
        "INVALID_QUANTITY",
        "Mængden skal være et positivt tal."
      );
    }

    if (!allowedUnits.has(material.unit)) {
      addIssue(
        issues,
        index,
        "INVALID_UNIT",
        `Ukendt måleenhed: ${String(material.unit)}`
      );
    }

    if (!hasText(material.productCode)) {
      addIssue(
        issues,
        index,
        "MISSING_PRODUCT_CODE",
        "Produktkoden mangler."
      );
    }
  });

  return {
    totalLines: materials.length,
    issueCount: issues.length,
    valid: issues.length === 0,
    issues
  };
}

function auditFile(inputPath, outputPath) {
  const source = fs.readFileSync(
    inputPath,
    "utf8"
  );

  const materials = JSON.parse(source);
  const report = validateMaterials(materials);

  fs.writeFileSync(
    outputPath,
    JSON.stringify(report, null, 2),
    "utf8"
  );

  return report;
}

if (require.main === module) {
  const inputPath = process.argv[2];
  const outputPath =
    process.argv[3] || "material-report.json";

  try {
    let report;

    if (inputPath) {
      report = auditFile(inputPath, outputPath);
    } else {
      report = validateMaterials(
        exampleMaterials
      );

      fs.writeFileSync(
        outputPath,
        JSON.stringify(report, null, 2),
        "utf8"
      );
    }

    console.log(
      `Kontrollerede linjer: ${report.totalLines}`
    );

    console.log(
      `Fundne fejl: ${report.issueCount}`
    );

    console.log(
      `Rapport gemt: ${outputPath}`
    );

    if (!report.valid) {
      process.exitCode = 1;
    }
  } catch (error) {
    console.error(
      `Kontrollen mislykkedes: ${error.message}`
    );

    process.exitCode = 1;
  }
}

module.exports = {
  validateMaterials,
  auditFile
};
Enter fullscreen mode Exit fullscreen mode

Vi bruger kun funktioner, som findes i Node.js.

Der kræves ingen eksterne pakker.

5. Kør den første kontrol

Åbn en terminal i mappen med filen.

Kør:

node material-audit.js
Enter fullscreen mode Exit fullscreen mode

Programmet gennemgår vores eksempeldata.

Det forventede output er:

Kontrollerede linjer: 4
Fundne fejl: 4
Rapport gemt: material-report.json
Enter fullscreen mode Exit fullscreen mode

Vi har bevidst lavet fire fejl.

Den tredje linje mangler en produktkode.

Den fjerde linje har tre problemer:

  • Et ID, som allerede findes.
  • En negativ mængde.
  • En ukendt måleenhed.

Det giver fire fejl i alt.

Programmet opretter en JSON-rapport og returnerer exitkode 1, fordi valideringen fandt fejl.

Det er nyttigt, hvis vi senere vil køre kontrollen automatisk som en del af en større arbejdsproces.

6. Sådan ser fejlrapporten ud

Åbn filen material-report.json.

Den indeholder følgende resultat:

{
  "totalLines": 4,
  "issueCount": 4,
  "valid": false,
  "issues": [
    {
      "line": 3,
      "code": "MISSING_PRODUCT_CODE",
      "message": "Produktkoden mangler."
    },
    {
      "line": 4,
      "code": "DUPLICATE_ID",
      "message": "ID MAT-002 findes flere gange."
    },
    {
      "line": 4,
      "code": "INVALID_QUANTITY",
      "message": "Mængden skal være et positivt tal."
    },
    {
      "line": 4,
      "code": "INVALID_UNIT",
      "message": "Ukendt måleenhed: meter"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Hvorfor er en struktureret rapport bedre end én lang fejlmeddelelse?

Fordi andre programmer kan bruge oplysningerne.

En brugergrænseflade kunne eksempelvis vise fejlene ud for de relevante materialelinjer.

Et importsystem kunne afvise data, indtil fejlene er rettet.

Og et testværktøj kunne kontrollere, om bestemte fejlkoder bliver oprettet.

Det er fordelen ved at bruge maskinlæsbare fejl frem for kun almindelig tekst.

7. Læs materialer fra din egen JSON-fil

Vi behøver ikke holde data inde i JavaScript-filen.

Opret en ny fil med navnet materials.json:

[
  {
    "lineId": "MAT-101",
    "name": "Træbrædder",
    "quantity": 24,
    "unit": "stk",
    "productCode": "DEMO-T24"
  },
  {
    "lineId": "MAT-102",
    "name": "Monteringsliste",
    "quantity": 16,
    "unit": "m",
    "productCode": "DEMO-L16"
  },
  {
    "lineId": "MAT-103",
    "name": "Plademateriale",
    "quantity": 6,
    "unit": "m2",
    "productCode": "DEMO-P06"
  }
]
Enter fullscreen mode Exit fullscreen mode

Kør derefter:

node material-audit.js materials.json
Enter fullscreen mode Exit fullscreen mode

Denne gang bør programmet vise:

Kontrollerede linjer: 3
Fundne fejl: 0
Rapport gemt: material-report.json
Enter fullscreen mode Exit fullscreen mode

Filen indeholder nu:

{
  "totalLines": 3,
  "issueCount": 0,
  "valid": true,
  "issues": []
}
Enter fullscreen mode Exit fullscreen mode

Vi har dermed lavet en enkel proces, hvor data kan indlæses, kontrolleres og rapporteres uden at blive ændret.

Bemærk dog, at programmets godkendelse kun betyder, at materialerne opfylder vores valideringsregler.

Det betyder ikke, at de er egnede til et bestemt byggeprojekt.

8. Hvorfor bruger vi Set til dubletkontrol?

Vi gemmer de ID'er, vi allerede har set, i et Set:

const seenIds = new Set();
Enter fullscreen mode Exit fullscreen mode

Derefter undersøger vi hvert nyt ID:

if (seenIds.has(id)) {
  // ID'et findes allerede.
} else {
  seenIds.add(id);
}
Enter fullscreen mode Exit fullscreen mode

Det er en enkel måde at registrere dubletter på.

Vi bruger ikke produktkoden som unik identifikator.

Det skyldes, at samme produkt godt kan optræde på flere forskellige materialelinjer.

For eksempel kan det samme bræt være registreret i to forskellige dele af et projekt.

En gentaget produktkode er derfor ikke nødvendigvis en fejl.

Men hver materialelinje bør have sit eget ID i vores datamodel.

Den forskel er vigtig.

En materialelinje og et produkt er ikke det samme.

9. Hvorfor kontrollerer vi måleenheder?

Forestil dig disse to registreringer:

const first = {
  quantity: 12,
  unit: "m"
};

const second = {
  quantity: 12,
  unit: "stk"
};
Enter fullscreen mode Exit fullscreen mode

Begge indeholder tallet 12.

Men de beskriver forskellige mængder.

Hvis man fjerner måleenheden, mister man vigtig information.

Det kan skabe problemer ved eksport, indkøb eller videre behandling af data.

Derfor bør enheder være en del af datamodellen.

Vi tillader heller ikke automatisk alle mulige stavemåder.

Eksempelvis bruger vores system m, ikke meter.

Et mere avanceret program kunne tilbyde en kontrolleret konvertering mellem kendte betegnelser.

Men sådan en konvertering bør være tydelig og forudsigelig.

Vi må aldrig ændre enhedens betydning uden at gøre det klart.

10. Tilføj automatiske tests

En valideringsfunktion bør testes.

Vi kan bruge Node.js' indbyggede testværktøjer.

Opret filen material-audit.test.js:

"use strict";

const test = require("node:test");
const assert = require("node:assert/strict");

const {
  validateMaterials
} = require("./material-audit");

test("accepterer en gyldig materialelinje", () => {
  const report = validateMaterials([
    {
      lineId: "MAT-001",
      name: "Træliste",
      quantity: 5,
      unit: "m",
      productCode: "DEMO-L01"
    }
  ]);

  assert.equal(report.valid, true);
  assert.equal(report.issueCount, 0);
});

test("finder en manglende produktkode", () => {
  const report = validateMaterials([
    {
      lineId: "MAT-002",
      name: "Træbræt",
      quantity: 8,
      unit: "stk",
      productCode: ""
    }
  ]);

  assert.equal(report.valid, false);

  assert.ok(
    report.issues.some(
      issue =>
        issue.code === "MISSING_PRODUCT_CODE"
    )
  );
});

test("finder dublerede linje-ID'er", () => {
  const report = validateMaterials([
    {
      lineId: "MAT-003",
      name: "Liste A",
      quantity: 4,
      unit: "m",
      productCode: "DEMO-A"
    },
    {
      lineId: "MAT-003",
      name: "Liste B",
      quantity: 6,
      unit: "m",
      productCode: "DEMO-B"
    }
  ]);

  assert.ok(
    report.issues.some(
      issue => issue.code === "DUPLICATE_ID"
    )
  );
});

test("afviser ugyldige mængder", () => {
  const report = validateMaterials([
    {
      lineId: "MAT-004",
      name: "Plademateriale",
      quantity: -2,
      unit: "m2",
      productCode: "DEMO-P"
    }
  ]);

  assert.ok(
    report.issues.some(
      issue => issue.code === "INVALID_QUANTITY"
    )
  );
});
Enter fullscreen mode Exit fullscreen mode

Kør testene med:

node --test material-audit.test.js
Enter fullscreen mode Exit fullscreen mode

Testene kontrollerer fire situationer:

  1. En gyldig materialelinje.
  2. En manglende produktkode.
  3. To linjer med samme ID.
  4. En negativ mængde.

Hvis alle tests består, har vi et godt udgangspunkt for at videreudvikle programmet.

Det er dog ikke det samme som at bevise, at alle mulige fejl er håndteret.

Flere tests kan være relevante, hvis programmet skal anvendes i større systemer.

11. Datavalidering er ikke teknisk godkendelse

Her er en vigtig begrænsning.

Vores program kan kontrollere, at der står et positivt tal i feltet quantity.

Men det ved ikke, om mængden er tilstrækkelig til projektet.

Det kan kontrollere, at produktkoden ikke er tom.

Men det ved ikke, om koden henviser til det rigtige produkt.

Det kan acceptere en måleenhed.

Men det kan ikke afgøre, om materialet opfylder relevante konstruktionskrav.

Derfor skal vi skelne mellem tre typer kontrol:

Formatkontrol

Har oplysningerne den forventede struktur?

Datakontrol

Er felterne udfyldt, og er værdierne gyldige efter systemets regler?

Faglig vurdering

Er de valgte produkter, mængder og løsninger egnede til den konkrete byggeopgave?

Vores program løser de to første opgaver.

Den tredje kræver relevant produktdokumentation, projektinformation og faglig vurdering.

12. Hvorfor er det relevant for tømrerarbejde?

I et tømrerprojekt kan der indgå forskellige materialer, beslag og produkter.

Når oplysningerne bliver registreret ensartet, kan de være lettere at finde og kontrollere.

Det kan også være nyttigt, hvis oplysningerne senere skal bruges til at finde produktvejledninger eller dokumentation.

Men digitale værktøjer bør understøtte den praktiske vurdering, ikke erstatte den.

Tømrerfirmaet Cronberg ApS har base i Odense og arbejder blandt andet med gulve, døre, terrasser, køkkenrenovering og andet tømrerarbejde.

Ved professionelt tømrerarbejde i Odense kan korrekt produktinformation og tydelig dokumentation være relevant for planlægningen af et projekt.

Vores JavaScript-værktøj er et generelt udviklingseksempel og ikke et system, som vi hævder, at virksomheden anvender.

Det viser blot, hvordan strukturerede data kan bidrage til en mere overskuelig arbejdsproces.

13. Mulige forbedringer

Hvis projektet skulle udvikles til en større applikation, kunne vi tilføje flere funktioner.

Import fra CSV

Materialer kunne importeres fra regneark.

Det ville kræve korrekt håndtering af feltafgrænsning, tekstkodning og forskellige dataformater.

Producentoplysninger

Datamodellen kunne udvides med producentnavn og henvisning til produktdokumentation.

Projektområder

Materialelinjer kunne knyttes til bestemte rum eller dele af en bygning.

Versionshistorik

Programmet kunne registrere, hvornår en materialelinje blev ændret.

Advarsler og fejl

Nogle problemer kunne markeres som advarsler, mens andre skulle forhindre videre behandling.

Brugergrænseflade

En browserbaseret applikation kunne vise fejl direkte ved de felter, der skal rettes.

JSON Schema

Datamodellen kunne beskrives i et formelt JSON Schema, så andre systemer kan validere strukturen.

Disse funktioner ville gøre programmet mere fleksibelt.

Men grundprincippet ville være det samme:

Data bør være tydelige, kontrollerbare og forståelige.

14. Hvad har vi lært?

Vi har bygget et lille Node.js-værktøj, som kan:

  • Læse en liste med materialer.
  • Kontrollere obligatoriske felter.
  • Registrere ugyldige måleenheder.
  • Finde dublerede linje-ID'er.
  • Kontrollere numeriske mængder.
  • Oprette en JSON-fejlrapport.
  • Returnere en exitkode, der viser om kontrollen lykkedes.
  • Afprøves med automatiske tests.

Det mest interessante ved projektet er ikke mængden af kode.

Det er forskellen mellem at have oplysninger og at kunne stole på deres struktur.

En materialeliste med mange linjer er ikke automatisk en god materialeliste.

Hvis enhederne mangler, ID'erne gentages, eller produktreferencerne er uklare, kan oplysningerne være vanskelige at bruge.

Og selv når vores program godkender dataene, skal de stadig vurderes i forhold til den virkelige opgave.

Det er en nyttig påmindelse for udviklere:

Software kan hjælpe os med at finde fejl i oplysninger. Men vi skal stadig forstå, hvad oplysningerne skal bruges til.

Top comments (0)