# Averiado.com

> SaaS para gestión de talleres de reparación de electrónica. Permite
> gestionar reparaciones, repuestos, clientes, aparatos y facturación con
> interfaz para móvil y escritorio. Multitenant con seguridad RLS sobre
> Supabase. Pagos vía Stripe.

## Páginas públicas

- [Home](https://averiado.com/): landing del producto.
- [Directorio](https://averiado.com/directorio): listado público de
  talleres registrados.
- [Repuestos](https://averiado.com/repuestos): catálogo público de
  repuestos electrónicos.
- [Precios](https://averiado.com/precios): planes Free, Pro y Negocio.
- [Login](https://averiado.com/login): inicio de sesión (noindex).
- [Seguimiento](https://averiado.com/seguimiento): consulta pública del
  estado de una reparación con código + email/teléfono (noindex).
- [Contacto](https://averiado.com/contacto): cómo contactar al equipo
  (noindex).

## Preguntas frecuentes (FAQ)

Páginas con `noindex,nofollow` pero accesibles públicamente. Misma
apariencia que las páginas legales. Locator de página:
`[data-agent-id="faq-<slug>-page"]`.

- [Cómo funciona](https://averiado.com/faq/faq-funcionamiento): roles
  (jefe, técnico, administrativo, auxiliar) y flujo básico de una
  reparación.
- [Consulta de estado](https://averiado.com/faq/faq-seguimiento): cómo
  usar `/seguimiento` con código + email/teléfono.
- [Planes y límites](https://averiado.com/faq/faq-precios): tabla
  comparativa Free, Pro y Negocio con límites por recurso.

## Recursos para agentes

- [robots.txt](https://averiado.com/robots.txt): política de crawling
  (RFC 9309). Buscadores tradicionales y AI bots permitidos en público,
  bloqueados en áreas con login.
- [sitemap.xml](https://averiado.com/sitemap.xml): URLs canónicas
  públicas (sitemaps.org).

## Documentación legal

- [Aviso legal](https://averiado.com/legal/aviso-legal)
- [Política de privacidad](https://averiado.com/legal/privacidad)
- [Política de cookies](https://averiado.com/legal/cookies)
- [Términos y condiciones](https://averiado.com/legal/terminos)

## Convenciones AI-ready de la UI privada

El dashboard privado (`/dashboard/*`) expone locators estables para agentes:

- `data-agent-id="<scope>-<name>"` en formularios y contenedores únicos.
- `data-ai-action="<verb>-<noun>"` en botones y enlaces que ejecutan una acción.
- `data-ai-help="<texto corto>"` en modales y widgets complejos, describiendo qué hacen.
- Estados dinámicos sincronizados vía ARIA: `aria-pressed`, `aria-expanded`, `aria-busy`, `aria-describedby`.

## Locators de la página de precios

Ruta pública: `/precios`. Cada tarjeta de plan es un `<article>`
semántico con `aria-labelledby` al título del plan y `data-agent-id`
único. Los botones de acción llevan `data-ai-action` y `aria-label`
contextual.

- `[data-agent-id="precios-grid"]`: contenedor `<div role="list">` con
  los planes disponibles.
- `[data-agent-id="plan-base"]`: plan Base (0 €/mes).
  - Botón contratar: `[data-ai-action="select-plan-base"]`
    (`aria-label="Solicitar acceso al plan Base"`).
- `[data-agent-id="plan-profesional"]`: plan Profesional (29 €/mes),
  destacado con `.border-primary`.
  - Botón contratar: `[data-ai-action="select-plan-profesional"]`
    (`aria-label="Registrarse en el plan Profesional"`).
- `[data-agent-id="plan-avanzado"]`: plan Avanzado (59 €/mes).
  - Botón contratar: `[data-ai-action="select-plan-avanzado"]`
    (`aria-label="Contactar para contratar el plan Avanzado"`).

Cada lista de características del plan es un `<ul aria-label="Caracteristicas
incluidas en el plan X">`. El precio se expone como
`<p class="card-title h3" aria-label="Precio: N euros al mes">`.

## Locators del footer público

Cada columna navegacional del footer es un `<nav aria-label="...">`
con `data-agent-id` único. Cada enlace lleva
`data-ai-action="footer-<seccion>-<slug>"` y
`rel="nofollow noopener noreferrer"`.

- `[data-agent-id="footer-legal-nav"]`: Aviso legal, Privacidad,
  Cookies, Términos.
- `[data-agent-id="footer-links-nav"]`: Precios, Login, Seguimiento,
  Contacto.
- `[data-agent-id="footer-faq-nav"]`: Cómo funciona, Consulta de
  estado, Planes y límites.
- `[data-agent-id="footer-comunidad-nav"]`: Directorio, Averías
  (próximamente), Repuestos, Esquemas (próximamente). Los items
  pendientes son `<span class="public-footer-link-pending"
  aria-label="...próximamente">`, no enlaces.
- `[data-agent-id="footer-preferencias-nav"]`: acciones sobre la página
  actual (no navegación). `[data-ai-action="open-voice-intro"]` y
  `[data-ai-action="open-cookies-settings"]` abren overlays modales.

El copyright `[data-ai-action="footer-home"]` enlaza al home con
`rel="follow"` (única señal SEO follow del footer).

### Convención general: doble confirmación en mutaciones de BD

Todo botón que escribe en base de datos (alta, edición, borrado) exige **doble click** por seguridad.

- El botón se marca con `data-ai-confirm-required="true"` (declarativo, visible para agentes).
- **Primer click**: el botón pasa a `data-ai-state="awaiting-confirmation"` y `aria-pressed="true"`. Muestra un countdown en el atributo `data-confirm-remaining="N"` (segundos restantes).
- **Segundo click dentro de la ventana**: ejecuta la acción real. El atributo `data-ai-state` vuelve a `idle`.
- Timeout o tecla `Esc`: el botón vuelve a `idle` sin efecto.
- La ventana por defecto es 5 segundos (3 en acciones destructivas). Leer `data-confirm-seconds` para saberla exacta.

Un agente LLM debe, al encontrar `data-ai-confirm-required="true"`:
1. Hacer el primer click.
2. Esperar al menos 200 ms.
3. Hacer el segundo click antes de que `data-confirm-remaining` llegue a 0.

## Acciones críticas en el dashboard

### Crear reparación (sub-acción: crear cliente rápido)

Ruta: `/dashboard/reparaciones/alta` (requiere autenticación).

Formulario principal de alta de reparación. Si el cliente no existe en el
desplegable, hay un botón `+` que abre una modal para darlo de alta sin salir
de la página:

- Trigger: `[data-ai-action="open-cliente-quick"]` junto al `<select id="cliente_id">`.
- Modal: `#clienteQuickModal`. Texto de ayuda para agentes en `data-ai-help`.
- Formulario del modal: `[data-agent-id="cliente-quick-form"]`.
- Campos (todos con `aria-describedby` apuntando a helper + error placeholder):
  - `[name="nombre"]` obligatorio, 2-500 caracteres.
  - `[name="nif"]` opcional, 5-50 caracteres, se normaliza a mayúsculas.
  - `[name="email"]` opcional, formato email válido, se normaliza a minúsculas.
  - `[name="telefono"]` opcional, 5-30 caracteres, sólo dígitos/+/-/()/espacios.
  - `[name="notas_cliente"]` opcional, máximo 5000 caracteres.
- Submit: `[data-ai-action="submit-cliente-quick"]`. Requiere doble click (`data-ai-confirm-required="true"`, ventana 5s). Tras confirmar:
  - Backend devuelve `{cliente_id, message}`.
  - La nueva opción queda seleccionada en `<select id="cliente_id">` del form padre.
  - La modal se cierra.
- Cancelar: `[data-ai-action="cancel-cliente-quick"]` o botón `×` con `[data-ai-action="close-cliente-quick"]`.

Rate limit del endpoint subyacente (`POST /api/v1/clientes`): 30 creaciones por hora por usuario.

## Estado de discoverability para agentes (Fase 1)

- robots.txt: implementado.
- sitemap.xml: implementado.
- llms.txt: este fichero.
- Link headers RFC 8288: implementados en respuestas HTML públicas.

## Roadmap

Próximas mejoras planeadas para mejorar el descubrimiento:

- Markdown for Agents (Cloudflare): negociar `Accept: text/markdown` y
  devolver versión MD del HTML.
- OAuth/OIDC discovery (`/.well-known/openid-configuration`) apuntando al
  issuer Supabase.
- API Catalog (`/.well-known/api-catalog`) cuando se exponga API pública.