v0.11 U4: Rückfrage, Folgefrage, Erinnerung und Ergänzungslink

- data_requests: ein Beschaffungsvorgang je Vorgang mit Modus
  (automatisch / Freigabe / manuell), getrennten Zählern für Folgefragen
  und Erinnerungen ohne Rücksetzen, Antwortfrist ≠ Reservierungsfrist.
- RequestCaseData: fragt nach, was für das nächste Angebot, die
  Wunschbestätigung oder (bei verbindlichen Buchungen) administrativ fehlt;
  ohne E-Mail keine Rückfrage. Teilantwort → gezielte Folgefrage, Schweigen
  → Erinnerungen, an der Grenze Aufgabe für die Vermieterin. Nie ein Hold.
- Mail DataRequested mit Texten nach tatsächlichem Sperrstatus (M11);
  Dokumentart „Rückfrage“ – im Live-Betrieb ohne Freigabe nur nach Klick.
- Signierter, versionierter Ergänzungslink (/angebot/angaben): Lesen
  schreibt nicht, Absenden über den Fakteneingang, idempotent.
- Vorgang: „Rückfrage an den Gast senden“ / „Rückfrage beenden“;
  Eingangsbestätigung nennt die Klärungsreservierung korrekt.
- Zeitplan: cases:data-requests alle fünf Minuten.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
LarsandClaude Opus 5.5 committed 2026-11-03 13:25:48 +01:00
1 parent 37f48defcc
commit e4a3cb7f7b
22 files changed
+1224 -7

No files matched your search

