cobro_digital 1.8.0 → 1.9.0

data/docs/behavior/behavior.md

@@ -0,0 +1,84 @@
+# Comportamiento — cobro_digital
+
+> meta: artefacto · RFC-007 · generado arch-enrich · anclado a v1.9.0 · cobertura: 2 flujos documentados; ausencia ≠ inexistencia
+
+## 1. Resumen
+
+Dos flujos cubren el comportamiento de la gema: la **operación simple** (construir → `call` → `parse_response`) y el **batch meta** (agrupar N operaciones en una llamada). Ambos terminan en el mismo transporte `Client#call`.
+
+## Cobertura
+
+| flujo | estado |
+|---|---|
+| operación simple (cualquier subclase de `Operador`) | **documentado** |
+| batch `meta` | **documentado** |
+| selección de transporte SOAP vs HTTPS (interno a `Client`) | **documentado** (en flujo 1) |
+| manejo de error de transporte | parcial — propaga sin envolver (ver `docs/consumed §d`) |
+
+## 2. Flujos
+
+### 2.1 Operación simple
+
+El consumidor construye una operación con un método de clase, la ejecuta con `#call(id, sid)` y decodifica con `#parse_response`. `Client#call` mergea el bloque de comercio (con handshake) y despacha al transporte elegido.
+
+```mermaid
+sequenceDiagram
+    actor Consumer
+    participant Op as Operador subclase
+    participant Cli as Client
+    participant WS as WS CobroDigital
+
+    Consumer->>Op: Boleta.generar(...) construye
+    Consumer->>Op: call(id_comercio, sid)
+    Op->>Cli: Client.new(id, sid, http_method)
+    Op->>Cli: call(request)
+    Cli->>Cli: comercio.merge(request) agrega handshake MD5
+    alt client_to_use soap (default)
+        Cli->>WS: webservice_cobrodigital via savon
+    else client_to_use https
+        Cli->>WS: Net HTTP Post o Get
+    end
+    WS-->>Cli: respuesta cruda
+    Cli-->>Op: guarda en response
+    Consumer->>Op: parse_response
+    Op-->>Consumer: resultado, log, datos
+```
+
+**Contexto:** `parse_response` decodifica el JSON de `output`, evalúa `ejecucion_correcta == '1'` y aplana `datos`. No levanta excepción ante `resultado: false` (`lib/cobro_digital/operador.rb:22`).
+
+### 2.2 Batch meta
+
+`Meta.meta` toma una lista de operaciones ya construidas y las indexa en un único payload. Cada sub-operación conserva su `metodo_webservice`. Se ejecuta como una sola llamada POST.
+
+```mermaid
+sequenceDiagram
+    actor Consumer
+    participant Meta as Meta
+    participant Cli as Client
+    participant WS as WS CobroDigital
+
+    Consumer->>Meta: meta([op0, op1, ...]) construye
+    Meta->>Meta: render(objs) indexa 0 => op0.render, 1 => op1.render
+    Consumer->>Meta: call(id_comercio, sid)
+    Meta->>Cli: call(request) metodo_webservice meta
+    Cli->>WS: POST batch
+    WS-->>Cli: respuesta cruda
+    Cli-->>Meta: guarda en response
+    Consumer->>Meta: parse_response
+    Meta-->>Consumer: resultado, log, datos
+```
+
+**Contexto:** `Meta.transaction` es un helper que pre-arma una `Transaccion.consultar` con filtro tipo=ingreso por default (`lib/cobro_digital/meta.rb:42`).
+
+## 3. Inferencias
+
+| inferencia | confidence | a verificar |
+|---|---|---|
+| el batch `meta` se procesa server-side como unidad (atomicidad) | unknown | el código no lo expresa; preguntar a CobroDigital |
+| la selección GET vs POST por operación es exigida por el WS | inferred | cada constructor fija `http_method`; confirmar que el WS lo requiere así |
+
+## 4. Cobertura y fronteras
+
+- **Cobertura:** 2 flujos, los dos caminos de ejecución reales de la gema.
+- **No documentado:** el procesamiento interno del WS (caja negra del proveedor); el manejo de reintentos/timeout en degradación → `docs/consumed §c/§e`.
+- **Mermaid:** diagramas pasados por el checklist render-safe (sin `;`, sin `::` en mensajes, un solo `:` por mensaje, ids no reservados).

data/docs/config/configuracion.md

