♻️ deprecate additional field in CheckinSuccessResource (#4553)

Author: MrKrisKrisu

API_CHANGELOG.md

@@ -14,6 +14,7 @@ Check back here regularly to stay ahead of removals.
 
 | Announced  | What?                                                                                                                                                                                                                             | Safe until | PR                                                            |
 |------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|---------------------------------------------------------------|
+| 2026-03-07 | `CheckinSuccessResource.points.additional` is always `null` and deprecated                                                                                                                                                        | 2026-09-30 | [#4553](https://github.com/Traewelling/traewelling/pull/4553) |
 | 2026-03-07 | `DepartureResource.destination` is deprecated → use `direction` instead                                                                                                                                                           | 2026-09-30 | [#4552](https://github.com/Traewelling/traewelling/pull/4552) |
 | 2026-03-07 | `DepartureResource.delay` is deprecated → use `when`/`plannedWhen` difference instead                                                                                                                                             | 2026-09-30 | [#4552](https://github.com/Traewelling/traewelling/pull/4552) |
 | 2026-03-07 | `DepartureResource` HAFAS-compat fields deprecated: `provenance`, `remarks`, `origin`, `currentTripPosition`, `loadFactor`, `stop.products`, `line.public`, `line.adminCode`, `line.productName`, `line.product`, `line.operator` | 2026-09-30 | [#4552](https://github.com/Traewelling/traewelling/pull/4552) |
@@ -33,6 +34,8 @@ Check back here regularly to stay ahead of removals.
 
 # 2026-03-07
 
+The `CheckinSuccessResource.points.additional` field is now **deprecated** (always `null`) and will be removed after **2026-09-30**.
+
 The following fields of `DepartureResource` are now **deprecated** and will be removed after **2026-09-30**:
 
 - `destination` → use `direction` for the destination name

app/Dto/PointCalculation.php

@@ -10,24 +10,24 @@ class PointCalculation
 {
     public readonly int $points;
 
-    public readonly int $basePoints;
+    public readonly int $base;
 
-    public readonly int $distancePoints;
+    public readonly int $distance;
 
     public readonly PointReason $reason;
 
     public readonly float $factor;
 
     public function __construct(
         int $points,
-        int $basePoints,
-        int $distancePoints,
+        int $base,
+        int $distance,
         PointReason $reason,
         float $factor,
     ) {
         $this->points = $points;
-        $this->basePoints = $basePoints;
-        $this->distancePoints = $distancePoints;
+        $this->base = $base;
+        $this->distance = $distance;
         $this->reason = $reason;
         $this->factor = $factor;
     }

app/Http/Controllers/Backend/Transport/PointsCalculationController.php

@@ -39,24 +39,24 @@ public static function calculatePoints(
         $distance = ceil($distanceInMeter / 10000);
 
         return self::calculatePointsWithReason(
-            basePoints: $base,
-            distancePoints: $distance,
+            base: $base,
+            distance: $distance,
             pointReason: self::getReason($departure, $arrival, $forceCheckin, $tripSource, $timestampOfView),
         );
     }
 
     #[Pure]
     private static function calculatePointsWithReason(
-        float $basePoints,
-        float $distancePoints,
+        float $base,
+        float $distance,
         PointReason $pointReason
     ): PointCalculation {
         $factor = self::getFactorByReason($pointReason);
 
         return new PointCalculation(
-            points: self::getPointsByReason($pointReason, ($basePoints + $distancePoints), $factor),
-            basePoints: $basePoints,
-            distancePoints: $distancePoints,
+            points: self::getPointsByReason($pointReason, ($base + $distance), $factor),
+            base: $base,
+            distance: $distance,
             reason: $pointReason,
             factor: $factor,
         );
@@ -66,8 +66,8 @@ private static function returnZeroPoints(): PointCalculation
     {
         return new PointCalculation(
             points: 0,
-            basePoints: 0,
-            distancePoints: 0,
+            base: 0,
+            distance: 0,
             reason: PointReason::POINTS_DISABLED,
             factor: 0,
         );

app/Http/Resources/CheckinSuccessResource.php

@@ -25,7 +25,7 @@
     properties: [
         new OA\Property(property: 'points', description: 'points', type: 'integer', example: 1),
         new OA\Property(property: 'calculation', ref: '#/components/schemas/PointsCalculation'),
-        new OA\Property(property: 'additional', description: 'extra points that can be given', type: 'array', items: new OA\Items(), nullable: true),
+        new OA\Property(property: 'additional', description: 'Deprecated. Always null.', type: 'array', items: new OA\Items(), nullable: true, deprecated: true),
     ],
 )]
 #[OA\Schema(
@@ -56,16 +56,15 @@ public function toArray($request): array
         /** @var CheckinSuccessDto $this */
         return [
             'status' => new StatusResource($this->status),
-            // ToDo: Rewrite ['points'] so the DTO will match the documented structure -> non-breaking api change
             'points' => [
                 'points' => $this->pointCalculation->points,
                 'calculation' => [
-                    'base' => $this->pointCalculation->basePoints,
-                    'distance' => $this->pointCalculation->distancePoints,
+                    'base' => $this->pointCalculation->base,
+                    'distance' => $this->pointCalculation->distance,
                     'factor' => $this->pointCalculation->factor,
                     'reason' => $this->pointCalculation->reason->value,
                 ],
-                'additional' => null, // unused old attribute (not removed so this isn't breaking)
+                'additional' => null, // @deprecated - remove after 2026-09-30
             ],
             'alsoOnThisConnection' => StatusResource::collection($this->alsoOnThisConnection),
         ];

app/Http/Resources/StationResource.php

@@ -52,8 +52,8 @@ public function toArray($request): array
             'name' => $this->name,
             'latitude' => $this->latitude,
             'longitude' => $this->longitude,
-            'ibnr' => null, // @deprecated - remove after 2025-09
-            'rilIdentifier' => null, // @deprecated - remove after 2025-09
+            'ibnr' => null, // @deprecated - remove after 2026-09-30
+            'rilIdentifier' => null, // @deprecated - remove after 2026-09-30
             'areas' => AreaResource::collection($this->whenLoaded('areas')),
             'identifiers' => StationIdentifierResource::collection($this->whenLoaded('stationIdentifiers')),
         ];

resources/types/Api.gen.ts

@@ -737,7 +737,10 @@ export interface Points {
    */
   points?: number;
   calculation?: PointsCalculation;
-  /** extra points that can be given */
+  /**
+   * Deprecated. Always null.
+   * @deprecated
+   */
   additional?: any[] | null;
 }
 

storage/api-docs/api-docs.json

@@ -6517,10 +6517,11 @@
                         "$ref": "#/components/schemas/PointsCalculation"
                     },
                     "additional": {
-                        "description": "extra points that can be given",
+                        "description": "Deprecated. Always null.",
                         "type": "array",
                         "items": {},
-                        "nullable": true
+                        "nullable": true,
+                        "deprecated": true
                     }
                 },
                 "type": "object"