Core Laravel Package

Getting Started

The package is the core of the Robot Council task/seat allocation system: developers are placed in seats, seats have assignment hours, and work is claimed via task_claim. v0.8.3 tightens the claim endpoint so it enforces the seat's own state and schedule.

Minimal steps:

1. composer require robot-council/core and run the package migrations (php artisan migrate). Publish config with php artisan vendor:publish --tag=robot-council-config if you need to override assignment-hour defaults.
2. Find the claim endpoint first — the task_claim route and its form request/controller are the seam you will touch most. Then look at the rule classes it references (ParkedSeat, WithinAssignmentHours, or similarly named) since those produce the 422s.
3. First useful call: submit a task_claim for a seat that is active and inside its hours. Confirm a 2xx and inspect the created claim. Then deliberately claim from a parked seat to see the 422 shape before you build UI around it.

Implementation Patterns

• Treat the 422 as a first-class outcome, not an exception. A claim can legitimately be refused for seat parked or outside assignment hours. Catch Illuminate\Validation\ValidationException (or inspect the JSON errors bag) at the controller boundary and translate the rule keys into user-facing messages rather than letting them bubble to a generic error page.
• Pre-flight before submit. When building a claim form, resolve the seat's parked state and assignment hours first and disable the claim action with an explanation. Reserve the round-trip 422 for races (seat gets parked between render and submit).
• Schedule-aware dispatch jobs. If you batch-claim or auto-assign tasks, gate the job on now() being inside the seat's assignment window in the seat's timezone, not the server's. This avoids a queue full of predictable 422s.
• Wrap claims in a domain service. Put claim orchestration (resolve seat → validate window → call package endpoint → map errors) in one class so both HTTP controllers and queued jobs share the same handling.
• Test both refusal paths explicitly. Use the package factories to create a parked seat and a seat with a narrow/expired window, then assert assertStatus(422) and assertJsonValidationErrors([...]) on the rule key. This pins the contract you depend on.

Gotchas and Tips

• The 422 names the rule — use the error-bag key (not the message string) to branch logic. Messages are localisable and may change; keys are the stable contract.
• Parked vs. out-of-hours both return 422. Don't infer the cause from the status code alone; read the rule name in the response body. If your client only checks response.ok, you will lose the distinction.
• Timezone drift is the usual culprit when a claim that "should" be in-hours is refused. Verify the seat's assignment hours are stored and compared in the same zone you expect; a UTC/Local mismatch shows up as an off-by-hours refusal.
• Refusals are not errors in your logs. Log 422s at debug/info, not error, or your alerting will drown in expected validation outcomes.
• Extension points: custom rule classes and the assignment-hours config are the intended places to adapt behaviour (e.g. grace periods). Prefer registering a rule over forking the controller; that keeps you upgrade-safe across releases like this one.
• Upgrade note for v0.8.3: if any caller previously relied on a parked/out-of-hours claim succeeding (or on a different status), audit those paths — the new 422 refusal is a behaviour change at the claim boundary, though it does not alter the response shape.