# Spec — Rediseño "Portal Minería" (look Terrano)

**Fecha:** 2026-06-06
**Estado:** aprobado por el usuario, en implementación
**Rama:** `feat/terrano-redesign`

## Objetivo

Adoptar la **imagen y estructura** de https://mining.terraworks.cl/ (proyecto "Terrano")
sobre la plataforma actual, usando la **información real** que ya tiene la app (BD Prisma,
auth propia, asistente de publicación). Re-skin completo "todo de una".

Referencia visual fiel (capturas reales renderizadas del sitio) en `docs/terrano-ref/`:
`terrano-home.png`, `terrano-listings.png`, `terrano-detail.png`, `hero-mine.png`.
Código fuente de referencia ya analizado (React + estilos inline + window globals — **NO**
se copia ese enfoque; se porta idiomáticamente a Next 16 + Tailwind + Prisma).

## Decisiones tomadas

- **Marca:** "Portal Minería" (wordmark `PORTAL MINERÍA · CL`).
- **Alcance:** todas las páginas en esta iteración.
- **Datos faltantes (híbrido honesto):** cada ficha muestra solo datos reales; los totales se
  calculan de la BD. Precios de commodities (ticker + franja de mercado) son **estáticos
  marcados como "referencial"**, aislados para conectar a una fuente real luego.
- **Mapa:** ilustrado estilo Terrano en **vista satélite** (textura de terreno + curvas de nivel +
  distritos), pines en coordenadas `lat/lng` reales proyectadas. Es el "Atlas de activos mineros".
- **Imágenes de publicaciones (requisito explícito):** **todas** las publicaciones muestran una
  imagen del lugar relacionado (no placeholders rayados). Ver sección "Imágenes".
- **Login funcional** y plataforma interna (dashboard + publicar) re-skineados y operativos.
- **localhost = la web real** (`npm run dev`), no maquetas.

## Sistema de diseño

`src/app/globals.css` reemplaza el tema oscuro/ámbar por los tokens Terrano:

- Base: `--bg:#f4f1ea`, `--bg-elev:#fbf9f4`, `--bg-sunk:#ece7dc`, `--ink:#141414`,
  `--ink-2:#2d2a25`, `--muted:#6e6a62`, `--muted-2:#9b968c`,
  `--line:#1a1a1a`, `--line-soft:#c9c3b5`, `--line-softer:#dfd9cc`.
- Acentos: `--accent:#14314a` (azul), `--accent-2:#B87333` (cobre), `--accent-3:#2D6A4F` (verde), `--ok:#2D6A4F`.
- Tipografías vía `next/font/google`: **Space Grotesk** (display), **Inter** (cuerpo), **JetBrains Mono** (datos).
- Radios 0–4px, sombras mínimas. `color-scheme: light`.
- Tailwind v4 `@theme` mapea estos tokens a utilidades. Clases utilitarias `.mono`, `.display`,
  `.uppercase`, `.btn`(+`.accent/.ghost/.sm/.xs`), `.pill`, `.card`, `.input`, `.placeholder`.

## Mapeo datos reales → UI

| UI Terrano        | Campo real |
|-------------------|-----------|
| mineral principal | `commodities` con `isPrimary` (símbolo de `COMMODITY_SYMBOLS`, color por mineral) |
| minerales 2°      | resto de `commodities` |
| tipo / typeLabel  | `assetType` → label (Concesión minera / Terreno-proyecto / Relave-ripio-escoria / Infraestructura-planta) |
| etapa + código    | `stage` → `STAGE_LABELS` + código corto derivado |
| hectáreas         | `surfaceHa` |
| concesiones       | `concessionCount` |
| ubicación         | `city`, `region`, `country` (`COUNTRY_LABELS`) |
| coords            | `lat`, `lng` reales |
| modalidad         | `dealTypes` → labels (resumen "Venta / Earn-in") |
| precio            | `priceUsd` → `formatUsd` ("USD X.XM" / "Consultar") |
| verificado        | `verified` |
| publicador        | `sellerCompany` (fallback owner.name / "Publicador privado") |
| agua / energía    | `waterAccess` / `energyAccess` |
| mineralización    | `mineralizationType`, `works` |

No se muestran ley/reservas/altitud/vistas (no existen). Documentos = "Solicitar al publicador".

Colores de mineral (chips/pines): Cu `#B87333`, Au `#c9a227`, Ag `#9ca3af`, Li `#7c9885`,
Fe `#7a3b2e`, Mo `#4a5568`, otros `#6e6a62`.

## Imágenes de publicaciones

- Set curado de fotos de paisaje/faena por **tipo + región** en `public/listings/` (p. ej. desierto de
  Atacama, cordillera de Coquimbo, salar/litio, Patagonia/Santa Cruz, puna/Jujuy, planta de
  procesamiento, depósito de relaves, rajo abierto).
- `helper` `listingImage(listing)` resuelve la imagen: usa `imageSeed` si mapea a un archivo
  curado; si no, elige por `assetType`+`region`+commodity primaria. **Garantiza que toda
  publicación tenga imagen** (incluidas las nuevas creadas por el asistente, que aún no suben archivo).
