feat(badge-scan): support attendee email lookup with source audit trail

smarcet · smarcet · commit 31b61e77b40e · 2026-04-06T22:13:23.000-03:00
diff --git a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitBadgeScanApiController.php b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitBadgeScanApiController.php
@@ -93,7 +93,8 @@ public function __construct
     function getAddValidationRules(array $payload): array
     {
         return [
-            'qr_code'   => 'required|string',
+            'qr_code'   => 'required_without:attendee_email|string',
+            'attendee_email'   => 'required_without:qr_code|email',
             'scan_date' => 'required|date_format:U|epoch_seconds',
             'notes' => 'sometimes|string|max:1024',
             'extra_questions' => 'sometimes|extra_question_dto_array',
diff --git a/app/ModelSerializers/Summit/Registration/SponsorBadgeScanCSVSerializer.php b/app/ModelSerializers/Summit/Registration/SponsorBadgeScanCSVSerializer.php
@@ -35,6 +35,7 @@ final class SponsorBadgeScanCSVSerializer extends AbstractSerializer
         'SponsorId' => 'sponsor_id:json_int',
         'UserId' => 'scanned_by_id:json_int',
         'BadgeId' => 'badge_id:json_int',
+        'Source' => 'source:json_string',
         'AttendeeFirstName' => 'attendee_first_name:json_string',
         'AttendeeLastName' => 'attendee_last_name:json_string',
         'AttendeeEmail' => 'attendee_email:json_string',
diff --git a/app/ModelSerializers/Summit/Registration/SponsorBadgeScanSerializer.php b/app/ModelSerializers/Summit/Registration/SponsorBadgeScanSerializer.php
@@ -28,7 +28,8 @@ final class SponsorBadgeScanSerializer extends SilverStripeSerializer
         'SponsorId'    => 'sponsor_id:json_int',
         'UserId'       => 'scanned_by_id:json_int',
         'BadgeId'      => 'badge_id:json_int',
-        'Notes'        => 'notes:json_string'
+        'Notes'        => 'notes:json_string',
+        'Source'       => 'source:json_string',
     ];
 
     protected static $allowed_relations = [
diff --git a/app/Models/Foundation/Summit/Registration/SponsorBadgeScan.php b/app/Models/Foundation/Summit/Registration/SponsorBadgeScan.php
@@ -19,6 +19,7 @@
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\Common\Collections\Criteria;
 use Illuminate\Support\Facades\Log;
+use models\exceptions\ValidationException;
 use models\main\Member;
 use models\utils\One2ManyPropertyTrait;
 use Doctrine\ORM\Mapping AS ORM;
@@ -82,6 +83,15 @@ class SponsorBadgeScan extends SponsorUserInfoGrant
     #[ORM\Column(name: 'Notes', type: 'string')]
     private $notes;
 
+
+    public const Source_QR = 'QRCode';
+    public const Source_Attendee_Email = 'AttendeeEmail';
+
+    public const ValidSources = [self::Source_QR, self::Source_Attendee_Email];
+
+    #[ORM\Column(name: 'Source', type: 'string', options: ['default' => self::Source_QR])]
+    private $source;
+
     /**
      * @var SponsorBadgeScanExtraQuestionAnswer[]
      */
@@ -91,6 +101,7 @@ class SponsorBadgeScan extends SponsorUserInfoGrant
     public function __construct()
     {
         parent::__construct();
+        $this->source = self::Source_QR;
         $this->extra_question_answers = new ArrayCollection();
     }
 
@@ -304,4 +315,13 @@ public function getScanByNice():string{
         if(!$this->hasUser()) return "TBD";
         return sprintf("%s (%s)",$this->user->getFullName(), $this->user->getEmail());
     }
-}
+
+    public function setSource(string $source): void{
+        if(!in_array($source, self::ValidSources)) throw new ValidationException("Invalid source.");
+        $this->source = $source;
+    }
+
+    public function getSource(): string{
+        return $this->source;
+    }
+}
diff --git a/app/Services/Model/Imp/SponsorUserInfoGrantService.php b/app/Services/Model/Imp/SponsorUserInfoGrantService.php
@@ -22,6 +22,7 @@
 use models\exceptions\ValidationException;
 use models\main\Member;
 use models\summit\ISponsorUserInfoGrantRepository;
+use models\summit\ISummitAttendeeRepository;
 use models\summit\SponsorBadgeScan;
 use models\summit\SponsorUserInfoGrant;
 use models\summit\Summit;
@@ -45,21 +46,29 @@ final class SponsorUserInfoGrantService
      */
     private $badge_repository;
 
+    /**
+     * @var ISummitAttendeeRepository
+     */
+    private $attendee_repository;
+
     /**
      * SponsorBadgeScanService constructor.
      * @param ISponsorUserInfoGrantRepository $repository
+     * @param ISummitAttendeeRepository $attendee_repository
      * @param ISummitAttendeeBadgeRepository $badge_repository
      * @param ITransactionService $tx_service
      */
     public function __construct
     (
         ISponsorUserInfoGrantRepository $repository,
+        ISummitAttendeeRepository $attendee_repository,
         ISummitAttendeeBadgeRepository $badge_repository,
         ITransactionService $tx_service
     )
     {
         parent::__construct($tx_service);
         $this->repository = $repository;
+        $this->attendee_repository = $attendee_repository;
         $this->badge_repository = $badge_repository;
     }
 
