FEAT: VAA Event Stand Planning by MrAdder · Pull Request #1810 · VATSIM-UK/uk-controller-api

MrAdder · 2026-02-15T13:00:06Z

🛠️ Summary of Changes in FEAT: VAA Event Stand Planning (#1810)

This PR introduces a complete stand reservation plan submission and approval workflow with backend logic, API endpoints, and admin UI support.

✨ New Features

Stand Reservation Plan Workflow
- Added StandReservationPlan model to store JSON payloads, approval metadata, and reservation counts.
- Includes new scopes (pending, pendingWithinApprovalWindow) and a new migration for the stand_reservation_plans table.
New VAA Role
- Added new enum RoleKeys::VAA.
- Migration creates the vaa role if not present.
- Only users with this role can submit stand reservation plans.
JSON Support for Importing Stand Reservations
- stand-reservations:import console command now supports .json files and root-level arrays.
- Extraction supports default or explicit date fields.
Refactored Import Logic
- StandReservationsImport now:
  - Supports indexed JSON rows.
  - Extracts and validates fields including cid, origin, destination.
  - Outputs optional progress and returns the count of created reservations.
  - Skips invalid rows with warnings.

📡 API Endpoints Added

POST /stand/reservations/plan: Submit a new plan (VAA role required).
GET /stand/reservations/plan/pending: List pending plans.
PATCH /stand/reservations/plan/{id}/approve: Approve a pending plan within its approval window, import reservations, and update approval metadata.

🧑‍💼 Admin UI (Filament)

Added StandReservationPlanSubmission page for authorised roles (VAA, Web Team, Ops Team, Division Staff):
- Validates JSON format
- Allows plan submission
- Shows success notifications

🧪 Tests Updated

Console command test updated to rename assertion and ensure success return code.
Added missing Collection import for tests.

Overall, this PR implements a robust stand reservation planning feature with role-based submissions, import support for JSON, administrative UI, and approval workflows.

kristiankunc · 2026-02-19T23:35:52Z

I very much dislike this UI, can we use the filament builtins?

We probably gotta document the accepted format a bit more somewhere
After I approve a stand plan - it seems to disappear, we probably need some better flow

Instead of multiple pages, I suggest creating a single one for uploading, reviewing and history tracking. Take a look at the recently added SMR WIP area management - those are decent and you just gotta add the approval flow.

MrAdder · 2026-02-20T12:03:47Z

Just a couple of updates, uses the filament builtins, approved stand are now included,

Started some documentation aswell (zoomed out screenshot due to not having my snapshot tool for entire page)

Removed useless pages Made into single page format with filament builtins (Ref Screenshot in PR) started some documentation shows Review history

kristiankunc · 2026-02-20T14:29:15Z

Looks much better - maybe we could publish a JSON schema? Probably would make it clear and we could have the users validate their data beforehand / know the exact spect we're looking for.

MrAdder · 2026-02-20T17:02:10Z

Requested the issue creator to look at the Images and the doc's that I have modified to check it ticks the boxes for what was proposed, from a backend side is to make sure it actually reserves the stand for the user and if we need to make modifications to the plugin itself.

kristiankunc · 2026-02-21T00:35:37Z

Plugin changes should not be required, stand assignments are handled on the server + given some of the stand reservation logic is already present we can assume that it works.

MrAdder · 2026-02-25T17:31:37Z

Plugin changes should not be required, stand assignments are handled on the server + given some of the stand reservation logic is already present we can assume that it works.

Good to here no response from Issue poster so at your discretion if your happy with the changes feel free with the merge

cpawley · 2026-02-25T19:01:29Z

I dont think I have strong opinions about how it might work

main concerns are

is it documented well - looks like it is
can we add a 3rd party the (temporary) authority to do this - looks like it isnt

if we give VAA's stand assignment authority we have to be able to protect ourselves from them abusing this

thanks for moving this forward :)

MrAdder · 2026-02-25T19:40:39Z

I dont think I have strong opinions about how it might work

main concerns are

is it documented well - looks like it is can we add a 3rd party the (temporary) authority to do this - looks like it isnt

if we give VAA's stand assignment authority we have to be able to protect ourselves from them abusing this

thanks for moving this forward :)

@cpawley VAA role has only Upload permissions, authority of Approval is done by the other roles from Web/Admin team of UKCP potentially may add another role for Events team to approve but that is a different discussion

