# CLAUDE.md — Peninsula Fitness Commercial Ecosystem

Última actualización: se agrega módulo administrativo CRUD completo para que leads, cotizaciones, oportunidades, productos y datos comerciales sean 100% editables por usuarios administradores.

## Purpose
Build a staged commercial ecosystem for Peninsula Fitness using Astro. This is not just a landing page: it is a mobile-first catalog + quote engine + lightweight HubSpot-inspired CRM, later extended with payments, marketplace/accounting APIs, WhatsApp automation, and campaign optimization.

Primary site: https://peninsulafitness.com.mx/  
Detailed architecture: `docs/ARCHITECTURE.md`  
Product seed: `src/data/peninsula-products.seed.json`

## Current stage priority
Work in stages. Do not implement future-stage production features until the current stage is stable.

1. Stage 1: catalog + quote engine + CRM + follow-up tasks + dashboard + dataLayer events.
2. Stage 2: Alegra, Mercado Libre, Amazon, Mercado Pago, PayPal, closed-quote payment landing.
3. Stage 3: WhatsApp bot for FAQs, lead qualification, quoting and recovery.
4. Stage 4: private campaign cockpit for Meta/Google recommendations and premium improvements.

## Non-negotiable rules
- Mobile-first always. If mobile is broken, the feature is incomplete.
- Every commercial action must create or update CRM records.
- Admin users must be able to create, read, update, edit and delete all operational CRM/catalog records through protected UI and API flows: leads/contacts, companies, opportunities, quotes, quote items, products, variants, tasks, activities, files and automation rules. Use soft delete by default and audit every mutation.
- Validate public inputs with Zod on both client and server.
- Never commit secrets, API keys, tokens, `.env` values or credentials.
- Use `dataLayer` as the central tracking contract for GTM, GA4 and Meta Pixel.
- Security must be handled with VPS hardening, app validation, headers, rate limiting, audit logs and least privilege. Do not rely on paid external security services.
- Payments must never trust frontend totals. Backend quote is source of truth.
- WhatsApp/campaign automation must be human-safe: no spammy flows, no publishing campaigns without approval.
- Keep implementation lightweight; do not add heavy dependencies without clear value.

## Business context
Peninsula Fitness sells high-resistance rubber flooring for gyms, boxes, studios, home gyms, acoustic projects and commercial spaces in Mexico. Main categories include roll flooring, puzzle/interlocking flooring, double density tiles, acoustic products, sheets, adhesives and accessories. The catalog data comes from the uploaded Excel and is normalized into 102 product records.

Key conversion flow:
visitor selects product -> enters square meters + postal code -> enters name/company/WhatsApp/email -> quote is calculated -> user chooses `levantar_orden` or `hablar_con_especialista` -> CRM records are created.

## Stage 1 required modules
- Public home page.
- Product catalog.
- Product detail pages.
- Mobile quote wizard.
- CRM login.
- CRM dashboard with KPIs.
- CRM opportunities table.
- Admin CRUD console for leads, contacts, companies, opportunities, quotes, quote items, products/catalog, tasks, activities and automation rules.
- Pipeline Kanban.
- Opportunity detail with activity drawer.
- Tasks and follow-up automation.
- Tracking helper for `dataLayer`.

## CRM stages
Use these exact stages unless explicitly changed:
`lead_nuevo -> contactado -> cotizacion_enviada -> seguimiento -> negociacion -> ganado -> perdido`

## CRM KPIs
- active opportunities
- total pipeline amount
- won deals this month
- stalled opportunities
- pending follow-ups

## Product data contract
Use `src/data/peninsula-products.seed.json` only as the initial seed/import source. After import, PostgreSQL is the source of truth and admin users must be able to create, modify, publish/unpublish or soft-delete products and variants from the private CRM/catalog admin.

Important fields:
- `id`
- `slug`
- `name`
- `sku`
- `normalized_category`
- `dimensions`
- `coverage_m2_per_unit`
- `thickness`
- `color`
- `price_without_vat_mxn`
- `vat_rate`
- `quote_enabled`
- `requires_specialist_quote`

Only products with `quote_enabled = true` can be automatically quoted. Products with missing coverage or price require specialist validation.

## Quote formula
For quote-enabled products:
- roll waste factor: 8%
- default waste factor: 5%
- effective m2 = requested m2 * (1 + waste factor)
- units = ceil(effective m2 / coverage_m2_per_unit)
- subtotal = units * price_without_vat_mxn
- tax = subtotal * 0.16
- total = subtotal + tax + shippingEstimate when available

