"""
Contenido de la guía de conexión con Google.

Está en el servidor y no escrito dentro de la pantalla por una razón concreta:
la interfaz y el recorrido guiado muestran los mismos pasos, y duplicarlos
garantiza que en algún momento uno diga una ruta de menú que Google ya cambió y
el otro no.

Cada paso trae tres cosas, y las tres son obligatorias: **qué se consigue**, **la
ruta exacta dentro de las pantallas de Google**, y **un ejemplo del dato que hay
que traer de vuelta**. El ejemplo es la parte que no se puede omitir: alguien que
nunca entró a Google Cloud no sabe distinguir un identificador de proyecto de un
número de proyecto, y describirlo con palabras no alcanza para reconocerlo.
"""

#: Ejemplo anonimizado del archivo de cuenta de servicio.
#:
#: No contiene material secreto real: la clave privada está recortada a un texto
#: evidentemente falso. Existe para que alguien pueda comparar el archivo que
#: bajó con el que esperamos, campo por campo, antes de subirlo.
#:
#: Queda en inglés y sin traducir, por el mismo motivo que la cabecera del CSV:
#: es una copia de un archivo que Google genera en inglés, y traducirlo lo
#: volvería inútil para compararlo con el que la persona tiene delante.
KEY_FILE_EXAMPLE = {
    'type': 'service_account',
    'project_id': 'my-project-123456',
    'private_key_id': 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0',
    'private_key': (
        '-----BEGIN PRIVATE KEY-----\n(a long block goes here)\n-----END PRIVATE KEY-----\n'
    ),
    'client_email': 'tools-patiospools@my-project-123456.iam.gserviceaccount.com',
    'client_id': '123456789012345678901',
    'auth_uri': 'https://accounts.google.com/o/oauth2/auth',
    'token_uri': 'https://oauth2.googleapis.com/token',
    'auth_provider_x509_cert_url': 'https://www.googleapis.com/oauth2/v1/certs',
    'client_x509_cert_url': 'https://www.googleapis.com/robot/v1/metadata/x509/tools-patiospools',
    'universe_domain': 'googleapis.com',
}

#: Campos que la pantalla resalta en el ejemplo. Son los que hay que reconocer
#: para saber si el archivo es el correcto; el resto es ruido para quien recién
#: llega.
KEY_FILE_HIGHLIGHTS = ('type', 'project_id', 'private_key_id', 'client_email')

#: Los siete pasos del recorrido, en orden.
#:
#: `verifiable` marca los que se comprueban de verdad contra el estado del
#: sistema. Los que no lo son se confirman a mano, y la pantalla lo dice: marcar
#: como cumplido algo que nadie comprobó es la forma más rápida de que el
#: recorrido termine con una configuración que no funciona (FR-017).
#: El texto de cada paso —qué se consigue, la ruta dentro de Google, el ejemplo
#: y su aclaración— vive en el catálogo del cliente, bajo `step.<CODE>.*`. Acá
#: queda lo que **no** es una redacción: qué pasos hay, en qué orden, cuáles se
#: comprueban de verdad y si el paso trae un ejemplo para mostrar.
#:
#: El módulo sigue existiendo por el motivo de siempre: la pantalla de
#: configuración y el recorrido muestran los mismos pasos, y duplicar la lista
#: garantiza que en algún momento una diga una ruta de menú que Google ya cambió
#: y la otra no. Lo que se movió es dónde está escrito el texto, no quién decide
#: cuáles son los pasos.
STEPS = (
    {'code': 'GOOGLE_PROJECT', 'has_example': True, 'verifiable': True},
    {'code': 'ENABLE_API', 'has_example': False, 'verifiable': True},
    # El primer paso **opcional** del recorrido, y las dos marcas dicen por qué.
    #
    # `verifiable` en falso es lo honesto: la única forma de comprobarlo es
    # publicar una dirección, y eso gasta del techo real de la cuota de
    # indexación. El paso se confirma con la evidencia del primer pedido que
    # salga de verdad, no con una sonda que consuma una publicación del día.
    #
    # `required` en falso es la consecuencia obligada. Un paso que nunca llega a
    # cumplirse solo dejaría el recorrido imposible de terminar: quien sólo
    # quiere mirar la cobertura quedaría parado para siempre en una API que no
    # necesita. Se muestra, se explica y se comprueba; lo que no hace es frenar
    # el final.
    {
        'code': 'ENABLE_INDEXING_API',
        'has_example': True,
        'verifiable': False,
        'required': False,
    },
    {'code': 'SERVICE_ACCOUNT_KEY', 'has_example': True, 'verifiable': True},
    {'code': 'AUTHORIZE_PROPERTY', 'has_example': True, 'verifiable': True},
    {'code': 'ADD_DOMAIN', 'has_example': True, 'verifiable': True},
    {'code': 'ADD_SITEMAP', 'has_example': True, 'verifiable': True},
    # El checklist llama a este paso «Lanzar la primera inspección». El título
    # del catálogo dice otra cosa a propósito: lo que el paso encola es una
    # sincronización, que lee los sitemaps y da de alta las URLs. Las
    # inspecciones vienen después, de a tandas y contra el cupo. Ponerle el
    # nombre del checklist haría esperar estados de cobertura para dentro de un
    # minuto, y no llegan hasta el primer ciclo.
    {'code': 'FIRST_BATCH', 'has_example': False, 'verifiable': True},
)

STEP_CODES = tuple(step['code'] for step in STEPS)

#: Los que hay que cumplir para que el recorrido termine.
#:
#: Se separan de `STEP_CODES` porque son dos preguntas distintas: qué pasos hay
#: —que es lo que se dibuja y se comprueba— y cuáles hacen falta para dar la
#: configuración por terminada. Un paso opcional que contara para el final
#: dejaría el recorrido abierto para siempre en quien no lo necesita.
#:
#: Los que no declaran `required` lo son: la excepción se escribe, la regla no.
REQUIRED_STEP_CODES = tuple(step['code'] for step in STEPS if step.get('required', True))


def step(code: str) -> dict | None:
    return next((s for s in STEPS if s['code'] == code), None)


def guide() -> dict:
    """Todo lo que la pantalla de configuración necesita para dibujar la guía."""
    return {
        'steps': list(STEPS),
        'key_file_example': KEY_FILE_EXAMPLE,
        'key_file_highlights': list(KEY_FILE_HIGHLIGHTS),
    }