Guía de personalización

Esta guía cubre la superficie de personalización sin código compatible para las bifurcaciones de The Pool tal como existe ahora.

El objetivo es permitir que las bifurcaciones cambien el nombre, el estilo y la reconfiguración de la plataforma a través de la configuración, manteniendo alineados el pago, los informes, los correos electrónicos y el trabajador.

El modelo de configuración estructurado en _config.yml es ahora la superficie canónica orientada a la horquilla.

Comience aquí

Para la mayoría de las bifurcaciones, los principales archivos de personalización son:

• _config.yml
• _config.local.yml
• worker/wrangler.toml

Utilice ./scripts/dev.sh --podman para la verificación local después de los cambios de configuración.

Para ediciones normales del operador, utilice el panel de administración privado en /admin/ o /es/admin/:

• Configuración edita la configuración de toda la plataforma y las herramientas de administración de tiempo de ejecución para superadministradores.
• Complementos edita productos complementarios de la plataforma para superadministradores.
• Campañas edita la configuración de la campaña, el contenido de la página, los niveles, los elementos de soporte, los complementos de la campaña, los objetivos ampliados, los elementos en curso, las entradas del diario y las decisiones.
• Configuración -> Usuarios es solo en tiempo de ejecución y se guarda directamente en Worker KV en admin-users:v1; no se publica en GitHub.
• Secretos y credenciales tiene un estado de solo lectura. Los valores secretos aún pertenecen a los secretos de los trabajadores, los secretos del repositorio de GitHub o los archivos env locales ignorados.

Trate _config.local.yml como un archivo de solo anulación. Mantenga la configuración de bifurcación canónica en _config.yml y use el archivo local solo para cosas que deberían diferir en su máquina, como las URL del host local o la visibilidad de la campaña solo local.

La ruta local normal ahora está basada en localhost:

• sitio: http://127.0.0.1:4000
• Trabajador: http://127.0.0.1:8787

El sitio estático generado ahora también excluye carpetas internas del repositorio como worker/, scripts/ y tests/, por lo que la verificación estática se asemeja más a lo que realmente publicaría una bifurcación.

Áreas de configuración admitidas

La configuración del sitio está organizada en torno a estas secciones orientadas hacia la bifurcación:

• nivel superior title / description
• seo
• platform
• pricing
• tax
• shipping
• reports
• i18n
• design
• debug
• performance
• launch_reminders
• add_ons
• checkout
• cache

Nivel superior title / description

Utilice los metadatos de Jekyll de nivel superior para la identidad social/búsqueda predeterminada del sitio.

Teclas admitidas:

• title
• description

Estos valores alimentan:

• reserva HTML predeterminada <title>
• reserva de meta descripción predeterminada
• descripción alternativa de WebSite JSON-LD en todo el sitio

platform.name sigue siendo la principal superficie visible de la marca. Trate title / description de nivel superior como la línea base de SEO orientada a la bifurcación en lugar de la interfaz principal de marca de UI.

platform

Utilice platform para identidad, URL y activos de marca.

Teclas admitidas:

• name
• version
• release_label
• company_name
• support_email
• pledges_email_from
• updates_email_from
• site_url
• worker_url
• default_creator_name
• timezone
• logo_path
• footer_logo_path
• favicon_path
• default_social_image_path

Estos valores alimentan:

• marca de encabezado/pie de página
• publicar metadatos para documentos/copia pública cuando una bifurcación quiera mostrar su hito actual
• títulos de página y metaetiquetas
• metadatos del título de la aplicación para superficies móviles/compartidas
• imagen de tarjeta social predeterminada
• copia alternativa del creador de la campaña
• Comportamiento de fecha límite/cuenta regresiva de la campaña y ventanas del ciclo de vida programadas del trabajador.
• pago/Administrar la copia de la interfaz de usuario de Pledge y la configuración del cliente de arranque
• Marca de correo electrónico del trabajador cuando se refleja

Notas:

• platform.* es la superficie de marca principal.
• platform.version debe ser la versión canónica del producto legible por máquina para el sitio, mientras que platform.release_label puede seguir siendo más amigable para copias públicas como v1.0.3.
• platform.timezone debe ser una zona horaria compatible con la IANA. El valor predeterminado es America/Denver, por lo que las bifurcaciones existentes mantienen el comportamiento del ciclo de vida anterior hasta que lo cambien.
• title / author de nivel superior todavía existen en Jekyll, pero trátelos como metadatos/respaldo generales del sitio en lugar de la interfaz principal de personalización de la bifurcación.
• platform.default_social_image_path es el valor predeterminado admitido para tarjetas OG/Twitter cuando una página o campaña no proporciona una imagen más específica.
• platform.logo_path es también la marca reflejada que se utiliza en los correos electrónicos de los seguidores.
• El dominio en platform.pledges_email_from y platform.updates_email_from debe estar autorizado por el proveedor de correo electrónico configurado. Con Resend, autorizar pool.example.com no autoriza a example.com y viceversa.

Ejemplo:

platform:
  name: My Fork
  version: 1.0.3
  release_label: v1.0.3
  company_name: Example Studio
  support_email: [email protected]
  pledges_email_from: "My Fork <[email protected]>"
  updates_email_from: "My Fork <[email protected]>"
  site_url: https://crowdfund.example.com
  worker_url: https://pledge.example.com
  default_creator_name: Example Studio
  timezone: America/Denver
  logo_path: /assets/images/brand/logo-square.png
  footer_logo_path: /assets/images/brand/logo-footer.png
  favicon_path: /assets/images/brand/favicon.png
  default_social_image_path: /assets/images/brand/social-card.png

pricing

