{"id":31785584,"url":"https://github.com/cripterhack/epayco","last_synced_at":"2026-02-18T11:03:03.237Z","repository":{"id":317785717,"uuid":"1068804744","full_name":"CripterHack/epayco","owner":"CripterHack","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-03T15:09:12.000Z","size":188,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-10T12:00:13.745Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CripterHack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-02T23:56:10.000Z","updated_at":"2025-10-03T15:09:16.000Z","dependencies_parsed_at":"2025-10-03T03:38:35.541Z","dependency_job_id":"bd6bcf65-7234-4d98-80cd-e8a0a619faa4","html_url":"https://github.com/CripterHack/epayco","commit_stats":null,"previous_names":["cripterhack/epayco"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CripterHack/epayco","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CripterHack%2Fepayco","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CripterHack%2Fepayco/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CripterHack%2Fepayco/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CripterHack%2Fepayco/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CripterHack","download_url":"https://codeload.github.com/CripterHack/epayco/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CripterHack%2Fepayco/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29576866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T08:38:15.585Z","status":"ssl_error","status_checked_at":"2026-02-18T08:38:14.917Z","response_time":162,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-10T11:59:38.250Z","updated_at":"2026-02-18T11:03:03.228Z","avatar_url":"https://github.com/CripterHack.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EPayco Wallet Platform\r\n\r\nMonorepo pnpm que orquesta la billetera virtual de EPayco. Incluye un frontend Vue 3 accesible, una API pública (BFF) en NestJS, un servicio interno de dominio con acceso a MySQL y artefactos de infraestructura para desarrollo local.\r\n\r\n## Arquitectura\r\n\r\n```mermaid\r\ngraph TD\r\n    subgraph Frontend\r\n        A[Vue 3 SPA]\r\n    end\r\n\r\n    subgraph Public API\r\n        B[NestJS Wallet API]\r\n    end\r\n\r\n    subgraph Internal Services\r\n        C[NestJS Wallet DB Service]\r\n        D[(MySQL)]\r\n    end\r\n\r\n    subgraph Tooling\r\n        E[MailHog]\r\n        F[docker-compose]\r\n    end\r\n\r\n    A \u003c-- Axios + Pinia --\u003e B\r\n    B \u003c-- HTTP + API Key --\u003e C\r\n    C \u003c-- TypeORM --\u003e D\r\n    B -. Webhooks/Emails .-\u003e E\r\n    F --- A\r\n    F --- B\r\n    F --- C\r\n    F --- E\r\n```\r\n\r\n## Estructura de carpetas\r\n\r\n- `apps/frontend`: SPA Vue 3 + Vite con Pinia, i18n y formularios accesibles.\r\n- `services/wallet-api-service`: API pública (BFF) con Swagger, rate limiting y pruebas e2e.\r\n- `services/wallet-db-service`: servicio interno orientado a dominio, gestiona MySQL y correo.\r\n- `packages/shared`: contratos TypeScript compartidos entre servicios y frontend.\r\n- `infra`: definición de docker-compose y scripts auxiliares.\r\n- `services/wallet-api-service/postman`: colección y environment Postman listos para importar.\r\n\r\n## Requisitos\r\n\r\n- Node.js 20+\r\n- pnpm 8+\r\n- Docker + Docker Compose v2 (opcional pero recomendado)\r\n- PowerShell 7+ (Windows) o Bash compatible\r\n\r\n## Configuración de entorno\r\n\r\n1. `pnpm install` en la raíz del monorepo.\r\n2. Duplica cada `.env.example` y renómbralo como `.env` en la misma carpeta (`.env` raíz, `apps/frontend/.env`, `services/*/.env`).\r\n3. Ajusta las variables si cambias puertos o credenciales.\r\n\r\n### Variables principales\r\n\r\n| Archivo | Clave | Descripción |\r\n| --- | --- | --- |\r\n| `.env` | `INTERNAL_API_KEY` | API key compartida entre servicios NestJS (debe coincidir en ambos). |\r\n| `.env` | `MAILHOG_URL` | URL de MailHog para inspeccionar correos de tokens. |\r\n| `apps/frontend/.env` | `VITE_API_BASE_URL` | URL base del BFF (por defecto `http://localhost:3000/api`). |\r\n| `services/wallet-api-service/.env` | Ver `.env.example` | Configura puerto, prefijo, CORS y conexión al servicio interno. |\r\n| `services/wallet-db-service/.env` | Ver `.env.example` | Configura conexión MySQL y parámetros de correo/token. |\r\n\r\n## Inicio rápido con Docker Compose\r\n\r\nEstas instrucciones levantan toda la plataforma usando la infraestructura de `infra/docker-compose.yml`.\r\n\r\n```bash\r\npnpm install\r\ncp .env.example .env                             # repite en apps/frontend y services/*\r\npnpm --filter @epayco/infra docker:up            # mysql + mailhog + redes\r\npnpm --filter @epayco/wallet-db-service migration:run\r\npnpm --filter @epayco/wallet-db-service seed:run # datos demo opcionales\r\npnpm --filter @epayco/wallet-db-service start:dev\r\npnpm --filter @epayco/wallet-api-service start:dev\r\npnpm --filter @epayco/frontend dev\r\n```\r\n\r\n- Swagger: `http://localhost:3000/api/docs`\r\n- Frontend: `http://localhost:5173`\r\n- MailHog: `http://localhost:8025`\r\n\r\n## Configuración manual sin Docker\r\n\r\nSi prefieres usar servicios locales gestionados manualmente (como WampServer en Windows):\r\n\r\n### Prerrequisitos para Windows con WampServer\r\n\r\n1. **WampServer instalado y funcionando** con MySQL 8+ y phpMyAdmin\r\n2. **Configurar PATH de MySQL** (temporal para la sesión actual):\r\n   ```powershell\r\n   $env:PATH += \";c:\\wamp64\\bin\\mysql\\mysql9.1.0\\bin\"\r\n   ```\r\n   O agregar permanentemente `c:\\wamp64\\bin\\mysql\\mysql9.1.0\\bin` a las variables de entorno del sistema.\r\n\r\n### Configuración de la base de datos\r\n\r\n1. **Crear la base de datos y usuario** (usando MySQL CLI o phpMyAdmin):\r\n\r\n   **Opción A - MySQL CLI:**\r\n   ```bash\r\n   mysql -u root -p -e \"CREATE DATABASE wallet CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\"\r\n   ```\r\n\r\n   **Opción B - phpMyAdmin:**\r\n   - Accede a `http://localhost/phpmyadmin`\r\n   - Crea una nueva base de datos llamada `wallet`\r\n   - Configura charset: `utf8mb4` y collation: `utf8mb4_unicode_ci`\r\n\r\n   **Verificar usuario wallet** (el usuario debería existir desde configuraciones previas):\r\n   ```sql\r\n   CREATE USER 'wallet'@'%' IDENTIFIED BY 'wallet';\r\n   GRANT ALL PRIVILEGES ON wallet.* TO 'wallet'@'%';\r\n   FLUSH PRIVILEGES;\r\n   ```\r\n\r\n### Configuración de servicios\r\n\r\n2. **Actualizar configuración de servicios:**\r\n   - En `services/wallet-db-service/.env`:\r\n     - `DB_HOST=localhost`\r\n     - `DB_PORT=3306`\r\n     - `MAIL_HOST=localhost` (o tu servidor SMTP local)\r\n     - `MAIL_PORT=25` (o el puerto de tu servidor SMTP)\r\n\r\n### Ejecutar migraciones y seeds\r\n\r\n3. **Ejecutar migraciones y seeds:**\r\n\r\n   ```bash\r\n   pnpm --filter @epayco/wallet-db-service migration:run\r\n   pnpm --filter @epayco/wallet-db-service seed:run\r\n   ```\r\n\r\n### Iniciar servicios\r\n\r\n4. **Levantar los servicios en terminales separados:**\r\n\r\n   ```bash\r\n   pnpm --filter @epayco/wallet-db-service start:dev\r\n   pnpm --filter @epayco/wallet-api-service start:dev\r\n   pnpm --filter @epayco/frontend dev\r\n   ```\r\n\r\n### Configuración de correos (opcional)\r\n\r\n5. **Para pruebas con correos:**\r\n   - **Opción A:** Instala y ejecuta [MailHog](https://github.com/mailhog/MailHog/releases) y ajusta `MAIL_HOST=localhost`, `MAIL_PORT=1025`\r\n   - **Opción B:** Configura tu servidor SMTP local en las variables `MAIL_HOST`, `MAIL_PORT`, `MAIL_USER`, `MAIL_PASSWORD`\r\n   - **Nota:** El flujo de confirmación de pagos funciona sin configuración de correo, pero no podrás capturar los tokens de confirmación.\r\n\r\n### Verificación\r\n\r\nDespués de completar la configuración, verifica que todo funcione:\r\n- **Base de datos:** Revisa las tablas creadas en phpMyAdmin (`http://localhost/phpmyadmin`)\r\n- **API:** `http://localhost:3001/health` (wallet-db-service)\r\n- **Swagger:** `http://localhost:3000/api/docs` (wallet-api-service)\r\n- **Frontend:** `http://localhost:5173`\r\n\r\n## Colecciones Postman\r\n\r\nImporta los archivos en `services/wallet-api-service/postman/`:\r\n\r\n- `epayco-wallet-api.postman_collection.json`\r\n- `epayco-wallet-local.postman_environment.json`\r\n\r\nLa colección cubre registro, recarga, pagos (inicio/confirmación), balance y healthcheck.\r\n\r\n## Scripts\r\n\r\n- `pnpm dev`: ejecuta los scripts dev de todos los paquetes en paralelo para un flujo de desarrollo rapido.\r\n- `pnpm build`: compila todos los paquetes respetando las dependencias internas.\r\n- `pnpm lint`: ejecuta los linters configurados en cada paquete.\r\n- `pnpm test`: lanza la suite de pruebas de cada paquete.\r\n\r\n## Pruebas\r\n\r\n- Frontend: `pnpm --filter @epayco/frontend test`\r\n- API pública unit tests: `pnpm --filter @epayco/wallet-api-service test`\r\n- API pública e2e (Supertest): `pnpm --filter @epayco/wallet-api-service test:e2e`\r\n- Servicio interno: `pnpm --filter @epayco/wallet-db-service test`\r\n\r\n\u003e Nota: en entornos sin `node`, pnpm devolverá `node: not found`; instala Node.js y vuelve a ejecutar.\r\n\r\n## Convenciones\r\n\r\nConsulta `docs/contributing.md` para detalles completos.\r\n\r\n- **Commits:** sigue [Conventional Commits](https://www.conventionalcommits.org/) (ejemplo: `feat(api): add wallet e2e tests`).\r\n- **Changelog:** los cambios significativos se documentan en `CHANGELOG.md`.\r\n- **CI/CD:** todos los scripts respetan ESLint, Prettier y pruebas unitarias/e2e antes de desplegar.\r\n\r\n## Solución de problemas\r\n\r\n### Errores comunes con Docker Compose\r\n\r\n#### Error: `npm error EEXIST: file already exists /usr/local/bin/pnpm`\r\n\r\n**Síntoma:** Al ejecutar `pnpm --filter @epayco/infra docker:up`, el build falla con:\r\n```\r\nnpm error code EEXIST\r\nnpm error path /usr/local/bin/pnpm\r\nnpm error EEXIST: file already exists\r\n```\r\n\r\n**Causa:** Conflicto entre `corepack enable` y la instalación global de pnpm en la imagen base de Node.js.\r\n\r\n**Solución:** Ya está corregido en los Dockerfiles del proyecto. Si encuentras este error en versiones anteriores, agrega `--force` al comando de instalación de pnpm:\r\n```dockerfile\r\nRUN corepack enable \u0026\u0026 npm i -g pnpm@8.15.4 --force\r\n```\r\n\r\n#### Error: `Context transfer too large`\r\n\r\n**Síntoma:** El build de Docker es muy lento o falla por transferir demasiados archivos.\r\n\r\n**Solución:** \r\n1. Verifica que `.dockerignore` esté presente en cada servicio/app\r\n2. Asegúrate de que `node_modules` esté incluido en `.dockerignore`\r\n3. Ejecuta `docker system prune` para limpiar caché de Docker\r\n\r\n#### Error: `Port already in use`\r\n\r\n**Síntoma:** Los contenedores no pueden iniciarse porque los puertos están ocupados.\r\n\r\n**Solución:**\r\n1. Detén otros servicios que usen los mismos puertos (3000, 3001, 5173, 3306, 8025)\r\n2. O modifica los puertos en `infra/docker-compose.yml` y actualiza las variables de entorno correspondientes\r\n\r\n#### Error: `Database connection failed`\r\n\r\n**Síntoma:** Los servicios no pueden conectarse a MySQL.\r\n\r\n**Solución:**\r\n1. Verifica que el contenedor de MySQL esté ejecutándose: `docker ps`\r\n2. Espera unos segundos más para que MySQL termine de inicializarse\r\n3. Verifica las credenciales en los archivos `.env`\r\n4. Reinicia los contenedores: `docker compose down \u0026\u0026 docker compose up -d`\r\n\r\n#### Error: `vue-tsc` build failure\r\n\r\n**Síntoma:** El build del frontend falla con errores como \"Search string not found\" en `vue-tsc.js` durante `vue-tsc --noEmit \u0026\u0026 vite build`.\r\n\r\n**Causa:** Incompatibilidad entre versiones de `vue-tsc` y TypeScript. Versiones antiguas de `vue-tsc` (como 1.8.x) pueden tener problemas con TypeScript 5.4+.\r\n\r\n**Solución:**\r\n1. Actualiza `vue-tsc` a una versión compatible (2.0.29 o superior):\r\n   ```bash\r\n   # En el directorio apps/frontend\r\n   pnpm add -D vue-tsc@^2.0.29\r\n   ```\r\n2. Actualiza el lockfile:\r\n   ```bash\r\n   pnpm install\r\n   ```\r\n3. Limpia la caché de Docker y reconstruye:\r\n   ```bash\r\n   docker system prune -f\r\n   pnpm --filter @epayco/infra docker:up\r\n   ```\r\n\r\n### Comandos útiles para diagnóstico\r\n\r\n```bash\r\n# Ver logs de todos los contenedores\r\ndocker compose logs -f\r\n\r\n# Ver logs de un servicio específico\r\ndocker compose logs -f wallet-api-service\r\n\r\n# Verificar estado de contenedores\r\ndocker ps\r\n\r\n# Limpiar caché de Docker (si hay problemas de build)\r\ndocker system prune -a\r\n\r\n# Reconstruir contenedores desde cero\r\ndocker compose down\r\ndocker compose build --no-cache\r\ndocker compose up -d\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcripterhack%2Fepayco","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcripterhack%2Fepayco","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcripterhack%2Fepayco/lists"}