pleno-vue/docs/customer-attributes-refactor-plan.md

# Customer attributes refactor and migration plan

## Problem statement

Customer attributes are currently represented as loosely typed string flags and evaluated in several UI, POS, and invoicing paths. This makes product restrictions vulnerable to broad category heuristics. The immediate defect is that `restrictAdditionalServices` ("Begræns tillægsydelser") treats related booking add-ons as additional services, so interior wash add-ons plus trailer/dolly additions are blocked even though that attribute is intended to cover standalone additional services only.

## Target behavior matrix

| Attribute                            | Canonical intent                                       | Product availability behavior                                                                                                     | Invoice/workflow behavior                                                   |
| ------------------------------------ | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `restrictAdditionalServices`         | Block standalone additional services/tillægsydelser.   | Block standalone additional-service catalog items; do not block related booking add-ons such as interior wash, trailer, or dolly. | Flag only order lines that are standalone additional services.              |
| `restrictTankCleaning`               | Block tank-cleaning services.                          | Block products whose category or legacy name identifies tank cleaning.                                                            | Flag tank-cleaning order lines.                                             |
| `restrictSpotFree`                   | Block Spot Free/RO rinse products.                     | Block canonical Spot Free product IDs and legacy Spot Free/RO naming.                                                             | Flag Spot Free order lines.                                                 |
| `restrictInteriorCleaning`           | Block interior wash services.                          | Block products whose names/categories explicitly identify interior wash.                                                          | Flag interior-wash order lines.                                             |
| `onlyTankCleaning`                   | Allow only tank-cleaning services.                     | Block every non-tank-cleaning product while keeping tank-cleaning products available.                                             | Flag non-tank-cleaning order lines.                                         |
| `requiresReferenceNumber`            | Require an order reference.                            | No product filtering.                                                                                                             | Flag orders missing a required reference.                                   |
| `requiresRegistrationNumbersInvoice` | Require registration numbers on invoice/order context. | No product filtering.                                                                                                             | Flag orders missing required registration numbers.                          |
| `invoiceAllOrdersIndividually`       | Prevent grouped invoicing.                             | No product filtering.                                                                                                             | Split/flag invoice collections containing multiple orders for the customer. |
| `invoiceWithStripe`                  | Invoice through Stripe workflow.                       | No product filtering.                                                                                                             | Route the customer through Stripe invoicing/payment handling.               |
| `showPricesOnBookingPage`            | Show customer prices during booking.                   | No product filtering.                                                                                                             | Presentation-only booking behavior.                                         |
| `usePONumbers`                       | Use/prompt for PO numbers.                             | No product filtering.                                                                                                             | Require or expose PO-number workflow where configured.                      |
| `exemptFromAdministrationFee`        | Do not charge administration fees.                     | No product filtering.                                                                                                             | Suppress/flag administration-fee order lines for this customer.             |

## Refactor plan

1. **Create a canonical customer-rule domain module**

   - Keep `CUSTOMER_RULE_DEFINITIONS` as the registry of public attributes, but extend each entry with a typed evaluator contract: product predicate, category predicate, invoice predicate, and UI impact metadata.
   - Replace scattered string comparisons with registry lookups so every surface uses the same semantics.
   - Add explicit names for ambiguous categories: `standaloneAdditionalService`, `relatedAddon`, `primaryProduct`, `tankCleaning`, `spotFree`, and `interiorCleaning`.

2. **Normalize product classification once**

   - Build a `classifyCustomerRuleProduct(product, context)` helper returning booleans for each product class.
   - Treat related add-ons (`isRelatedAddon`, `relatedItemId`) as context, not as proof that the item is a standalone additional service.
   - Reserve `restrictAdditionalServices` for category 8/standalone service context or explicit additional-service labels, not numeric booking add-on category 4.

3. **Migrate rule evaluation paths**

   - POS product cards and mobile flows should call `getCustomerProductRestriction` only with the normalized product context.
   - Customer-rule tooltips should derive blocked/available products from the same evaluator used by POS.
   - Invoicing-period flag generation should use the same classification vocabulary as product availability so historical and current orders are flagged consistently.

4. **Backfill and data migration**

   - Keep existing attribute keys unchanged to avoid a destructive migration.
   - Add a one-time data audit/report listing customers with `restrictAdditionalServices` and recent orders containing interior wash, trailer, or dolly add-ons. These rows should be verified as no longer violating the rule after deployment.
   - If any historical invoice flags were created solely because related add-ons were treated as additional services, provide an idempotent cleanup command to recalculate customer-rule violations for affected invoice periods.

5. **Regression test coverage**

   - Unit-test every attribute in the target behavior matrix.
   - Add focused cases for the defect: interior wash related add-on, trailer related add-on, and dolly related add-on must remain available under `restrictAdditionalServices`.
   - Add invoice-flag fixtures mirroring the same products so invoicing behavior cannot drift from POS behavior.
   - Keep tooltip tests aligned with the evaluator, showing standalone additional services under `restrictAdditionalServices` and not showing related add-ons.

6. **Rollout and verification**
   - Ship the evaluator patch behind the existing attribute keys.
   - Run unit tests and targeted POS/customer-rule e2e tests.
   - Verify with production-like catalog data that `restrictAdditionalServices` blocks only standalone additional services while `restrictInteriorCleaning`, `restrictTankCleaning`, `restrictSpotFree`, and `onlyTankCleaning` continue to behave exactly as listed above.