Files
fewo-stommer/CLAUDE.md
T
Lars StommerandClaude Opus 5.5 0b7205e050 Portal-Synchronisation: unser System führt
- Connector-System (app/Channels, config/channels.php) mit iCal-Connector, robustem Parser und Export-Feed je Portal (ohne eigene Belegungen, ohne Gästedaten)
- Abgleich alle 5 Min. mit Protokoll, Echo-Erkennung, Konflikt-Mail bei möglicher Doppelbuchung
- Überwachung: Störungs-Mail, Status-Endpunkt /health/sync für n8n
- Portal-Aufgaben für Sofortbuchungsportale (FeWo-direkt): automatisch aus Buchungen/Sperren/anderen Portalen, Mail + Erinnerung, Abhaken im Admin
- Optionaler signierter Automatisierungs-Webhook mit Rückmeldung
- Herkunftsmessung: Abfrage im Formular + UTM-Parameter
- Portal-Analyse: AGB-Prüfung Automatisierung, Umsetzungsbeschreibung

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 11:13:55 +02:00

9.0 KiB
Raw Blame History

Ferienwohnung Stommer

Website + booking management for a holiday apartment in Kühlungsborn. Concept and roadmap: docs/KONZEPT.md.

  • Hosting target: Strato shared webhosting (PHP + MySQL, no Node at runtime) – build assets locally.
  • UI and all user-facing texts are German; code, identifiers and PHPDoc are English.
  • Money is stored as integer euro cents; edit via App\Filament\Forms\Components\EuroInput, display via ->money('EUR', divideBy: 100, locale: 'de').
  • Season periods are half-open: a night belongs to a season when starts_on <= night < ends_on.
  • Pricing lives in app/Pricing (PriceCalculator → PriceQuote); guest-facing errors are QuoteException messages.
  • Portals must be integrated through a pluggable channel-connector system (see concept §7), never hard-coded.
  • Bookings/blocks use nights: arrival <= night < departure; same-day changeover is allowed. Reservations with an elapsed hold never occupy the calendar (scope Booking::occupying()), cron only updates status.
  • Business operations live in app/Actions (CreateReservation, ConfirmBooking, …); Filament pages and Livewire components call them instead of changing bookings directly.
  • Special offers are evaluated automatically by PriceCalculator; discounts are QuoteLineType::Discount lines with negative amounts.
  • Portal sync lives in app/Channels (connector interface + registry in config/channels.php, iCal connector/parser/feed). Our system leads; SyncChannel imports portal occupations as BlockedPeriod rows with channel_id; each channel's export feed excludes its own blocks. Observers on Booking/BlockedPeriod create ChannelTasks for portals with requires_manual_blocking. Portal analysis: docs/PORTALE.md.
  • Vite fonts plugin is removed on purpose (corporate proxy breaks remote font downloads, and fonts must be self-hosted for GDPR).
  • PHP/Composer on this machine: winget package dir %LOCALAPPDATA%\Microsoft\WinGet\Packages\PHP.PHP.8.4_* (Composer as composer\composer.phar there).
  • Git remote: Gitea https://gitea.stommer.de/Lars/fewo-stommer.git, branch main.
=== foundation rules ===

Laravel Boost Guidelines

Foundational Context

This application is a Laravel application running on PHP 8.4. Always use the APIs that match the installed major version of each package — do not assume a version.

Before relying on a package's API, confirm its installed version:

  • PHP packages: run composer show --direct to list direct dependencies with versions, or composer show <vendor/package> for a single package.
  • JS packages: check package.json for the installed versions.

Skills Activation

