# Architect — F-017 Pricing module

## Feature
F-017 adds server-side pricing and VAT calculation behind a public `PricingService`, so future cart/checkout flows never trust frontend-supplied prices.

## Design

### Module boundaries
Create `project/src/modules/pricing/` following existing module structure:
- `domain/price.ts` for money, VAT rate, price record and calculation result types.
- `domain/ports.ts` for `PricingRepository` and `PricingService` contracts.
- `domain/errors.ts` for missing price and invalid pricing command errors.
- `application/pricing-service.ts` implementing calculations and price changes.
- `infrastructure/pg-pricing-repository.ts` owning PostgreSQL persistence.
- `api/pricing.routes.ts` for explicit backend endpoints.
- `index.ts` exporting only the public pricing API.

Catalog remains independent. Pricing stores `variant_id` as an opaque UUID reference and does not join or import catalog internals. Future cart/checkout must depend on `PricingService`, injected at composition root.

### Money and VAT rules
Use integer cents only — no floating point money.
- Stored base price: `net_unit_amount_cents` (pre-VAT).
- VAT rate: enum `general` = 21% and `reduced` = 10% for this slice.
- Calculation: `netSubtotal = netUnit * quantity`; `vatAmount = round(netSubtotal * vatBps / 10000)`; `total = netSubtotal + vatAmount`.
- Currency is fixed to `EUR` by database default and API response. Multi-currency is explicitly out of scope.

### Data model
Add migration `012_pricing.js`:
- `pricing_variant_prices`
  - `variant_id uuid primary key`
  - `net_unit_amount_cents integer not null check >= 0`
  - `vat_rate text not null check in ('general', 'reduced')`
  - `currency text not null default 'EUR' check = 'EUR'`
  - timestamps
- `pricing_price_history`
  - append-only audit rows for every price change
  - stores previous and new net amount/rate/currency, plus timestamp
  - first price creation also writes a history row with previous fields null

### Public service interface
Expose `PricingService` from module index:
- `calculate({ variantId, quantity }): Promise<PriceCalculation>`
- `setVariantPrice({ variantId, netUnitAmountCents, vatRate }): Promise<VariantPrice>`
- `getVariantPrice(variantId): Promise<VariantPrice | undefined>`

`calculate` never accepts or uses client unit price, subtotal, VAT, discount, or total fields. That is the core rule: callers provide product identity and quantity; pricing returns truth.

### API slice
Add routes:
- `GET /pricing/variants/:variantId` — public read of current server-side price.
- `PUT /pricing/variants/:variantId` — admin-only price change.
- `POST /pricing/calculate` — calculation by `variantId` and `quantity`; schema strips/ignores extra client fields.

HTTP errors:
- `PRICING_PRICE_NOT_FOUND` as 404 when calculating/read has no server-side price.
- `INVALID_PRICE` as 422 for invalid commands.

### Tests
- Unit tests for VAT calculation for general/reduced rates and invalid quantity/amount.
- Unit/API test proving client-supplied price fields are ignored by schema/service and server price is used.
- Integration test proving every price change writes a history row, including create and update.
- Boundary test proving catalog does not reference `pricing_` tables or pricing internals.
- Migration suite remains the safety net for up/down/idempotency.

## Acceptance trace
- PricingService.calculate returns totals with VAT from persisted server price.
- Client price ignored: calculate only uses variant id + quantity; schema strips extra price fields and tests send bogus client values.
- Price history: repository writes append-only rows on creation and update.
- `verify.sh`: must pass after gates.

## Risks / constraints
- Do not add decimal/money dependencies; integer cents are sufficient and safer.
- Do not couple pricing to catalog by FK or join in this slice; variant existence validation is a later orchestration concern.
- Do not store or trust client totals anywhere.