refactor(cmdb): carry the import run and row in context objects (REVIEW)

lib/Service/Cmdb/CmdbImportRow.php

@@ -0,0 +1,131 @@
+<?php
+
+/**
+ * One row of a CMDB import, and what its steps found so far.
+ *
+ * @category  Service
+ * @package   OCA\Stackiq\Service\Cmdb
+ * @author    Conduction b.v. <info@conduction.nl>
+ * @copyright 2026 Conduction B.V.
+ * @license   EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @link      https://github.com/ConductionNL/stackiq
+ *
+ * @spec openspec/changes/cmdb-export-import/tasks.md#task-7
+ *
+ * SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>
+ * SPDX-License-Identifier: EUPL-1.2
+ */
+
+declare(strict_types=1);
+
+namespace OCA\Stackiq\Service\Cmdb;
+
+/**
+ * A row (or an application the reconciliation handles): where it is, its values,
+ * its warnings, the step it is at and the objects it saved.
+ *
+ * @spec openspec/changes/cmdb-export-import/tasks.md#task-7
+ */
+final class CmdbImportRow {
+
+	/**
+	 * The normalised row, whose values are also taken out of a failure's log line.
+	 *
+	 * @var array<string, string>
+	 */
+	public array $values = [];
+
+	/**
+	 * Row warnings.
+	 *
+	 * @var array<int, string>
+	 */
+	public array $warnings = [];
+
+	/**
+	 * The APPID's match key.
+	 *
+	 * @var string
+	 */
+	public string $matchKey = '';
+
+	/**
+	 * The module's import key.
+	 *
+	 * @var string
+	 */
+	public string $externalKey = '';
+
+	/**
+	 * The step the row is at.
+	 *
+	 * @var string
+	 */
+	public string $step = 'mapping';
+
+	/**
+	 * The supplier, when there is one.
+	 *
+	 * @var string|null
+	 */
+	public ?string $providerUuid = null;
+
+	/**
+	 * The owner contact persons by usage field.
+	 *
+	 * @var array<string, string|null>
+	 */
+	public array $owners = [];
+
+	/**
+	 * The module, once saved or matched.
+	 *
+	 * @var string|null
+	 */
+	public ?string $moduleUuid = null;
+
+	/**
+	 * The usage, once saved.
+	 *
+	 * @var string|null
+	 */
+	public ?string $usageUuid = null;
+
+	/**
+	 * Build the row.
+	 *
+	 * @param CmdbImportRun|null                                          $run   The run, or null for a lookup outside one.
+	 * @param array{sheet: string, row: int, appId: string, name: string} $entry Where the row is.
+	 *
+	 * @spec openspec/changes/cmdb-export-import/tasks.md#task-7
+	 */
+	public function __construct(
+		public readonly ?CmdbImportRun $run,
+		public readonly array $entry,
+	) {
+	}//end __construct()
+
+	/**
+	 * Add the row's outcome to the run's report, with its warnings and objects.
+	 *
+	 * @param string             $outcome The outcome.
+	 * @param array<int, string> $reasons Reasons.
+	 *
+	 * @return void
+	 *
+	 * @spec openspec/changes/cmdb-export-import/tasks.md#task-7
+	 */
+	public function report(string $outcome, array $reasons = []): void {
+		$this->run?->report->addRow(
+			sheet: $this->entry['sheet'],
+			row: $this->entry['row'],
+			appId: $this->entry['appId'],
+			name: $this->entry['name'],
+			outcome: $outcome,
+			reasons: $reasons,
+			warnings: $this->warnings,
+			moduleUuid: $this->moduleUuid,
+			usageUuid: $this->usageUuid
+		);
+	}//end report()
+}//end class

lib/Service/Cmdb/CmdbImportRun.php

@@ -0,0 +1,111 @@
+<?php
+
+/**
+ * What every row and the reconciliation of one CMDB import share.
+ *
+ * @category  Service
+ * @package   OCA\Stackiq\Service\Cmdb
+ * @author    Conduction b.v. <info@conduction.nl>
+ * @copyright 2026 Conduction B.V.
+ * @license   EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @link      https://github.com/ConductionNL/stackiq
+ *
+ * @spec openspec/changes/cmdb-export-import/tasks.md#task-7
+ *
+ * SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>
+ * SPDX-License-Identifier: EUPL-1.2
+ */
+
+declare(strict_types=1);
+
+namespace OCA\Stackiq\Service\Cmdb;
+
+/**
+ * One import run: its report, the municipality, the archive sheet and the options.
+ *
+ * @spec openspec/changes/cmdb-export-import/tasks.md#task-7
+ */
+final class CmdbImportRun {
+
+	/**
+	 * The consumer, as the service resolved it.
+	 *
+	 * @var array{uuid: string, name: string, created: bool}
+	 */
+	public readonly array $municipality;
+
+	/**
+	 * The archive sheet.
+	 *
+	 * @var array{sheet: string, present: bool, keyColumnMissing: bool, uncachedRows: array<int, int>, keys: array<string, true>}
+	 */
+	public readonly array $archive;
+
+	/**
+	 * The operation id.
+	 *
+	 * @var string
+	 */
+	public readonly string $operationId;
+
+	/**
+	 * The `missingRecords` mode: keep or archive.
+	 *
+	 * @var string
+	 */
+	public readonly string $missingRecords;
+
+	/**
+	 * Whether a matched module is updated.
+	 *
+	 * @var bool
+	 */
+	public readonly bool $updateExisting;
+
+	/**
+	 * The publicationDate of a created module, or null to create it unpublished.
+	 *
+	 * @var string|null
+	 */
+	public readonly ?string $publicationDate;
+
+	/**
+	 * The workbook's date system.
+	 *
+	 * @var bool
+	 */
+	public readonly bool $date1904;
+
+	/**
+	 * Build the run.
+	 *
+	 * @param CmdbImportReport     $report   The report.
+	 * @param array<string, mixed> $settings municipality, archive, operationId, missingRecords,
+	 *                                       updateExisting, publicationDate and date1904.
+	 *
+	 * @spec openspec/changes/cmdb-export-import/tasks.md#task-7
+	 */
+	public function __construct(
+		public readonly CmdbImportReport $report,
+		array $settings,
+	) {
+		$this->municipality    = $settings['municipality'];
+		$this->archive         = $settings['archive'];
+		$this->operationId     = (string) $settings['operationId'];
+		$this->missingRecords  = (string) $settings['missingRecords'];
+		$this->updateExisting  = (bool) $settings['updateExisting'];
+		$this->publicationDate = $settings['publicationDate'];
+		$this->date1904        = (bool) $settings['date1904'];
+	}//end __construct()
+
+	/**
+	 * The consumer's uuid.
+	 *
+	 * @return string
+	 *
+	 * @spec openspec/changes/cmdb-export-import/tasks.md#task-7
+	 */
+	public function municipalityUuid(): string {
+		return $this->municipality['uuid'];
+	}//end municipalityUuid()
+}//end class