@@ -0,0 +1,86 @@
+# Configuración — cobro_digital
+
+> meta: artefacto · RFC-012 · generado arch-structure + arch-enrich · anclado a v1.9.0 · inventario base + §f cobertura 2/2
+
+## 1. Resumen
+
+Gema con configuración mínima: dos variables de entorno (`ENDPOINT_COBRODIGITAL` selecciona el endpoint del WS; `COBRODIGITAL_LOG_LEVEL` el nivel de log del cliente SOAP), más constantes de tuning fijas en código (`TIMEOUT`, cliente default, filtros de log). Las credenciales del comercio (`id_comercio`, `sid`) NO son configuración de entorno: se pasan por argumento en cada `#call`.
+
+## 2. §a Hecho verificable
+
+| métrica | valor |
+|---|---|
+| total vars (env) | 2 |
+| requeridas | 0 |
+| con default | 2 |
+| derivadas | 3 (`URI`, `WSDL` ← `ENDPOINT_COBRODIGITAL`; `LOG_LEVEL` ← `COBRODIGITAL_LOG_LEVEL`) |
+| secretas (env) | 0 |
+
+## 3. §b Inventario base
+
+| nombre | tipo | requerida | default | origen | consumidor (file:line) | secret? | categoría | failure-mode | side-effect | business reason |
+|---|---|---|---|---|---|---|---|---|---|---|
+| `ENDPOINT_COBRODIGITAL` | String (URL base) | no | `https://cobro.digital:14365` | env | `lib/cobro_digital.rb:21-22` | no | — | — | — | — |
+| `COBRODIGITAL_LOG_LEVEL` | Symbol (nivel de log) | no | `error` | env | `lib/cobro_digital.rb:30-31` | no | — | — | — | — |
+
+**Constantes de runtime (no env, fijas en código — `lib/cobro_digital.rb`):**
+
+| constante | valor | nota |
+|---|---|---|
+| `CobroDigital::TIMEOUT` | `300` | open/read timeout (s) para SOAP y HTTPS |
+| `CobroDigital::SOAP` | `'soap'` | cliente default si no se pasa `:con_client` |
+| `CobroDigital::URI` | `"#{endpoint}/ws3/"` | derivada — ver §d |
+| `CobroDigital::WSDL` | `"#{endpoint}/ws3/?wsdl"` | derivada — ver §d |
+| `CobroDigital::LOG_LEVEL` | `error` (default) | derivada de `COBRODIGITAL_LOG_LEVEL` (string vacío → `error`) |
+| `CobroDigital::DEBUG_LOG` | `false` (default) | `true` solo si `LOG_LEVEL == :debug`; gobierna `pretty_print_xml` |
+| `CobroDigital::LOG_FILTERS` | `[:parametros_de_entrada]` | nodo SOAP enmascarado (`***FILTERED***`) — protege sid + PII |
+
+**Credenciales (NO configuración de entorno — argumentos de invocación):**
+
+| dato | dónde entra | secret? |
+|---|---|---|
+| `id_comercio` | argumento de `Operador#call(id_comercio, sid, …)` / `Client.new(id_comercio:)` | no |
+| `sid` | argumento de `Operador#call(id_comercio, sid, …)` / `Client.new(sid:)` | **sí** |
+
+## 4. §d Derivaciones simples
+
+| var derivada | fórmula |
+|---|---|
+| `CobroDigital::URI` | `(ENV['ENDPOINT_COBRODIGITAL'] \|\| 'https://cobro.digital:14365') + '/ws3/'` |
+| `CobroDigital::WSDL` | `(ENV['ENDPOINT_COBRODIGITAL'] \|\| 'https://cobro.digital:14365') + '/ws3/?wsdl'` |
+| `CobroDigital::LOG_LEVEL` | `_l = ENV['COBRODIGITAL_LOG_LEVEL'].to_s; (_l.empty? ? 'error' : _l).to_sym` |
+
+> Todas se evalúan **una vez al cargar la gema** (`require`). Cambiar las env en runtime tras el `require` NO re-deriva las constantes.
+
+## 5. §c/§e/§i/§j (sembrados)
+
+- **§e Scheduling:** no aplica (gema sin scheduler).
+- **§i Inyecciones al host:** no aplica (no hay Railtie/Engine; la gema no muta el host).
+- **§j Inyección a gemas configuradas:** no aplica (no hay bloque `configure`; el `@with_handshake` configurable está comentado en `Client#initialize`).
+- Campos `categoría · failure-mode · side-effect · scope-override · business reason` de §b: `—` (los llena `arch-enrich`).
+
+## f. Enriquecimiento semántico
+
+> cobertura: 2/2 vars enriquecidas; ausencia ≠ "no aplica".
+
+### f.1 endpoint (`ENDPOINT_COBRODIGITAL`)
+
+| var | categoría | failure-mode | side-effect | scope-override | business-reason / definición |
+|---|---|---|---|---|---|
+| `ENDPOINT_COBRODIGITAL` | integration | `silent-default` @ require — si falta, usa producción (`https://cobro.digital:14365`) silenciosamente | `restart` (las constantes `URI`/`WSDL` se `freeze`an al cargar la gema) | `boot-only` | selecciona el entorno del WS de CobroDigital (sandbox vs producción). **Sin var ⇒ producción.** Un entorno de pruebas que olvide setearla pega contra el WS real → riesgo de crear pagadores/boletas reales. |
+
+### f.2 logging (`COBRODIGITAL_LOG_LEVEL`)
+
+| var | categoría | failure-mode | side-effect | scope-override | business-reason / definición |
+|---|---|---|---|---|---|
+| `COBRODIGITAL_LOG_LEVEL` | observability | `silent-default` @ require — sin var ⇒ `:error` (no loguea el body del request) | `restart` (constante evaluada al cargar la gema) | `boot-only` | controla la verbosidad del log de Savon. **Seguridad:** con `=debug` el XML formateado expone el `sid` + PII del pagador en claro → no habilitar en producción. El nodo `parametros_de_entrada` se enmascara vía `LOG_FILTERS` aun en debug, pero `pretty_print_xml` sigue exponiendo el body. |
+
+**Ramificadores:** ninguno (no condiciona otras vars).
+
+**Threading:** n/a (constantes evaluadas una vez al `require`).
+
+## 6. Cobertura y fronteras
+
+- **Cobertura:** total. Una sola env var; resto es tuning fijo en código.
+- **Heurística a verificar (humano):** `ENDPOINT_COBRODIGITAL` se infiere `requerida=no` por tener default literal embebido. Confirmar que apuntar a producción vs sandbox se hace solo cambiando esta var.
+- **Sin valor real comprometido:** el inventario no incluye literales de credenciales (las credenciales no son env vars).

data/docs/consumed/cobrodigital.md

