v0.11 U3: Klärungsreservierung für unvollständige Anfragen

- bookings.hold_purpose (offer wie bisher / clarification).
- RequestHold: vollständige Anfrage → Angebots-Hold unverändert;
  unvollständig, aber Wohnung, Zeitraum, verwendbare E-Mail und freier
  Zeitraum → nur Klärungsreservierung (15 min automatisch / 180 min
  Freigabe oder manuell, 0 = keine); sonst nichts (B1). Auch für
  Portalanfragen ohne Gastdaten.
- ExpireReservations beendet nur Angebots-Holds; ein abgelaufener
  Klärungsblock gibt nur den Kalender frei, der Vorgang bleibt offen.
- Vervollständigen erzeugt keinen Hold; erst SendOffer setzt den
  unveränderten Angebots-Hold. AutoOffer prüft danach nur die Verfügbarkeit.
- Booking::clarificationState() liefert den tatsächlichen Sperrstatus.
- Architekturtest: nur die bestehenden Reservierungsschritte schreiben Holds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
LarsandClaude Opus 5.5 committed 2026-11-03 13:13:24 +01:00
1 parent ccac78a6c9
commit 37f48defcc
9 files changed
+264 -5

No files matched your search

+3 -1
View File
@@ -54,7 +54,9 @@ public function blockers(Booking $booking): array
if ($information && ($booking->status !== BookingStatus::Reserved || $booking->information_version > 0)) {
$reasons[] = 'Die Anfrage ist bereits beantwortet oder nicht mehr offen.';
}
if (! $information && ($booking->status !== BookingStatus::Reserved || ! $booking->isHoldActive())) {
// A request after its clarification hold (v0.11) only needs free dates, which are checked below.
$clarified = $booking->hold_purpose === Booking::HOLD_CLARIFICATION;
if (! $information && ($booking->status !== BookingStatus::Reserved || (! $clarified && ! $booking->isHoldActive()))) {
$reasons[] = 'Die Anfrage ist nicht mehr vorgemerkt (Frist abgelaufen oder bereits bearbeitet).';
}
if (blank($booking->guest?->email)) {
+5 -1
View File
@@ -17,6 +17,7 @@
use App\Pricing\QuoteException;
use App\Pricing\StayRequest;
use App\Process\ProcessSettings;
use App\Process\RequestHold;
use App\Support\Settings;
use App\Tenancy\TenantContext;
use App\Tenancy\TenantContextMissing;
@@ -81,8 +82,12 @@ private function create(Property $property, StayRequest $stay, array $guestData,
$profile = $originChannel === null && $source === 'website'
? app(ProcessSettings::class)->forWebsite($property)
: app(ProcessSettings::class)->resolve($property, $originChannel, IntakeKind::Inquiry);
$draft = new Booking(['property_id' => $property->id, 'arrival' => $stay->arrival->toDateString(), 'departure' => $stay->departure->toDateString(), 'guests' => $stay->guests]);
$draft->setRelation('guest', $guest);
$hold = RequestHold::for($draft, $profile);
return $property->bookings()->create([
...$hold,
'guest_id' => $guest->id,
'status' => BookingStatus::Reserved,
'source' => $source,
@@ -98,7 +103,6 @@ private function create(Property $property, StayRequest $stay, array $guestData,
'total' => $quote->total(),
'deposit' => $quote->deposit(),
'balance_due_on' => $quote->balanceDueOn->toDateString(),
'hold_expires_at' => $profile->preReservation() ? now()->addHours($profile->holdHours()) : null,
'message' => $message,
'internal_notes' => $differences !== [] ? "Abweichende Angaben in dieser Anfrage (Gästekartei nicht geändert):\n".implode("\n", $differences) : null,
]);
+2 -1
View File
@@ -20,7 +20,8 @@ public function handle(): int
$expired = Booking::query()
->whereIn('status', BookingStatus::holding())
->where(fn ($query) => $query
->where('hold_expires_at', '<=', now())
// A lapsed clarification hold (v0.11) only frees the calendar; the request stays open for its details.
->where(fn ($offer) => $offer->where('hold_expires_at', '<=', now())->where('hold_purpose', Booking::HOLD_OFFER))
// An information without a hold (package 7) ends when its link expires and the guest did not ask for the booking.
->orWhere(fn ($information) => $information->where('status', BookingStatus::Reserved)->whereNull('hold_expires_at')
->where('information_valid_until', '<=', now())->whereNull('wish_at')))
+1
View File
@@ -117,6 +117,7 @@ public function handle(Booking $booking, array $changes = [], bool $sendMail = t
'deposit' => $quote->deposit(),
'balance_due_on' => $quote->balanceDueOn->toDateString(),
'hold_expires_at' => filled($changes['valid_until'] ?? null) ? CarbonImmutable::parse($changes['valid_until']) : now()->addHours($booking->process()->holdHours()),
'hold_purpose' => Booking::HOLD_OFFER,
'offer_version' => $booking->offer_version + 1,
'offer_sent_at' => now(),
'offer_message' => $changes['offer_message'] ?? null,
+6 -1
View File
@@ -11,6 +11,7 @@
use App\Models\Channel;
use App\Process\CaseAutomation;
use App\Process\ProcessSettings;
use App\Process\RequestHold;
use Carbon\CarbonImmutable;
use Illuminate\Support\Facades\DB;
@@ -41,8 +42,13 @@ public function handle(Channel $channel, CarbonImmutable $arrival, CarbonImmutab
}
$profile = $this->settings->resolve($property, $channel, IntakeKind::Inquiry);
// v0.11 (B1): a portal request without the guest's details holds nothing until the details are there; the
// offer hold comes with the offer.
$draft = new Booking(['property_id' => $property->id, 'arrival' => $arrival->toDateString(), 'departure' => $departure->toDateString()]);
$draft->setRelation('guest', null);
return $property->bookings()->create([
...RequestHold::for($draft, $profile),
'status' => BookingStatus::Reserved,
'source' => 'portal',
'intake' => IntakeKind::Inquiry,
@@ -50,7 +56,6 @@ public function handle(Channel $channel, CarbonImmutable $arrival, CarbonImmutab
'portal_reference' => $reference,
'arrival' => $arrival->toDateString(),
'departure' => $departure->toDateString(),
'hold_expires_at' => $profile->preReservation() ? now()->addHours($profile->holdHours()) : null,
'processing_mode' => $processingMode,
'internal_notes' => $notes,
]);
+26
View File
@@ -18,6 +18,7 @@
use App\Process\CaseRecorder;
use App\Process\ProcessProfile;
use App\Process\ProcessSettings;
use Carbon\CarbonImmutable;
use Carbon\CarbonInterface;
use Database\Factories\BookingFactory;
use Illuminate\Database\Eloquent\Attributes\Fillable;
@@ -71,6 +72,7 @@
'balance_due_on',
'contract_path',
'hold_expires_at',
'hold_purpose',
'offer_version',
'offer_sent_at',
'offer_message',
@@ -118,6 +120,12 @@ class Booking extends Model
public const DIRECT_SOURCES = ['website', 'manual', 'phone', 'direct', 'email', 'internal'];
/** The hold of a request or an offer (unchanged behaviour of v0.10). */
public const HOLD_OFFER = 'offer';
/** The short hold of an incomplete request while details are fetched (v0.11, E-033). */
public const HOLD_CLARIFICATION = 'clarification';
public function isDirect(): bool
{
return $this->import_channel_id === null && $this->origin_channel_id === null && in_array($this->source, self::DIRECT_SOURCES, true);
@@ -516,6 +524,24 @@ public function isHoldActive(): bool
return in_array($this->status, BookingStatus::holding(), true) && $this->hold_expires_at?->isFuture();
}
/**
* The real state of the clarification hold, for what the guest may be told (v0.11, CH §2a table): none (setting 0,
* not qualified, or no clarification at all), active until a real point in time, or expired. Only this – never the
* configured value – may be put into a message.
*
* @return array{state: 'none'|'active'|'expired', until: ?CarbonImmutable}
*/
public function clarificationState(): array
{
if ($this->hold_purpose !== self::HOLD_CLARIFICATION || $this->hold_expires_at === null) {
return ['state' => 'none', 'until' => null];
}
return $this->isHoldActive()
? ['state' => 'active', 'until' => $this->hold_expires_at]
: ['state' => 'expired', 'until' => $this->hold_expires_at];
}
/**
* The website this stay belongs to, regardless of which landlord is current.
*/
+42
View File
@@ -0,0 +1,42 @@
<?php
namespace App\Process;
use App\Models\Booking;
use Carbon\CarbonImmutable;
/**
* What a new request holds when it comes in (v0.11, B1, E-033):
*
* - complete for an offer: the offer hold exactly as before (if the settings reserve at all);
* - incomplete, but with property, dates and a usable e-mail address (V1): only the clarification hold of its data
* request mode, 0 = none;
* - otherwise nothing.
*
* A request answered with an information "unter Vorbehalt" (no offer hold) needs no details first and holds nothing,
* as before. The free calendar was checked by the caller under its lock.
*/
final class RequestHold
{
/**
* @param Booking $draft the new case, not yet stored, with its guest relation
* @return array{hold_expires_at: ?CarbonImmutable, hold_purpose: string}
*/
public static function for(Booking $draft, ProcessProfile $profile): array
{
if (! $profile->preReservation()) {
return ['hold_expires_at' => null, 'hold_purpose' => Booking::HOLD_OFFER];
}
if (CaseRequirements::isComplete($draft)) {
return ['hold_expires_at' => now()->addHours($profile->holdHours())->toImmutable(), 'hold_purpose' => Booking::HOLD_OFFER];
}
$minutes = $profile->clarificationHoldMinutes();
if ($minutes === 0 || ! CaseRequirements::qualifiesForClarificationHold($draft)) {
return ['hold_expires_at' => null, 'hold_purpose' => Booking::HOLD_CLARIFICATION];
}
return ['hold_expires_at' => now()->addMinutes($minutes)->toImmutable(), 'hold_purpose' => Booking::HOLD_CLARIFICATION];
}
}
+178
View File
@@ -0,0 +1,178 @@
<?php
namespace Tests\Feature;
use App\Actions\ContributeCaseFacts;
use App\Actions\CreateReservation;
use App\Actions\ExpireReservations;
use App\Actions\SendOffer;
use App\Actions\TakeOverExternalBooking;
use App\Enums\BookingStatus;
use App\Enums\FactSource;
use App\Exceptions\ReservationException;
use App\Models\Booking;
use App\Models\Channel;
use App\Models\Property;
use App\Pricing\StayRequest;
use App\Support\Content;
use App\Support\Settings;
use Carbon\CarbonImmutable;
use Database\Seeders\PropertySeeder;
use Database\Seeders\SiteSeeder;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\Storage;
use Tests\TestCase;
/**
* v0.11 package U3: the optional clarification hold of an incomplete request (E-033, G1a, B1, M11 reservation part,
* M12 protection of binding bookings). The offer hold stays exactly as it was.
*/
class ClarificationHoldTest extends TestCase
{
use RefreshDatabase;
private const ADDRESS = ['street' => 'Strandweg 1', 'postal_code' => '18225', 'city' => 'Kühlungsborn', 'country' => 'DE'];
private Property $property;
protected function setUp(): void
{
parent::setUp();
$this->travelTo(CarbonImmutable::parse('2026-10-22 10:00'));
$this->seed([PropertySeeder::class, SiteSeeder::class]);
$this->property = Property::sole();
Mail::fake();
Storage::fake('local');
Http::fake(['*' => Http::response('', 500)]);
Content::save(['contract.terms' => '<p>Echte Bedingungen</p>', 'stay.cancellation' => '<p>Echtes Storno</p>']);
Settings::tenant()->update(['bank_iban' => 'DE02120300000000202051']);
}
public function test_a_complete_request_keeps_the_offer_hold_as_before(): void
{
$booking = $this->request(self::ADDRESS);
$this->assertSame(Booking::HOLD_OFFER, $booking->hold_purpose);
$this->assertTrue($booking->hold_expires_at->equalTo(now()->addHours(48)));
}
public function test_an_incomplete_request_gets_only_the_clarification_hold_of_its_mode(): void
{
$manual = $this->request();
$this->assertSame(Booking::HOLD_CLARIFICATION, $manual->hold_purpose);
$this->assertTrue($manual->hold_expires_at->equalTo(now()->addMinutes(180)), 'release or manual request: 180 minutes');
$this->assertSame('active', $manual->clarificationState()['state']);
Settings::tenant()->update(['process_defaults' => ['data_request_mode' => 'automatic']]);
$automatic = $this->request(email: 'zwei@example.org', arrival: '2026-11-20', departure: '2026-11-23');
$this->assertTrue($automatic->hold_expires_at->equalTo(now()->addMinutes(15)), 'automatic request: 15 minutes');
}
public function test_zero_means_no_clarification_hold_and_the_dates_stay_free(): void
{
Settings::tenant()->update(['process_defaults' => ['clarification_hold_manual_minutes' => 0]]);
$booking = $this->request();
$this->assertNull($booking->hold_expires_at);
$this->assertSame('none', $booking->clarificationState()['state']);
$this->assertSame(BookingStatus::Reserved, $booking->status);
$this->request(email: 'andere@example.org');
$this->assertSame(2, Booking::query()->count(), 'no hold: the same dates can still be requested');
}
public function test_a_request_without_usable_email_is_not_held(): void
{
$booking = app(CreateReservation::class)->handle($this->property->fresh(), new StayRequest(CarbonImmutable::parse('2026-11-07'), CarbonImmutable::parse('2026-11-10'), 2), ['first_name' => 'Paul', 'last_name' => 'Telefon', 'email' => ''], source: 'phone', sendMails: false);
$this->assertNull($booking->hold_expires_at);
}
public function test_an_expired_clarification_hold_leaves_the_request_open_and_the_offer_needs_free_dates(): void
{
$booking = $this->request();
$this->travel(181)->minutes();
app(ExpireReservations::class)->handle();
$booking->refresh();
$this->assertSame(BookingStatus::Reserved, $booking->status, 'the case stays open');
$this->assertSame('expired', $booking->clarificationState()['state']);
$this->assertFalse(Booking::query()->occupying()->whereKey($booking->id)->exists(), 'the calendar is free again');
app(ContributeCaseFacts::class)->handle($booking, collect(self::ADDRESS)->mapWithKeys(fn (string $value, string $key): array => ['guest.'.$key => $value])->all(), FactSource::GuestLink, ['reference' => 'link-1']);
$this->assertFalse($booking->fresh()->isHoldActive(), 'completing the details creates no offer hold by itself');
$this->assertSame(Booking::HOLD_CLARIFICATION, $booking->fresh()->hold_purpose);
$competitor = $this->request(self::ADDRESS, email: 'schneller@example.org');
$this->assertSame(Booking::HOLD_OFFER, $competitor->hold_purpose);
$this->expectException(ReservationException::class);
app(SendOffer::class)->handle($booking->fresh());
}
public function test_the_offer_turns_the_clarification_hold_into_the_unchanged_offer_hold(): void
{
$booking = $this->request();
app(ContributeCaseFacts::class)->handle($booking, collect(self::ADDRESS)->mapWithKeys(fn (string $value, string $key): array => ['guest.'.$key => $value])->all(), FactSource::GuestLink, ['reference' => 'link-1']);
$offer = app(SendOffer::class)->handle($booking->fresh());
$this->assertSame(Booking::HOLD_OFFER, $offer->hold_purpose);
$this->assertTrue($offer->hold_expires_at->equalTo(now()->addHours(48)));
}
public function test_a_binding_portal_booking_never_gets_a_clarification_hold(): void
{
$portal = Channel::factory()->for($this->property)->create(['name' => 'FeWo-direkt', 'booking_model' => 'portal_booking']);
$booking = app(TakeOverExternalBooking::class)->handle($this->property, $portal, CarbonImmutable::parse('2026-12-05'), CarbonImmutable::parse('2026-12-08'), ['portal_reference' => 'HA-7']);
$this->assertSame(BookingStatus::Confirmed, $booking->status);
$this->assertNotSame(Booking::HOLD_CLARIFICATION, $booking->hold_purpose);
$this->assertSame('none', $booking->clarificationState()['state']);
}
/**
* Holds are set only by the existing reservation and offer steps (plus the intake decision of v0.11). Nothing of
* the communication handler – data requests, answers, reminders, extraction – may extend or set one (CH-16/17).
*/
public function test_only_the_existing_reservation_steps_write_a_hold(): void
{
$allowed = [
'Actions/ConfirmBooking.php', 'Actions/CreateReservation.php', 'Actions/DecideBookingWish.php', 'Actions/DeclineBooking.php',
'Actions/RejectOffer.php', 'Actions/ReleaseReservation.php', 'Actions/SendInformation.php', 'Actions/SendOffer.php',
'Actions/SetBookingStatus.php', 'Actions/TakeOverExternalBooking.php', 'Actions/TakeOverPortalInquiry.php',
'Documents/DocumentComposer.php', 'Filament/Resources/Bookings/Pages/ViewBooking.php', 'Models/Booking.php', 'Process/RequestHold.php',
];
$writers = [];
$files = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator(app_path(), \FilesystemIterator::SKIP_DOTS));
foreach ($files as $file) {
$source = file_get_contents($file->getPathname());
if (preg_match("/'hold_expires_at' =>|hold_expires_at = |RequestHold::for/", $source)) {
$writers[] = str_replace('\\', '/', substr($file->getPathname(), strlen(app_path()) + 1));
}
}
sort($writers);
sort($allowed);
$this->assertSame($allowed, $writers);
}
/**
* @param array<string, string> $address
*/
private function request(array $address = [], string $email = 'gesa@example.org', string $arrival = '2026-11-07', string $departure = '2026-11-10'): Booking
{
return app(CreateReservation::class)->handle(
$this->property->fresh(),
new StayRequest(CarbonImmutable::parse($arrival), CarbonImmutable::parse($departure), 2),
['first_name' => 'Gesa', 'last_name' => 'Gast', 'email' => $email, ...$address],
sendMails: false,
)->fresh();
}
}
+1 -1
View File
@@ -143,7 +143,7 @@ private function reserve(string $arrival, string $departure, string $email = 'an
return app(CreateReservation::class)->handle(
$this->property,
new StayRequest($this->date($arrival), $this->date($departure), 2),
['first_name' => 'Anna', 'last_name' => 'Muster', 'email' => $email],
['first_name' => 'Anna', 'last_name' => 'Muster', 'email' => $email, 'street' => 'Strandweg 1', 'postal_code' => '18225', 'city' => 'Kühlungsborn', 'country' => 'DE'],
);
}