+320
View File
@@ -0,0 +1,320 @@
<?php
namespace App\Actions;
use App\Documents\DocumentReleases;
use App\Enums\BookingStatus;
use App\Enums\BookingTaskKind;
use App\Enums\BookingTaskStatus;
use App\Enums\DataRequestMode;
use App\Enums\DocumentKind;
use App\Enums\FactSource;
use App\Enums\IntakeKind;
use App\Mail\DataRequested;
use App\Models\Booking;
use App\Models\BookingTask;
use App\Models\DataRequest;
use App\Process\CaseLog;
use App\Process\CaseRequirements;
use App\Process\FactContribution;
use App\Support\Settings;
use Carbon\CarbonImmutable;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\URL;
use Throwable;
/**
* The data request of v0.11 (S1, S4, CH-04, CH-15–CH-18): when the next step of a case lacks details, the guest is
* asked – automatically, prepared for the landlord's release, or by the landlord himself, as the case's settings say.
* At most one request runs per case. A partial answer leads to a targeted follow-up question, silence to reminders;
* both have their own limits and counters that are never reset. At the limit the landlord takes over.
*
* The request decides nothing about the case: answers go through the common fact intake, which asks the existing
* process to carry on. It never touches a hold or a deadline of the offer (CH-16/17, architecture test).
*/
class RequestCaseData
{
/** What the details are needed for. */
public const FOR_OFFER = 'offer';
public const FOR_WISH = 'wish_confirmation';
public const FOR_BOOKING = 'booking';
/**
* What the case needs next and which details are missing for it, or null when nothing is to be asked.
*
* @return array{purpose: string, fields: list<string>}|null
*/
public static function needs(Booking $booking): ?array
{
$booking->loadMissing('guest');
if (in_array($booking->status, [BookingStatus::Cancelled, BookingStatus::Declined, BookingStatus::Expired, BookingStatus::Completed], true) || $booking->isInternal()) {
return null;
}
if ($booking->isBinding()) {
// A binding booking (also from a portal, E-036) stays binding; only administrative guest details are asked for.
if ($booking->departure->isPast()) {
return null;
}
$fields = array_values(array_filter(CaseRequirements::missing($booking), fn (string $field): bool => str_starts_with($field, 'guest.')));
return $fields === [] ? null : ['purpose' => self::FOR_BOOKING, 'fields' => $fields];
}
if ($booking->intake === IntakeKind::Booking || $booking->status !== BookingStatus::Reserved || $booking->offer_version > 0) {
return null;
}
$purpose = match (true) {
$booking->process()->preReservation() => self::FOR_OFFER,
$booking->wish_at !== null => self::FOR_WISH,
default => null,
};
if ($purpose === null) {
return null;
}
$fields = CaseRequirements::missing($booking, $purpose === self::FOR_WISH ? CaseRequirements::WISH_CONFIRMATION : CaseRequirements::OFFER);
return $fields === [] ? null : ['purpose' => $purpose, 'fields' => $fields];
}
/**
* Starts the request for the next step if details are missing and none runs yet. Returns the running request.
*/
public function forNextStep(Booking $booking, ?DataRequestMode $mode = null): ?DataRequest
{
$needs = self::needs($booking);
// Without an e-mail address there is no way back to the guest: the case shows "enter the contact details".
if ($needs === null || ! CaseRequirements::isValid('guest.email', $booking->guest?->email)) {
return null;
}
$request = DB::transaction(function () use ($booking, $needs, $mode): DataRequest {
$booking->lockForTransition();
$running = $booking->openDataRequest();
if ($running !== null) {
return $running;
}
$mode ??= $booking->process()->dataRequestMode();
return $booking->dataRequests()->create([
'tenant_id' => $booking->tenant_id,
'status' => match (true) {
$mode === DataRequestMode::Manual => DataRequest::MANUAL,
$mode === DataRequestMode::Automatic && self::mayGoOutAutomatically() => DataRequest::OPEN,
default => DataRequest::DRAFT,
},
'mode' => $mode,
'purpose' => $needs['purpose'],
'fields' => $needs['fields'],
'last_message' => DataRequest::INITIAL,
]);
});
if ($request->wasRecentlyCreated) {
CaseLog::record($booking, 'data_request', match ($request->status) {
DataRequest::OPEN => 'Fehlende Angaben werden beim Gast angefragt',
DataRequest::DRAFT => 'Rückfrage nach fehlenden Angaben vorbereitet – wartet auf Ihre Freigabe',
default => 'Fehlende Angaben: bitte selbst beim Gast nachfragen (Textvorschlag im Vorgang)',
}, data: ['fields' => $request->fields], actor: CaseLog::SYSTEM);
if ($request->status === DataRequest::OPEN) {
$this->send($request, DataRequest::INITIAL);
}
}
return $request;
}
/**
* The landlord releases the prepared question (or asks now although the case is set to manual).
*/
public function approve(DataRequest $request): bool
{
if (! $request->isRunning()) {
return false;
}
if (! CaseRequirements::isValid('guest.email', $request->booking->guest?->email)) {
return false;
}
$kind = $request->last_message === DataRequest::FOLLOWUP ? DataRequest::FOLLOWUP : DataRequest::INITIAL;
$request->update(['status' => DataRequest::OPEN]);
return $this->send($request, $kind);
}
/**
* Sends the question, follow-up or reminder. A failing mail is shown in the case; the landlord takes over.
*/
public function send(DataRequest $request, string $kind): bool
{
$booking = $request->booking()->with(['guest', 'property'])->firstOrFail();
$profile = $booking->process();
$needs = self::needs($booking);
if ($needs === null) {
$this->close($request, DataRequest::COMPLETED, 'alle Angaben da');
return false;
}
$request->fields = $needs['fields'];
if ($kind === DataRequest::FOLLOWUP) {
$request->followups_sent++;
$request->link_version++;
}
if ($kind === DataRequest::REMINDER) {
$request->reminders_sent++;
}
try {
Mail::to($booking->guest->email, $booking->guest->full_name)->send(new DataRequested($booking, $request, $kind, $this->url($request, $booking)));
} catch (Throwable $exception) {
Log::warning('Rückfrage nicht zugestellt', ['booking' => $booking->id, 'exception' => $exception::class]);
$request->forceFill(['status' => DataRequest::MANUAL])->save();
BookingTask::openOnce($booking, BookingTaskKind::GuestUnresponsive, 'r'.$request->id, ['due_on' => today(), 'note' => 'Die Rückfrage konnte nicht zugestellt werden – bitte die E-Mail-Adresse prüfen oder selbst nachfragen.']);
CaseLog::record($booking, 'data_request', 'Rückfrage konnte nicht zugestellt werden', actor: CaseLog::SYSTEM);
return false;
}
$request->forceFill([
'status' => DataRequest::OPEN,
'last_message' => $kind,
'last_sent_at' => now(),
'response_due_at' => now()->addHours($profile->reminderHours()),
'next_reminder_at' => now()->addHours($profile->reminderHours()),
])->save();
CaseLog::record($booking, 'data_request', match ($kind) {
DataRequest::FOLLOWUP => 'Gezielte Folgefrage an den Gast ('.$request->followups_sent.'.)',
DataRequest::REMINDER => 'Erinnerung an den Gast ('.$request->reminders_sent.'.)',
default => 'Rückfrage an den Gast gesendet',
}.': '.implode(', ', CaseRequirements::labels($request->fields)), actor: CaseLog::SYSTEM);
return true;
}
/**
* Details arrived (any source): the open reminder is cancelled; if everything is there the request ends, otherwise
* a targeted follow-up question follows within its limit (CH-15–17). The landlord's own entries never trigger a
* question to the guest.
*/
public function answered(Booking $booking, FactContribution $contribution, FactSource $source): void
{
$request = $booking->openDataRequest();
if ($request === null) {
return;
}
$needs = self::needs($booking->refresh());
if ($needs === null) {
$this->close($request, DataRequest::COMPLETED, 'alle Angaben da');
return;
}
if ($source->isAuthoritative() || $request->status !== DataRequest::OPEN || (! $contribution->anyApplied() && ! $contribution->needsReview())) {
$request->update(['fields' => $needs['fields']]);
return;
}
$request->forceFill(['answered_at' => now(), 'next_reminder_at' => null, 'fields' => $needs['fields']])->save();
if ($request->followups_sent >= $booking->process()->followupsMax()) {
$this->handOver($request, 'Antwort weiterhin unvollständig – die Grenze der Folgefragen ist erreicht.');
return;
}
if ($request->mode === DataRequestMode::Automatic && self::mayGoOutAutomatically()) {
$this->send($request, DataRequest::FOLLOWUP);
return;
}
$request->forceFill(['status' => $request->mode === DataRequestMode::Manual ? DataRequest::MANUAL : DataRequest::DRAFT, 'last_message' => DataRequest::FOLLOWUP])->save();
CaseLog::record($booking, 'data_request', 'Antwort unvollständig – Folgefrage vorbereitet: '.implode(', ', CaseRequirements::labels($needs['fields'])), actor: CaseLog::SYSTEM);
}
/**
* Due reminders of every running request (scheduler). At the limit the landlord takes over; nothing changes any
* deadline of the case.
*/
public function remindDue(): int
{
$count = 0;
$due = DataRequest::query()->where('status', DataRequest::OPEN)->whereNotNull('next_reminder_at')->where('next_reminder_at', '<=', now())->with('booking')->get();
foreach ($due as $request) {
$booking = $request->booking;
if ($booking === null || self::needs($booking) === null) {
$this->close($request, $booking === null ? DataRequest::STOPPED : DataRequest::COMPLETED, $booking === null ? 'Vorgang entfernt' : 'nichts mehr offen');
continue;
}
if ($request->reminders_sent >= $booking->process()->remindersMax()) {
$this->handOver($request, 'Der Gast hat auf die Rückfrage und '.$request->reminders_sent.' Erinnerung(en) nicht geantwortet.');
continue;
}
$count += $this->send($request, DataRequest::REMINDER) ? 1 : 0;
}
return $count;
}
/**
* Ends the request (all details there, the case ended, or the landlord stopped it).
*/
public function close(DataRequest $request, string $status, string $reason): void
{
if (! $request->isRunning()) {
return;
}
$request->forceFill(['status' => $status, 'closed_at' => now(), 'closed_reason' => $reason, 'next_reminder_at' => null])->save();
BookingTask::query()->where('booking_id', $request->booking_id)->where('kind', BookingTaskKind::GuestUnresponsive)->where('subject', 'r'.$request->id)->where('status', BookingTaskStatus::Open)
->get()->each(fn (BookingTask $task): bool => $task->forceFill(['status' => BookingTaskStatus::Done, 'completed_at' => now(), 'note' => trim($task->note.' · '.$reason)])->save());
if ($request->booking !== null) {
CaseLog::record($request->booking, 'data_request', 'Rückfrage beendet: '.$reason, actor: CaseLog::actor() ?? CaseLog::SYSTEM);
}
}
/**
* The guest's signed link to the form; it belongs to this request and its current version.
*/
public function url(DataRequest $request, ?Booking $booking = null): string
{
$booking ??= $request->booking;
$parameters = ['booking' => $booking, 'r' => $request->id, 'v' => $request->link_version];
$until = CarbonImmutable::now()->addDays($booking->process()->guestLinkValidDays());
return $booking->website()?->temporarySignedRoute('guest-data.show', $until, $parameters)
?? URL::temporarySignedRoute('guest-data.show', $until, $parameters);
}
/**
* Whether a question may go out without the landlord's click: its texts are released, or mails only reach the test
* recipient anyway (as for the automatic offer).
*/
public static function mayGoOutAutomatically(): bool
{
return DocumentReleases::isReleased(DocumentKind::DataRequest) || ! Settings::isLive();
}
private function handOver(DataRequest $request, string $note): void
{
$request->forceFill(['status' => DataRequest::MANUAL, 'next_reminder_at' => null])->save();
BookingTask::openOnce($request->booking, BookingTaskKind::GuestUnresponsive, 'r'.$request->id, ['due_on' => today(), 'note' => $note]);
CaseLog::record($request->booking, 'data_request', 'Rückfrage an Sie übergeben: '.$note, actor: CaseLog::SYSTEM);
}
}