P6.6: legacy:grandfather-subscriptions — aktive Legacy-Abos aus dem Rechnungsarchiv migrieren
Kriterien vom Auftraggeber (12.06.2026): Quelle der Aktiv-Erkennung ist
ausschliesslich das read-only Rechnungsarchiv legacy_invoices (D-12).
Legacy-Rechnungen bleiben Archiv; neue manuelle Rechnungen entstehen im
MAN-Rechnungskreis.
- Aktiv-Regel: juengste Rechnung pro (Portal, Legacy-Vereinbarung) mit
payment_option.type=recurring und user_payment_option.status=active;
next_due_date max. --grace-months (Default 12) ueberfaellig, sonst
stale -> bleibt reines Archiv. Einmal-Kaeufe werden nie uebernommen.
- Uebernahme als grandfathered in user_payment_options:
current_period_end = next_due_date, Betraege/Intervall der letzten
Legacy-Rechnung in legacy_conditions -> der taegliche MAN-Lauf
(billing:generate-manual-invoices) fakturiert zum gewohnten
jaehrlichen Rhythmus weiter. Versteckte Katalog-Platzhalter
LEGACY-{PE|BP}-{Artikel} in payment_options.
- Replay-faehig (D-18): Re-Runs aktualisieren anhand der Legacy-IDs in
legacy_conditions statt zu duplizieren — die Kern-Migration laeuft
kurz vor dem Relaunch erneut.
- Optionen: --dry-run, --as-of, --grace-months, --no-report; JSON-Report
nach storage/app/migration/. Dry-Run gegen Test-Snapshot: 22 aktive
jaehrliche Vereinbarungen, davon 4 sofort faellig, 0 stale.
- Doku: MIGRATION-STEPS.md (Runbook-Reihenfolge nach archive-invoices),
05-DATABASE-MERGE §5.6, 12-NAECHSTE-SCHRITTE 6.6, 08-PROGRESS,
PHASE-9-Plan + Checkliste.
Tests: GrandfatherLegacySubscriptionsTest (7, inkl. End-to-End
Migration -> MAN-Rechnung mit Legacy-Betraegen). Suite: 475 passed,
4 skipped. Pint clean.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
parent
d548f4b235
commit
1cd4d8e33a
8 changed files with 526 additions and 12 deletions
272
app/Console/Commands/GrandfatherLegacySubscriptions.php
Normal file
272
app/Console/Commands/GrandfatherLegacySubscriptions.php
Normal file
|
|
@ -0,0 +1,272 @@
|
|||
<?php
|
||||
|
||||
namespace App\Console\Commands;
|
||||
|
||||
use App\Enums\UserPaymentOptionStatus;
|
||||
use App\Models\LegacyInvoice;
|
||||
use App\Models\PaymentOption;
|
||||
use App\Models\UserPaymentOption;
|
||||
use Illuminate\Console\Command;
|
||||
use Illuminate\Support\Carbon;
|
||||
use Illuminate\Support\Facades\Storage;
|
||||
|
||||
/**
|
||||
* Leitet die noch aktiven, jährlich wiederkehrenden Legacy-Zahlungs-
|
||||
* vereinbarungen aus dem Rechnungsarchiv ab und migriert sie als
|
||||
* `grandfathered` in `user_payment_options` (D-13, Kriterien 12.06.2026).
|
||||
*
|
||||
* Quelle ist ausschließlich das read-only Archiv `legacy_invoices` (D-12):
|
||||
* Pro (Portal, Legacy-Vereinbarung) zählt die jüngste Rechnung. Aktiv ist,
|
||||
* was dort `payment_option.type = recurring`, `user_payment_option.status
|
||||
* = active` und eine nicht zu weit zurückliegende `next_due_date` trägt.
|
||||
* Alle anderen Rechnungen bleiben unangetastet im Archiv.
|
||||
*
|
||||
* Die migrierte Vereinbarung trägt `current_period_end = next_due_date` —
|
||||
* damit stellt `billing:generate-manual-invoices` (MAN-Kreis) die nächste
|
||||
* Rechnung zum gewohnten Rhythmus mit den Beträgen der letzten
|
||||
* Legacy-Rechnung aus.
|
||||
*
|
||||
* Wiederholbar (D-18): Re-Runs aktualisieren bestehende Einträge anhand
|
||||
* der Legacy-IDs in `legacy_conditions`, statt Duplikate anzulegen —
|
||||
* die Kern-Migration läuft kurz vor dem Relaunch erneut.
|
||||
*
|
||||
* Verwendung:
|
||||
* php artisan legacy:grandfather-subscriptions --dry-run
|
||||
* php artisan legacy:grandfather-subscriptions --as-of=2026-06-12
|
||||
* php artisan legacy:grandfather-subscriptions
|
||||
*/
|
||||
class GrandfatherLegacySubscriptions extends Command
|
||||
{
|
||||
protected $signature = 'legacy:grandfather-subscriptions
|
||||
{--dry-run : Nur anzeigen, nichts schreiben}
|
||||
{--as-of= : Stichtag für die Aktiv-Prüfung (Default: heute)}
|
||||
{--grace-months=12 : Wie lange eine überfällige next_due_date noch als aktiv gilt}
|
||||
{--no-report : Keinen JSON-Report schreiben}';
|
||||
|
||||
protected $description = 'Migriert aktive wiederkehrende Legacy-Zahlungen aus dem Rechnungsarchiv nach user_payment_options (grandfathered).';
|
||||
|
||||
private const CHUNK_SIZE = 200;
|
||||
|
||||
public function handle(): int
|
||||
{
|
||||
$isDryRun = (bool) $this->option('dry-run');
|
||||
$asOf = $this->option('as-of') ? Carbon::parse($this->option('as-of'))->startOfDay() : today();
|
||||
$graceMonths = max(0, (int) $this->option('grace-months'));
|
||||
$staleBefore = $asOf->copy()->subMonths($graceMonths);
|
||||
|
||||
if ($isDryRun) {
|
||||
$this->warn('[DRY-RUN] Kein tatsächlicher Schreibvorgang.');
|
||||
}
|
||||
|
||||
$candidates = $this->collectLatestRecurringAgreements();
|
||||
|
||||
$report = [
|
||||
'generated_at' => now()->toIso8601String(),
|
||||
'as_of' => $asOf->toDateString(),
|
||||
'grace_months' => $graceMonths,
|
||||
'dry_run' => $isDryRun,
|
||||
'created' => [],
|
||||
'updated' => [],
|
||||
'stale_skipped' => [],
|
||||
'immediately_due' => [],
|
||||
];
|
||||
|
||||
foreach ($candidates as $candidate) {
|
||||
$nextDue = $candidate['next_due_date'];
|
||||
|
||||
if ($nextDue->lessThan($staleBefore)) {
|
||||
$report['stale_skipped'][] = $this->describe($candidate);
|
||||
|
||||
continue;
|
||||
}
|
||||
|
||||
if ($nextDue->lessThanOrEqualTo($asOf)) {
|
||||
$report['immediately_due'][] = $this->describe($candidate);
|
||||
}
|
||||
|
||||
if ($isDryRun) {
|
||||
$this->line(sprintf('[dry-run] %s', $this->describe($candidate)));
|
||||
|
||||
continue;
|
||||
}
|
||||
|
||||
$paymentOption = $this->resolveCatalogOption($candidate);
|
||||
$existing = $this->findExisting($candidate);
|
||||
|
||||
$attributes = [
|
||||
'user_id' => $candidate['user_id'],
|
||||
'payment_option_id' => $paymentOption->id,
|
||||
'status' => UserPaymentOptionStatus::Grandfathered->value,
|
||||
'grandfathered_until' => $candidate['valid_until_date']?->toDateString(),
|
||||
'current_period_start' => $candidate['period_start']->toDateString(),
|
||||
'current_period_end' => $nextDue->toDateString(),
|
||||
'stripe_subscription_id' => null,
|
||||
'legacy_conditions' => $candidate['legacy_conditions'],
|
||||
];
|
||||
|
||||
if ($existing) {
|
||||
$existing->update($attributes);
|
||||
$report['updated'][] = $this->describe($candidate);
|
||||
} else {
|
||||
UserPaymentOption::query()->create($attributes);
|
||||
$report['created'][] = $this->describe($candidate);
|
||||
}
|
||||
}
|
||||
|
||||
$this->table(
|
||||
['Ergebnis', 'Anzahl'],
|
||||
[
|
||||
['Kandidaten (aktiv, recurring)', count($candidates)],
|
||||
['Neu angelegt', count($report['created'])],
|
||||
['Aktualisiert (Re-Run)', count($report['updated'])],
|
||||
['Übersprungen (stale)', count($report['stale_skipped'])],
|
||||
['Davon sofort fällig', count($report['immediately_due'])],
|
||||
],
|
||||
);
|
||||
|
||||
foreach ($report['immediately_due'] as $line) {
|
||||
$this->warn('Sofort fällig (MAN-Lauf rechnet beim nächsten Lauf ab): '.$line);
|
||||
}
|
||||
|
||||
if (! $this->option('no-report')) {
|
||||
$path = sprintf('migration/grandfather-subscriptions-%s.json', now()->format('Ymd-His'));
|
||||
Storage::put($path, json_encode($report, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE));
|
||||
$this->info("Report: storage/app/{$path}");
|
||||
}
|
||||
|
||||
return self::SUCCESS;
|
||||
}
|
||||
|
||||
/**
|
||||
* Jüngste Archiv-Rechnung pro (Portal, Legacy-Vereinbarung) mit
|
||||
* aktiver wiederkehrender Zahlungsoption.
|
||||
*
|
||||
* @return array<int, array<string, mixed>>
|
||||
*/
|
||||
private function collectLatestRecurringAgreements(): array
|
||||
{
|
||||
$latest = [];
|
||||
|
||||
LegacyInvoice::query()
|
||||
->whereNotNull('user_id')
|
||||
->whereNotNull('pdf_payload')
|
||||
->orderBy('id')
|
||||
->chunk(self::CHUNK_SIZE, function ($invoices) use (&$latest): void {
|
||||
foreach ($invoices as $invoice) {
|
||||
$payload = $invoice->pdf_payload;
|
||||
$upo = $payload['user_payment_option'] ?? null;
|
||||
$option = $payload['payment_option'] ?? null;
|
||||
|
||||
if (! $upo || ! $option) {
|
||||
continue;
|
||||
}
|
||||
|
||||
if (($option['type'] ?? null) !== 'recurring' || ($upo['status'] ?? null) !== 'active') {
|
||||
continue;
|
||||
}
|
||||
|
||||
$key = $invoice->legacy_portal->value.'#'.$upo['id'];
|
||||
$current = $latest[$key] ?? null;
|
||||
|
||||
if ($current && $current->invoice_date->greaterThanOrEqualTo($invoice->invoice_date)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$latest[$key] = $invoice;
|
||||
}
|
||||
});
|
||||
|
||||
return array_values(array_map(fn (LegacyInvoice $invoice): array => $this->toCandidate($invoice), $latest));
|
||||
}
|
||||
|
||||
/**
|
||||
* @return array<string, mixed>
|
||||
*/
|
||||
private function toCandidate(LegacyInvoice $invoice): array
|
||||
{
|
||||
$payload = $invoice->pdf_payload;
|
||||
$snapshot = $invoice->raw_snapshot ?? [];
|
||||
$upo = $payload['user_payment_option'];
|
||||
$option = $payload['payment_option'];
|
||||
|
||||
$nextDue = isset($upo['next_due_date'])
|
||||
? Carbon::parse($upo['next_due_date'])->startOfDay()
|
||||
: Carbon::parse($snapshot['service_period_end_date'] ?? $invoice->invoice_date)->startOfDay();
|
||||
|
||||
$periodStart = isset($snapshot['service_period_begin_date'])
|
||||
? Carbon::parse($snapshot['service_period_begin_date'])->startOfDay()
|
||||
: $nextDue->copy()->subYear();
|
||||
|
||||
return [
|
||||
'user_id' => $invoice->user_id,
|
||||
'legacy_portal' => $invoice->legacy_portal->value,
|
||||
'legacy_upo_id' => (int) $upo['id'],
|
||||
'article_number' => (string) ($option['article_number'] ?? 'UNBEKANNT'),
|
||||
'next_due_date' => $nextDue,
|
||||
'period_start' => $periodStart,
|
||||
'valid_until_date' => isset($upo['valid_until_date']) && $upo['valid_until_date']
|
||||
? Carbon::parse($upo['valid_until_date'])->startOfDay()
|
||||
: null,
|
||||
'legacy_conditions' => [
|
||||
'legacy_portal' => $invoice->legacy_portal->value,
|
||||
'legacy_user_payment_option_id' => (int) $upo['id'],
|
||||
'legacy_payment_option_id' => (int) ($option['id'] ?? 0),
|
||||
'article_number' => $option['article_number'] ?? null,
|
||||
'name' => $payload['payment_option_translation']['name'] ?? null,
|
||||
'interval' => 'yearly',
|
||||
'amount_cents' => $invoice->amount_cents,
|
||||
'tax_cents' => $invoice->tax_cents,
|
||||
'total_cents' => $invoice->total_cents,
|
||||
'is_netto' => (bool) ($snapshot['is_netto'] ?? false),
|
||||
'source_invoice_number' => $invoice->number,
|
||||
'source_invoice_date' => $invoice->invoice_date->toDateString(),
|
||||
],
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* Versteckter Katalog-Eintrag pro (Portal, Legacy-Artikel) — die
|
||||
* verbindlichen Beträge pro Vereinbarung liegen in legacy_conditions.
|
||||
*/
|
||||
private function resolveCatalogOption(array $candidate): PaymentOption
|
||||
{
|
||||
$portalShort = $candidate['legacy_portal'] === 'presseecho' ? 'PE' : 'BP';
|
||||
$articleNumber = sprintf('LEGACY-%s-%s', $portalShort, $candidate['article_number']);
|
||||
|
||||
return PaymentOption::query()->firstOrCreate(
|
||||
['article_number' => $articleNumber],
|
||||
[
|
||||
'type' => 'recurring',
|
||||
'price_cents' => $candidate['legacy_conditions']['amount_cents'],
|
||||
'currency' => 'EUR',
|
||||
'interval' => 'yearly',
|
||||
'is_hidden' => true,
|
||||
],
|
||||
);
|
||||
}
|
||||
|
||||
private function findExisting(array $candidate): ?UserPaymentOption
|
||||
{
|
||||
return UserPaymentOption::query()
|
||||
->where('user_id', $candidate['user_id'])
|
||||
->get()
|
||||
->first(function (UserPaymentOption $option) use ($candidate): bool {
|
||||
$conditions = $option->legacy_conditions ?? [];
|
||||
|
||||
return ($conditions['legacy_portal'] ?? null) === $candidate['legacy_portal']
|
||||
&& (int) ($conditions['legacy_user_payment_option_id'] ?? 0) === $candidate['legacy_upo_id'];
|
||||
});
|
||||
}
|
||||
|
||||
private function describe(array $candidate): string
|
||||
{
|
||||
return sprintf(
|
||||
'User #%d · %s · Legacy-UPO #%d · fällig %s · %s €',
|
||||
$candidate['user_id'],
|
||||
$candidate['legacy_portal'],
|
||||
$candidate['legacy_upo_id'],
|
||||
$candidate['next_due_date']->toDateString(),
|
||||
number_format($candidate['legacy_conditions']['total_cents'] / 100, 2, ',', '.'),
|
||||
);
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue