@openinc/parse-server-opendash 4.1.1 → 4.1.2

package/dist/scripts/migration/passes/03-equipment.js

@@ -0,0 +1,176 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pass03 = void 0;
+const node_1 = __importDefault(require("parse/node"));
+const index_js_1 = require("../../../types/index.js");
+const acl_js_1 = require("../lib/acl.js");
+const map_js_1 = require("../lib/map.js");
+const latest_js_1 = require("../lib/latest.js");
+const ptr_js_1 = require("../lib/ptr.js");
+const pass_js_1 = require("../lib/pass.js");
+/**
+ * Collect the ids of every `OD3_Source` that v1 data actually points at.
+ *
+ * D3 decided: referenced sources only, not the whole source tree. A data source is
+ * an openware/sensor concept and most of them are not physical equipment; importing
+ * all of them would fill the equipment picker with noise. Ancestors are added later
+ * regardless, or the hierarchy breaks.
+ */
+async function referencedSourceIds(ctx) {
+    const { config } = ctx;
+    const ids = new Set();
+    // Tickets reference a source through the side table.
+    for (const row of await (0, pass_js_1.all)(() => (0, pass_js_1.scopeToTenant)(new node_1.default.Query(index_js_1.Maintenance_Ticket_Source), config.tenantId), config.batchSize)) {
+        const id = (0, pass_js_1.refId)(row.get("source"));
+        if (id)
+            ids.add(id);
+    }
+    // Spare parts (pass 05) map `sources` → `equipment`, so those count too.
+    for (const item of await (0, pass_js_1.all)(() => (0, pass_js_1.scopeToTenant)(new node_1.default.Query(index_js_1.Maintenance_Item), config.tenantId), config.batchSize)) {
+        for (const src of await (0, latest_js_1.relationObjects)(item, "sources", config.batchSize)) {
+            if (src.id)
+                ids.add(src.id);
+        }
+    }
+    // Schedules are deferred (MIGRATION_PLAN §4.5) but their sources are included
+    // anyway: the equipment they will need should exist before that work starts, and
+    // a schedule's source is by definition real equipment.
+    for (const schedule of await (0, pass_js_1.all)(() => (0, pass_js_1.scopeToTenant)(new node_1.default.Query(index_js_1.Maintenance_Schedule), config.tenantId), config.batchSize)) {
+        const id = (0, pass_js_1.refId)(schedule.get("source"));
+        if (id)
+            ids.add(id);
+    }
+    return ids;
+}
+/**
+ * Pass 03 — `OD3_Source` → `OD3_Service_Equipment`.
+ *
+ * The one genuine remodelling in the migration. v1 attaches tickets to a data
+ * source; v2 attaches them to Equipment, which is only loosely coupled back to
+ * sources through `Equipment.sourceTags`.
+ *
+ * `source.tag` is not unique — several sources can carry the same tag — so
+ * Equipment→Source is deliberately not a bijection. Storing the tag string rather
+ * than a source id is the documented intent (see the openservice-core equipment
+ * README).
+ */
+exports.pass03 = {
+    id: "03",
+    title: "equipment",
+    needs: [],
+    async run(ctx) {
+        const { config, map, report, entry } = ctx;
+        const referenced = await referencedSourceIds(ctx);
+        if (referenced.size === 0) {
+            report.warn(entry, "no source is referenced by any ticket, item or schedule");
+            return;
+        }
+        // Load every source once; the tree walk needs arbitrary parents anyway.
+        const allSources = await (0, pass_js_1.all)(() => (0, pass_js_1.scopeToTenant)(new node_1.default.Query(index_js_1.Source), config.tenantId), config.batchSize);
+        const byId = new Map();
+        for (const s of allSources)
+            if (s.id)
+                byId.set(s.id, s);
+        // Close the referenced set over `parent`, so no equipment is left orphaned.
+        const needed = new Set();
+        for (const id of referenced) {
+            let cursor = id;
+            const guard = new Set();
+            while (cursor && byId.has(cursor) && !guard.has(cursor)) {
+                guard.add(cursor);
+                needed.add(cursor);
+                cursor = (0, pass_js_1.refId)(byId.get(cursor).get("parent"));
+            }
+            if (cursor && guard.has(cursor)) {
+                report.error(entry, `source ${id} sits in a parent cycle`);
+            }
+        }
+        const ancestorsAdded = needed.size - referenced.size;
+        report.info(entry, `${referenced.size} referenced source(s) + ${ancestorsAdded} ancestor(s) = ` +
+            `${needed.size} equipment; ${allSources.length - needed.size} source(s) skipped (D3)`);
+        // Parents before children, so `Equipment.parent` can resolve through the map.
+        const depth = (id) => {
+            let d = 0;
+            let cursor = id;
+            const guard = new Set();
+            while (cursor && byId.has(cursor) && !guard.has(cursor)) {
+                guard.add(cursor);
+                cursor = (0, pass_js_1.refId)(byId.get(cursor).get("parent"));
+                if (cursor && needed.has(cursor))
+                    d += 1;
+                else
+                    break;
+            }
+            return d;
+        };
+        const ordered = [...needed]
+            .map((id) => byId.get(id))
+            .sort((a, b) => depth(a.id) - depth(b.id));
+        for (const source of ordered) {
+            const sourceId = source.id;
+            if (!sourceId)
+                continue;
+            const existingId = map.get(index_js_1.Source.className, sourceId);
+            const target = existingId
+                ? new index_js_1.Service_Equipment({ objectId: existingId })
+                : new index_js_1.Service_Equipment();
+            const tenantId = (0, pass_js_1.refId)(source.get("tenant"));
+            if (!tenantId) {
+                // `Equipment.tenant` is required, so this row cannot be written.
+                report.error(entry, `source ${sourceId} ("${source.get("name")}") has no tenant; ` +
+                    `Equipment.tenant is required — skipped`);
+                entry.skipped++;
+                continue;
+            }
+            const parentTargetId = (() => {
+                const parentSourceId = (0, pass_js_1.refId)(source.get("parent"));
+                return parentSourceId ? map.get(index_js_1.Source.className, parentSourceId) : undefined;
+            })();
+            target.set("label", source.get("name") ?? sourceId);
+            target.set("deleted", false);
+            target.set("tenant", (0, ptr_js_1.tenantPtr)(tenantId));
+            // Stored raw as a string array; the tag is what links equipment back to a
+            // source at read time.
+            target.set("sourceTags", source.get("tag") ? [source.get("tag")] : []);
+            const parentPtr = (0, ptr_js_1.maybePtr)(index_js_1.Service_Equipment.className, parentTargetId);
+            if (parentPtr)
+                target.set("parent", parentPtr);
+            if (!source.get("tag")) {
+                report.warn(entry, `source ${sourceId} ("${source.get("name")}") has no tag — the equipment ` +
+                    `will not match any source at read time`);
+            }
+            if (!existingId) {
+                target.setACL((0, acl_js_1.migrationAcl)({ tenantId, allowTenantUserWrite: true }));
+            }
+            if (config.dryRun) {
+                existingId ? entry.updated++ : entry.created++;
+                if (!existingId) {
+                    await map.record(index_js_1.Source.className, sourceId, index_js_1.Service_Equipment.className, map_js_1.MigrationMap.dryId(sourceId));
+                }
+                continue;
+            }
+            try {
+                const newId = await (0, acl_js_1.saveMigrated)(config, target, {
+                    className: index_js_1.Service_Equipment.className,
+                    isNew: !existingId,
+                    createdAt: source.createdAt,
+                    updatedAt: source.updatedAt,
+                });
+                if (existingId) {
+                    entry.updated++;
+                }
+                else {
+                    entry.created++;
+                    await map.record(index_js_1.Source.className, sourceId, index_js_1.Service_Equipment.className, newId);
+                }
+            }
+            catch (error) {
+                report.error(entry, `source ${sourceId} failed: ${error.message}`);
+                continue;
+            }
+        }
+    },
+};

