# AGENTS.md ## Resumen para IA Plugin de pagos `Refácil Pay` para WooCommerce/WordPress. Implementa una pasarela personalizada, integración con checkout blocks y endpoints REST para callbacks de pagos y asociación de token. El flujo operativo principal es: instalación/registro de comercio -> creación de transacción -> webhook de estado -> actualización de orden. | Campo | Valor | |---|---| | Lenguaje | PHP | | Framework/Plataforma | WordPress + WooCommerce | | Testing | Sin suite automatizada en el repo | | Package manager | N/A (plugin PHP sin Composer/npm en esta raíz) | ### Scripts/comandos esenciales - `docker-compose up -d` - levanta WordPress + MySQL para entorno local. - `docker-compose down` - detiene y elimina contenedores locales. - `openspec init --tools "claude,cursor"` - reinstala estructura OpenSpec y comandos. - `/refacil:setup` - valida prerequisitos y configura entorno SDD-AI del repo. ### Reglas críticas condensadas **Siempre** - Mantener compatibilidad con WordPress/WooCommerce (hooks, REST, convenciones de `WC_Payment_Gateway`). - Preservar mapeo de estados de pago -> estado de orden WooCommerce. - Validar y sanear datos de entrada antes de persistir/actualizar en DB. - Probar manualmente flujo checkout + callback cuando se toque `class-gateway.php` o `includes/callback-refacil.php`. **Nunca** - Romper namespaces/rutas REST existentes (`/wp-json/api/payments/refacil`, `/wp-json/api/auth/refacil`). - Cambiar IDs/tables del plugin sin migración (`re_facil_*`). - Exponer secretos/tokens en logs o commits. - Introducir dependencias Node/TS como requisito central sin acordarlo. **Preguntar** - Si se desea cambiar ambiente default en `environment.php` (`ENV_PROD` actual). - Si se requiere migración de esquema para instalaciones activas. - Si se quiere agregar pipeline de tests automatizados (PHPUnit/WP test suite). - Si cambios de API impactan backend externo de Refácil Pay. ### Comandos `refacil:*` | Comando | Descripción | |---|---| | `/refacil:setup` | Instala OpenSpec y genera/actualiza AGENTS.md | | `/refacil:guide` | Guía interactiva para elegir flujo | | `/refacil:explore` | Explorar codebase sin cambios | | `/refacil:propose` | Crear propuesta de cambio | | `/refacil:apply` | Implementar tasks del cambio | | `/refacil:test` | Generar tests unitarios | | `/refacil:verify` | Validar implementación contra specs | | `/refacil:review` | Review con checklist de calidad | | `/refacil:archive` | Archivar cambio completado | | `/refacil:up-code` | Subir código y crear PR | | `/refacil:bug` | Flujo guiado de bugfix | | `/refacil:join ` | Unirse a sala de bus entre agentes | | `/refacil:say "..."` | Enviar anuncio a la sala | | `/refacil:ask @nombre "..." [--wait N]` | Pregunta dirigida a otro agente | | `/refacil:reply "..."` | Responder última pregunta dirigida | | `/refacil:attend` | Quedar en escucha activa | | `/refacil:inbox` | Ver mensajes nuevos del bus | Detalle ampliado debajo. Si hay anexos en `docs/agents-*.md`, leerlos solo cuando trabajes en esa area. --- ## Detalle del proyecto ### Arquitectura y flujo funcional - Archivo principal del plugin: `re-facil-gateway.php`. - Gateway WooCommerce: `class-gateway.php` (`Re_Facil_Gateway`). - Soporte Checkout Blocks: `class-block.php`. - REST callbacks/auth: - `includes/callback-refacil.php` (`WC_REST_Custom_Controller`) - `api/payments/refacil` (webhook estado pago) - `api/auth/refacil` (asociación token/store) - Persistencia y tablas custom: - `includes/event-log-refacil.php` crea/asegura tablas `re_facil_*`. - Config de ambientes/endpoints: `environment.php`. - Logging: `includes/logger.php` + `WC_Logger`. Flujo general: 1. Activación del plugin -> crea cron y tablas. 2. Comercio se registra y asocia token. 3. Cliente paga en checkout -> se crea transacción en API Refácil. 4. Webhook actualiza estado de orden. 5. Cron cada 10 minutos reconcilia órdenes pendientes. ### Stack y dependencias - Runtime: PHP sobre WordPress. - Integración de pagos: WooCommerce (`WC_Payment_Gateway`). - Infra local sugerida: Docker (`wordpress:latest`, `mysql:latest`) vía `docker-compose.yml`. - Sin gestor de dependencias de app en esta raíz (`composer.json`/`package.json` no presentes). ### Alias/rutas y convenciones - ID de gateway: `re_facil_gateway`. - Tablas esperadas: - `${wpdb->prefix}re_facil_event_logs` - `${wpdb->prefix}re_facil_payments` - `${wpdb->prefix}re_facil_webhook_consumption_logs` - `${wpdb->prefix}re_facil_store_id` - Endpoints REST: - `POST /wp-json/api/payments/refacil` - `POST /wp-json/api/auth/refacil` ### Base de datos El plugin maneja tablas propias para: - log transaccional/eventos, - relación orden <-> referencia/resource de pago, - trazabilidad de consumo de webhook, - storeId/token/userId del comercio. No hay migrador formal; la creación/ajuste se hace en código al cargar activación/constructor de tabla. ### Testing y validación No hay test suite automatizada en el repositorio. Validación recomendada mínima: - Activación del plugin sin errores. - Registro/token en admin WooCommerce. - Checkout exitoso y redirección. - Callback con firma válida y actualización de estado. - Reconciliación por cron en órdenes `pending`. ### Comandos de desarrollo (completos) - `docker-compose up -d` - `docker-compose down` - `openspec --version` - `openspec config list` - `openspec init --tools "claude,cursor"` ### Reglas ampliadas para agentes IA - Mantener retrocompatibilidad del flujo de negocio y hooks de WordPress. - Cambios en `environment.php` deben coordinarse con equipo (impacto directo en URLs productivas/testing). - Evitar refactors masivos en archivos críticos del checkout sin prueba manual end-to-end. - Si hay cambios de tablas o endpoints, documentar impacto y plan de migración. - Si falta contexto de otros repos, usar bus entre agentes (`refacil:*` de comunicación). ### Eficiencia de tokens (compact-guidance) `refacil-sdd-ai` mantiene en `AGENTS.md` un bloque `compact-guidance` para reducir consumo de contexto. Ese bloque se sincroniza automáticamente por el hook `check-update` en cada `SessionStart` (también en `init`/`update`). Si `AGENTS.md` aún no existe, la sincronización se omite sin error. No edites manualmente el contenido entre marcadores `compact-guidance`, porque se sobrescribe. ## Eficiencia de tokens Reglas para minimizar el consumo de contexto al trabajar en este repositorio. **Lectura de archivos** - Usa `Read` con `offset` y `limit` cuando conozcas la zona relevante del archivo. - No leas archivos de mas de 500 lineas completos; segmenta por rango. - Para descubrir estructura del repo: usa `Glob` en lugar de `ls -R` o `find`. - No releas el archivo completo si ya leiste el bloque relevante; continua desde ese contexto. - Antes de leer un archivo largo, ubica simbolos con busqueda y luego lee solo rangos candidatos. **Busqueda** - Usa `Grep` con `head_limit` en vez de dump crudo. - Cuando solo necesites ubicaciones, usa `output_mode: "files_with_matches"`. - Acota siempre con `glob` o `type` para no escanear de mas. **Git (via Bash)** - Historial: `git log --oneline -20` por defecto; amplia solo si es insuficiente. - Diffs: empieza con `git diff --stat`; pide el diff completo solo del archivo que vas a tocar. - Status: `git status -s` (short format). - Show: `git show --stat` antes del full. **Tests** - Reporta solo failures; no enumeres los passes en el output visible. - Si el runner tiene modo silencioso o summary (`jest --silent --reporters=summary`, `pytest -q`), usalo. - Si el runner es verboso por defecto, redirige: `2>&1 | tail -80`. **Logs y errores** - No pegues stack traces enteros; extrae solo el frame relevante con el mensaje. - Resume logs repetidos: "(N ocurrencias de )". - Para archivos de log: `tail -100` o filtra por nivel ERROR/WARN. **Build y lint** - `tsc`, `eslint`, `biome`: agrupa errores por archivo o por regla; no enumeres linea por linea. - Construccion exitosa: confirma con una sola linea, no pegues el output completo. - Si hay muchos errores similares: muestra un ejemplo y el conteo. **Docker y contenedores** - `docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Image}}"`. - `docker logs --tail 100` siempre; nunca logs completos. **Regla general** Cuando dudes entre verbosidad y concision, elige concision. El usuario puede pedir detalle bajo demanda.