Show the result as an estimate and mark shipping/installation as pending validation unless implemented.

## Data model minimum
Use PostgreSQL locally on VPS. Keep models explicit and auditable.

Core entities:
`users`, `roles`, `permissions`, `user_roles`, `contacts`, `companies`, `opportunities`, `opportunity_stage_history`, `quotes`, `quote_items`, `products`, `product_variants`, `activities`, `tasks`, `files`, `automation_rules`, `automation_runs`, `tracking_events`, `integration_accounts`, `integration_sync_logs`, `webhook_events`, `bot_conversations`, `campaign_snapshots`, `campaign_recommendations`, `audit_logs`, `soft_deleted_records`.

## Public API minimum
- `POST /api/quote/calculate`
- `POST /api/quote/create`
- `GET/POST/PATCH/DELETE /api/crm/opportunities`
- `GET/POST/PATCH/DELETE /api/crm/contacts`
- `GET/POST/PATCH/DELETE /api/crm/companies`
- `GET/POST/PATCH/DELETE /api/crm/quotes`
- `GET/POST/PATCH/DELETE /api/crm/quote-items`
- `GET/POST/PATCH/DELETE /api/catalog/products`
- `GET/POST/PATCH/DELETE /api/crm/tasks`
- `GET/POST/PATCH/DELETE /api/crm/activities`
- `POST /api/auth/login`

Future routes must live under provider folders: `integrations/alegra`, `integrations/mercadolibre`, `integrations/amazon`, `integrations/mercadopago`, `integrations/paypal`, `whatsapp`.

## Tracking events minimum
Push these via a helper, not scattered inline code:
- `view_catalog`
- `select_product`
- `quote_start`
- `quote_calculated`
- `generate_lead`
- `specialist_requested`
- `crm_stage_changed`
- `crm_quote_sent`
- `crm_opportunity_won`
- `crm_opportunity_lost`

Persist UTMs in first-party cookies for 30 days: `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `gclid`, `fbclid`.

## Recommended repo structure
```txt
src/pages/index.astro
src/pages/productos/index.astro
src/pages/productos/[slug].astro
src/pages/cotizar.astro
src/pages/gracias/[quoteId].astro
src/pages/crm/index.astro
src/pages/crm/pipeline.astro
src/pages/crm/oportunidades/[id].astro
src/pages/crm/leads/[id].astro
src/pages/crm/cotizaciones/[id].astro
src/pages/crm/productos/index.astro
src/pages/crm/productos/[id].astro
src/pages/api/quote/calculate.ts
src/pages/api/quote/create.ts
src/components/catalog/
src/components/quote/
src/components/crm/
src/islands/QuoteWizard.tsx
src/islands/PipelineBoard.tsx
src/islands/ActivityDrawer.tsx
src/lib/db/
src/lib/quote/
src/lib/crm/
src/lib/tracking/
src/lib/security/
src/lib/integrations/
src/data/peninsula-products.seed.json
```

## Security baseline
- Nginx reverse proxy.
- TLS via Certbot.
- UFW only 22/80/443.
- SSH key-only; no root login.
- Fail2ban.
- Secure cookies: HttpOnly, Secure, SameSite.
- CSRF for mutable authenticated forms.
- Rate limiting for quote, auth and webhook endpoints.
- CSP, HSTS, X-Content-Type-Options, Referrer-Policy, Permissions-Policy.
- Uploads outside public root.
- Audit log for login, admin CRUD changes, lead edits, quote edits, product edits, stage changes, amount changes, payment events and webhook events.
- Soft delete by default for operational records; hard delete only for superadmin/maintenance scripts with confirmation and audit trail.

## Implementation workflow
Before editing:
1. Inspect existing files.
2. Read this file.
3. Read only the relevant section of `docs/ARCHITECTURE.md`.
4. Make a short plan.

While editing:
1. Keep changes small.
2. Preserve stage boundaries.
3. Add or update tests for quote logic, CRM mutations and admin CRUD permissions.
4. Prefer typed helpers over duplicated logic.
5. Avoid broad rewrites.

Before finishing:
1. Run typecheck/build/lint/tests when available.
2. Report changed files, checks run and pending risks.

## First task prompt
Implement Stage 1 Sprint 1 only: Astro structure, mobile-first layout, catalog pages, product import from `src/data/peninsula-products.seed.json`, quote calculation with Zod, and dataLayer helper. Do not implement real payments, WhatsApp bot or external API sync yet. Include admin-protected CRUD contracts/UI scaffolding for products, leads/opportunities and quotes so Stage 1 data is editable from the CRM.