# Batteriemodelle, Versionen und Einheiten

> Wie BatteryPass Produkt, technische Stände und einzelne Batterien trennt und wo welcher Wert gespeichert ist.

BatteryPass hält Produktdaten auf drei Ebenen. Was alle Batterien eines Produkts gemeinsam haben, pflegen Sie
einmal an der Modellversion; was sich von Batterie zu Batterie unterscheidet, gehört zur Einheit. Jede Einheit
bekommt einen eigenen Pass, der bei der Veröffentlichung aus beiden Ebenen zusammengesetzt wird.

```mermaid
flowchart LR
  M["Batteriemodell: Name, SKU, GTIN, Kategorie"] --> VA["Modellversion A: abgelöst"]
  M --> VB["Modellversion B: freigegeben"]
  VA --> U1["Einheit SN-000184"]
  VB --> U2["Einheit SN-000417"]
  U2 --> P["Pass von SN-000417"]
```

## Die drei Ebenen

| Ebene                           | Was sie ist                                                    | Wichtige Felder                                                                                               | Lesen mit                                                                                                                                                                                                                                                                   |
| ------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Batteriemodell (`BatteryModel`) | Das Handelsprodukt                                             | `name`, `sku`, `gtin`, `category`, `archived_at`                                                              | [`listBatteryModels`](https://passport.kabin.sh/docs/de/api-reference/catalog/list-battery-models), [`getBatteryModel`](https://passport.kabin.sh/docs/de/api-reference/catalog/get-battery-model)                                                                      |
| Modellversion (`ModelVersion`)  | Ein technischer Stand des Modells, etwa nach einem Zellwechsel | `version_label`, `effective_from`, `status`, `unit_count`, `approved_at`, `registry_version`                  | [`listModelVersions`](https://passport.kabin.sh/docs/de/api-reference/catalog/list-model-versions), [`getModelVersion`](https://passport.kabin.sh/docs/de/api-reference/catalog/get-model-version)                                                                      |
| Einheit (`Battery`)             | Eine physische Batterie mit Seriennummer                       | `serial_number`, `model_version_id`, `manufacturing_date`, `facility_id`, `battery_status`, `passport_status` | [`listBatteries`](https://passport.kabin.sh/docs/de/api-reference/catalog/list-batteries), [`getBattery`](https://passport.kabin.sh/docs/de/api-reference/catalog/get-battery), [`exportUnits`](https://passport.kabin.sh/docs/de/api-reference/catalog/export-units) |

Die `category` eines Modells (`ev`, `lmt`, `industrial`, `stationary`, `industrial_without_bms`) bestimmt,
welche Felder das Register für seine Batterien verlangt.

## Status einer Modellversion

Eine Modellversion hat ein Startdatum, `effective_from`, und einen Status:

| `status`     | Bedeutung                                                                                                                                      |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `draft`      | In Vorbereitung. Einheiten einer Entwurfsversion lassen sich nicht veröffentlichen.                                                            |
| `approved`   | Der aktuelle technische Stand. Ein Modell hat höchstens eine freigegebene Version; die Freigabe erteilt ein Prüfer im Portal.                  |
| `superseded` | Von einer späteren freigegebenen Version abgelöst. Sie bleibt lesbar und behält ihre Einheiten; deren veröffentlichte Pässe ändern sich nicht. |

Ein Enddatum gibt es nicht: Eine Version gilt ab ihrem `effective_from`, bis eine spätere Version übernimmt.
Wird eine Einheit im Portal oder per Tabellenimport ohne Angabe einer Version angelegt, ordnet BatteryPass ihr
die Version zu, die an ihrem Herstellungsdatum galt: die mit dem spätesten `effective_from` an oder vor diesem
Datum, wobei freigegebene und abgelöste Versionen Vorrang vor Entwürfen haben. Die Freigabe einer neuen Version
verschiebt keine bestehende Einheit. Mitglieder verschieben Einheiten
im Portal nach einer Vorschau der Auswirkungen auf eine andere Version; der veröffentlichte Pass einer
verschobenen Einheit wird dann `update_needed` ([Pässe](https://passport.kabin.sh/docs/de/concepts/passports)).

## Welche Werte wo liegen

Das [Feldregister](https://passport.kabin.sh/docs/de/general/glossary) ordnet jedes Feld einer Ebene zu. Sie lesen es mit
[`getRegistrySchema`](https://passport.kabin.sh/docs/de/api-reference/registry/get-registry-schema): Jedes Feld hat `level` mit dem Wert
`model` oder `unit`.

| Ebene         | Typische Felder                                                                                                                                                                                                                                                      | Werte                                                                                                          | Vollständigkeit                                                                                                          |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Modellversion | Hersteller, Masse, Garantie, Chemie und Zusammensetzung, gefährliche Stoffe, CO₂-Fußabdruck, Sorgfaltspflichten, Kreislauffähigkeit, Leistungskennwerte, Kennzeichnung und Konformitätserklärung, z. B. `performance.nominal_voltage`, `materials.battery_chemistry` | [`listModelVersionValues`](https://passport.kabin.sh/docs/de/api-reference/values/list-model-version-values) | [`getModelVersionCompleteness`](https://passport.kabin.sh/docs/de/api-reference/values/get-model-version-completeness) |
| Einheit       | Seriennummer, Herstellungsdatum und -ort, Batteriestatus, Datum der Inbetriebnahme und die Zustandsdaten, z. B. `identification.serial_number`, `condition.capacity_fade`                                                                                            | [`listBatteryValues`](https://passport.kabin.sh/docs/de/api-reference/values/list-battery-values)            | [`getBatteryCompleteness`](https://passport.kabin.sh/docs/de/api-reference/values/get-battery-completeness)            |

Einige Registerfelder sind keine eigenen Werte, sondern Eigenschaften des Modells oder der Einheit selbst:
Produktname, SKU, GTIN und Kategorie des Modells; Seriennummer, Herstellungsdatum, Produktionsstätte,
Batteriestatus und Datum der Inbetriebnahme der Einheit. Sie lesen sie an `BatteryModel` und `Battery`.

> [!NOTE]
> Die Vollständigkeit einer Einheit enthält auch die Zusammenfassung ihrer Modellversion (`model_version`). Ein
> Aufruf zeigt also, ob eine der beiden Ebenen die Veröffentlichung noch blockiert.

## Kennungen

| Kennung                        | Wo                        | Regeln                                                                                                                                          |
| ------------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| GTIN                           | Am Batteriemodell         | Mit 8, 12, 13 oder 14 Stellen angenommen, als GTIN-14 mit gültiger Prüfziffer gespeichert                                                       |
| Seriennummer                   | An der Einheit            | Buchstaben, Ziffern, `-`, `/` und `.`, höchstens 50 Zeichen, eindeutig je Modell                                                                |
| GTIN und Seriennummer zusammen | Der Schlüssel der Einheit | Eindeutig über alle Organisationen; der [GS1 Digital Link](https://passport.kabin.sh/docs/de/concepts/digital-link) enthält genau dieses Paar |

Sobald die Kennungen gesperrt sind (für den Etikettendruck vor der Veröffentlichung oder bei der ersten
Veröffentlichung), ist `identifiers_locked_at` gesetzt; Seriennummer und GTIN des Modells lassen sich dann nicht
mehr ändern.

Second Life: Eine umgewidmete, wiederverwendete oder wiederaufbereitete Batterie ist eine neue Einheit. Sie
nennt das Original in `predecessor_battery_id` (das Original führt sie in `successor_battery_ids`) und bekommt
einen eigenen Pass.

## Den Katalog lesen

Lesen Sie die Versionen eines Modells und dann die Einheiten einer Version:

```bash title="cURL"
curl -s "$BATTERYPASS_URL/api/v1/battery-models/$MODEL_ID/versions" \
  -H "Authorization: Bearer $BATTERYPASS_API_KEY"

curl -s "$BATTERYPASS_URL/api/v1/batteries?model_version_id=$VERSION_ID&limit=200" \
  -H "Authorization: Bearer $BATTERYPASS_API_KEY"
```

`listModelVersions` liefert höchstens 200 Versionen, das späteste `effective_from` zuerst, ohne Cursor.
`listBatteries` ist nach Seriennummer sortiert und wird mit `limit` und `cursor` geblättert
([Paginierung](https://passport.kabin.sh/docs/de/pagination)); außerdem filtert es nach `battery_model_id`, `passport_status`,
`serial_prefix` und `import_id`.

> [!NOTE]
> Die API liest den Katalog, sie legt ihn nicht an und ändert ihn nicht. Modelle, Versionen und Einheiten legen
> Mitglieder im Portal oder per Tabellenimport an; Modellversionen geben Prüfer frei.