@@ -0,0 +1,82 @@
+# Dependencias consumidas — cobro_digital → WS CobroDigital
+
+> meta: artefacto · RFC-018 · generado arch-structure + arch-enrich · anclado a v1.9.0 · cobertura estructural (§a/§b/§d) + §c/§e enriquecidos 2/2
+
+## 1. Resumen
+
+La gema **es** un adaptador: su única dependencia consumida es el Web Service v3 de CobroDigital (pasarela de pago externa). Toda la superficie pública de la gema termina en una llamada a un único método SOAP (`webservice_cobrodigital`) o a su equivalente HTTPS sobre `…/ws3/`.
+
+## 2. §a Identidad
+
+| campo | valor |
+|---|---|
+| proveedor/servicio | CobroDigital — WS v3 (pasarela de pago) |
+| sub-tipo | **externo** (no es repo del fleet) |
+| transporte | SOAP 1.x sobre HTTPS (default) · HTTP form POST/GET (alternativo) |
+| cliente nuestro | `CobroDigital::Client` (`lib/cobro_digital.rb`); SOAP vía `savon ~> 2.12.1`, HTTPS vía `Net::HTTP` |
+| endpoint | `https://cobro.digital:14365/ws3/` (default); override por `ENV['ENDPOINT_COBRODIGITAL']` |
+| WSDL | `…/ws3/?wsdl` |
+| auth | credenciales de comercio en cada request: `idComercio` + `sid` + `handshake` (MD5 de `Time.now.to_f`) — ver `Client#comercio` |
+| doc oficial | Manual de implementación entregado por CobroDigital (no versionado en el repo); <http://cobrodigital.com> |
+
+## 3. §b Operaciones consumidas
+
+Todas viajan como un único método SOAP `webservice_cobrodigital` cuyo `parametros_de_entrada` es el JSON de `comercio.merge(request)`. El campo `metodo_webservice` discrimina la operación real:
+
+| operación (`metodo_webservice`) | transporte | qué mandamos | constructor de la gema |
+|---|---|---|---|
+| `crear_pagador` | POST | `{ pagador: {…} }` | `Pagador.crear` |
+| `editar_pagador` | POST | `{ identificador, buscar, pagador }` | `Pagador.editar` |
+| `verificar_existencia_pagador` | GET | `{ identificador, buscar }` | `Pagador.verificar` |
+| `obtener_codigo_electronico` | GET | `{ identificador, buscar }` | `Pagador.codigo_electronico` |
+| `consultar_estructura_pagadores` | GET | `{}` | `Pagador.estructura_de_datos` |
+| `generar_boleta` | POST | `{ identificador, buscar, fechas_vencimiento[`%Y%m%d`], importes, concepto, plantilla }` | `Boleta.generar` |
+| `inhabilitar_boleta` | POST | `{ nro_boleta }` | `Boleta.inhabilitar` |
+| `obtener_codigo_de_barras` | GET | `{ nro_boleta }` | `Boleta.obtener_codigo_de_barras` |
+| `consultar_transacciones` | GET | `{ desde[`%Y%m%d`], hasta[`%Y%m%d`], filtros }` | `Transaccion.consultar` |
+| `consultar_actividad_micrositio` | GET | `{ identificador, buscar, desde, hasta }` | `Micrositio.consultar_actividad` |
+| `meta` | POST | `{ 0 => {metodo_webservice,…}, 1 => {…}, … }` (batch) | `Meta.meta` |
+
+**Respuesta (forma común):** el WS responde un sobre cuyo `output` es un JSON string. `Operador#parse_response` lo decodifica a:
+
+| clave | origen en el JSON del WS | tipo |
+|---|---|---|
+| `resultado` | `ejecucion_correcta == '1'` | Boolean |
+| `log` | `log` | Array\<String\> (mensajes / errores) |
+| `datos` | `datos` (opcional) | Array (aplanado; cada fila se intenta `JSON.parse`) |
+
+## 4. §d Errores del proveedor → mapeo nuestro
+
+| condición del proveedor | manejo en la gema | excepción nuestra |
+|---|---|---|
+| `ejecucion_correcta != '1'` | `parse_response` devuelve `resultado: false` + `log` con los mensajes; **no levanta excepción** | — (no se traduce a excepción; el consumidor inspecciona `resultado`/`log`) |
+| fallo de transporte SOAP (HTTP ≠ 200, SOAP Fault) | sin `rescue` en la gema → propaga | `Savon::SOAPFault` / `Savon::HTTPError` (de `savon`, sin envolver) |
+| fallo de transporte HTTPS | sin `rescue` en la gema → propaga | excepción de `Net::HTTP` (sin envolver) |
+| `output` no parseable como JSON | sin `rescue` en `parse_response` (el `rescue` interno solo cubre filas de `datos`) | `JSON::ParserError` (sin envolver) |
+
+> La gema **no define excepciones propias** ni mapea las del proveedor a un catálogo propio → por eso `docs/errors/` es `n/a` para este repo (ver Mapa de conocimiento en `AGENTS.md`).
+
+## 5. §c Semántica de retry/idempotencia
+
+| aspecto | estado | detalle |
+|---|---|---|
+| retry | **no implementado** | la gema no reintenta; `TIMEOUT = 300s` open/read (`lib/cobro_digital.rb:20`). Cualquier reintento es responsabilidad del consumidor. |
+| idempotencia de escrituras | **no garantizada por el WS** | `crear_pagador` es **no idempotente**: el WS no deduplica (README §Crear Pagador: "es posible dar de alta eternamente el mismo pagador"). Reintentar a ciegas un POST puede duplicar pagadores/boletas. |
+| seguridad del reintento | condicional | **lecturas** (GET: `verificar`, `consultar_*`, `obtener_*`) son seguras de reintentar. **escrituras** (POST: `crear/editar_pagador`, `generar/inhabilitar_boleta`, `meta`) NO — verificar estado antes de reintentar. |
+| rol del `handshake` | `unknown` | se regenera por request (`Client#comercio`); no se confirmó si el WS lo usa como clave de idempotencia/anti-replay → no asumir que dedup. Verificar con el manual de CobroDigital. |
+
+## 6. §e Degradación (qué pasa si CobroDigital cae)
+
+| escenario | comportamiento actual | decisión de negocio |
+|---|---|---|
+| WS no responde / timeout (300s) | la excepción de transporte (`Savon::*` / `Net::HTTP`) **propaga sin envolver** al consumidor | no hay fallback ni cola en la gema; el consumidor decide reintento/cola/degradación |
+| WS responde error de negocio (`ejecucion_correcta != '1'`) | `parse_response` devuelve `resultado: false` + `log`; **no excepción** | el consumidor debe inspeccionar `resultado` y actuar; un flujo que ignore `resultado` trata un fallo como éxito |
+| SLA del proveedor | `unknown` | no documentado en el repo; consultar contrato con CobroDigital |
+
+> **Sin fallback local:** la gema es un transporte fino. Toda resiliencia (retry con backoff, circuit-breaker, cola de outbox para escrituras) vive —o debería— en el host consumidor, no acá.
+
+## 7. Cobertura y fronteras
+
+- **Cobertura:** §a/§b/§d estructurales + §c/§e enriquecidos, anclados al código del cliente.
+- **Subset, no la API completa:** se documentan solo los 11 métodos que la gema expone vía constructores; el WS de CobroDigital puede ofrecer más.
+- **Fuera de alcance:** el wire-schema interno de cada payload del WS (campos opcionales, validaciones server-side) vive en el Manual de implementación de CobroDigital, no versionado acá.

