diff --git a/workloads/docs-portal/docs/decisiones/0013-iniciativas-clientes.md b/workloads/docs-portal/docs/decisiones/0013-iniciativas-clientes.md new file mode 100644 index 0000000..3a0ca16 --- /dev/null +++ b/workloads/docs-portal/docs/decisiones/0013-iniciativas-clientes.md @@ -0,0 +1,122 @@ +# ADR 0013 — Iniciativas de clientes: Google Apps Script y AppSheet + +**Estado:** aceptada — **fase prioritaria**, precede la reanudación de +las Fases 2-4 del [ADR 0012](0012-practica-multicloud-gcp-azure.md). +Scaffold del repo en curso; primeras iniciativas reales se agregan +sesión a sesión, a medida que se comparten. +**Fecha:** 2026-09-21 + +## Contexto + +Iniciativas propias de la empresa (no del lab), trabajadas con **cuenta +personal de Google** — dos herramientas concretas: **Google Apps +Script** (código, automatizaciones) y **Google AppSheet** (apps +no-code sobre Sheets). Se abre como fase separada del ADR 0012 y con +prioridad sobre él por decisión explícita: retomar las Fases 2-4 del +lab (Terraform, Azure DevOps, GKE) espera a que esto avance primero. + +**Restricción dura, no negociable:** ningún repo ni documento de esta +iniciativa contiene credenciales, datos ni información real de +cliente. Apps Script versiona código (lógica), nunca datos. AppSheet +no tiene export de código — solo se documenta desde afuera (tablas, +columnas, expresiones, capturas), nunca se copian datos reales de +ninguna hoja de cálculo al repo. + +## Opciones consideradas + +### Apps Script: MCP vs. `clasp` + +| Opción | A favor | En contra | +|---|---|---| +| MCP para Apps Script | Interacción conversacional directa | **No existe un MCP oficial de Google.** Se verificó explícitamente buscando — solo hay servidores comunitarios (`mohalmah/google-appscript-mcp-server`, `whichguy/gas_mcp`, entre otros), ninguno publicado por Google. Se descartan sin evaluar más a fondo: no hay necesidad de agregar una dependencia comunitaria no verificada cuando existe una CLI oficial que cubre el caso de uso completo. | +| **`clasp`** (elegido) | CLI oficial de Google (`@google/clasp`), mantenida por el equipo de Apps Script, cubre push/pull/login/versiones/despliegues | Requiere login interactivo (OAuth) — mitigado: el login lo corre el dueño de la cuenta, nunca se comparte el código de autorización | + +### AppSheet: qué se puede versionar + +Se verificó contra la documentación oficial vigente (no se asumió): +**AppSheet no expone ningún mecanismo de export de la definición de la +app** (tablas virtuales, vistas, expresiones, automatizaciones) hacia +un formato versionable con git. La única superficie exportable es la +app en sí vía la consola de AppSheet, no un artefacto de código. Existe +un addon de terceros ("App Script Saver") pero es específico de Apps +Script, no de AppSheet, y no se evaluó como parte de esta decisión +(mismo criterio que con los MCP: no se instala nada de terceros sin +pasar primero por la verificación de publicador/permisos ya establecida +en el lab). + +**Decisión sobre AppSheet:** no se intenta versionar la app —se +documenta desde afuera. La documentación (markdown + capturas) es la +única fuente versionada; la app real en la consola de AppSheet sigue +siendo la fuente de verdad operativa, con el riesgo explícito de que +la documentación quede desactualizada (ver Consecuencias). + +## Decisión + +Repo privado nuevo `client-initiatives` en Gitea (separado de +`apps-registry`/`platform-infra`/`scripts`/`platform-multicloud` — ni +lab GitOps ni práctica multi-cloud, es su propia categoría). Estructura: +una carpeta por iniciativa bajo `apps-script/` (proyecto `clasp` +completo, con su propio `.clasp.json`) o `appsheet/` (documentación + +plantilla de estructura vacía). Mismo criterio de versionado semántico +y modularidad que ya usa `docs-portal`. + +**Flujo Apps Script:** rama `fix/*` → diff mostrado → `merge --no-ff` +a `main`. `clasp push` (subir el código a Google) es una confirmación +explícita **aparte**, nunca agrupada con el merge a git — son dos +sistemas de versionado distintos (git para el repo, Apps Script para +las versiones desplegadas) y no deben confundirse. + +**Gitleaks:** se agrega al pipeline del repo nuevo. Nota real +encontrada al planificar esto: Gitleaks hoy solo corre en +`apps-registry` (3 workflows) — `platform-infra` y `scripts` no tienen +Gitea Actions configurado en absoluto, no hay "los otros tres repos con +Gitleaks" como se asumió al principio. Se replica el step exacto que +ya usa `apps-registry` (Gitleaks v8.21.2, `--no-git --redact`, reporte +JSON) por ser el único precedente real en el lab. + +## Fases + +### Fase A — Google Apps Script + +1. Scaffold del repo `client-initiatives` (estructura, Gitleaks, + convenciones documentadas). +2. Login de `clasp` (`clasp login --no-localhost`) corrido por el + dueño de la cuenta — verificación posterior de que + `~/.clasprc.json` queda fuera de cualquier repo y con `chmod 600`. +3. Primeras iniciativas: pendientes de compartir, se agregan una por + una bajo `apps-script//` a medida que llegan. + +### Fase B — Google AppSheet + +1. Por cada app existente: documentar tablas, columnas y expresiones + en markdown, más capturas del estado actual, bajo + `appsheet//`. +2. Plantilla de estructura de datos vacía si aplica (schema, nunca + filas reales). +3. Limitación dejada explícita en cada README de iniciativa: sin diff + automático posible entre esta doc y la app real. + +## En pausa mientras esta fase esté activa + +Por decisión explícita del usuario, prioridad sobre lo ya documentado +en el ADR 0012 y el resto del lab: + +- **Swap de `tmux-host`** — no se corre en esta fase. +- **[Fase 4 del ADR 0012](0012-practica-multicloud-gcp-azure.md#fase-4-documentar-no-ejecutar-gke-real-con-spot-auto-apagado)** + (GKE real con Spot + auto-apagado) — sigue solo documentada. +- **Prueba del skill `frontend-design`** (pendiente desde la + instalación de plugins del 2026-09-20) — no se ejecuta. + +Tampoco se toca NPM, `cloudflared`, ni `lab-agent` durante esta fase. + +## Consecuencias + +- Se gana un espacio versionado y auditado (Gitleaks) para + automatizaciones reales de la empresa, sin mezclar nada con el lab + GitOps ni con la práctica multi-cloud. +- Se acepta como deuda consciente que la documentación de AppSheet + puede desincronizarse de la app real — no hay forma técnica de + evitarlo, solo disciplina de actualizarla. +- Revertir esta decisión implicaría: eliminar el repo + `client-initiatives` (las iniciativas seguirían existiendo en Google, + solo se perdería el historial versionado y la documentación externa). diff --git a/workloads/docs-portal/mkdocs.yml b/workloads/docs-portal/mkdocs.yml index ca494a0..57f2d76 100644 --- a/workloads/docs-portal/mkdocs.yml +++ b/workloads/docs-portal/mkdocs.yml @@ -101,6 +101,7 @@ nav: - "0010 · Pago y envío reales": decisiones/0010-pago-envio-reales-y-storefront.md - "0011 · Ambiente de Staging": decisiones/0011-ambiente-staging.md - "0012 · Práctica multi-cloud GCP/Azure": decisiones/0012-practica-multicloud-gcp-azure.md + - "0013 · Iniciativas de clientes": decisiones/0013-iniciativas-clientes.md - Plantilla ADR: decisiones/plantilla-adr.md - Playbooks: - Crashloop Medusa: playbooks/incidente-crashloop-medusa.md