I can look at adding Temporary role placement for the VAA role as well as the static role for verified VAA's (eg: BAV)

cpawley · 2026-02-25T20:00:38Z

then perfect, concept wise im happy :) this adds a huge amount of flexibility to our system and offers VAA's the chance to be actively involved in events where they take the driving seat :)

thanks!

MrAdder · 2026-02-25T21:34:46Z

I just realised a small flaw in my code in regards to the slot planning, It is currently set PER slot for one callsign for the entire event period but in regards to as an Example Speedbird24 its multiple different callsigns at a "Slot" so need to tweak the JSON formatting to accommodate this and the System on the backend.

So currently this is how it works

BAW1234 is expected between 9:00 and 9:30 so Stand 531 is reserved for them
BAW4321 is expected between 9:31 and 10:00 on Stand 531 and the stand according to the system is still reserved for BAW1234

The system currently reserves the slot for the entire Period of the Event for BAW1234

Proposed change to how it will work

BAW1234 is expected between 9:00 and 9:30 on Stand 531 and the stand is reserved for them
BAW4321 is expected between 9:31 and 10:00 on Stand 531 and the stand is reserved for them

System Picks up the change from within the plan that's uploaded by the VAA and so VATUK can limit (if they wish) the amount of Stands an Event can use, and can also assist planning teams of the VAA

cpawley · 2026-02-25T22:04:24Z

since some events can be 8->24 hrs this would need to be adopted - they need to assign stands for multiple time periods in the day

MrAdder · 2026-02-25T22:10:31Z

since some events can be 8->24 hrs this would need to be adopted - they need to assign stands for multiple time periods in the day

Downside of thinking about code while watching movies with the family

More of a logical approach to this further information in PR

MrAdder · 2026-02-26T07:46:49Z

🧾 Summary of changes (Activation + slot-based stand reservation plans)

🆕 New scheduled command: activate plans + sync assignments

Adds stand-reservations:activate-plans (ActivateStandReservationPlans):
- 🔁 Runs every minute (added to App\Console\Kernel)
- ✅ Finds approved StandReservationPlans where imported_reservations is null
- ⏱️ Only imports a plan once its event window has started (event_start or legacy start)
- 📥 Imports reservations via StandReservationsImport::importReservations() using a shared payload → rows mapper
- 🧠 Synchronises live stand assignments for active reservations:
  - Matches network aircraft by callsign (or CID) + optional origin/destination
  - Creates/updates a stand assignment with reason “Reservation”
  - Tracks “managed” assignments in cache (stand_reservations:managed_assignments)
  - Automatically lifts previously managed assignments once their reservation is no longer active

🧰 Import tooling: JSON now supports `stand_slots`

Updates stand-reservations:import command JSON parsing to support:
- ✅ Legacy flat rows (reservations array or raw array of rows)
- ✅ Slot-based payloads:
  - stand_slots[] containers with slot_reservations[]
  - Allows inheriting airfield/stand from the parent slot when omitted
Default datetime resolution updated:
- Uses event_start/event_finish first, then falls back to start/end

🌐 API: reservation slots take precedence over auto allocation

Updates StandController::requestAutomaticStandAssignment():
- 🥇 If an active reservation exists for the aircraft (callsign/CID + optional route match),
  it forces the reserved stand assignment before distance-based auto allocation.
- Adds helper activeReservedStandIdForAircraft() to locate the best matching active reservation.
Updates reservation plan upload/approval handling to accept slot-based payloads:
- reservations and stand_slots are now nullable
- Adds event_start/event_finish support
- Uses a shared rowsFromPayload() method to flatten both formats for import

📚 Docs + Schema updates

Updates Stand Allocation guide to document:
- ✅ Slot-based plan format (stand_slots + slot_reservations)
- ✅ Event-day activation task behaviour
Updates schema markdown and JSON schema files to:
- Require at least one of reservations or stand_slots
- Add event_start/event_finish
- Define standSlot + slotReservation structures
- Remove active_from/active_to from the request schema in this version

🧪 Tests added/updated

✅ New ActivateStandReservationPlansTest covers:
- Importing approved plans once event_start is due
- Skipping plans with future event_start
- Creating reservation-managed assignments and lifting expired ones via cache tracking
✅ Updates StandReservationsImportTest to validate slot-based JSON import flattening
✅ Updates API + Filament tests to use slot-based plan examples
✅ Adds controller test to confirm active reservations override automatic assignment

🔁 Backwards compatibility notes