This project has domain-specific skills available in **/skills/**. You MUST activate the relevant skill whenever you work in that domain—don't wait until you're stuck.

Conventions

  • You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, and naming.
  • Use descriptive names for variables and methods. For example, isRegisteredForDiscounts, not discount().
  • Check for existing components to reuse before writing a new one.

Verification Scripts

  • Do not create verification scripts or tinker when tests cover that functionality and prove they work. Unit and feature tests are more important.

Application Structure & Architecture

  • Stick to existing directory structure; don't create new base folders without approval.
  • Do not change the application's dependencies without approval.

Frontend Bundling

  • If a frontend change doesn't show in the UI or you get a "Unable to locate file in Vite manifest" error, run npm run build or ask the user to run npm run dev or composer run dev.

Documentation Files

  • You must only create documentation files if explicitly requested by the user.

=== boost rules ===

Laravel Boost

Project Rules

  • This project contains committed, area-grouped rules in .ai/rules when that directory exists, including path-scoped framework guidelines under .ai/rules/boost. Before you enter plan mode or create/edit any file, you MUST first: open @.ai/rules/index.md (it maps file globs to rule files), read every rule file whose globs cover the path(s) in scope, and run grep -rin 'keyword' .ai/rules to catch what a path match alone misses. Do not write code until you have read and are following every matching rule. If .ai/rules does not exist, continue without it.

Artisan

  • Run Artisan commands directly via the command line (e.g., php artisan route:list). Use php artisan list to discover available commands and php artisan [command] --help to check parameters.
  • Inspect routes with php artisan route:list. Filter with: --method=GET, --name=users, --path=api, --except-vendor, --only-vendor.
  • Read configuration values using dot notation: php artisan config:show app.name, php artisan config:show database.default. Or read config files directly from the config/ directory.

Tinker

  • Execute PHP in app context for debugging and testing code. Do not create models without user approval, prefer tests with factories instead. Prefer existing Artisan commands over custom tinker code.
  • Always use single quotes to prevent shell expansion: php artisan tinker --execute 'Your::code();'
    • Double quotes for PHP strings inside: php artisan tinker --execute 'User::where("active", true)->count();'

=== php rules ===

PHP

  • Always use curly braces for control structures, even for single-line bodies.
  • Use PHP 8 constructor property promotion: public function __construct(public GitHub $github) { }. Do not leave empty zero-parameter __construct() methods unless the constructor is private.
  • Use explicit return type declarations and type hints for all method parameters: function isAccessible(User $user, ?string $path = null): bool
  • Use TitleCase for Enum keys: FavoritePerson, BestLake, Monthly.
  • Prefer PHPDoc blocks over inline comments. Only add inline comments for exceptionally complex logic.
  • Use array shape type definitions in PHPDoc blocks.

=== deployments rules ===

Deployment

  • Laravel can be deployed using Laravel Cloud, which is the fastest way to deploy and scale production Laravel applications.
  • Activate the deploying-to-cloud skill whenever deploying to Laravel Cloud, configuring Cloud environments or resources, using the Cloud CLI, or troubleshooting Cloud deployments.

=== laravel/core rules ===

Do Things the Laravel Way

  • Use php artisan make: commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using php artisan list and check their parameters with php artisan [command] --help.
  • If you're creating a generic PHP class, use php artisan make:class.
  • Pass --no-interaction to all Artisan commands to ensure they work without user input. You should also pass the correct --options to ensure correct behavior.

Model Creation

  • When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using php artisan make:model --help to check the available options.

APIs & Eloquent Resources

  • For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention.

URL Generation

  • When generating links to other pages, prefer named routes and the route() function.

Testing

  • When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model.
  • Faker: Use methods such as $this->faker->word() or fake()->randomDigit(). Follow existing conventions whether to use $this->faker or fake().
  • When creating tests, make use of php artisan make:test [options] {name} to create a feature test, and pass --unit to create a unit test. Most tests should be feature tests.

=== pint/core rules ===

Laravel Pint Code Formatter

  • If you have modified any PHP files, you must run vendor/bin/pint --dirty --format agent before finalizing changes to ensure your code matches the project's expected style.
  • Do not run vendor/bin/pint --test --format agent, simply run vendor/bin/pint --format agent to fix any formatting issues.

=== phpunit/core rules ===

PHPUnit

  • This project uses PHPUnit. Create tests with php artisan make:test --phpunit {name}.
  • Do not include the test suite directory in {name}. Use SomeFeatureTest, not Feature/SomeFeatureTest.
  • Read the testing-best-practices skill for guidance on coverage, naming, structure, dependency isolation, and review.

Running Tests

  • Run the narrowest set of tests that covers the change. Pass a file path or --filter=testName to php artisan test --compact.
  • Rerun a test after each change to it.
  • Run vendor/bin/phpunit to call the test runner directly. It accepts the same file path and --filter=testName arguments.