data/docs/glossary/glossary.md

@@ -0,0 +1,101 @@
+# Glosario — cobro_digital
+
+> meta: artefacto · RFC-009 · generado arch-enrich · anclado a v1.9.0 · cobertura parcial (acreta por PR); ausencia ≠ inexistencia
+
+## 1. Resumen
+
+Lenguaje ubicuo del bounded context de la gema: los términos del dominio de cobranza de CobroDigital tal como los modela esta gema. Sin capa de datos propia (`docs/data/` = n/a), el `**Binding:**` apunta al símbolo público que materializa el concepto (`docs/interface/interface.md`), no a tabla/columna.
+
+## 2. Términos
+
+## comercio
+
+La entidad cliente de CobroDigital que usa el webservice. Se identifica en cada request con dos credenciales emitidas por CobroDigital al dar de alta: `id_comercio` (identificador público) y `sid` (secreto). No es un objeto del dominio de la gema — son argumentos de `#call` que viajan en el bloque de identificación.
+
+**Binding:** `CobroDigital::Client#id_comercio`, `CobroDigital::Client#sid`; bloque armado en `Client#comercio` (`lib/cobro_digital.rb:84`).
+
+## handshake
+
+Token anti-replay que acompaña la identificación del comercio en cada request: el MD5 de `Time.now.to_f`. Se regenera por llamada. El comentario `@with_handshake` (comentado en `Client#initialize`) sugiere que alguna vez fue opcional; hoy es siempre-on.
+
+**Binding:** `Client#comercio` → `Digest::MD5.hexdigest(Time.now.to_f.to_s)` (`lib/cobro_digital.rb:85`).
+
+## pagador
+
+El cliente final al que el comercio le factura (a quien se le cobra). Su forma (campos) la define cada comercio con CobroDigital — la gema no la valida ni la fija. El WS **no controla duplicados**: dar de alta el mismo pagador dos veces crea dos. El control de unicidad es del consumidor.
+
+**Binding:** `CobroDigital::Pagador` (`lib/cobro_digital/pagador.rb`).
+
+## identificador / buscar
+
+Par clave-valor para localizar un pagador en el WS: `identificador` es el nombre del campo identificador (ej. `'Su_identificador'`, `'id'`); `buscar` es el valor a matchear (ej. `1234`). Aparece en casi toda operación que opera sobre un pagador existente.
+
+**Binding:** argumentos de `Pagador.editar/verificar/codigo_electronico`, `Boleta.generar`, `Micrositio.consultar_actividad`.
+
+## boleta
+
+El documento de cobro que el comercio informa a CobroDigital para que ejecute el cobro por los medios de la pasarela. Lleva hasta 4 vencimientos (el 1º = fecha de emisión) y hasta 4 importes (el 1º = valor; el resto = recargos por vencimiento). Generarla devuelve un número de boleta.
+
+**Binding:** `CobroDigital::Boleta` (`lib/cobro_digital/boleta.rb`).
+
+## codigo electronico
+
+Código que habilita a los pagadores a pagar por PagosMisCuentas y LinkPagos. Solo se puede obtener **después** de generada la primera boleta del pagador.
+
+**Binding:** `Pagador.codigo_electronico` → WS `obtener_codigo_electronico` (`lib/cobro_digital/pagador.rb:34`).
+
+## codigo de barras
+
+String del código de barras de una boleta (uno por vencimiento/importe). Para renderizarlo a imagen se usa el código 128b (la gema no renderiza; sugiere `barby`).
+
+**Binding:** `Boleta.obtener_codigo_de_barras` → WS `obtener_codigo_de_barras`.
+
+## plantilla
+
+Modelo de estilo/formato de la boleta. Cada comercio la provee/acuerda con CobroDigital (ej. `'init_273'`). Argumento opcional de `Boleta.generar`.
+
+**Binding:** parámetro `plantilla` de `Boleta.generar` (`lib/cobro_digital/boleta.rb:9`).
+
+## transaccion
+
+Un movimiento de la cuenta del comercio en CobroDigital. Se consulta por rango de fechas con filtros. Tipos:
+
+- **ingreso** (`ingresos`): todo lo que incrementa el saldo de la cuenta; generalmente las cobranzas.
+- **egreso** (`egresos`): retiros del dinero depositado por los pagadores.
+- **tarjeta_credito**: cobranzas abonadas con tarjeta de crédito.
+- **debito_automatico**: débitos realizados por CBU.
+
+**Binding:** `CobroDigital::Transaccion` + constantes `FILTRO_TIPO_*` (`lib/cobro_digital/transaccion.rb`).
+
+## micrositio
+
+El sitio de pago que CobroDigital expone para un pagador. La gema consulta su **actividad** en un rango de fechas.
+
+**Binding:** `CobroDigital::Micrositio.consultar_actividad` → WS `consultar_actividad_micrositio`.
+
+## meta
+
+Operación batch: agrupa N operaciones (crear pagadores, generar/inhabilitar boletas, etc.) en una sola llamada al WS, indexadas `{ 0 => …, 1 => … }`. Cada sub-operación lleva su propio `metodo_webservice` y `handshake`.
+
+**Binding:** `CobroDigital::Meta.meta(objs)` → WS `meta` (`lib/cobro_digital/meta.rb:64`).
+
+## resultado / log / datos
+
+La tripleta de la respuesta parseada (`Operador#parse_response`): `resultado` (Boolean, éxito de la consulta), `log` (mensajes/errores del WS), `datos` (payload de la consulta, opcional). Es el contrato de salida que todo consumidor inspecciona.
+
+**Binding:** `Operador#parse_response` (`lib/cobro_digital/operador.rb:22`).
+
+## 3. Inferencias
+
+| término | inferencia | confidence | a verificar |
+|---|---|---|---|
+| handshake | propósito anti-replay/idempotencia | inferred | confirmar con manual de CobroDigital si el WS lo valida o lo ignora |
+| meta | el batch es transaccional (todo-o-nada) o best-effort | unknown | preguntar a CobroDigital — el código no lo expresa |
+| micrositio | "actividad" = pagos/visitas/intentos | inferred | precisar qué devuelve `datos` para esta consulta |
+
+## 4. Cobertura y fronteras
+
+- **Cobertura:** parcial declarada. Cubre los términos materializados en la superficie pública actual. Acreta por PR que toque el dominio.
+- **Sin binding tabular:** gema sin DB; los bindings apuntan a símbolos públicos (ISO 11179 admite materialización no-tabular cuando hay símbolo estable que *es* el concepto).
+- **Candidatos a glosario canónico (RFC-019):** `boleta`, `pagador`, `transaccion` probablemente aparecen en otros repos del fleet que integran cobranza → **flaggeados** como candidatos a entrada canónica. arch-enrich no la crea (es cross-repo); se propone la promoción.
+- **No documentado:** la semántica fina de los campos del payload del WS (los define el manual de CobroDigital, no versionado acá).