Flat reservations format remains supported ✅
Top-level defaults still support start/end ✅
Slot format (stand_slots) is the preferred structure going forward ✅

kristiankunc · 2026-02-26T21:49:12Z

This is way too big for me to review atm. Coby might take a look

CLC0609 · 2026-02-26T22:28:49Z

Just to confirm, are we matching aircraft to stands via CID or Callsign?

MrAdder · 2026-02-27T06:23:50Z

both, but for arrival stand allocation the system tries CID-reserved first, then (after user-requested) callsign+flightplan reserved.

The allocator order in StandServiceProvider puts CidReservedArrivalStandAllocator before CallsignFlightplanReservedArrivalStandAllocator.
CID matching is explicitly done on cid (plus destination).
Callsign reservation matching is done on callsign plus origin/destination flightplan fields.
The docs also describe rule order as CID Reserved, then Callsign Reserved.

For plan-activation matching specifically, it checks by callsign, and if CID is present it also allows matching by CID (callsign OR cid).

If required I can switch it to whichever you would prefer, from an event space we can not reserve callsigns, hence the reason for CID matching.

CLC0609

Quite a big review so apologies if I have missed something that makes one of my comments irrelevant.

In terms of CID vs Callsign matching.

I think we should use CID matching only instead of callsigns. I do not see a reason that they would need to provide both or have both allocators as, if we do it by CID irrelevant of the callsign the user is using they would get assigned the correct stand. Could you update the docs to reflect using CID only as well please.

CLC0609 · 2026-02-26T22:14:26Z

app/Console/Kernel.php

        $schedule->command('plugin-events:clean')->everyTenMinutes()->doNotMonitor();
        $schedule->command('metars:update')->everyMinute();
        $schedule->command('database:check-table-updates')->everyMinute();
+        $schedule->command('stand-reservations:activate-plans')->everyMinute()->doNotMonitor();


Does this need to run every minute, I feel its unlikely that an event would start its stand allocation at 13:03 for example and not just 13:00? Maybe 10 or 15 minutes instead just to make this slightly less resource intensive?

CLC0609 · 2026-02-26T22:15:09Z

app/Services/Stand/StandReservationPayloadRowsBuilder.php

Do we need both this file and app/Support/StandReservationPayloadRows.php, they seem to do very similar things?

CLC0609 · 2026-02-26T22:22:10Z

app/Console/Commands/ActivateStandReservationPlans.php