Utilice pricing para los valores predeterminados de impuestos y sugerencias de plataforma que deben permanecer consistentes en todo el sitio y el trabajador. Las tarifas de reserva de envío se encuentran bajo shipping.

Teclas admitidas:

• sales_tax_rate
• default_tip_percent
• max_tip_percent

Ejemplo:

pricing:
  sales_tax_rate: 0.0825
  default_tip_percent: 5
  max_tip_percent: 15

tax

Utilice tax para la selección del motor de impuestos del lado del trabajador y su configuración de búsqueda no secreta.

Teclas admitidas:

• provider
• origin_country
• use_regional_origin
• nm_grt_api_base
• zip_tax_api_base

Valores actuales del proveedor:

• flat mantiene el legado configurado pricing.sales_tax_rate
• offline_rules utiliza reglas proporcionadas para el IVA/GST internacional y el manejo alternativo a nivel estatal
• nm_grt utiliza un conjunto de datos inicial suministrado por Nuevo México y puede refinar búsquedas completas de direcciones de calles de NM con la API gratuita EDAC GRT
• zip_tax usa ZIP.TAX para búsquedas de impuestos de EE. UU. a nivel local/jurisdiccional y recurre a offline_rules para destinos fuera de EE. UU./CA

Nota de UX actual:

• El carrito y el proceso de pago pueden mostrar el impuesto provisional como -- hasta que el navegador tenga suficientes detalles de destino para el proveedor configurado.
• nm_grt es actualmente la ruta de datos locales integrada más completa para impuestos jurisdiccionales de EE. UU. y generalmente necesita datos completos de destino a nivel de calle de Nuevo México antes de poder devolver un resultado preciso.

Ejemplo:

tax:
  provider: nm_grt
  origin_country: US
  use_regional_origin: false
  nm_grt_api_base: https://grt.edacnm.org
  zip_tax_api_base: https://api.zip-tax.com

Si habilita zip_tax, configure también el secreto de trabajador ZIP_TAX_API_KEY. Mantenga ese secreto fuera de _config.yml.

El archivo inicial de Nuevo México suministrado se encuentra en worker/src/tax-data/nm-grt-starter.js. Actualízalo con:

node ./scripts/update-nm-grt-starter.mjs

i18n

Utilice i18n para el modelo local admitido en el sitio estático.

Teclas admitidas:

• default_lang
• supported_langs
• language_labels
• pages

pages es el mapa de ruta de la página pública utilizado por los ayudantes de configuración regional compartidos. Permite que las bifurcaciones agreguen un nuevo idioma mediante configuración más contenido traducido en lugar de editar la lógica de navegación a mano.

Ejemplo:

i18n:
  default_lang: en
  supported_langs:
    - en
    - es
  language_labels:
    en: English
    es: Español
  pages:
    home:
      en: /
      es: /es/
    about:
      en: /about/
      es: /es/about/
    terms:
      en: /terms/
      es: /es/terms/

Patrón soportado actualmente:

• La copia compartida del sistema/UI se encuentra en _data/i18n/{lang}.yml.
• Las páginas públicas no predeterminadas se encuentran bajo un prefijo local como /es/.
• Los mensajes compartidos de tiempo de ejecución/navegador se emiten a través de assets/i18n.json.
• Los correos electrónicos de los seguidores de los trabajadores reutilizan ese catálogo de configuración regional compartido y preferredLang persistente
• El cromo de la campaña, como el botón de video principal/texto de carga, el texto teaser de la comunidad de seguidores, las pestañas del diario, los controles de la fase de producción, las etiquetas de accesibilidad de la galería, los resúmenes de los botones del carrito y el texto auxiliar de ubicación de impuestos de pago ahora también provienen de _data/i18n/{lang}.yml.
• el conmutador de idioma del pie de página compartido es automático cuando se configura más de un idioma
• Las páginas de formato largo como about y terms deberían usar páginas fuente localizadas en lugar de intentar almacenar cada párrafo en YAML.
• Los metadatos públicos y las sugerencias de lenguaje de datos estructurados también siguen el mismo modelo local, por lo que las páginas públicas localizadas no necesitan un segundo sistema de traducción exclusivo para SEO.

Qué significa esto en la práctica:

• cambiar i18n.default_lang solo cambia la configuración regional predeterminada en la que se resuelve el sitio
• agregar un nuevo archivo _data/i18n/{lang}.yml es suficiente para Chrome compartido, interfaz de usuario en tiempo de ejecución y copia del correo electrónico del asistente del trabajador.
• No es suficiente para un sitio completamente traducido por sí solo.
• El soporte completo de idiomas también necesita:
  • el nuevo idioma agregado a i18n.supported_langs
  • su etiqueta agregada a i18n.language_labels
  • rutas localizadas agregadas a i18n.pages
  • páginas de origen localizadas para contenido de formato largo que realmente desea traducir
• Las rutas tokenizadas de administración de promesas siguen funcionando en todas las configuraciones regionales porque el conmutador de idioma compartido conserva la cadena de consulta y el hash actuales.

Flujo de trabajo de bifurcación recomendado:

1. Copiar _data/i18n/en.yml a _data/i18n/{lang}.yml
2. Agregue el idioma al bloque i18n en _config.yml
3. Agregue páginas de origen localizadas para rutas de formato largo como /about/ y /terms/
4. Compile localmente y verifique tanto la copia de la interfaz de usuario compartida como las rutas localizadas

superficie SEO

Los fundamentos actuales de SEO están intencionalmente limitados. Las horquillas deben tratarlas como perillas soportadas:

• nivel superior title
• nivel superior description
• seo.x_handle
• seo.same_as
• seo.index_public_community_hub
• seo.default_social_image_alt
• seo.og_locale_overrides
• platform.name
• platform.site_url
• platform.default_social_image_path
• página localizada title / description portada en páginas públicas
• campaña title, short_blurb e imágenes principales