@@ -104,10 +113,53 @@ public function addGrant(Summit $summit, int $sponsor_id, Member $current_member
     public function addBadgeScan(Summit $summit, Member $current_member, array $data): SponsorBadgeScan
     {
         return $this->tx_service->transaction(function() use($summit, $current_member, $data){
+            $raw_qr_code = $data['qr_code'] ?? null;
+            $raw_attendee_email = $data['attendee_email'] ?? null;
+            if(empty($raw_qr_code) && empty($raw_attendee_email))
+                throw new ValidationException("Missing required parameters (qr_code or attendee_email).");
+            $ticket_number = null;
+            $qr_code = null;
+            $source = null;
+            if(!empty($raw_qr_code)) {
+                $qr_code = SummitAttendeeBadge::decodeQRCodeFor($summit, $raw_qr_code);
+                $fields = SummitAttendeeBadge::parseQRCode($qr_code);
+                $prefix = $fields['prefix'];
+                if($summit->getBadgeQRPrefix() != $prefix)
+                    throw new ValidationException
+                    (
+                        sprintf
+                        (
+                            "%s qr code is not valid for summit %s.",
+                            $qr_code,
+                            $summit->getId()
+                        )
+                    );
+                $ticket_number = $fields['ticket_number'];
+                $source = SponsorBadgeScan::Source_QR;
+            }
+            else if(!empty($raw_attendee_email)) {
+                if(!$current_member->isAdmin())
+                    throw new ValidationException("User should have admin rights.");
+
+                $attendee = $this->attendee_repository->getBySummitAndEmail($summit, trim($raw_attendee_email));
+                if(is_null($attendee)){
+                    throw new EntityNotFoundException("Attendee not found.");
+                }
+                $ticket = null;
+                foreach ($attendee->getTickets() as $t) {
+                    if ($t->isActive() && $t->hasBadge()) { $ticket = $t; break; }
+                }
+
+                if(is_null($ticket)){
+                    throw new EntityNotFoundException("Ticket not found.");
+                }
+                $ticket_number = $ticket->getNumber();
+                $badge = $ticket->getBadge();
+                // normalize qr code
+                $qr_code = SummitAttendeeBadge::decodeQRCodeFor($summit, $badge->getQRCode());
+                $source = SponsorBadgeScan::Source_Attendee_Email;
+            }
 
-            $qr_code         = SummitAttendeeBadge::decodeQRCodeFor($summit, $data['qr_code']);
-            $fields          = SummitAttendeeBadge::parseQRCode($qr_code);
-            $prefix          = $fields['prefix'];
             $scan_date_epoch = intval($data['scan_date']);
             $scan_date       = new \DateTime("@$scan_date_epoch");
             $begin_date      = $summit->getBeginDate();
@@ -117,24 +169,14 @@ public function addBadgeScan(Summit $summit, Member $current_member, array $data
             if(!($scan_date >= $begin_date && $scan_date <= $end_date))
                 throw new ValidationException("scan_date is does not belong to summit period.");
             */
-
-            if($summit->getBadgeQRPrefix() != $prefix)
-                throw new ValidationException
-                (
-                    sprintf
-                    (
-                        "%s qr code is not valid for summit %s",
-                        $qr_code,
-                        $summit->getId()
-                    )
-                );
-
-            $ticket_number = $fields['ticket_number'];
+            if(empty($ticket_number)){
+                throw new ValidationException("Ticket not found.");
+            }
 
             $badge = $this->badge_repository->getBadgeByTicketNumber($ticket_number);
 
             if(is_null($badge))
-                throw new EntityNotFoundException("badge not found");
+                throw new EntityNotFoundException("badge not found.");
 
             $sponsor = $current_member->getSponsorBySummit($summit);
 
@@ -146,6 +188,7 @@ public function addBadgeScan(Summit $summit, Member $current_member, array $data
             $scan->setQRCode($qr_code);
             $scan->setUser($current_member);
             $scan->setBadge($badge);
+            $scan->setSource($source);
             $scan->setNotes(isset($data['notes'])? trim($data['notes']): "");
 
             $sponsor->addUserInfoGrant($scan);
@@ -228,4 +271,4 @@ public function getBadgeScan(Summit $summit, Member $current_member, int $scan_i
             return $scan;
         });
     }
-}
+}
diff --git a/database/migrations/model/Version20260407003923.php b/database/migrations/model/Version20260407003923.php
@@ -0,0 +1,54 @@
+<?php namespace Database\Migrations\Model;
+
+/**
+ * Copyright 2026 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+
+use Doctrine\DBAL\Schema\Schema;
+use Doctrine\Migrations\AbstractMigration;
+use LaravelDoctrine\Migrations\Schema\Builder;
+use LaravelDoctrine\Migrations\Schema\Table;
+
+/**
+ * Class Version20260407003923
+ * @package Database\Migrations\Model
+ */
+final class Version20260407003923 extends AbstractMigration
+{
+    public function getDescription(): string
+    {
+        return "Add Source column to SponsorBadgeScan table with default 'QRCode'.";
+    }
+
+    public function up(Schema $schema): void
+    {
+        $builder = new Builder($schema);
+        if ($schema->hasTable("SponsorBadgeScan") && !$builder->hasColumn("SponsorBadgeScan", "Source")) {
+            $builder->table("SponsorBadgeScan", function (Table $table) {
+                $table->string('Source')
+                    ->setNotnull(true)
+                    ->setLength(255)
+                    ->setDefault('QRCode');
+            });
+        }
+    }
+
+    public function down(Schema $schema): void
+    {
+        $builder = new Builder($schema);
+        if ($schema->hasTable("SponsorBadgeScan") && $builder->hasColumn("SponsorBadgeScan", "Source")) {
+            $builder->table("SponsorBadgeScan", function (Table $table) {
+                $table->dropColumn('Source');
+            });
+        }
+    }
+}
diff --git a/tests/oauth2/OAuth2SummitBadgeScanApiControllerTest.php b/tests/oauth2/OAuth2SummitBadgeScanApiControllerTest.php
