@enerlence/suntropy-cli 0.1.4 → 0.3.0

package/dist/bin/suntropy.js

@@ -2116,6 +2116,312 @@ Example: suntropy studies set data --file study.json --data '{"referenceId":"REF
       outputError(handleApiError(err));
     }
   });
+  studies.command("optimize-peakpower").description(
+    "Optimize peak power based on consumption.\n\nSupports two modes:\n  - Panel mode (default or when solarPanel is set): iterates peak power\n  - Kit mode (when solarKit is set or --use-kits): evaluates available kits\n\nOptimization criteria (pick one):\n  --energy-savings <pct>     Target energy savings percentage\n  --raw-consumption <pct>    Production as percentage of consumption\n  --max-excesses <pct>       Max excesses as percentage of production\n  --max-overproduction-months <n>  Max months with overproduction\n\nSurface constraints:\n  If surfaces have area + panel dimensions, max panels per surface is calculated.\n  Without area, no surface constraint is applied (unlimited space).\n\nExamples:\n  suntropy studies optimize-peakpower --file study.json --energy-savings 70\n  suntropy studies optimize-peakpower --file study.json --raw-consumption 100 --use-kits\n  suntropy studies optimize-peakpower --file study.json --max-excesses 15"
+  ).option("--file <path>", "Study file path").option("--energy-savings <pct>", "Target energy savings %").option("--raw-consumption <pct>", "Target production as % of consumption").option("--max-excesses <pct>", "Max excesses as % of production").option("--max-overproduction-months <n>", "Max months with overproduction").option("--use-kits", "Force kit mode (fetch all active kits and select optimal)").option("--apply", "Apply the result to the study file (set peakpower/kit, recalculate production)").action(async (opts) => {
+    try {
+      const global = getGlobalOpts6(studies);
+      const filePath = resolveFile(opts);
+      const study = readStudy(filePath);
+      const evaluationMode = {};
+      if (opts.energySavings !== void 0) evaluationMode.energyPercentageSavings = parseFloat(opts.energySavings);
+      else if (opts.rawConsumption !== void 0) evaluationMode.rawConsumptionPercentage = parseFloat(opts.rawConsumption);
+      else if (opts.maxExcesses !== void 0) evaluationMode.maxExcessesPercentage = parseFloat(opts.maxExcesses);
+      else if (opts.maxOverproductionMonths !== void 0) evaluationMode.maxNumberOfOverproductionMonths = parseInt(opts.maxOverproductionMonths);
+      else {
+        evaluationMode.rawConsumptionPercentage = 100;
+      }
+      const surfaces = study.surfaces;
+      if (!surfaces?.length) {
+        outputError(new Error("No surfaces in study. Use: studies add surface"));
+        return;
+      }
+      const consumptionData = study.consumption;
+      if (!consumptionData) {
+        outputError(new Error("No consumption in study. Use: studies set consumption"));
+        return;
+      }
+      const surfacesWithoutProduction = surfaces.filter((s) => !s.production);
+      if (surfacesWithoutProduction.length > 0) {
+        outputError(new Error(`${surfacesWithoutProduction.length} surface(s) without production. Use: studies calculate production --all-surfaces`));
+        return;
+      }
+      const { PowerCurve } = await import("energy-types/lib/energy/classes/powerCurve.class.js");
+      const cd = consumptionData;
+      const consumptionCurve = new PowerCurve(cd.days || cd, cd.ignore0 ?? false, cd.identifier || "consumption", cd.parseDate ?? false);
+      const totalConsumption = consumptionCurve.getTotalAcumulate();
+      const baseProduction = {};
+      for (const surface of surfaces) {
+        const sid = surface.surfaceId;
+        const prodData = surface.production;
+        const prodCurve = new PowerCurve(prodData.days || prodData, false, sid, false);
+        const installedPower = surface.installedPower || 5e3;
+        baseProduction[sid] = prodCurve.applyMultiplier(1 / (installedPower / 1e3));
+      }
+      const useKits = opts.useKits || study.peakPowerIntroductionMode === "solarKit";
+      const solarClient = createServiceClient("solar", global);
+      if (useKits) {
+        const phaseNumber = study.phaseNumber || "single_phase";
+        const kitsRes = await solarClient.get("/solar-kits", { params: { limit: 500 } });
+        let allKits = Array.isArray(kitsRes.data) && Array.isArray(kitsRes.data[0]) ? kitsRes.data[0] : Array.isArray(kitsRes.data) ? kitsRes.data : kitsRes.data?.data || [];
+        allKits = allKits.filter((k) => k.phaseNumber === phaseNumber && k.active !== false);
+        const isCoplanar = surfaces.every((s) => !s.panelInclination);
+        allKits = allKits.filter(
+          (k) => isCoplanar === void 0 ? true : isCoplanar === (k.coplanar === null ? true : k.coplanar)
+        );
+        allKits.sort(
+          (a, b) => a.panelNumber * (a.kitSolarPanel?.peakPower || 0) - b.panelNumber * (b.kitSolarPanel?.peakPower || 0)
+        );
+        if (allKits.length === 0) {
+          outputError(new Error("No compatible kits found for current phase/surface configuration"));
+          return;
+        }
+        let selectedKit = null;
+        let bestApproxKit = null;
+        let bestApproxValue = -Infinity;
+        let firstValidKit = null;
+        const optimizationLog = {};
+        for (const kit of allKits) {
+          const kitPanel = kit.kitSolarPanel;
+          if (!kitPanel) continue;
+          let remainingPanels = kit.panelNumber || 0;
+          const surfPanelCount = {};
+          let fits = true;
+          for (const surface of surfaces) {
+            const sid = surface.surfaceId;
+            const area = surface.area;
+            let maxPanels;
+            if (area && kitPanel.width && kitPanel.heigth) {
+              maxPanels = calculateMaxPanels(
+                area,
+                kitPanel,
+                surface.availableAreaPercentage || 85,
+                surface.panelInclination || 0,
+                surface.inclination || 0,
+                surface.panelPosition || "vertical",
+                surface.polygonPath?.[0]?.lat || 37
+              );
+            } else {
+              maxPanels = remainingPanels;
+            }
+            const assigned = Math.min(remainingPanels, maxPanels);
+            surfPanelCount[sid] = assigned;
+            remainingPanels -= assigned;
+          }
+          if (remainingPanels > 0) continue;
+          if (!firstValidKit) firstValidKit = kit;
+          let totalProd = null;
+          for (const surface of surfaces) {
+            const sid = surface.surfaceId;
+            const panelCount = surfPanelCount[sid] || 0;
+            const surfPeakPower = panelCount * kitPanel.peakPower / 1e3;
+            const surfProd = baseProduction[sid].applyMultiplier(surfPeakPower);
+            totalProd = totalProd ? totalProd.aggregatePowerCurve(surfProd) : surfProd;
+          }
+          const netConsumption = consumptionCurve.aggregatePowerCurve(totalProd.applyMultiplier(-1));
+          const kitPeakPower = (kit.panelNumber || 0) * kitPanel.peakPower / 1e3;
+          const totalProdKwh = totalProd.getTotalAcumulate();
+          let criterionValue;
+          let criterionMet = false;
+          if (evaluationMode.energyPercentageSavings !== void 0) {
+            const netFiltered = netConsumption.filterNegativeValues().getTotalAcumulate();
+            criterionValue = (totalConsumption - netFiltered) / totalConsumption * 100;
+            criterionMet = criterionValue >= evaluationMode.energyPercentageSavings;
+          } else if (evaluationMode.rawConsumptionPercentage !== void 0) {
+            criterionValue = totalProdKwh / totalConsumption * 100;
+            criterionMet = criterionValue >= evaluationMode.rawConsumptionPercentage;
+          } else if (evaluationMode.maxExcessesPercentage !== void 0) {
+            const excessesCurve = netConsumption.filterPositiveValues();
+            criterionValue = excessesCurve.getTotalAcumulate() / totalProdKwh * 100 * -1;
+            criterionMet = criterionValue <= evaluationMode.maxExcessesPercentage;
+          } else if (evaluationMode.maxNumberOfOverproductionMonths !== void 0) {
+            const stats = netConsumption.calculateStatistics().statistics.anualMonthAccumulate;
+            let byMonth = stats[Object.keys(stats).find((k) => k !== "definition") || ""] || {};
+            delete byMonth.yearly;
+            criterionValue = Object.values(byMonth).filter((v) => v < 0).length;
+            criterionMet = criterionValue <= evaluationMode.maxNumberOfOverproductionMonths;
+          } else {
+            criterionValue = 0;
+          }
+          optimizationLog[kit.idSolarKit] = {
+            identifier: kit.identifier,
+            peakPower: kitPeakPower,
+            totalProduction: totalProdKwh,
+            criterionValue,
+            criterionMet,
+            panelDistribution: surfPanelCount
+          };
+          if (criterionValue > bestApproxValue) {
+            bestApproxValue = criterionValue;
+            bestApproxKit = kit;
+          }
+          if (criterionMet) {
+            selectedKit = kit;
+            break;
+          }
+        }
+        if (!selectedKit) {
+          selectedKit = bestApproxKit || firstValidKit;
+        }
+        const resultData = {
+          mode: "kit",
+          evaluationMode,
+          selectedKit: selectedKit ? {
+            idSolarKit: selectedKit.idSolarKit,
+            identifier: selectedKit.identifier,
+            peakPower: (selectedKit.panelNumber || 0) * (selectedKit.kitSolarPanel?.peakPower || 0) / 1e3,
+            panelNumber: selectedKit.panelNumber,
+            price: selectedKit.price
+          } : null,
+          kitsEvaluated: Object.keys(optimizationLog).length,
+          optimizationLog
+        };
+        if (opts.apply && selectedKit) {
+          updateStudy(filePath, (s) => {
+            s.solarKit = selectedKit;
+            s.peakPowerIntroductionMode = "solarKit";
+            s.solarPanel = void 0;
+            s.solarInverters = void 0;
+            s.peakPowerOptimizationMethod = evaluationMode;
+            return void 0;
+          });
+          resultData.applied = true;
+        }
+        output(resultData, global);
+      } else {
+        const panel = study.solarPanel;
+        if (!panel) {
+          outputError(new Error("No solar panel set. Use: studies set panel --panel-id <id>"));
+          return;
+        }
+        const panelPeakPower = panel.peakPower || 450;
+        const panelWidth = panel.width || 1134;
+        const panelHeight = panel.heigth || panel.height || 1762;
+        const panelObj = { peakPower: panelPeakPower, width: panelWidth, heigth: panelHeight };
+        const surfacesMaxPeakPower = {};
+        let totalMaxPeakPower = 0;
+        for (const surface of surfaces) {
+          const sid = surface.surfaceId;
+          const area = surface.area;
+          if (area && panelWidth && panelHeight) {
+            const maxPanels = calculateMaxPanels(
+              area,
+              panelObj,
+              surface.availableAreaPercentage || 85,
+              surface.panelInclination || 0,
+              surface.inclination || 0,
+              surface.panelPosition || "vertical",
+              surface.polygonPath?.[0]?.lat || 37
+            );
+            surfacesMaxPeakPower[sid] = maxPanels * panelPeakPower / 1e3;
+          } else {
+            surfacesMaxPeakPower[sid] = 500;
+          }
+          totalMaxPeakPower += surfacesMaxPeakPower[sid];
+        }
+        const isAscending = evaluationMode.energyPercentageSavings !== void 0 || evaluationMode.economicPercentageSavings !== void 0 || evaluationMode.rawConsumptionPercentage !== void 0;
+        let peakPower = isAscending ? panelPeakPower / 1e3 : totalMaxPeakPower;
+        const optimizationLog = {};
+        let resultPeakPower = {};
+        let lastResult;
+        const MAX_ITERATIONS = 200;
+        const TOLERANCE = 5e-3;
+        let correctionFactor = 1;
+        let itersSinceCorrection = 0;
+        for (let iter = 0; iter < MAX_ITERATIONS && peakPower > 0 && peakPower <= totalMaxPeakPower; iter++) {
+          peakPower = parseFloat(peakPower.toFixed(2));
+          itersSinceCorrection++;
+          if (itersSinceCorrection >= 20) {
+            correctionFactor += 1.1;
+            itersSinceCorrection = 0;
+          }
+          let changeRate;
+          if (peakPower < 20) changeRate = panelPeakPower / 1e3 * correctionFactor;
+          else if (peakPower < 500) changeRate = 5 * correctionFactor;
+          else changeRate = 50 * correctionFactor;
+          let remaining = peakPower;
+          let totalProd = null;
+          resultPeakPower = {};
+          for (const surface of surfaces) {
+            const sid = surface.surfaceId;
+            const surfPP = Math.min(remaining, surfacesMaxPeakPower[sid]);
+            remaining -= surfPP;
+            resultPeakPower[sid] = surfPP;
+            const surfProd = baseProduction[sid].applyMultiplier(surfPP);
+            totalProd = totalProd ? totalProd.aggregatePowerCurve(surfProd) : surfProd;
+          }
+          const netConsumption = consumptionCurve.aggregatePowerCurve(totalProd.applyMultiplier(-1));
+          const totalProdKwh = totalProd.getTotalAcumulate();
+          let criterionValue;
+          let criterionMet = false;
+          if (evaluationMode.energyPercentageSavings !== void 0) {
+            const netFiltered = netConsumption.filterNegativeValues().getTotalAcumulate();
+            criterionValue = (totalConsumption - netFiltered) / totalConsumption * 100;
+            criterionMet = criterionValue >= evaluationMode.energyPercentageSavings;
+          } else if (evaluationMode.rawConsumptionPercentage !== void 0) {
+            criterionValue = totalProdKwh / totalConsumption * 100;
+            criterionMet = criterionValue >= evaluationMode.rawConsumptionPercentage;
+          } else if (evaluationMode.maxExcessesPercentage !== void 0) {
+            const excessesCurve = netConsumption.filterPositiveValues();
+            criterionValue = excessesCurve.getTotalAcumulate() / totalProdKwh * 100 * -1;
+            criterionMet = criterionValue <= evaluationMode.maxExcessesPercentage;
+          } else if (evaluationMode.maxNumberOfOverproductionMonths !== void 0) {
+            const stats = netConsumption.calculateStatistics().statistics.anualMonthAccumulate;
+            let byMonth = stats[Object.keys(stats).find((k) => k !== "definition") || ""] || {};
+            delete byMonth.yearly;
+            criterionValue = Object.values(byMonth).filter((v) => v < 0).length;
+            criterionMet = criterionValue <= evaluationMode.maxNumberOfOverproductionMonths;
+          } else {
+            criterionValue = 0;
+          }
+          optimizationLog[peakPower] = {
+            totalProduction: totalProdKwh,
+            criterionValue,
+            criterionMet,
+            surfacesPeakpower: { ...resultPeakPower }
+          };
+          if (criterionMet) break;
+          if (isAscending && lastResult !== void 0 && lastResult * (1 + TOLERANCE) >= criterionValue) {
+            break;
+          }
+          lastResult = criterionValue;
+          peakPower += isAscending ? changeRate : -changeRate;
+        }
+        const totalOptimizedPeakPower = Object.values(resultPeakPower).reduce((a, b) => a + b, 0);
+        const totalPanels = Math.round(totalOptimizedPeakPower / (panelPeakPower / 1e3));
+        const resultData = {
+          mode: "panel",
+          evaluationMode,
+          optimizedPeakPower: parseFloat(totalOptimizedPeakPower.toFixed(2)),
+          estimatedPanels: totalPanels,
+          surfacesPeakpower: resultPeakPower,
+          iterations: Object.keys(optimizationLog).length,
+          optimizationLog
+        };
+        if (opts.apply) {
+          updateStudy(filePath, (s) => {
+            const surfs = s.surfaces;
+            if (surfs) {
+              for (const surf of surfs) {
+                const sid = surf.surfaceId;
+                if (resultPeakPower[sid] !== void 0) {
+                  const surfPanels = Math.round(resultPeakPower[sid] / (panelPeakPower / 1e3));
+                  surf.panelNumber = surfPanels;
+                  surf.installedPower = resultPeakPower[sid] * 1e3;
+                }
+              }
+            }
+            s.peakPowerOptimizationMethod = evaluationMode;
+            return "surfaces";
+          });
+          resultData.applied = true;
+        }
+        output(resultData, global);
+      }
+    } catch (err) {
+      outputError(handleApiError(err));
+    }
+  });
   studies.command("add-comment").description(
     'Add a comment to the local study file.\nExample: suntropy studies add-comment --file study.json --content "Panel layout reviewed"'
   ).option("--file <path>", "Study file path").requiredOption("--content <text>", "Comment text").action(async (opts) => {
@@ -2209,6 +2515,24 @@ async function generateFromProfile(global, tariff, market, year, mode, data) {
   }
   throw new Error(`Unknown consumption mode: ${mode}`);
 }
+function calculateMaxPanels(areaM2, panel, availablePercentage, panelInclination, surfaceInclination, panelPosition, latitude) {
+  const { heigth, width } = panel;
+  let area = areaM2 * 1e6 * (availablePercentage / 100);
+  const x = 1 / Math.atan(61 - (latitude - surfaceInclination));
+  let totalPanelNumber;
+  if (panelPosition === "horizontal") {
+    const h = width * Math.asin(panelInclination * (Math.PI / 180));
+    const minimumDistance = x * h;
+    const panelArea = (heigth + 20) * (width + minimumDistance);
+    totalPanelNumber = area / panelArea;
+  } else {
+    const h = heigth * Math.asin(panelInclination * (Math.PI / 180));
+    const minimumDistance = x * h;
+    const panelArea = (width + 20) * (heigth + minimumDistance);
+    totalPanelNumber = area / panelArea;
+  }
+  return isNaN(totalPanelNumber) ? 0 : Math.floor(totalPanelNumber);
+}
 function collectAssets(value, previous) {
   const [idStr, qtyStr] = value.split(":");
   const id = parseInt(idStr);
@@ -2293,6 +2617,50 @@ var EXPAND_SECTIONS = {
   client: ["clientDetails", "clientsDetails"],
   location: ["location", "mapCenter", "geographicalZone", "atrTariff"]
 };
+var METADATA_ONLY_FIELDS = {
+  peakPower: "metadata",
+  sellingPrice: "metadata",
+  totalCost: "metadata",
+  anualProduction: "metadata",
+  anualConsumption: "metadata",
+  currentState: "metadata",
+  clientName: "metadata",
+  idSolarStudyMetadata: "metadata",
+  solarStudyId: "metadata"
+};
+var COMPUTED_OR_UNKNOWN_FIELDS = {
+  completionPercentage: "computed by `studies validate` / `studies save` from stepsProgress",
+  isCompleted: "not a persisted field; derive from solarStudyProgress or completionPercentage",
+  stepsProgress: "computed by `studies validate` / `studies save`"
+};
+function explainMissingStudyFields(missing, studyId) {
+  const metadataFields = missing.filter((f) => f in METADATA_ONLY_FIELDS);
+  const computedFields = missing.filter((f) => f in COMPUTED_OR_UNKNOWN_FIELDS);
+  const unknownFields = missing.filter((f) => !(f in METADATA_ONLY_FIELDS) && !(f in COMPUTED_OR_UNKNOWN_FIELDS));
+  const lines = [];
+  lines.push(`warning: ${missing.length} requested field(s) are not present on the study document returned by findById.`);
+  if (metadataFields.length > 0) {
+    lines.push("");
+    lines.push(`  These fields live on the STUDY METADATA (MySQL), not on the study document:`);
+    for (const f of metadataFields) lines.push(`    - ${f}`);
+    lines.push(`  Use:  suntropy studies metadata ${studyId} --by-study-id --fields ${metadataFields.join(",")}`);
+    lines.push(`  Or:   suntropy studies list --client-name <name>   (list already projects these fields)`);
+  }
+  if (computedFields.length > 0) {
+    lines.push("");
+    lines.push(`  These fields are not persisted on the study:`);
+    for (const f of computedFields) lines.push(`    - ${f}: ${COMPUTED_OR_UNKNOWN_FIELDS[f]}`);
+    lines.push(`  Use:  suntropy studies validate ${studyId}   (returns stepsProgress + completionPercentage)`);
+  }
+  if (unknownFields.length > 0) {
+    lines.push("");
+    lines.push(`  These fields were not found on the study document:`);
+    for (const f of unknownFields) lines.push(`    - ${f}`);
+    lines.push(`  If you expected them, try:  suntropy studies get ${studyId} --expand all --format json`);
+    lines.push(`  and inspect the full payload to locate the correct field path.`);
+  }
+  process.stderr.write(lines.join("\n") + "\n");
+}
 var CORE_FIELDS = [
   "_id",
   "id",
@@ -2377,14 +2745,22 @@ function registerStudiesCommands(program2) {
     }
   });
   studies.command("get <studyId>").description(
-    "Get solar study by MongoDB ID. By default returns summary (no heavy curves).\nExpand sections: surfaces, results, economics, batteries, consumption, equipment, client, location\nExamples:\n  suntropy studies get abc123\n  suntropy studies get abc123 --expand surfaces,results\n  suntropy studies get abc123 --expand all"
+    "Get solar study by MongoDB ID. By default returns summary (no heavy curves).\nExpand sections: surfaces, results, economics, batteries, consumption, equipment, client, location\nExamples:\n  suntropy studies get abc123\n  suntropy studies get abc123 --expand surfaces,results\n  suntropy studies get abc123 --expand all\n  suntropy studies get abc123 --fields name,market  (bypasses expand filter)"
   ).option("--expand <sections>", 'Comma-separated sections to expand (or "all")').action(async (studyId, opts) => {
     try {
       const global = getGlobalOpts7(studies);
       const client = createServiceClient("solar", global);
       const res = await client.get(`/solar-study/findById/${studyId}`);
       const study = res.data;
-      const filtered = filterStudy(study, opts.expand);
+      const filtered = global.fields ? study : filterStudy(study, opts.expand);
+      if (global.fields) {
+        const requested = global.fields.split(",").map((f) => f.trim());
+        const topLevel = requested.map((f) => f.split(".")[0]);
+        const missing = topLevel.filter((f) => !(f in study));
+        if (missing.length > 0) {
+          explainMissingStudyFields(missing, studyId);
+        }
+      }
       output(filtered, global);
     } catch (err) {
       outputError(handleApiError(err));