Esa superficie controla actualmente:

• URL canónicas
• meta descripciones
• Vistas previas de Open Graph y Twitter
• generación de URL del mapa del sitio
• en todo el sitio Organization / WebSite JSON-LD
• campaña CreativeWork / ruta de navegación JSON-LD
• texto alternativo de imagen social alternativa
• Cadenas de configuración regional de Open Graph

La implementación es deliberadamente limitada:

• Los flujos privados/tokenizados/solo para seguidores están marcados noindex
• robots.txt y sitemap.xml solo anuncian la superficie pública
• no existe una matriz gigante de configuración de SEO por página más allá de los campos de contenido que el sitio ya admite

Ejemplo:

seo:
  x_handle: dustwave
  same_as:
    - https://www.instagram.com/dustwave
    - https://www.youtube.com/@dustwave
  index_public_community_hub: true
  default_social_image_alt: "Social card for your deployment"
  og_locale_overrides:
    en: en_US
    es: es_ES

debug

Utilice debug para el tiempo de ejecución compartido del navegador y el registro de la consola de trabajo.

Teclas admitidas:

• console_logging_enabled
• verbose_console_logging

Qué hacen:

• console_logging_enabled: false suprime la salida del navegador y del trabajador console en el carrito compartido, la campaña, la comunidad, las estadísticas en vivo, la gestión de promesas, el webhook, el administrador y los tiempos de ejecución de las tareas programadas.
• verbose_console_logging: false mantiene el registrador activo pero suprime el ruido de depuración/información/registro de menor gravedad y al mismo tiempo permite advertencias y errores.

Estos valores predeterminados son intencionalmente true en _config.yml, por lo que las bifurcaciones comienzan con diagnósticos completos disponibles y pueden desactivar el registro más tarde sin cambios de código.

Cuando están habilitados, los registradores compartidos ahora emiten:

• marcas de tiempo ISO
• Prefijos consistentes de navegador/ámbito de trabajo
• etiquetas de gravedad como LOG, WARN y ERROR
• cargas útiles Error normalizadas
• captura del navegador para errores no detectados y rechazos de promesas no controlados

shipping

Utilice shipping para la configuración de envío de origen y de reserva, además del catálogo preestablecido para productos físicos comunes.

Claves admitidas hoy:

• origin_zip
• origin_country
• fallback_flat_rate
• free_shipping_default
• default_option
• usps.enabled
• usps.client_id
• usps.api_base
• usps.timeout_ms
• usps.quote_cache_ttl_seconds
• usps.failure_cooldown_seconds
• usps.rate_limit_cooldown_seconds
• presets

Opcionalmente, las campañas también pueden establecer shipping_fallback_flat_rate al frente. Cuando está presente, esa reserva específica de la campaña anula el shipping.fallback_flat_rate global si la cotización de USPS no está disponible.

Opcionalmente, las campañas también pueden establecer shipping_options al frente para optar por el conjunto de políticas de envío limitado para patrocinadores:

• signature_required
• adult_signature_required

standard siempre está disponible implícitamente y no es necesario incluirlo en la lista.

Cuando una promesa califica para múltiples opciones de entrega, el carrito compartido y las UI de Administrar promesa muestran el mismo selector localizado y el Trabajador mantiene la opción seleccionada como parte del total de envío canónico.

Límite secreto importante:

• mantener shipping.usps.client_id en _config.yml
• mantenga el compañero USPS_CLIENT_SECRET en Secretos del trabajador o worker/.dev.vars
• no guardes el secreto en la configuración de Jekyll

La lista de destinos de pago ahora está intencionalmente separada de esas perillas. Mantenga los países de envío permitidos actualmente en _data/shipping_countries.yml en lugar de editar el código de ejecución del navegador.

Ejemplo:

shipping:
  origin_zip: "87120"
  origin_country: "US"
  fallback_flat_rate: 3.00
  free_shipping_default: false
  default_option: standard
  usps:
    enabled: true
    client_id: "your-usps-client-id"
    api_base: ""
    timeout_ms: 5000
    quote_cache_ttl_seconds: 600
    failure_cooldown_seconds: 300
    rate_limit_cooldown_seconds: 1800
  presets:
    poster:
      weight_oz: 5
      packaging_weight_oz: 3
      length_in: 18
      width_in: 3
      height_in: 3
      stack_height_in: 0.5
    vinyl:
      weight_oz: 18
      packaging_weight_oz: 4
      length_in: 13
      width_in: 13
      height_in: 1

Qué permite esto:

• un origen de envío USPS a nivel de implementación
• un valor predeterminado de envío gratuito a nivel de implementación que las campañas aún pueden anular
• una tasa de reserva configurada si la cotización del operador en vivo no está disponible
• una superficie de política de cotización de USPS orientada a la bifurcación para tiempos de espera, reutilización de cotizaciones de corta duración y tiempos de reutilización temporales después de fallas repetidas o limitación de tarifas
• una superficie de selección de opciones de entrega compartida en el carrito y Administrar compromiso sin abrir opciones arbitrarias de velocidad del transportista
• nombres shipping_preset reutilizables en niveles de campaña para que las bifurcaciones no necesiten repetir dimensiones comunes de merchandising
• sugerencias de perfil de USPS de nivel preestablecido opcionales para tipos de artículos que necesitan una forma de cotización nacional diferente
• pedido opcional de clases de correo nacional de nivel preestablecido para productos que califican para clases de USPS más económicas como Media Mail

Los metadatos preestablecidos y anulados pueden incluir:

• weight_oz
• packaging_weight_oz
• length_in
• width_in
• height_in
• stack_height_in
• manual_domestic_rate
• usps_domestic.processing_category
• usps_domestic.rate_indicator
• usps_domestic.destination_entry_facility_type
• usps_domestic.price_type
• usps_domestic.mail_classes

weight_oz es el peso del artículo. packaging_weight_oz es una asignación de embalaje única para esa línea de pedido, y stack_height_in permite apilar niveles físicos de varias cantidades de manera más realista que el simple height * qty.

El patrón más seguro es codificar deliberadamente un orden válido más barato por valor preestablecido en lugar de intentar inferir la elegibilidad “letra” o “plana” a partir de dimensiones sin procesar en tiempo de ejecución. El sitio actual ahora usa:

• sticker
  • manual_domestic_rate: FIRST_CLASS_FLAT
  • luego, un perfil USPS nacional de una sola pieza más económico si el envío ya no califica para pisos
• signed_script
  • manual_domestic_rate: FIRST_CLASS_FLAT
  • luego MEDIA_MAIL
  • luego USPS_GROUND_ADVANTAGE
  • luego PRIORITY_MAIL
• cd, dvd, bluray
  • MEDIA_MAIL
  • USPS_GROUND_ADVANTAGE
  • PRIORITY_MAIL

Si un producto no califica de manera confiable para una clase más barata, déjelo en la ruta de paquete predeterminada. También tenga en cuenta que la ruta actual de la API de precios de USPS no expone directamente la calificación plana o de carta de primera clase nacional, por lo que la lógica de “sobre grande” se implementa aquí como una tabla manual explícita (FIRST_CLASS_FLAT), no como una cotización API de USPS en vivo.

add_ons

Utilice add_ons para un catálogo global de productos o ventas adicionales a nivel de plataforma que no esté vinculado a support_items de una sola campaña.

La ruta de trabajo actual los trata como selecciones a nivel de paquete. Los manifiestos de pago pendientes también pueden almacenar una campaña ancla, de modo que los carritos de múltiples campañas sigan siendo compatibles mientras que los flujos posteriores de liquidación y administración siguen siendo compatibles con la campaña.

Claves admitidas hoy:

• enabled
• low_stock_threshold
• products

Actualmente, cada producto admite:

• id
• name
• description
• image_url
• price
• category
• inventory
• shipping_preset
• shipping
• source_url
• variant_option_name
• variants

Ejemplo:

add_ons:
  enabled: true
  low_stock_threshold: 5
  products:
    - id: dust-wave-tshirt
      name: "DUST WAVE T-Shirt"
      description: "Our official t-shirt. 100% cotton."
      price: 25.00
      category: physical
      shipping_preset: tshirt
      source_url: "https://shop.example.com/"
      variant_option_name: Size
      variants:
        - { id: xs, label: XS, inventory: 1 }
        - { id: s, label: S, inventory: 2 }
        - { id: m, label: M, inventory: 4 }

Esto está destinado a artículos de catálogo de precio fijo y variantes simples, como tallas de camisa. Es independiente de la campaña support_items, que sigue teniendo el alcance de la campaña y la cantidad.

En el panel de administración, los complementos de la plataforma se encuentran en la pestaña Complementos de nivel superior, mientras que los complementos con alcance de campaña se encuentran en la subpestaña Complementos de la campaña propietaria. Se conservan los ID heredados. Los nuevos ID de producto se derivan del nombre del producto y los nuevos ID de variante se derivan de la etiqueta de variante, por lo que los editores no necesitan escribir los valores slug a mano.

Comportamiento de envío de complementos:

• category: digital significa que el complemento nunca contribuye al envío.
• category: physical significa que el complemento participa en la misma calculadora de envío utilizada para los niveles físicos y los artículos de soporte físico.
• Los complementos físicos pueden:
  • hacer referencia a un shipping_preset compartido
  • o proporcione shipping.weight_oz, shipping.packaging_weight_oz, shipping.length_in, shipping.width_in, shipping.height_in y shipping.stack_height_in explícitos
• en el panel, esos campos explícitos de peso/dimensión aparecen solo para complementos físicos cuando el valor preestablecido de envío es none

Comportamiento actual del inventario de complementos:

• inventory puede vivir del producto en sí o de cada variante.
• low_stock_threshold controla cuándo la interfaz de usuario de administración/carro compartido muestra mensajes de escasez
• Las variantes agotadas se eliminan de la superficie compartida del estado del producto, a menos que el colaborador ya posea esa variante exacta en un compromiso existente.
• Los complementos vendidos guardados cuentan en vivo en add-on-inventory-sold:v1 después del inicio de la primera proyección, y las rutas de creación, modificación y cancelación del compromiso mantienen la proyección actualizada.
• Tanto el carrito como Manage Pledge utilizan el mismo modelo de tarjeta de producto adicional compartido, por lo que las bifurcaciones no necesitan diseñar ni configurar dos sistemas de merchandising diferentes.
• el encabezado de la sección complementaria y la nota de soporte se localizan a través de los archivos i18n de tiempo de ejecución normal, y la nota de soporte interpola automáticamente el nombre del autor del sitio configurado.

Las campañas también pueden definir complementos con alcance de campaña directamente en el frente de la campaña en campaign_add_ons.

Ese catálogo propiedad de la campaña utiliza la misma forma de producto que las entradas globales add_ons.products, pero se comporta de manera diferente en dos formas importantes:

• los complementos de la campaña se muestran en una sección separada Campaign Add-ons en el carrito y en Administrar compromiso
• Los complementos de la campaña cuentan para el subtotal de propiedad de la campaña/el progreso de financiación y siguen las reglas de envío de esa campaña.

Por el contrario, los add_ons.products globales siguen siendo productos de plataforma:

• se renderizan bajo la sección normal Add-ons
• no cuentan para los totales de financiación de la campaña
• Los complementos físicos globales se combinan en un cargo de envío/envío de plataforma independiente.

reports

Utilice reports para conocer el comportamiento de los informes de los ejecutores de campañas que deben mantenerse alineados con la programación de los trabajadores y la generación de informes del panel.

Claves admitidas hoy:

• campaign_runner.enabled
• campaign_runner.daily_pledge_report_enabled
• campaign_runner.fulfillment_report_enabled
• campaign_runner.send_hour
• campaign_runner.send_minute
• campaign_runner.include_stats_summary
• campaign_runner.include_csv_attachment
• campaign_runner.email_subject_prefix

Comportamiento actual:

• Los destinatarios a nivel de campaña viven en el frente de la campaña como runner_report_emails.
• Si el campo de la campaña falta o está vacío, no se envían correos electrónicos al responsable de la campaña para esa campaña.
• la ventana de envío se interpreta en platform.timezone para que el tiempo del informe permanezca alineado con el resto del modelo del ciclo de vida de la campaña.
• email_subject_prefix se puede configurar como una cadena vacía para desactivar el prefijo por completo
• cuando el prefijo se omite en tiempo de ejecución, el trabajador vuelve a [platform.name]
• Los temas de los informes son concisos y están orientados a la capacidad de entrega: sin emoji, etiquetas de informe cortas y un patrón consistente de prefijo + tipo de informe + título de campaña.
• Los correos electrónicos de promesas diarias utilizan un resumen exclusivo de la campaña con las promesas totales, las nuevas promesas en las 24 horas anteriores, el total de las promesas, el progreso de los objetivos y la cuenta regresiva/tiempo transcurrido de la fecha límite.
• Los envíos de cumplimiento se dividen por cumplimiento:
  • Los destinatarios del corredor de campaña reciben solo las filas completadas por la campaña.
  • platform.support_email recibe un correo electrónico de cumplimiento de plataforma por separado cuando existen filas de complementos de plataforma
• los resúmenes de cumplimiento son intencionalmente concisos y orientados al cumplimiento; no reutilizan el resumen del cuerpo del informe de compromiso diario
• Ambos tipos de informes pueden incluir una breve nota de orientación en el cuerpo para que los corredores reciban recordatorios de comunicación de cumplimiento o motivación específicos de la etapa de la campaña junto con el CSV.

Ejemplo:

reports:
  campaign_runner:
    enabled: true
    daily_pledge_report_enabled: true
    fulfillment_report_enabled: true
    send_hour: 7
    send_minute: 0
    include_stats_summary: true
    include_csv_attachment: true
    email_subject_prefix: "[My Fork]"

Qué permite esto:

• Correos electrónicos diarios del libro mayor de compromisos relacionados con la campaña durante las campañas en vivo.
• Exportaciones de cumplimiento únicas después de que pasa la fecha límite de la campaña.
• Separe los correos electrónicos de cumplimiento de la plataforma y del corredor de la campaña cuando sea necesario entregar tanto los elementos de la campaña como los de la plataforma.
• resúmenes del cuerpo opcionales y archivos adjuntos CSV opcionales sin cambiar los archivos de contenido de la campaña
• un prefijo de asunto consistente, que por defecto es "[The Pool]" en este repositorio y vuelve a [platform.name] si se omite en tiempo de ejecución

Ejemplo de destinatario por campaña:

runner_report_emails:
  - [email protected]
  - [email protected]

design

Utilice design para anulaciones seleccionadas del sistema de diseño que no requieren ediciones de Sass.

Estos valores se emiten en la hoja de estilo generada assets/main.css, que mantiene el puente de variables de diseño compatible con el estricto CSP del sitio. assets/theme-vars.css permanece como un artefacto de compatibilidad, pero los diseños públicos no lo solicitan por separado. Las bifurcaciones no necesitan editar Sass solo para cambiar los tokens admitidos.

Las mismas variables CSS generadas ahora también son el tema del sidecar Stripe Elements en el sitio, por lo que las anulaciones de tipografía/color/radio admitidas se llevan a cabo en la interfaz de usuario de pago personalizada sin agregar una capa de configuración separada solo para el pago.

Un subconjunto deliberadamente más pequeño de la misma superficie de marca se refleja en el Worker para que los correos electrónicos de los seguidores puedan reutilizar el logotipo configurado, las pilas de fuentes, el color principal, los colores de borde/superficie y el radio del botón.

Claves admitidas actualmente:

• tipografía:
  • font_body
  • font_display
• diseño:
  • layout_max_width
• radio:
  • radius_sm
  • radius_chip
  • radius_md
  • radius_lg
  • radius_xl
• texto:
  • color_text
  • color_text_strong
  • color_text_muted
  • color_text_soft
• superficies:
  • color_page_background
  • color_surface_base
  • color_surface_subtle
  • color_surface_soft
  • color_surface_strong
  • color_page_background_overlay
  • color_surface_base_overlay
  • color_surface_subtle_overlay
• fronteras:
  • color_border
  • color_border_strong
  • color_border_soft
• primario/énfasis:
  • color_primary
  • color_primary_soft
  • color_primary_border
  • color_primary_hover
  • color_primary_focus_ring
  • color_progress
• comentarios / tintes:
  • color_success
  • color_danger_soft
  • color_danger_softer
  • surface_tint_softer
  • surface_tint_soft
  • surface_tint_medium
  • surface_tint_hover
  • surface_tint_strong

Ejemplo:

design:
  font_body: '"Source Sans 3", sans-serif'
  font_display: '"Space Grotesk", sans-serif'
  layout_max_width: 1080px
  radius_md: 12px
  radius_xl: 18px
  color_text: "#1f2430"
  color_page_background: "#f6f3ee"
  color_surface_base: "#ffffff"
  color_border: "#d9d2c7"
  color_primary: "#111111"
  color_primary_hover: "#000000"
  color_progress: "#111111"

checkout

La sección checkout es intencionadamente estrecha.

Clave admitida hoy:

• stripe_publishable_key

El tiempo de ejecución del carrito propio y el flujo de pago personalizado en el sitio se tratan como un comportamiento integrado en la plataforma, no como cambios de modo orientados hacia la bifurcación.

cache

Utilice cache para ajustar el almacenamiento en caché público del navegador de lectura en vivo.

Teclas admitidas:

• live_stats_ttl_seconds
• live_inventory_ttl_seconds

performance

Utilice performance para controles de rendimiento de páginas públicas que una bifurcación puede necesitar ajustar sin cambios de código.

Teclas admitidas:

• intent_prefetch_enabled
• intent_prefetch_delay_ms
• intent_prefetch_limit

Estos controlan el tiempo de ejecución seguro de captación previa de documentos del mismo origen cargados en páginas públicas. El valor predeterminado está habilitado, con exclusiones conservadoras de rutas/consultas y un límite bajo por página. Las superficies de aplicaciones privadas, como administración, pago, gestión de compromiso y rutas de la comunidad de seguidores, no cargan el tiempo de ejecución de captación previa pública.

Los superadministradores pueden editar estos campos en el panel en Configuración -> Rendimiento avanzado. Los cambios publicados actualizan _config.yml, reflejan los valores de INTENT_PREFETCH_* orientados al trabajador y entran en vigor en las páginas estáticas después de la ruta normal de reconstrucción/implementación.

launch_reminders

Utilice launch_reminders para el formulario de recordatorio público único que se muestra en las próximas páginas de la campaña.

Teclas admitidas:

• enabled
• turnstile_site_key

Comportamiento actual:

• el formulario solo se muestra para campañas cuyo estado efectivo es upcoming
• la clave pública del sitio se puede borrar en _config.local.yml para ocultar el widget localmente
• el secreto correspondiente pertenece a los secretos del trabajador como TURNSTILE_SECRET_KEY o LAUNCH_REMINDER_TURNSTILE_SECRET_KEY
• La lógica de registro, cancelación de suscripción y envío de recordatorios reside en el trabajador y reutiliza el módulo de correo electrónico de reenvío existente.

Ejemplo:

launch_reminders:
  enabled: true
  turnstile_site_key: "0x..."

Configuraciones de solo sitio versus configuraciones reflejadas por trabajadores

Algunas configuraciones solo afectan la compilación de Jekyll y la interfaz de usuario propiedad del navegador. Otros también se reflejan automáticamente en el entorno del trabajador.

No reflejado por el script de sincronización

Estos se pueden cambiar en _config.yml sin agregar nuevas entradas de entorno de trabajador:

• i18n.*
• platform.version
• platform.release_label
• admin.production_site_url
• admin.production_worker_url
• shipping.presets
• add_ons.*
• Tema principal de la campaña, incluido campaign_add_ons, bloques de contenido, entradas del diario, niveles, elementos de apoyo, objetivos ambiciosos y decisiones.
• tokens de diseño/diseño que solo son consumidos por el CSS del sitio generado y no por los correos electrónicos de soporte

Estos valores siguen siendo importantes para el sitio generado y, en algunos casos, para las cargas útiles de API estáticas obtenidas por el trabajador. Simplemente scripts/sync-worker-config.rb no los escribe en worker/wrangler.toml.

Reflejado automáticamente al trabajador

Estos valores de configuración del sitio también se reflejan en los valores del entorno del trabajador en worker/wrangler.toml:

• title -> SITE_TITLE
• description -> SITE_DESCRIPTION
• author -> PLATFORM_AUTHOR
• platform.name -> PLATFORM_NAME
• platform.company_name -> PLATFORM_COMPANY_NAME
• platform.default_creator_name -> PLATFORM_DEFAULT_CREATOR_NAME
• platform.support_email -> SUPPORT_EMAIL
• platform.pledges_email_from -> PLEDGES_EMAIL_FROM
• platform.updates_email_from -> UPDATES_EMAIL_FROM
• platform.logo_path -> EMAIL_LOGO_PATH
• platform.footer_logo_path -> PLATFORM_FOOTER_LOGO_PATH
• platform.favicon_path -> PLATFORM_FAVICON_PATH
• platform.default_social_image_path -> PLATFORM_DEFAULT_SOCIAL_IMAGE_PATH
• platform.site_url -> SITE_BASE y CORS_ALLOWED_ORIGIN
• platform.worker_url -> WORKER_BASE
• seo.default_social_image_alt -> SEO_DEFAULT_SOCIAL_IMAGE_ALT
• seo.x_handle -> SEO_X_HANDLE
• seo.same_as -> SEO_SAME_AS
• seo.index_public_community_hub -> SEO_INDEX_PUBLIC_COMMUNITY_HUB
• admin.users -> ADMIN_USERS_JSON
• admin.local_test_campaigns -> ADMIN_TEST_CAMPAIGNS en el entorno de desarrollo
• checkout.stripe_publishable_key -> STRIPE_PUBLISHABLE_KEY
• design.font_body -> EMAIL_FONT_FAMILY
• design.font_display -> EMAIL_HEADING_FONT_FAMILY
• design.color_text -> EMAIL_COLOR_TEXT
• design.color_text_muted -> EMAIL_COLOR_MUTED
• design.color_surface_subtle -> EMAIL_COLOR_SURFACE
• design.color_border -> EMAIL_COLOR_BORDER
• design.color_primary -> EMAIL_COLOR_PRIMARY
• design.radius_lg -> EMAIL_BUTTON_RADIUS
• pricing.sales_tax_rate -> SALES_TAX_RATE
• tax.provider -> TAX_PROVIDER
• tax.origin_country -> TAX_ORIGIN_COUNTRY
• tax.use_regional_origin -> TAX_USE_REGIONAL_ORIGIN
• tax.nm_grt_api_base -> NM_GRT_API_BASE
• tax.zip_tax_api_base -> ZIP_TAX_API_BASE
• pricing.flat_shipping_rate -> FLAT_SHIPPING_RATE (solo compatibilidad con versiones anteriores; prefiera shipping.fallback_flat_rate)
• pricing.default_tip_percent -> DEFAULT_PLATFORM_TIP_PERCENT
• pricing.max_tip_percent -> MAX_PLATFORM_TIP_PERCENT
• shipping.origin_zip -> SHIPPING_ORIGIN_ZIP
• shipping.origin_country -> SHIPPING_ORIGIN_COUNTRY
• shipping.fallback_flat_rate -> SHIPPING_FALLBACK_FLAT_RATE
• shipping.free_shipping_default -> FREE_SHIPPING_DEFAULT
• shipping.default_option -> SHIPPING_DEFAULT_OPTION
• shipping.usps.enabled -> USPS_ENABLED
• shipping.usps.client_id -> USPS_CLIENT_ID
• shipping.usps.api_base -> USPS_API_BASE
• shipping.usps.timeout_ms -> USPS_TIMEOUT_MS
• shipping.usps.quote_cache_ttl_seconds -> USPS_QUOTE_CACHE_TTL_SECONDS
• shipping.usps.failure_cooldown_seconds -> USPS_FAILURE_COOLDOWN_SECONDS
• shipping.usps.rate_limit_cooldown_seconds -> USPS_RATE_LIMIT_COOLDOWN_SECONDS
• platform.timezone -> PLATFORM_TIMEZONE
• reports.campaign_runner.enabled -> CAMPAIGN_RUNNER_REPORTS_ENABLED
• reports.campaign_runner.daily_pledge_report_enabled -> CAMPAIGN_RUNNER_DAILY_PLEDGE_REPORT_ENABLED
• reports.campaign_runner.fulfillment_report_enabled -> CAMPAIGN_RUNNER_FULFILLMENT_REPORT_ENABLED
• reports.campaign_runner.send_hour -> CAMPAIGN_RUNNER_REPORT_HOUR
• reports.campaign_runner.send_minute -> CAMPAIGN_RUNNER_REPORT_MINUTE
• reports.campaign_runner.include_stats_summary -> CAMPAIGN_RUNNER_INCLUDE_STATS_SUMMARY
• reports.campaign_runner.include_csv_attachment -> CAMPAIGN_RUNNER_INCLUDE_CSV_ATTACHMENT
• reports.campaign_runner.email_subject_prefix -> CAMPAIGN_RUNNER_EMAIL_SUBJECT_PREFIX
• launch_reminders.enabled -> LAUNCH_REMINDERS_ENABLED
• debug.console_logging_enabled -> DEBUG_CONSOLE_LOGGING_ENABLED
• debug.verbose_console_logging -> DEBUG_VERBOSE_CONSOLE_LOGGING
• performance.intent_prefetch_enabled -> INTENT_PREFETCH_ENABLED
• performance.intent_prefetch_delay_ms -> INTENT_PREFETCH_DELAY_MS
• performance.intent_prefetch_limit -> INTENT_PREFETCH_LIMIT
• cache.live_stats_ttl_seconds -> LIVE_STATS_CACHE_TTL_SECONDS
• cache.live_inventory_ttl_seconds -> LIVE_INVENTORY_CACHE_TTL_SECONDS

Los correos electrónicos del superadministrador de arranque local no se reflejan intencionalmente desde _config.yml. Ponlos en worker/.dev.vars ignorados como ADMIN_BOOTSTRAP_EMAILS; Semillas npm run secrets:dev que valoran de worker/.dev.vars.example cuando faltan.

El script de sincronización también escribe valores de URL derivados:

• la producción [vars] obtiene CANONICAL_SITE_BASE / CANONICAL_WORKER_BASE de la producción platform.site_url / platform.worker_url
• dev [env.dev.vars] obtiene SITE_BASE / WORKER_BASE local de _config.local.yml, mientras que CANONICAL_SITE_BASE / CANONICAL_WORKER_BASE permanecen fijados a los valores de producción de _config.yml

La pestaña Informes del panel del navegador ofrece vistas previas y descargas CSV de compromiso/cumplimiento para campañas a las que puede acceder el administrador. No envía correos electrónicos de informes y no escribe marcadores de “enviado”.

El repositorio mantiene esos valores alineados automáticamente a través de las rutas principales locales/de desarrollo/prueba. Después de cambiarlos, reinicie la pila local para que tanto el sitio como el trabajador recojan los nuevos valores:

./scripts/dev.sh --podman

Para mayor comodidad, el repositorio ahora incluye:

npm run sync:worker-config

Ese comando sincroniza los valores reflejados por el trabajador en worker/wrangler.toml de _config.yml y _config.local.yml.

No escribe secretos de trabajador, archivos multimedia ni resultados de optimización generados. Los secretos de USPS OAuth, las claves secretas de Stripe, las claves de reenvío, las claves ZIP.TAX, los secretos de Turnstile, los tokens de GitHub y las credenciales de implementación de Cloudflare aún pertenecen a los secretos de Worker, los secretos del repositorio de GitHub o los archivos env locales ignorados.