package/dist/scripts/migration/passes/04-projects.d.ts

@@ -0,0 +1,27 @@
+import { type Pass } from "../lib/pass.js";
+/**
+ * A 3-letter `Project.shortcode`, derived from the label.
+ *
+ * v1 has no equivalent column, so this is synthesised. Uniqueness is **per
+ * tenant**, which is also how the field reads in the UI.
+ *
+ * Candidates, in order: the first three letters; then the first two plus each
+ * later letter (so "Instandhaltung" and "Instandsetzung" become INS and INT
+ * rather than INS and INS1); then a numeric suffix as a last resort. Diacritics
+ * are folded rather than dropped, or "Öltank" would become "LTA".
+ */
+export declare function shortcodeCandidates(label: string): string[];
+/**
+ * Pass 04 — `OD3_Maintenance_Project` → `OD3_Service_Project`.
+ *
+ * `ticketCounter` starts at 0, and only on a newly created project — a re-run must
+ * not reset it. The backend `beforeSave` that normally increments it is not
+ * registered in migration mode (it is what would strip the historical `createdAt`),
+ * so `TicketNumberer` in pass 08 seeds itself from these values, hands out the
+ * numbers in-process and writes the final counter back at the end of that pass.
+ *
+ * Dropped per MIGRATION_PLAN A4: the `assignedUsers` / `assignedRoles` relations
+ * (no equivalent on the v2 Project) and the `tickets` relation (replaced by the
+ * inverse `Ticket.project`). `finished` maps to `deleted` (D4).
+ */
+export declare const pass04: Pass;