+    private function matchingAircraftForReservation(StandReservation $reservation): ?NetworkAircraft
+    {
+        $query = NetworkAircraft::query()->notTimedOut()->where(function ($query) use ($reservation) {
+            $query->where('callsign', $reservation->callsign);


Shouldn't this match with the CID not the callsign? Otherwise the stand could be assigned to a random aircraft who took the callsign first.

CLC0609 · 2026-02-27T09:39:45Z

docs/schemas/stand-reservation-plan-format.md

+  - `stand_slots`: array of one or more stand-slot objects.
+- Optional top-level default datetimes:
+  - `event_start` / `event_finish` (preferred event-window names)
+  - `start` / `end` (legacy)


If this is legacy does it need to be included in the documentation?

CLC0609 · 2026-02-27T09:43:27Z

docs/schemas/stand-reservation-plan-format.md

+- Exactly one of:
+  - `airfield`: ICAO code, or
+  - `airport`: ICAO code alias (optional when inherited from `stand_slots[].airfield` / `airport`).


Could we standardise to using airport instead of airfield throughout the documentation and the code. So instead of allowing airport and airfield just have airport inline with the rest of the API.

This will remove the need for lines like this $slotAirfield = $standSlot['airfield'] ?? $standSlot['airport'] ?? null;

CLC0609 · 2026-02-27T10:15:26Z

docs/guides/StandAllocation.md

+
+### Event-day activation task
+
+Approved plans can be activated automatically on event day with:


Does this need to be in the public facing documentation?

docs/schemas/stand-reservation-plan-format.md

docs/README.md

CLC0609 · 2026-02-27T10:27:50Z

app/Console/Commands/ActivateStandReservationPlans.php

Could we split this into two jobs. One to activate the reservation plans, and one to do the stand reservation logic. It seems we deviated from the name ActivateStandReservationPlans.

The activate plan job can run less often than the job handling the stand reservation.

MrAdder · 2026-02-27T10:42:42Z

Totally fine it is a massive feature will look at your review later and start replying/making changes

Co-authored-by: Coby Chapman <cobylc.121@gmail.com>

sonarqubecloud · 2026-02-27T13:17:32Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.8% Duplication on New Code

See analysis details on SonarQube Cloud

MrAdder · 2026-02-27T13:17:42Z

Will do the rest later on

MrAdder added 5 commits February 15, 2026 12:41

Event Stand Reservations

26d81eb

Forgotten Commits

230b116

Style issyue

84507f1

Fixes Sonar

2f74fe8

Update StandControllerTest.php

9dea646

kristiankunc self-requested a review February 15, 2026 16:51

Merge branch 'VATSIM-UK:main' into issue-1763

bef55a5

Updates

ecb2aa5

Removed useless pages Made into single page format with filament builtins (Ref Screenshot in PR) started some documentation shows Review history

MrAdder added 3 commits February 20, 2026 16:29

JSON Schema and Tests

53396d8

Update StandReservationPlanSchemaValidator.php

4d87dfc

Fix CI issues and SonarQube

1976660

MrAdder added 7 commits February 26, 2026 06:42

Update

aa17e6c

More of a logical approach to this further information in PR

Fix for Sonar

5428242

Fix for some of Sonar

8b8c198

Update StandController.php

dc450b8

Remove some of Duplication

82112ff

Hopefully this fixes the Sonar issues

c4835b4

Linting and duplication fix

194a491

kristiankunc requested a review from CLC0609 February 26, 2026 21:49

CLC0609 requested changes Feb 27, 2026

View reviewed changes

MrAdder and others added 5 commits February 27, 2026 13:13

Update docs/README.md

55d9e08

Co-authored-by: Coby Chapman <cobylc.121@gmail.com>

Update docs/guides/StandAllocation.md

48af009

Co-authored-by: Coby Chapman <cobylc.121@gmail.com>

Update docs/schemas/stand-reservation-plan-format.md

5c8a926

Co-authored-by: Coby Chapman <cobylc.121@gmail.com>

Update docs/schemas/stand-reservation-plan-format.md

18ad792

Co-authored-by: Coby Chapman <cobylc.121@gmail.com>

Update docs/guides/StandAllocation.md

70c799f

Co-authored-by: Coby Chapman <cobylc.121@gmail.com>


		### Event-day activation task

		Approved plans can be activated automatically on event day with:

Conversation

MrAdder commented Feb 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛠️ Summary of Changes in FEAT: VAA Event Stand Planning (#1810)

✨ New Features

📡 API Endpoints Added

🧑‍💼 Admin UI (Filament)

🧪 Tests Updated

Uh oh!

kristiankunc commented Feb 19, 2026

Uh oh!

MrAdder commented Feb 20, 2026

Uh oh!

kristiankunc commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MrAdder commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kristiankunc commented Feb 21, 2026

Uh oh!

MrAdder commented Feb 25, 2026

Uh oh!

cpawley commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MrAdder commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cpawley commented Feb 25, 2026

Uh oh!

MrAdder commented Feb 25, 2026

Uh oh!

cpawley commented Feb 25, 2026

Uh oh!

MrAdder commented Feb 25, 2026

Uh oh!

MrAdder commented Feb 26, 2026

🧾 Summary of changes (Activation + slot-based stand reservation plans)

🆕 New scheduled command: activate plans + sync assignments

🧰 Import tooling: JSON now supports stand_slots

🌐 API: reservation slots take precedence over auto allocation

📚 Docs + Schema updates

🧪 Tests added/updated

🔁 Backwards compatibility notes

Uh oh!

kristiankunc commented Feb 26, 2026

Uh oh!

CLC0609 commented Feb 26, 2026

Uh oh!

MrAdder commented Feb 27, 2026

Uh oh!

CLC0609 left a comment

Choose a reason for hiding this comment

Uh oh!

CLC0609 Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

CLC0609 Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

CLC0609 Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

CLC0609 Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

CLC0609 Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

CLC0609 Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CLC0609 Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

MrAdder commented Feb 27, 2026

MrAdder commented Feb 15, 2026 •

edited

Loading

kristiankunc commented Feb 20, 2026 •

edited

Loading

MrAdder commented Feb 20, 2026 •

edited

Loading

cpawley commented Feb 25, 2026 •

edited

Loading

MrAdder commented Feb 25, 2026 •

edited

Loading

🧰 Import tooling: JSON now supports `stand_slots`