Los recordatorios de lanzamiento tienen una configuración pública y un límite secreto:

• _config.yml launch_reminders.enabled controla si las próximas páginas de la campaña muestran el formulario de recordatorio.
• _config.yml launch_reminders.turnstile_site_key es la clave pública del sitio Cloudflare Turnstile utilizada por ese formulario.
• _config.local.yml puede anular launch_reminders.turnstile_site_key con una cadena vacía para ocultar el widget en el desarrollo local, coincidiendo con la anulación del torniquete de inicio de sesión del administrador local.
• El secreto Turnstile correspondiente pertenece a los secretos de los trabajadores como TURNSTILE_SECRET_KEY o LAUNCH_REMINDER_TURNSTILE_SECRET_KEY.
• Los correos electrónicos de recordatorio utilizan el módulo de correo electrónico de trabajador respaldado por reenvío existente y el remitente platform.updates_email_from configurado.

Los medios cargados en el panel tampoco agregan una nueva configuración de script de sincronización. Carga archivos fuente de confirmación en los directorios de activos existentes; Las cargas de imágenes/vídeos solicitan el flujo de trabajo Optimizar medios del panel después de que la confirmación se realice correctamente. npm run media:optimize / npm run media:optimize:check, las variantes respaldadas por Podman para máquinas sin optimizadores nativos y el mismo flujo de trabajo manejan la compresión de imágenes, variantes WebP responsivas en 320w, 480w, 640w, 960w y 1600w, y derivados de WebM fuera del Worker.

La minificación de CSS/JS generada también está fuera de la ruta de guardado del trabajador y del panel. Las implementaciones de producción ejecutan npm run assets:minify solo después de que Jekyll escribe _site, por lo que las bifurcaciones deben mantener los recursos fuente legibles en assets/ y permitir que el paso de implementación del artefacto maneje la salida minimizada. La compresión de borde de Cloudflare debería permanecer habilitada, pero Cloudflare Auto Minify debería permanecer deshabilitada para evitar una segunda capa de reescritura.

Las principales rutas de validación local/de desarrollo ya llaman a esa sincronización automáticamente:

• ./scripts/dev.sh --podman
• ./scripts/dev.sh
• ./scripts/test-worker.sh
• ./scripts/test-checkout.sh
• cd worker && npm run dev
• cd worker && npm run deploy
• npm run test:premerge

Lo que todavía requiere código

La plataforma ahora admite una gran personalización sin código personalizado, pero aún no todo es configurable intencionalmente.

Todavía a nivel de código hoy:

• agregar nuevos proveedores de pago o modos de pago
• cambiar proveedores de inserción compatibles
• ampliar las listas permitidas de CSP para hosts externos arbitrarios
• cambiar el estilo de campo propiedad de Stripe más allá del puente de token de diseño admitido y la API de apariencia de Stripe
• introducir estructuras de diseño, plantillas de página o tipos de bloques de contenido completamente nuevos
• cambiar el comportamiento del alojamiento de fuentes/CSP más allá de las pilas de fuentes actualmente admitidas

Tenga en cuenta también:

• no todas las fichas de Sass están expuestas a propósito
• no todas las variables de entorno de trabajador pertenecen a _config.yml
• la superficie de soporte está curada para evitar regresiones de seguridad y mantenimiento
• el panel carga archivos de confirmación en los directorios de activos existentes y actualiza los campos de configuración/campaña; Las cargas de imágenes/videos solicitan la canalización de medios externos después de la confirmación, la publicación elimina los medios propiedad del panel de la misma campaña a los que ya no se hace referencia, y agregar una nueva categoría de carga o backend de almacenamiento sigue siendo un trabajo a nivel de código.

Flujo de trabajo seguro para horquillas

1. Prefiere el panel de administración para configuraciones/campañas/ediciones de complementos admitidas. Utilice ediciones directas de archivos al revisar los cambios generados, cambiar campos no admitidos o trabajar sin el trabajador.
2. Si edita archivos directamente, actualice _config.yml o el _campaigns/*.md correspondiente.
3. Ejecute npm run sync:worker-config si está editando configuraciones fuera de los puntos de entrada normales y desea actualizar worker/wrangler.toml inmediatamente.
4. Ejecutar:

npm run podman:doctor
./scripts/dev.sh --podman

1. Verificar:

• marca de encabezado/pie de página
• metaimagen / favicon
• respaldo del creador de campañas
• Las páginas sensibles a CSP aún se cargan sin infracciones de CSP de la consola
• totales del carrito/pago
• Estilo de interfaz de usuario de pago de franjas
• Gestionar compromiso
• correos electrónicos de seguidores
• Estado de publicación del panel de administración, estado de secretos de solo lectura y visibilidad de la campaña con alcance de función cuando se cambian los campos del panel

1. Ejecute las comprobaciones pertinentes:

npx vitest run tests/unit/config-boot.test.ts tests/unit/cart-provider.test.ts tests/unit/manage-page.test.ts tests/unit/worker-business-logic.test.ts
./scripts/podman-self-check.sh

Orientación para futuras incorporaciones

Al agregar nuevas perillas de personalización, prefiera este orden:

1. ponga el valor orientado al sitio en _config.yml
2. reflejarlo en el entorno del trabajador solo si el proceso de pago, los informes o los correos electrónicos lo necesitan
3. si necesita Worker env, actualice scripts/sync-worker-config.rb en TOP_LEVEL_ORDER, DEV_ENV_ORDER y build_mirror_values
4. documentarlo aquí
5. Mantenga la superficie soportada seleccionada en lugar de exponer cada detalle de implementación.

Esto mantiene la personalización flexible sin convertir la plataforma en un motor de temas inestable de forma libre.