- Tarjetas, galería de ficha y fila del atlas usan esa imagen (con `next/image`). Etiqueta mono
  superpuesta con `region · city` (estética Terrano) sobre la foto.
- Hero del home: `public/hero-mine.png` (rajo abierto).
- Imágenes obtenidas de fuentes libres (Unsplash/Wikimedia). Si la descarga falla en build, fallback
  a degradado con nombre del lugar (se registra en consola, no se simula como real).

## Estructura / navegación

Header global (`PORTAL MINERÍA · CL`): **Explorar(/)** · **Activos(/marketplace)** ·
**Mapa(/mapa)** · **Mercado(/mercado)** · **Publicar(/dashboard/publicar-activo)** + mini-ticker
referencial + **Ingresar/usuario**.

Rutas:
- `/` Home
- `/marketplace` Catálogo (Listados) — grilla / lista / mapa
- `/marketplace/[slug]` Ficha técnica
- `/mapa` Atlas satélite a pantalla completa de activos mineros
- `/mercado` Panel de mercado (precios referenciales) — "Próximamente" estilizado
- `/(auth)/login`, `/(auth)/registro`
- `/dashboard` Mi panel (mis publicaciones) + `/dashboard/publicar-activo` (asistente 7 pasos)
- secundarias `productos` `servicios` `inversionistas` `como-funciona` — re-skin "Próximamente"

## Páginas (resumen)

1. **Home:** marquee (cifras reales + precios "ref."), hero foto + 4 stats de BD, consola de
   búsqueda con pestañas (Activos/Productos/Servicios/Inversión) que enlazan a `/marketplace`
   con filtros, **Atlas satélite + lista en vivo**, destacados (tarjetas reales), franja de
   mercado (referencial), footer.
2. **Catálogo:** breadcrumb, título + conteo/ha reales, orden, toggle grilla/lista/mapa, sidebar de
   facetas (mineral, etapa, modalidad, superficie, país, verificado) sobre `getListings`/`parseSearchParams`
   existentes (se extienden filtros stage/surface ya soportados por la capa de datos), paginación visual.
3. **Ficha:** header (chips, tipo, verificado, título, código ref, ubicación, coords, precio,
   "Contactar publicador"), **galería con foto del lugar**, pestañas Resumen / Datos técnicos /
   Documentación / Ubicación (mapa satélite) / Publicador, sidebar (form contacto + snapshot oscuro),
   relacionados por mineral. Solo campos reales.
4. **Atlas `/mapa`:** mapa satélite grande con todos los pines + panel lateral filtrable.
5. **Comparador:** drawer lado a lado (estado en cliente, persistido en `localStorage`).
6. **Dashboard:** "mis publicaciones" (lista de `Listing` del owner) re-skineado; CTA publicar.
7. **Asistente publicar (7 pasos):** mismo flujo y server action `createListingAction`, re-skin Terrano.
8. **Auth:** login/registro re-skineados (funcionales, ya existen server actions).

## Componentes (nuevos / migrados)

`src/components/terrano/`: `Icon`, `Placeholder`, `Logo`, `MineralChip`, `DataRow`, `Btn`, `Pill`,
`SectionHeader`, `ListingCard` (grid/list), `SatelliteMap` (client), `MapPanel`, `SearchConsole`
(client), `Marquee`, `MarketStrip`, `CompareDrawer` (client), `Facets` (client).
Header/Footer reescritos. Átomos viejos (`VerifiedBadge`, `CommodityBadge`, `DealTypeBadge`,
`StageBadge`, `PriceTag`, `Thumb`, `ComingSoon`) migrados a la paleta nueva o reemplazados.

## Mapa satélite (técnico)

Componente `SatelliteMap` (client): caja con textura satelital (gradientes de terreno cálidos +
curvas de nivel SVG + polígonos de distritos punteados + grilla UTM tenue), botones de capa
(Satelital activo / Geológico / Concesiones / Infra), leyenda de minerales, chrome de coords.
Proyección lineal simple de `lat/lng` a XY normalizado sobre un bounding box
(aprox. lat −18..−52, lng −76..−66 cubriendo Chile + Andes/Argentina). Pines con símbolo de
mineral + tooltip (código, título, ha, precio). Hover/selección sincronizada con la lista.

## Estrategia técnica

- Server Components para fetch (Prisma) — Client Components solo para interacción (tabs, facetas,
  mapa hover, comparador). Sin `window` globals, sin Babel runtime, sin estilos inline masivos.
- Respetar `AGENTS.md`: leer los docs de Next en `node_modules/next/dist/docs/` antes de patrones nuevos.
- Mantener tests existentes (filtros, listings, auth, publish) verdes; ajustar solo si cambia contrato.
- TDD para helpers nuevos con lógica (`listingImage`, proyección de mapa, derivación de código/modalidad).

## Fuera de alcance (esta iteración)

Subida real de archivos, precios de commodities en vivo, IA real, recuperación de contraseña,
deploy a PostgreSQL. (El ticker/franja quedan listos para cablear.)