Files
fewo-stommer/CLAUDE.md
T
Lars StommerandClaude Opus 5.5 4f69b426a4 Booking path 1 (offer + guest acceptance), 2FA for all, privacy hardening, brand graphics in theme
- Offer workflow: "Angebot senden" in the admin (dates, guests, promo code, manual price adjustment,
  validity from the property's hold time, message, guest data for the contract) with live price;
  contract draft PDF; signed, versioned offer page for the guest to accept (acceptance record without
  IP) or decline; expiry job, landlord notifications, editable offer texts, wording on the website.
- 2FA is mandatory for every admin account.
- Privacy: complete anonymisation (notes, attribution, review names, offer messages), shorter
  periods for unbinding requests, portal mail excerpts and attribution (configurable proposals),
  iCal summary not stored, known e-mail no longer overwrites guest data, security headers, bearer
  tokens for automations, metadata stripped from photo originals, review link throttled.
- Daily database backup (backup:database) and scripts/backup-pull.sh for the NAS.
- Theme: brand mark in header/footer, favicon/touch icon, wave divider, icons, illustration as
  image placeholder; navy follows the text colour for dark appearances.

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

11 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. Kinds (OfferKind): rule, fixed dates, gap filler (App\Availability\GapFinder). Which offers the website advertises is decided by App\Pricing\OfferShowcase (not by appearances); it prices fixed dates/gaps with PriceCalculator.
  • 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 booking e-mails are a fast path (app/Channels/Mail, ProcessPortalMail): they create blocks with source email, which SyncChannel later confirms/replaces and never removes as stale. Portal analysis: docs/PORTALE.md.
  • Website = theme system (docs/THEMES.md): themes live in resources/themes/<key> (theme.json, theme.css, theme.js, views); views resolve via the theme:: namespace (theme → parent → base ostsee-licht). Pages are lists of sections (app/Themes/Sections, catalogue in config/themes.php); seasonal Appearances override tokens/texts/hero photo/photos per section (stable data.id per placed section) and sections can be limited to appearances. Theme views use only token colour classes (bg-accent, text-muted, …). New designs are additional themes: php artisan themes:make <key>, themes:check, themes:preview – never edit ostsee-licht for a new design; authoring rules in docs/THEME-ERSTELLUNG.md. Resolve Theme lazily (app(Theme::class)), never in constructors – middleware ResolveTheme replaces it per request.
  • Operations (environments, Strato access, server .env, admin accounts, 2FA, known pitfalls): docs/BETRIEB.md – read it before touching a server. Admin accounts: php artisan users:create; 2FA (Filament app authentication) is mandatory for every account. Admin modes (App\Enums\AdminMode: simple/expert per user, user menu switch) only shape the menu via the FollowsAdminMode trait on every resource/page (simple menu = AdminMode::SIMPLE_NAVIGATION); permissions stay with roles/policies. New admin resources must use FollowsAdminMode.
  • Deployment: scripts/deploy.sh <env> setup|deploy [ref]|rollback|releases|artisan (atomic releases on Strato, docs/DEPLOYMENT.md; the server keeps only the active release because of Strato's file quota – history = Git tags deploy/<env>/<timestamp>); CI .gitea/workflows/deploy.yml. Production has no dev packages (no factories/Faker) – production seeding via ProductionSeeder.
  • 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.