package/dist/scripts/migration/passes/04-projects.js

@@ -0,0 +1,241 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pass04 = void 0;
+exports.shortcodeCandidates = shortcodeCandidates;
+const node_1 = __importDefault(require("parse/node"));
+const index_js_1 = require("../../../types/index.js");
+const acl_js_1 = require("../lib/acl.js");
+const map_js_1 = require("../lib/map.js");
+const env_js_1 = require("../lib/env.js");
+const latest_js_1 = require("../lib/latest.js");
+const ptr_js_1 = require("../lib/ptr.js");
+const pass_js_1 = require("../lib/pass.js");
+/**
+ * The inbox Status a project should default to.
+ *
+ * Pass 01 produces exactly one per tenant in the normal case; the oldest wins if a
+ * v1 tenant somehow had several inbox states.
+ */
+async function inboxStatusId(tenantId) {
+    const query = new node_1.default.Query(index_js_1.Service_Status)
+        .equalTo("category", "inbox")
+        .ascending("createdAt");
+    if (tenantId) {
+        query.equalTo("tenant", (0, ptr_js_1.tenantPtr)(tenantId));
+    }
+    const status = await query.first(env_js_1.MK);
+    return status?.id;
+}
+/**
+ * A 3-letter `Project.shortcode`, derived from the label.
+ *
+ * v1 has no equivalent column, so this is synthesised. Uniqueness is **per
+ * tenant**, which is also how the field reads in the UI.
+ *
+ * Candidates, in order: the first three letters; then the first two plus each
+ * later letter (so "Instandhaltung" and "Instandsetzung" become INS and INT
+ * rather than INS and INS1); then a numeric suffix as a last resort. Diacritics
+ * are folded rather than dropped, or "Öltank" would become "LTA".
+ */
+function shortcodeCandidates(label) {
+    const cleaned = (label ?? "")
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .replace(/ß/gi, "SS")
+        .toUpperCase()
+        .replace(/[^A-Z0-9]/g, "");
+    // A label with no usable characters at all still needs a code.
+    if (cleaned.length === 0) {
+        return Array.from({ length: 99 }, (_, i) => `P${String(i + 1).padStart(2, "0")}`);
+    }
+    const out = [];
+    const push = (code) => {
+        const c = code.slice(0, 3).padEnd(3, "X");
+        if (!out.includes(c))
+            out.push(c);
+    };
+    push(cleaned);
+    const head = cleaned.slice(0, 2).padEnd(2, "X");
+    for (let i = 3; i < cleaned.length; i++)
+        push(head + cleaned[i]);
+    for (let n = 1; n <= 9; n++)
+        push(head + n);
+    for (let n = 10; n <= 99; n++)
+        push(cleaned[0] + n);
+    return out;
+}
+/** First candidate not already taken in this tenant. */
+function pickShortcode(label, taken) {
+    for (const candidate of shortcodeCandidates(label)) {
+        if (!taken.has(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * Pass 04 — `OD3_Maintenance_Project` → `OD3_Service_Project`.
+ *
+ * `ticketCounter` starts at 0, and only on a newly created project — a re-run must
+ * not reset it. The backend `beforeSave` that normally increments it is not
+ * registered in migration mode (it is what would strip the historical `createdAt`),
+ * so `TicketNumberer` in pass 08 seeds itself from these values, hands out the
+ * numbers in-process and writes the final counter back at the end of that pass.
+ *
+ * Dropped per MIGRATION_PLAN A4: the `assignedUsers` / `assignedRoles` relations
+ * (no equivalent on the v2 Project) and the `tickets` relation (replaced by the
+ * inverse `Ticket.project`). `finished` maps to `deleted` (D4).
+ */
+exports.pass04 = {
+    id: "04",
+    title: "projects",
+    needs: ["01"],
+    async run({ config, map, report, entry }) {
+        const projects = await (0, pass_js_1.all)(() => (0, pass_js_1.scopeToTenant)(new node_1.default.Query(index_js_1.Maintenance_Project), config.tenantId), config.batchSize);
+        if (projects.length === 0)
+            return;
+        // Shortcodes already in use, per tenant. Seeded from every existing v2
+        // project — not just migrated ones — so a code cannot collide with one a
+        // user typed in by hand.
+        const takenByTenant = new Map();
+        const takenFor = (id) => {
+            const existing = takenByTenant.get(id);
+            if (existing)
+                return existing;
+            const created = new Set();
+            takenByTenant.set(id, created);
+            return created;
+        };
+        for (const existing of await (0, pass_js_1.all)(() => new node_1.default.Query(index_js_1.Service_Project), config.batchSize)) {
+            const code = existing.get("shortcode");
+            const owner = (0, pass_js_1.refId)(existing.get("tenant"));
+            if (typeof code === "string" && code && owner)
+                takenFor(owner).add(code);
+        }
+        const defaultStatusId = await inboxStatusId(config.tenantId);
+        if (!defaultStatusId) {
+            report.warn(entry, "no inbox Status found — projects will be created without a defaultStatus " +
+                "(run pass 01 first)");
+        }
+        // Parents before children so `Project.parent` resolves through the map.
+        const byId = new Map();
+        for (const p of projects)
+            if (p.id)
+                byId.set(p.id, p);
+        const depth = (project) => {
+            let d = 0;
+            let cursor = (0, pass_js_1.refId)(project.get("parent"));
+            const guard = new Set();
+            while (cursor && byId.has(cursor) && !guard.has(cursor)) {
+                guard.add(cursor);
+                d += 1;
+                cursor = (0, pass_js_1.refId)(byId.get(cursor).get("parent"));
+            }
+            return d;
+        };
+        const ordered = [...projects].sort((a, b) => depth(a) - depth(b));
+        let droppedAssignments = 0;
+        for (const project of ordered) {
+            const sourceId = project.id;
+            if (!sourceId)
+                continue;
+            const existingId = map.get(index_js_1.Maintenance_Project.className, sourceId);
+            const target = existingId
+                ? new index_js_1.Service_Project({ objectId: existingId })
+                : new index_js_1.Service_Project();
+            const tenantId = (0, pass_js_1.refId)(project.get("tenant"));
+            if (!tenantId) {
+                report.error(entry, `project ${sourceId} ("${project.get("name")}") has no tenant; ` +
+                    `Project.tenant is required — skipped`);
+                entry.skipped++;
+                continue;
+            }
+            const parentSourceId = (0, pass_js_1.refId)(project.get("parent"));
+            const parentTargetId = parentSourceId
+                ? map.get(index_js_1.Maintenance_Project.className, parentSourceId)
+                : undefined;
+            const ownerId = (0, pass_js_1.refId)(project.get("user"));
+            target.set("label", project.get("name"));
+            target.set("tenant", (0, ptr_js_1.tenantPtr)(tenantId));
+            // v1 had no soft-delete on projects; `finished` is the closest thing and D4
+            // chose to reuse `deleted` rather than add a column.
+            target.set("deleted", project.get("finished") === true);
+            if (!existingId)
+                target.set("ticketCounter", 0);
+            if (!existingId) {
+                // Only on create. On a re-run `target` is a bare stub with no loaded
+                // attributes, so setting this would overwrite whatever the project
+                // already carries — including a code a user has since edited.
+                const taken = takenFor(tenantId);
+                const shortcode = pickShortcode(project.get("name") ?? "", taken);
+                if (shortcode) {
+                    target.set("shortcode", shortcode);
+                    taken.add(shortcode);
+                }
+                else {
+                    report.warn(entry, `project ${sourceId} ("${project.get("name")}") could not be given a ` +
+                        `unique shortcode — tenant ${tenantId} has exhausted the candidates`);
+                }
+            }
+            if (project.get("description"))
+                target.set("description", project.get("description"));
+            if (project.get("color"))
+                target.set("color", project.get("color"));
+            if (project.get("icon"))
+                target.set("icon", project.get("icon"));
+            if (project.get("start"))
+                target.set("start", project.get("start"));
+            if (project.get("end"))
+                target.set("end", project.get("end"));
+            if (ownerId)
+                target.set("manager", (0, ptr_js_1.userPtr)(ownerId));
+            const parentPtr = (0, ptr_js_1.maybePtr)(index_js_1.Service_Project.className, parentTargetId);
+            if (parentPtr)
+                target.set("parent", parentPtr);
+            const statusPtr = (0, ptr_js_1.maybePtr)(index_js_1.Service_Status.className, defaultStatusId);
+            if (statusPtr)
+                target.set("defaultStatus", statusPtr);
+            // Report the relations that have nowhere to go, rather than losing them
+            // quietly — a customer using project-level assignment will notice.
+            for (const field of ["assignedUsers", "assignedRoles"]) {
+                const ids = await (0, latest_js_1.relationIds)(project, field, config.batchSize);
+                droppedAssignments += ids.length;
+            }
+            if (!existingId) {
+                target.setACL((0, acl_js_1.migrationAcl)({ tenantId, userId: ownerId, allowTenantUserWrite: true }));
+            }
+            if (config.dryRun) {
+                existingId ? entry.updated++ : entry.created++;
+                if (!existingId) {
+                    await map.record(index_js_1.Maintenance_Project.className, sourceId, index_js_1.Service_Project.className, map_js_1.MigrationMap.dryId(sourceId));
+                }
+                continue;
+            }
+            try {
+                const newId = await (0, acl_js_1.saveMigrated)(config, target, {
+                    className: index_js_1.Service_Project.className,
+                    isNew: !existingId,
+                    createdAt: project.createdAt,
+                    updatedAt: project.updatedAt,
+                });
+                if (existingId) {
+                    entry.updated++;
+                }
+                else {
+                    entry.created++;
+                    await map.record(index_js_1.Maintenance_Project.className, sourceId, index_js_1.Service_Project.className, newId);
+                }
+            }
+            catch (error) {
+                report.error(entry, `project ${sourceId} failed: ${error.message}`);
+                continue;
+            }
+        }
+        if (droppedAssignments > 0) {
+            report.info(entry, `${droppedAssignments} project-level user/role assignment(s) dropped — the v2 ` +
+                `Project has no equivalent (A4)`);
+        }
+    },
+};

package/dist/scripts/migration/passes/05-articles.d.ts

@@ -0,0 +1,25 @@
+import { type Pass } from "../lib/pass.js";
+/**
+ * Pass 05 — `OD3_Maintenance_Item` → `OD3_BDE_Article`.
+ *
+ * The parts *catalogue*. It used to target `OD3_Service_SparePart`; that class is
+ * retired and material now references the shared article catalogue instead, so
+ * the same v1 rows land in `OD3_BDE_Article` with `type: "spare_part"`.
+ *
+ * **The shapes do not line up, so the surplus goes to plugin-meta.**
+ * `BDE_Article` is a lean catalogue — `articleNumber`, `description`, `unit`,
+ * `type`, `targettime` — and it is shared with BDE and its ABAS sync, so it is
+ * not ours to widen. v1's stock-keeping fields (price, stock levels, storage
+ * location, supplier, category, order number) and its equipment links are
+ * therefore written as a `Meta_Entry` under `["service","article","meta"]`,
+ * editable through the article admin view in `openservice-core`. Nothing is
+ * dropped. See `lib/articleMeta.ts` for why that context and not the ABAS one.
+ *
+ * Two naming traps, both inherited from BDE: the label column is `description`,
+ * not `name`; and the soft-delete flag is `isDeleted`, not `deleted`.
+ *
+ * Per-ticket consumption (`OD3_Maintenance_Ticket_Material`) is a separate
+ * concern — passes 08 and 12 fold and replay it onto `Ticket.material`, which
+ * resolves its article ids through the map this pass writes.
+ */
+export declare const pass05: Pass;

package/dist/scripts/migration/passes/05-articles.js

@@ -0,0 +1,203 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pass05 = void 0;
+const node_1 = __importDefault(require("parse/node"));
+const index_js_1 = require("../../../types/index.js");
+const acl_js_1 = require("../lib/acl.js");
+const articleMeta_js_1 = require("../lib/articleMeta.js");
+const latest_js_1 = require("../lib/latest.js");
+const map_js_1 = require("../lib/map.js");
+const ptr_js_1 = require("../lib/ptr.js");
+const pass_js_1 = require("../lib/pass.js");
+/**
+ * `Article.type` for everything this pass creates.
+ *
+ * `OD3_BDE_Article` is a shared catalogue holding several kinds of thing —
+ * products, spare parts — distinguished by `type` rather than by class. Every v1
+ * `Maintenance_Item` was a maintenance part, so they all arrive as this.
+ * Mirrors `ARTICLE_TYPE.sparePart` in `@opendash/plugin-openservice-core`.
+ */
+const ARTICLE_TYPE_SPARE_PART = "spare_part";
+/**
+ * Pass 05 — `OD3_Maintenance_Item` → `OD3_BDE_Article`.
+ *
+ * The parts *catalogue*. It used to target `OD3_Service_SparePart`; that class is
+ * retired and material now references the shared article catalogue instead, so
+ * the same v1 rows land in `OD3_BDE_Article` with `type: "spare_part"`.
+ *
+ * **The shapes do not line up, so the surplus goes to plugin-meta.**
+ * `BDE_Article` is a lean catalogue — `articleNumber`, `description`, `unit`,
+ * `type`, `targettime` — and it is shared with BDE and its ABAS sync, so it is
+ * not ours to widen. v1's stock-keeping fields (price, stock levels, storage
+ * location, supplier, category, order number) and its equipment links are
+ * therefore written as a `Meta_Entry` under `["service","article","meta"]`,
+ * editable through the article admin view in `openservice-core`. Nothing is
+ * dropped. See `lib/articleMeta.ts` for why that context and not the ABAS one.
+ *
+ * Two naming traps, both inherited from BDE: the label column is `description`,
+ * not `name`; and the soft-delete flag is `isDeleted`, not `deleted`.
+ *
+ * Per-ticket consumption (`OD3_Maintenance_Ticket_Material`) is a separate
+ * concern — passes 08 and 12 fold and replay it onto `Ticket.material`, which
+ * resolves its article ids through the map this pass writes.
+ */
+exports.pass05 = {
+    id: "05",
+    title: "articles",
+    needs: ["03"],
+    async run({ config, map, report, entry }) {
+        const items = await (0, pass_js_1.all)(() => (0, pass_js_1.scopeToTenant)(new node_1.default.Query(index_js_1.Maintenance_Item), config.tenantId), config.batchSize);
+        if (items.length === 0)
+            return;
+        // Existing entries, so a re-run updates rather than duplicates. Config ids
+        // are resolved per tenant on first use.
+        const metaByArticle = await (0, articleMeta_js_1.loadArticleMetaEntries)(config);
+        const metaConfigByTenant = new Map();
+        const contextString = (0, ptr_js_1.contextToString)(articleMeta_js_1.ARTICLE_META_CONTEXT);
+        let withMeta = 0;
+        let unparseablePrices = 0;
+        for (const item of items) {
+            const sourceId = item.id;
+            if (!sourceId)
+                continue;
+            const existingId = map.get(index_js_1.Maintenance_Item.className, sourceId);
+            const target = existingId
+                ? new index_js_1.BDE_Article({ objectId: existingId })
+                : new index_js_1.BDE_Article();
+            const tenantId = (0, pass_js_1.refId)(item.get("tenant"));
+            // `description` is BDE's label column — v1's `name` goes here, not into a
+            // `name` field, which does not exist.
+            target.set("description", item.get("name"));
+            target.set("type", ARTICLE_TYPE_SPARE_PART);
+            // Soft delete is `isDeleted` here, not `deleted`.
+            target.set("isDeleted", false);
+            if (tenantId)
+                target.set("tenant", (0, ptr_js_1.tenantPtr)(tenantId));
+            if (item.get("internalNumber")) {
+                target.set("articleNumber", item.get("internalNumber"));
+            }
+            if (item.get("stockUnit"))
+                target.set("unit", item.get("stockUnit"));
+            // Everything v1 tracked that the article catalogue has no room for goes
+            // to meta rather than being dropped.
+            const metaValues = {};
+            for (const field of [
+                "storageLocation",
+                "supplier",
+                "category",
+                "orderNumber",
+                "stockUnit",
+            ]) {
+                const value = item.get(field);
+                if (typeof value === "string" && value.trim()) {
+                    metaValues[field] = value.trim();
+                }
+            }
+            for (const field of ["stock", "stockAlarmAt"]) {
+                const value = item.get(field);
+                if (typeof value === "number")
+                    metaValues[field] = value;
+            }
+            // v1 stored price as a free-form string; keep the number, report the rest
+            // rather than silently discarding it.
+            const rawPrice = item.get("price");
+            const price = (0, articleMeta_js_1.parsePrice)(rawPrice);
+            if (price !== undefined)
+                metaValues.price = price;
+            else if (rawPrice) {
+                unparseablePrices += 1;
+                report.warn(entry, `item ${sourceId} ("${item.get("name")}") price "${String(rawPrice)}" ` +
+                    `is not a number — left unset on the meta entry`);
+            }
+            // `Item.sources` (Relation<Source>) -> the migrated Equipment ids.
+            const equipmentIds = [];
+            for (const src of await (0, latest_js_1.relationObjects)(item, "sources", config.batchSize)) {
+                if (!src.id)
+                    continue;
+                const equipmentId = map.get(index_js_1.Source.className, src.id);
+                if (equipmentId)
+                    equipmentIds.push(equipmentId);
+                else {
+                    report.warn(entry, `item ${sourceId} references source ${src.id}, which has no ` +
+                        `Equipment (not referenced by a ticket? see D3)`);
+                }
+            }
+            if (equipmentIds.length)
+                metaValues.equipment = equipmentIds;
+            if (!existingId) {
+                target.setACL((0, acl_js_1.migrationAcl)({ tenantId, allowTenantUserWrite: true }));
+            }
+            if (config.dryRun) {
+                existingId ? entry.updated++ : entry.created++;
+                // Pass 08 resolves ticket material through this map. Without a
+                // placeholder every material line in a dry run would report an
+                // unresolved article, burying the genuine findings.
+                if (!existingId) {
+                    await map.record(index_js_1.Maintenance_Item.className, sourceId, index_js_1.BDE_Article.className, map_js_1.MigrationMap.dryId(sourceId));
+                }
+                continue;
+            }
+            try {
+                const newId = await (0, acl_js_1.saveMigrated)(config, target, {
+                    className: index_js_1.BDE_Article.className,
+                    isNew: !existingId,
+                    createdAt: item.createdAt,
+                    updatedAt: item.updatedAt,
+                });
+                if (existingId) {
+                    entry.updated++;
+                }
+                else {
+                    entry.created++;
+                    await map.record(index_js_1.Maintenance_Item.className, sourceId, index_js_1.BDE_Article.className, newId);
+                }
+                // Meta last: it needs the article id, and an entry with no values is
+                // not worth a row.
+                if (Object.keys(metaValues).length > 0) {
+                    if (!metaConfigByTenant.has(tenantId ?? "")) {
+                        metaConfigByTenant.set(tenantId ?? "", await (0, articleMeta_js_1.ensureArticleMetaConfig)(config, tenantId ?? ""));
+                    }
+                    const existingMeta = metaByArticle.get(newId);
+                    const metaEntry = existingMeta ?? new index_js_1.Meta_Entry();
+                    metaEntry.set("context", contextString);
+                    metaEntry.set("entryClassName", index_js_1.BDE_Article.className);
+                    metaEntry.set("entryObjectId", newId);
+                    metaEntry.set("values", metaValues);
+                    const originPtr = (0, ptr_js_1.maybePtr)("OD3_Meta_Config", metaConfigByTenant.get(tenantId ?? ""));
+                    if (originPtr)
+                        metaEntry.set("origin", originPtr);
+                    if (tenantId)
+                        metaEntry.set("tenant", (0, ptr_js_1.tenantPtr)(tenantId));
+                    if (!existingMeta) {
+                        metaEntry.setACL((0, acl_js_1.migrationAcl)({ tenantId, allowTenantUserWrite: true }));
+                    }
+                    await (0, acl_js_1.saveMigrated)(config, metaEntry, {
+                        className: index_js_1.Meta_Entry.className,
+                        isNew: !existingMeta,
+                        createdAt: item.createdAt,
+                        updatedAt: item.updatedAt,
+                    });
+                    metaByArticle.set(newId, metaEntry);
+                    withMeta += 1;
+                }
+            }
+            catch (error) {
+                report.error(entry, `item ${sourceId} failed: ${error.message}`);
+                continue;
+            }
+        }
+        if (withMeta > 0) {
+            report.info(entry, `${withMeta} article(s) carry stock-keeping data as meta under ` +
+                `["service","article","meta"] — editable in the article admin view`);
+        }
+        if (unparseablePrices > 0) {
+            report.info(entry, `${unparseablePrices} price(s) could not be parsed into a number — see ` +
+                `above and fix by hand after the run`);
+        }
+        report.info(entry, `articles written with type "${ARTICLE_TYPE_SPARE_PART}"; the article ` +
+            `catalogue is shared with BDE, so a re-run updates rather than duplicates`);
+    },
+};