data/docs/interface/interface.md

@@ -0,0 +1,106 @@
+# Interfaz — cobro_digital
+
+> meta: artefacto · RFC-004 · generado arch-structure · anclado a v1.9.0 · cobertura total de `lib/**`
+
+## 1. Resumen
+
+API Ruby pública de la gema adaptadora del WS de CobroDigital. Superficie: el módulo `CobroDigital` con el transporte `Client`, la clase base `Operador` y cinco subclases-operación (`Pagador`, `Boleta`, `Transaccion`, `Micrositio`, `Meta`) que se construyen con métodos de clase y se ejecutan con `#call`.
+
+## 2. Símbolos públicos
+
+| símbolo | tipo | nota |
+|---|---|---|
+| `CobroDigital` | módulo | namespace raíz (`lib/cobro_digital.rb`) |
+| `CobroDigital::SOAP` | constante (`'soap'`) | cliente de transporte default |
+| `CobroDigital::HTTPS` | constante (`'https'`) | cliente de transporte alternativo |
+| `CobroDigital::CLIENTS` | constante (`[SOAP, HTTPS]`) | clientes soportados |
+| `CobroDigital::URI` | constante (String) | endpoint `…/ws3/`; derivada de `ENV['ENDPOINT_COBRODIGITAL']` |
+| `CobroDigital::WSDL` | constante (String) | endpoint `…/ws3/?wsdl`; derivada de `ENV['ENDPOINT_COBRODIGITAL']` |
+| `CobroDigital::TIMEOUT` | constante (`300`) | open/read timeout en segundos |
+| `CobroDigital::LOG_LEVEL` | constante (Symbol) | nivel de log del cliente SOAP; derivada de `ENV['COBRODIGITAL_LOG_LEVEL']` (default `:error`) |
+| `CobroDigital::DEBUG_LOG` | constante (Boolean) | `true` si `LOG_LEVEL == :debug`; gobierna `pretty_print_xml` |
+| `CobroDigital::LOG_FILTERS` | constante (`[:parametros_de_entrada]`) | nodo SOAP enmascarado en el log (protege sid + PII) |
+| `CobroDigital::Https` | módulo | namespace de métodos HTTP |
+| `CobroDigital::Https::POST` | constante (`'Post'`) | método HTTP POST |
+| `CobroDigital::Https::GET` | constante (`'Get'`) | método HTTP GET |
+| `CobroDigital::Client` | clase | transporte hacia el WS |
+| `CobroDigital::Client#id_comercio` | attr_accessor | credencial del comercio |
+| `CobroDigital::Client#sid` | attr_accessor | credencial del comercio (secreto) |
+| `CobroDigital::Client#client_to_use` | attr_accessor | `'soap'` \| `'https'` |
+| `CobroDigital::Client#http_method` | attr_accessor | `'Post'` \| `'Get'` (solo transporte HTTPS) |
+| `CobroDigital::Client#pagadores` | attr_accessor | acumulador (Array, inicializa `[]`) |
+| `CobroDigital::Client#boletas` | attr_accessor | acumulador (Array, inicializa `[]`) |
+| `CobroDigital::Client#transacciones` | attr_accessor | acumulador (Array, inicializa `[]`) |
+| `CobroDigital::Client#micrositios` | attr_accessor | acumulador (Array, inicializa `[]`) |
+| `CobroDigital::Client#requests` | attr_accessor | sin inicializar en `#initialize` |
+| `CobroDigital::Client#request_xml` | attr_accessor | XML del último request SOAP (`#soap_client`) |
+| `CobroDigital::Client#initialize(attrs={})` | método de instancia | `attrs`: `:id_comercio`, `:sid`, `:con_client`, `:http_method`; levanta `ArgumentError` si `client_to_use` ∉ `CLIENTS` |
+| `CobroDigital::Client#soap_client(params)` | método de instancia | arma y ejecuta el request Savon `:webservice_cobrodigital` |
+| `CobroDigital::Client#https_client(params)` | método de instancia | ejecuta vía `Net::HTTP` (`Post`/`Get`) |
+| `CobroDigital::Client#call(request)` | método de instancia | despacha a `#{client_to_use}_client` mergeando `#comercio` |
+| `CobroDigital::Client#comercio` | método de instancia | bloque de identificación `{idComercio, sid, handshake}` (handshake = MD5) |
+| `CobroDigital::Operador` | clase | clase base de las operaciones |
+| `CobroDigital::Operador#http_method` | attr_accessor | método HTTP del transporte |
+| `CobroDigital::Operador#webservice` | attr_accessor | nombre del método del WS |
+| `CobroDigital::Operador#render` | attr_accessor | payload de la operación (Hash) |
+| `CobroDigital::Operador#response` | attr_accessor | respuesta cruda tras `#call` |
+| `CobroDigital::Operador#client` | attr_accessor | `Client` instanciado en `#call` |
+| `CobroDigital::Operador#initialize(attrs={})` | método de instancia | `attrs`: `:http_method`, `:webservice`, `:render` |
+| `CobroDigital::Operador#request` | método de instancia | `{ metodo_webservice: webservice }.merge(render)` |
+| `CobroDigital::Operador#call(id_comercio, sid, opt={})` | método de instancia | instancia `Client` y ejecuta; guarda `#response` |
+| `CobroDigital::Operador#parse_response` | método de instancia | decodifica el JSON de salida → `{ resultado:, log:, datos: }` |
+| `CobroDigital::Pagador` | clase `< Operador` | operaciones sobre pagadores |
+| `CobroDigital::Pagador::CREAR_PAGADOR_WS` | constante (`'crear_pagador'`) | nombre del método WS |
+| `CobroDigital::Pagador::EDITAR_PAGADOR_WS` | constante (`'editar_pagador'`) | nombre del método WS |
+| `CobroDigital::Pagador::VERIFICAR_PAGADOR_WS` | constante (`'verificar_existencia_pagador'`) | nombre del método WS |
+| `CobroDigital::Pagador::OBTENER_CODIGO_ELECTRONICO_WS` | constante (`'obtener_codigo_electronico'`) | nombre del método WS |
+| `CobroDigital::Pagador::CONSULTAR_ESTRUCTURA_PAGADORES_WS` | constante (`'consultar_estructura_pagadores'`) | nombre del método WS |
+| `CobroDigital::Pagador.crear(pagador)` | método de clase (constructor) | POST; `render: { pagador: }` |
+| `CobroDigital::Pagador.editar(identificador, buscar, pagador)` | método de clase (constructor) | POST |
+| `CobroDigital::Pagador.verificar(identificador, buscar)` | método de clase (constructor) | GET |
+| `CobroDigital::Pagador.codigo_electronico(identificador, buscar)` | método de clase (constructor) | GET |
+| `CobroDigital::Pagador.estructura_de_datos` | método de clase (constructor) | GET; `render: {}` |
+| `CobroDigital::Boleta` | clase `< Operador` | operaciones sobre boletas |
+| `CobroDigital::Boleta::GENERAR_BOLETA_WS` | constante (`'generar_boleta'`) | nombre del método WS |
+| `CobroDigital::Boleta::INHABILITAR_BOLETA_WS` | constante (`'inhabilitar_boleta'`) | nombre del método WS |
+| `CobroDigital::Boleta::OBTENER_CODIGO_BARRA_WS` | constante (`'obtener_codigo_de_barras'`) | nombre del método WS |
+| `CobroDigital::Boleta.generar(identificador, buscar, fechas_vencimiento, importes, concepto, plantilla=nil)` | método de clase (constructor) | POST; `fechas_vencimiento` se formatean a `%Y%m%d` |
+| `CobroDigital::Boleta.inhabilitar(nro_boleta)` | método de clase (constructor) | POST |
+| `CobroDigital::Boleta.obtener_codigo_de_barras(nro_boleta)` | método de clase (constructor) | GET |
+| `CobroDigital::Transaccion` | clase `< Operador` | consulta de transacciones |
+| `CobroDigital::Transaccion::CONSULTAR_TRANSACCIONES_WS` | constante (`'consultar_transacciones'`) | nombre del método WS |
+| `CobroDigital::Transaccion::FILTRO_TIPO` | constante (`'tipo'`) | clave de filtro |
+| `CobroDigital::Transaccion::FILTRO_NOMBRE` | constante (`'nombre'`) | clave de filtro |
+| `CobroDigital::Transaccion::FILTRO_CONCEPTO` | constante (`'concepto'`) | clave de filtro |
+| `CobroDigital::Transaccion::FILTRO_NRO_BOLETA` | constante (`'nro_boleta'`) | clave de filtro |
+| `CobroDigital::Transaccion::FILTRO_IDENTIFICADOR` | constante (`'identificador'`) | clave de filtro |
+| `CobroDigital::Transaccion::FILTRO_TIPO_EGRESO` | constante (`'egresos'`) | valor de filtro tipo |
+| `CobroDigital::Transaccion::FILTRO_TIPO_INGRESO` | constante (`'ingresos'`) | valor de filtro tipo |
+| `CobroDigital::Transaccion::FILTRO_TIPO_TARJETA_CREDITO` | constante (`'tarjeta_credito'`) | valor de filtro tipo |
+| `CobroDigital::Transaccion::FILTRO_TIPO_DEBITO_AUTOMATICO` | constante (`'debito_automatico'`) | valor de filtro tipo |
+| `CobroDigital::Transaccion.render(desde, hasta, filtros={})` | método de clase | arma `{ desde, hasta, filtros }`; `desde`/`hasta` a `%Y%m%d` |
+| `CobroDigital::Transaccion.consultar(desde, hasta, filtros={})` | método de clase (constructor) | GET |
+| `CobroDigital::Micrositio` | clase `< Operador` | consulta de actividad de micrositio |
+| `CobroDigital::Micrositio::CONSULTAR_ACTIVIDAD_MICROSITIO_WS` | constante (`'consultar_actividad_micrositio'`) | nombre del método WS |
+| `CobroDigital::Micrositio.consultar_actividad(identificador, buscar, desde, hasta)` | método de clase (constructor) | GET; `desde`/`hasta` a `%Y%m%d` |
+| `CobroDigital::Meta` | clase `< Operador` | agrupa operaciones en una llamada batch al WS `meta` |
+| `CobroDigital::Meta::META_WS` | constante (`'meta'`) | nombre del método WS |
+| `CobroDigital::Meta.transaction(desde, hasta, filtros={})` | método de clase | helper que arma una `Transaccion.consultar` con filtro tipo=ingreso por default |
+| `CobroDigital::Meta.render(objs)` | método de clase | indexa N operaciones en `{ 0 => …, 1 => … }` |
+| `CobroDigital::Meta.meta(objs)` | método de clase (constructor) | POST; `render: render(objs)` |
+| `CobroDigital::VERSION` | constante (`'1.9.0'`) | versión de la gema (`lib/cobro_digital/version.rb`) |
+
+## 3. Inferencias
+
+| inferencia | confidence | a verificar |
+|---|---|---|
+| `Client#requests` es atributo público pero no se inicializa ni se usa en el código leído | inferred | ¿atributo muerto o lo setea un consumidor externo? |
+| `Client#pagadores/boletas/transacciones/micrositios` se inicializan a `[]` pero no se leen ni escriben en `lib/**` | inferred | acumuladores planeados sin uso actual |
+| `Pagador.estructura_de_datos` y `Pagador::CONSULTAR_ESTRUCTURA_PAGADORES_WS` no figuran en el README | declared | superficie real, no documentada para el humano |
+| El comentario `@with_handshake` comentado en `Client#initialize` sugiere un handshake opcional descartado | inferred | confirmar que el handshake es siempre-on (hoy lo es vía `#comercio`) |
+
+## 4. Cobertura y fronteras
+
+- **Cobertura:** total sobre `lib/**` (8 archivos). Todos los símbolos top-level del namespace `CobroDigital` están listados.
+- **Fuera de alcance (otra capa):** el contrato del payload que cada operación envía al WS y la forma de la respuesta cruda → `docs/consumed/cobrodigital.md` (RFC-018). El significado de negocio de cada operación → `docs/glossary/` (RFC-009, `arch-enrich`).
+- **Sin dependencia de ActiveSupport (desde v1.9.0):** el código usa solo stdlib (`to_s.empty?` en `Client#initialize`, `Net::HTTP::Post/Get` en `Client#https_client`). La gema ya no asume Rails → ver `docs/topology/topology.md`.

