Address PR review: rename to eda_visibility, merge migrations, API versioning

Changes based on jbtronics' review of PR #1241:

- Rename kicad_export -> eda_visibility (entities, forms, templates,
  translations, tests) with nullable bool for system default support
- Merge two database migrations into one (Version20260211000000)
- Rename createCachedJsonResponse -> createCacheableJsonResponse
- Change bool $apiV2 -> int $apiVersion with version validation
- EDA visibility field only shown for part parameters, not other entities
- PopulateKicadCommand: check alternative names of footprints/categories
- PopulateKicadCommand: support external JSON mapping file (--mapping-file)
- Ship default mappings JSON at contrib/kicad-populate/default_mappings.json
- Add system-wide defaultEdaVisibility setting in KiCadEDASettings
- Add KiCad HTTP Library v2 spec link in controller docs

src/Services/EDA/KiCadHelper.php

@@ -47,6 +47,9 @@ class KiCadHelper
     /** @var bool Whether to resolve actual datasheet PDF URLs (true) or use Part-DB page links (false) */
     private readonly bool $datasheetAsPdf;
 
+    /** @var bool The system-wide default for EDA visibility when not explicitly set on an element */
+    private readonly bool $defaultEdaVisibility;
+
     public function __construct(
         private readonly NodesListBuilder $nodesListBuilder,
         private readonly TagAwareCacheInterface $kicadCache,
@@ -59,6 +62,7 @@ class KiCadHelper
     ) {
         $this->category_depth = $kiCadEDASettings->categoryDepth;
         $this->datasheetAsPdf = $kiCadEDASettings->datasheetAsPdf ?? true;
+        $this->defaultEdaVisibility = $kiCadEDASettings->defaultEdaVisibility;
     }
 
     /**
@@ -194,10 +198,14 @@ class KiCadHelper
     }
 
     /**
-     * @param bool $apiV2 If true, use API v2 format with volatile field support
+     * @param int $apiVersion The API version to use (1 or 2). Version 2 adds volatile field support.
      */
-    public function getKiCADPart(Part $part, bool $apiV2 = false): array
+    public function getKiCADPart(Part $part, int $apiVersion = 1): array
     {
+        if ($apiVersion < 1 || $apiVersion > 2) {
+            throw new \InvalidArgumentException(sprintf('Unsupported API version %d. Supported versions: 1, 2.', $apiVersion));
+        }
+
         $result = [
             'id' => (string)$part->getId(),
             'name' => $part->getName(),
@@ -277,13 +285,14 @@ class KiCadHelper
         }
 
         // Add supplier information from orderdetails (include obsolete orderdetails)
-        // If any orderdetail has kicad_export=true, only export those; otherwise export all (backward compat)
+        // If any orderdetail has eda_visibility explicitly set to true, only export those;
+        // otherwise export all (backward compat when no flags are set)
         $allOrderdetails = $part->getOrderdetails(false);
         if ($allOrderdetails->count() > 0) {
-            $hasKicadExportFlag = false;
+            $hasExplicitEdaVisibility = false;
             foreach ($allOrderdetails as $od) {
-                if ($od->isKicadExport()) {
-                    $hasKicadExportFlag = true;
+                if ($od->isEdaVisibility() !== null) {
+                    $hasExplicitEdaVisibility = true;
                     break;
                 }
             }
@@ -291,8 +300,9 @@ class KiCadHelper
             $supplierCounts = [];
             foreach ($allOrderdetails as $orderdetail) {
                 if ($orderdetail->getSupplier() !== null && $orderdetail->getSupplierPartNr() !== '') {
-                    // Skip orderdetails not marked for export when the flag is used
-                    if ($hasKicadExportFlag && !$orderdetail->isKicadExport()) {
+                    // When explicit flags exist, filter by resolved visibility
+                    $resolvedVisibility = $orderdetail->isEdaVisibility() ?? $this->defaultEdaVisibility;
+                    if ($hasExplicitEdaVisibility && !$resolvedVisibility) {
                         continue;
                     }
 
@@ -330,14 +340,15 @@ class KiCadHelper
             }
         }
         // In API v2, stock and location are volatile (shown but not saved to schematic)
-        $result['fields']['Stock'] = $this->createField($totalStock, false, $apiV2);
+        $result['fields']['Stock'] = $this->createField($totalStock, false, $apiVersion >= 2);
         if ($locations !== []) {
-            $result['fields']['Storage Location'] = $this->createField(implode(', ', array_unique($locations)), false, $apiV2);
+            $result['fields']['Storage Location'] = $this->createField(implode(', ', array_unique($locations)), false, $apiVersion >= 2);
         }
 
-        //Add parameters marked for KiCad export
+        //Add parameters marked for EDA export (explicit true, or system default when null)
         foreach ($part->getParameters() as $parameter) {
-            if ($parameter->isKicadExport() && $parameter->getName() !== '') {
+            $paramVisibility = $parameter->isEdaVisibility() ?? $this->defaultEdaVisibility;
+            if ($paramVisibility && $parameter->getName() !== '') {
                 $fieldName = $parameter->getName();
                 //Don't overwrite hardcoded fields
                 if (!isset($result['fields'][$fieldName])) {