data/docs/test/testing.md

@@ -0,0 +1,67 @@
+# Test — cobro_digital
+
+> meta: artefacto · RFC-013 · generado arch-structure + arch-enrich · anclado a v1.9.0 · inventario estructural (§a-§d) + §e-§h enriquecidos
+
+## 1. Resumen
+
+Suite RSpec (`spec/cobro_digital_spec.rb`) que cubre la versión, los constructores de las operaciones (`Pagador`/`Boleta`/`Transaccion`) y el parser `Operador#parse_response`. No cubre el transporte real (SOAP/HTTPS) — requiere doble del WS.
+
+## 2. §a Suites, frameworks y niveles
+
+| framework | versión | dónde |
+|---|---|---|
+| RSpec | `~> 3.13` (dev-dep en `cobro_digital.gemspec`) | `.rspec`, `spec/`, `Rakefile` (`RSpec::Core::RakeTask`) |
+
+| suite (archivo) | nivel | propósito | tags |
+|---|---|---|---|
+| `spec/cobro_digital_spec.rb` | unit | versión · constructores de operaciones (webservice/http_method/render/fechas) · `parse_response` (éxito y `resultado=false`) | — |
+
+## 3. §b Comando de corrida
+
+| contexto | comando |
+|---|---|
+| local | `bundle exec rspec` |
+| vía rake (default task) | `bundle exec rake` → `:spec` (`Rakefile`) |
+| CI | GitHub Actions `.github/workflows/main.yml` — `bundle exec rspec` sobre Ruby 2.7 en PRs y push a `master` |
+
+Config RSpec (`.rspec`): `--format documentation --color`.
+
+## 4. §c Fixtures / Factories
+
+Ninguna. No hay `spec/factories/`, `spec/fixtures/` ni FactoryBot. `spec/spec_helper.rb` solo agrega `lib` al `$LOAD_PATH` y requiere `cobro_digital`. El doble del sobre del WS para `parse_response` es un `Struct` anónimo vía `let` (sin constante leaky).
+
+## 5. §d Configuración de coverage
+
+Ninguna. No hay SimpleCov ni `.simplecov` ni umbral declarado.
+
+## 6. §e Gaps de cobertura
+
+| dominio / flujo | cubierto | nota |
+|---|---|---|
+| `CobroDigital::VERSION` presente | sí | — |
+| construcción de operaciones (`Pagador.crear/.verificar`, `Boleta.generar`, `Transaccion.consultar`) | **sí** | verifica `webservice`, `http_method`, `render`, `request` y formateo `%Y%m%d` |
+| `Operador#parse_response` | **sí** | respuesta exitosa (`resultado/log/datos`, rescue por fila) y `resultado=false` |
+| `Micrositio`/`Meta` | **no** | constructores sin test directo |
+| selección de transporte SOAP/HTTPS (`Client#call`, `soap_client`, `https_client`) | **no** | requiere doble de Savon/`Net::HTTP` |
+| guard de `client_to_use` inválido (`ArgumentError`) | **no** | agregado en v1.9.0, sin test aún |
+
+## 7. §f Contract-assessment
+
+| contrato público | test que lo cubre | estado |
+|---|---|---|
+| interfaz (`docs/interface/`) — constructores + `parse_response` | sí (parcial) | cubre la construcción y el parseo; falta el transporte |
+| dependencias consumidas (`docs/consumed/`) — payloads/parseo del WS | parcial | `parse_response` cubierto; el envío real (Savon) sin contract-test |
+| errores | n/a | la gema no define errores propios |
+
+## 8. §g Link a incidente
+
+`—`. No hay tests de regresión atados a incidentes.
+
+## 9. §h PII en fixtures/factories
+
+Sin fixtures ni factories → **sin PII en datos de prueba**. Los tests usan datos sintéticos triviales (`'Nombre' => 'Juan'`, `'id'`, números). Si a futuro se agregan factories de pagador, clasificar como **PII** (nombre/documento/e-mail/teléfono) — nunca versionar valores reales.
+
+## 10. Cobertura y fronteras
+
+- **Cobertura:** total sobre `spec/` (1 archivo) + §e-§h enriquecidos.
+- **Fuera de alcance:** el transporte real (SOAP vía Savon, HTTPS vía `Net::HTTP`) no se ejercita — necesita un doble del WS; candidato a contract-test.

data/docs/topology/topology.md

@@ -0,0 +1,42 @@
+# Topología — cobro_digital
+
+> meta: artefacto · RFC-006 · generado arch-structure · anclado a v1.9.0 · cobertura total de deps declaradas
+
+## 1. Resumen
+
+Gema-adaptador de un solo salto: el consumidor la usa para hablar con el WS externo de CobroDigital. Una dependencia de runtime (`savon`) para el transporte SOAP; el transporte HTTPS alternativo usa `Net::HTTP` de la stdlib. **No depende de ActiveSupport** (desde v1.9.0 usa solo stdlib).
+
+## 2. §a Dependencias
+
+| nombre | versión | rol |
+|---|---|---|
+| `savon` | `~> 2.12.1` | runtime — cliente SOAP hacia el WS (`Client#soap_client`) |
+| `net/http` · `uri` · `digest` · `json` | stdlib Ruby | runtime — transporte HTTPS, parseo de URI, handshake MD5, (de)serialización JSON (requeridos explícitamente en `lib/cobro_digital.rb`) |
+| `rake` | `>= 13.2.1` | desarrollo |
+| `rspec` | `~> 3.13` | desarrollo (suite) |
+
+> **Ruby:** `required_ruby_version = ['>= 2.7', '< 3.0']` — el stack `savon ~> 2.12.1` (httpi 2.x usa `URI.escape`, removido en Ruby 3.0) no corre en 3.0+. El único consumer (wispro_cloud) usa Ruby 2.7.6.
+
+## 3. §b Grafo
+
+```mermaid
+flowchart LR
+  Host["Host (consumidor)"] -->|usa la gema| Gem["cobro_digital"]
+  Gem -->|SOAP vía savon| WS["WS CobroDigital ws3"]
+  Gem -->|HTTPS vía Net HTTP stdlib| WS
+```
+
+## 4. §c Modos de ejecución / transporte
+
+| modo | cómo se elige | cliente |
+|---|---|---|
+| SOAP (default) | `client_to_use = 'soap'` si no se pasa `:con_client` | `savon` → `webservice_cobrodigital` |
+| HTTPS | `con_client: CobroDigital::HTTPS` | `Net::HTTP::Post`/`Net::HTTP::Get` directo |
+
+Un `con_client` que no esté en `CLIENTS` (`['soap','https']`) levanta `ArgumentError` en `Client#initialize`.
+
+## 5. Cobertura y fronteras
+
+- **Cobertura:** total sobre las deps declaradas en `cobro_digital.gemspec` + las de stdlib requeridas en `lib/**`.
+- **ActiveSupport eliminado (v1.9.0):** las únicas dos APIs de AS (`present?`, `constantize`) se reemplazaron por stdlib (`to_s.empty?`, `Net::HTTP::Post/Get`). La gema ya no asume Rails. (Los ejemplos del README que usan `Date#+`/`.days` son ilustrativos del host, no de la gema.)
+- **Sin `Gemfile.lock` versionado:** las versiones resueltas dependen del host; solo el pin del gemspec es contrato. La CI resuelve con `bundler-cache`.

data/lib/cobro_digital/version.rb

@@ -1,3 +1,3 @@
 module CobroDigital
-  VERSION = "1.8.0"
+  VERSION = "1.9.0"
 end