{"id":46531237,"url":"https://github.com/workteam01/sistema_de_ventas_php","last_synced_at":"2026-05-23T21:01:13.239Z","repository":{"id":253178156,"uuid":"842718308","full_name":"WorkTeam01/Sistema_de_Ventas_PHP","owner":"WorkTeam01","description":"Sistema integral de Punto de Venta (POS) e Inventario en PHP 8.x con MySQL. MVC custom, PDO prepared statements, TCPDF, AdminLTE 3, control de roles, stack seguro. Documentación para colaboradores + skills IA. Código abierto MIT.","archived":false,"fork":false,"pushed_at":"2026-05-22T22:53:54.000Z","size":35622,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-23T00:27:11.815Z","etag":null,"topics":["adminlte","bootstrap","composer","csrf-protection","education","inventory","inventory-management","mvc","mysql","open-source","php","point-of-sale","pos","psr-4","sales","sistema-de-ventas","tcpdf"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WorkTeam01.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"2024-08-15T00:03:15.000Z","updated_at":"2026-05-22T22:53:58.000Z","dependencies_parsed_at":"2024-08-25T20:37:15.726Z","dependency_job_id":null,"html_url":"https://github.com/WorkTeam01/Sistema_de_Ventas_PHP","commit_stats":null,"previous_names":["workteam01/sistema_de_ventas_php"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/WorkTeam01/Sistema_de_Ventas_PHP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WorkTeam01%2FSistema_de_Ventas_PHP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WorkTeam01%2FSistema_de_Ventas_PHP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WorkTeam01%2FSistema_de_Ventas_PHP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WorkTeam01%2FSistema_de_Ventas_PHP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WorkTeam01","download_url":"https://codeload.github.com/WorkTeam01/Sistema_de_Ventas_PHP/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WorkTeam01%2FSistema_de_Ventas_PHP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33412082,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T18:09:33.147Z","status":"ssl_error","status_checked_at":"2026-05-23T18:09:31.380Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["adminlte","bootstrap","composer","csrf-protection","education","inventory","inventory-management","mvc","mysql","open-source","php","point-of-sale","pos","psr-4","sales","sistema-de-ventas","tcpdf"],"created_at":"2026-03-06T22:14:23.862Z","updated_at":"2026-05-23T21:01:13.228Z","avatar_url":"https://github.com/WorkTeam01.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Sistema de Ventas — PHP \u0026 MySQL\n\nSistema web de gestión de ventas con control de inventario, facturación en PDF, gestión de clientes/proveedores y\ncontrol de acceso por roles.\n\n![Versión](https://img.shields.io/badge/Versión-1.9.0-blue)\n![PHP](https://img.shields.io/badge/PHP-8.x-777BB4?logo=php\u0026logoColor=white)\n![MySQL](https://img.shields.io/badge/MySQL-5.7%2B-4479A1?logo=mysql\u0026logoColor=white)\n![AdminLTE](https://img.shields.io/badge/AdminLTE-3.2.0-3c8dbc)\n![Bootstrap](https://img.shields.io/badge/Bootstrap-4-7952B3?logo=bootstrap\u0026logoColor=white)\n![PHPUnit](https://img.shields.io/badge/PHPUnit-11.x-6C6EAA?logo=php\u0026logoColor=white)\n![Tests](https://github.com/WorkTeam01/Sistema_de_Ventas_PHP/actions/workflows/tests.yml/badge.svg)\n![Licencia](https://img.shields.io/badge/Licencia-MIT-green)\n\n\u003c/div\u003e\n\n---\n\n## Seguridad y Buenas Prácticas Implementadas\n\nEste proyecto implementa una arquitectura MVC con PSR-4. Todos los módulos están completamente migrados. Mantiene los\nestándares de seguridad web modernos:\n\n- **Prevención de Inyecciones SQL**: 100% migrado a `PDO Prepared Statements` con _placeholders_ para parametrización.\n- **Protección CSRF**: Intercepción de suplantaciones cruzadas mediante _tokens_ obligatorios en la sesión y formularios\n  mutables.\n- **Escudos XSS**: Renderizado condicionado de entidades HTML (`htmlspecialchars()`) para neutralizar ejecución de\n  _scripts_ reflejados/almacenados.\n- **Integridad Transaccional**: Operaciones de control de inventario/ventas están bajo control transaccional estricto (\n  `PDO::beginTransaction()` / `commit` / `rollBack`), garantizando un stock 100% consistente ante fallas.\n- **Validaciones Back-End**: Todo envío por _POST_ recibe depuración estricta en el servidor para forzar cast a valores\n  numéricos, tipados seguros y sanitización antes del contacto con la BDD.\n- **Encriptado Seguro**: Uso de API moderna de Hashes de contraseñas de PHP (`PASSWORD_DEFAULT` / BCRYPT).\n- **Restablecimiento de Contraseña**: Flujo completo con tokens seguros (`bin2hex(random_bytes(32))`), expiración\n  de 1 hora, invalidación de un solo uso y envío por email vía PHPMailer + Gmail SMTP.\n- **\"Recordarme\"**: Cookie httponly/samesite=Strict con token SHA-256 almacenado en BD; rotación en cada\n  auto-login; lifetime configurable (`REMEMBER_LIFETIME`, default 14 días).\n- **Timeout de sesión**: Expiración por inactividad configurable (`SESSION_LIFETIME`, default 60 minutos).\n- **Rate Limiting en Login**: Bloqueo temporal de cuenta tras 5 intentos fallidos consecutivos (15 minutos). Estado\n  persistido en columnas `login_intentos` y `login_bloqueado_hasta` de `tb_usuarios`, sin tabla adicional. Al quedar\n  bloqueado, el sistema indica al usuario usar la opción \"¿Olvidaste tu contraseña?\".\n- **Optimizaciones de UI**: Control Sidebar de AdminLTE implementado de forma 100% nativa con un script dedicado,\n  integrando persistencia automatizada en `localStorage` y mecanismos Anti-FOUC para prevenir \"flashes\" blancos al\n  navegar con la temática oscura.\n\n---\n\n## Módulos\n\n| Módulo          | Descripción                                                                                           |\n| --------------- | ----------------------------------------------------------------------------------------------------- |\n| **Almacén**     | Gestión de productos con stock, precios, imágenes y categorías                                        |\n| **Ventas**      | POS wizard (Cliente → Carrito → Pago), creación inline de clientes, cálculo de totales y facturas PDF |\n| **Compras**     | Registro de compras a proveedores con actualización automática de stock                               |\n| **Clientes**    | Base de datos de clientes con historial de compras                                                    |\n| **Proveedores** | Gestión de proveedores y datos de contacto                                                            |\n| **Usuarios**    | Administración de cuentas con roles y permisos                                                        |\n| **Perfil**      | Perfil propio para todos los roles: editar datos y cambiar contraseña                                 |\n| **Auditoría**   | Registro de operaciones sensibles (eliminaciones, cambios de precio y rol) con vista de detalle       |\n\n---\n\n## Requisitos\n\n- PHP 8.x (extensiones: `pdo_mysql`, `gd`, `mbstring`, `json`)\n- MySQL 5.7+ / MariaDB 10.4+\n- Apache 2.4+ (incluido en XAMPP)\n\n---\n\n## Instalación\n\n### 1. Clonar el repositorio\n\nColocar el proyecto dentro del directorio `htdocs` de XAMPP:\n\n```bash\n# Linux\ngit clone \u003curl\u003e /opt/lampp/htdocs/Sistema_de_Ventas_PHP\n\n# Windows\ngit clone \u003curl\u003e C:\\xampp\\htdocs\\Sistema_de_Ventas_PHP\n\n# macOS\ngit clone \u003curl\u003e /Applications/XAMPP/htdocs/Sistema_de_Ventas_PHP\n```\n\n### 2. Instalar dependencias (Composer)\n\n```bash\ncomposer install\n```\n\n### 3. Crear e importar la base de datos\n\n**Linux / macOS:**\n\n```bash\nmysql -u root -p -e \"CREATE DATABASE sistemadeventas;\"\nmysql -u root -p sistemadeventas \u003c database/schema.sql\nmysql -u root -p sistemadeventas \u003c database/seeder.sql\n```\n\n**Windows** (desde `C:\\xampp\\mysql\\bin\\`):\n\n```bat\nmysql -u root -p -e \"CREATE DATABASE sistemadeventas;\"\nmysql -u root -p sistemadeventas \u003c C:\\xampp\\htdocs\\Sistema_de_Ventas_PHP\\database\\schema.sql\nmysql -u root -p sistemadeventas \u003c C:\\xampp\\htdocs\\Sistema_de_Ventas_PHP\\database\\seeder.sql\n```\n\n#### Credenciales por defecto\n\nEl seeder crea los siguientes usuarios de prueba:\n\n| Rol           | Email                 | Contraseña   |\n| ------------- | --------------------- | ------------ |\n| Administrador | admin@sistema.com     | admin123     |\n| Vendedor      | vendedor@sistema.com  | vendedor123  |\n| Comprador     | comprador@sistema.com | comprador123 |\n\n\u003e **Importante:** Cambiar estas contraseñas antes de usar en producción.\n\n### 4. Configurar la conexión\n\nCopiar el archivo de entorno de ejemplo y editarlo con tus credenciales:\n\n```bash\ncp .env.example .env\n```\n\nVariables mínimas en `.env`:\n\n```dotenv\nDB_HOST=localhost\nDB_NAME=sistemadeventas\nDB_USER=root\nDB_PASS=\nAPP_URL=http://localhost/Sistema_de_Ventas_PHP/public\nAPP_TIMEZONE=America/La_Paz\nAPP_DEBUG=false\nSESSION_LIFETIME=60\nREMEMBER_LIFETIME=14\n```\n\nPara habilitar el restablecimiento de contraseña por email, agregar también:\n\n```dotenv\nMAIL_HOST=smtp.gmail.com\nMAIL_PORT=587\nMAIL_USERNAME=tu_email@gmail.com\nMAIL_PASSWORD=xxxx_xxxx_xxxx_xxxx\nMAIL_ENCRYPTION=tls\nMAIL_FROM_ADDRESS=tu_email@gmail.com\nMAIL_FROM_NAME=\"Sistema de Ventas\"\n```\n\n\u003e `APP_URL` debe incluir `/public` — es la ruta al front controller.\n\u003e `MAIL_PASSWORD` debe ser una **Contraseña de Aplicación** de Google (no la contraseña de la cuenta).\n\n### 5. Configurar permisos (Linux / macOS)\n\n```bash\nchmod 755 public/uploads/products/\n```\n\n### 6. Iniciar el servidor\n\n**Linux:**\n\n```bash\nsudo /opt/lampp/lampp start\n```\n\n**Windows:** Abrir `xampp-control.exe` e iniciar Apache y MySQL.\n\n**macOS:**\n\n```bash\nsudo /Applications/XAMPP/xamppfiles/xampp start\n```\n\nAcceder en: `http://localhost/Sistema_de_Ventas_PHP/public/`\n\n---\n\n## Control de Acceso por Roles\n\nEl sistema cuenta con tres roles. Cada módulo restringe el acceso según el rol del usuario autenticado:\n\n| Rol             | Acceso                                        |\n| --------------- | --------------------------------------------- |\n| `Administrador` | Acceso completo a todos los módulos           |\n| `Vendedor`      | Ventas, clientes y consulta de inventario     |\n| `Comprador`     | Compras, proveedores y consulta de inventario |\n\n---\n\n## Stack Tecnológico\n\n**Backend:** PHP con PDO (prepared statements), TCPDF (`tecnickcom/tcpdf`) para generación de facturas PDF, PHPMailer (\n`phpmailer/phpmailer`) para envío de emails.\n\n**Frontend:** AdminLTE 3.2.0 sobre Bootstrap 4, jQuery, DataTables, SweetAlert2.\n\n**Base de datos:** MySQL con relaciones entre productos, ventas, compras, clientes y usuarios.\n\n**Testing:** PHPUnit 11.x — suite Unit (lógica pura, sin BD) y suite Integration (SQLite in-memory). CI con GitHub Actions en PHP 8.2 y 8.3. Ver [Testing en CLAUDE.md](CLAUDE.md#testing).\n\n---\n\n## Estructura del Proyecto\n\n```\nSistema_de_Ventas_PHP/\n├── app/\n│   ├── Controllers/        # Controladores MVC (Auth, Dashboard, User, Role, Category, Supplier, Client, Product, Purchase, Sale, ActivityLog)\n│   ├── Core/               # Núcleo MVC (Router, Controller, Model, Database, Auth, Config)\n│   ├── Helpers/            # Helpers PSR-4 (NumberToWords, InvoicePdf, PurchaseReportPdf, ActivityLogRenderer)\n│   ├── Middleware/         # Middlewares PSR-4 (AuthMiddleware, GuestMiddleware, AdminMiddleware, SellerMiddleware)\n│   ├── Models/             # Modelos de dominio (User, Role, Category, Supplier, Client, Product, Purchase, Sale, CartItem, ActivityLog)\n│   └── Services/           # Servicios PSR-4 (EmailService — PHPMailer SMTP)\n├── views/\n│   ├── layouts/            # Plantillas compartidas (header, footer, messages) + partials/_sidebar.php\n│   ├── errors/             # Páginas de error standalone (404, 403, 500)\n│   ├── auth/               # Vistas de autenticación (login, forgot-password, reset-password, show-reset-link)\n│   ├── dashboard/          # Vista del dashboard\n│   ├── users/              # Vistas CRUD del módulo users\n│   ├── roles/              # Módulo roles — patrón modal + AJAX (solo index.php)\n│   ├── categories/         # Módulo categories — patrón modal + AJAX (solo index.php)\n│   ├── suppliers/          # Vistas CRUD del módulo suppliers + partial/_modals.php\n│   ├── clients/            # Vistas CRUD del módulo clients\n│   ├── products/           # Vistas CRUD del módulo almacen (index, create, edit, show, delete)\n│   ├── purchases/          # Vistas CRUD del módulo compras (index, create, edit, show)\n│   ├── sales/              # Vistas del módulo ventas (index, create, show, delete, invoice vía TCPDF)\n│   └── activity-log/       # Módulo auditoría (index, show) + partial/_data-panel.php, _item-accordion.php\n├── routes/\n│   └── web.php             # Registro de rutas MVC\n├── public/\n│   ├── index.php           # Front controller (bootstrap: Dotenv, BASE_URL, BASE_PATH, $pdo)\n│   ├── css/\n│   │   ├── core/           # Utilitarios globales (ui-components.css)\n│   │   ├── modules/        # Estilos por módulo (auth/login.css, …)\n│   │   ├── lib/            # Vendors CSS (adminlte/, fontawesome/, bootstrap/)\n│   │   └── plugins/        # Plugins CSS (sweetalert2/, datatables/, select2/)\n│   ├── js/\n│   │   ├── core/           # Utilitarios globales (sweetalert-utils.js, control_sidebar.js)\n│   │   ├── modules/        # Scripts por módulo (auth/login.js, users/users-index.js, …)\n│   │   ├── lib/            # Vendors JS (jquery/, bootstrap/, adminlte/)\n│   │   └── plugins/        # Plugins JS (sweetalert2/)\n│   ├── uploads/products/   # Imágenes de productos (producto_default.png trackeado; resto ignorado)\n│   └── templates/          # AdminLTE fuente completa (no modificar)\n└── database/\n    ├── schema.sql          # Estructura de tablas\n    └── seeder.sql          # Datos iniciales\n```\n\n---\n\n## 📖 Documentación para Desarrolladores\n\n| Archivo                            | Propósito                                                   |\n| ---------------------------------- | ----------------------------------------------------------- |\n| [AGENT.md](AGENT.md)               | 🏗️ Arquitectura MVC, stack, convenciones, prohibiciones     |\n| [CLAUDE.md](CLAUDE.md)             | 🛠️ Instrucciones operacionales locales (XAMPP, BD, rutas)   |\n| [PROMPTS.md](PROMPTS.md)           | 📝 Plantillas de prompts efectivos para agentes IA          |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | 🤝 Guía para colaboradores — flujo de PRs, commits, testing |\n\n\u003e **Requisito:** Lee [AGENT.md](AGENT.md) antes de contribuir. Es la fuente de verdad del proyecto.\n\n---\n\n## 🤝 Contribuciones\n\n¿Te gustaría colaborar? ¡Excelente! Sigue estos pasos:\n\n1. **Lee primero** [CONTRIBUTING.md](CONTRIBUTING.md) — contiene todo lo necesario\n2. **Abre un issue** describiendo tu propuesta (feature, bug fix, docs)\n3. **Fork + Branch:** `git checkout -b feature/nombre-funcionalidad`\n4. **Código:** Sigue convenciones de [AGENT.md](AGENT.md)\n5. **Commit:** Usa formato convencional → `feat(scope): description`\n6. **Push + PR:** Abre pull request con descripción clara\n\n**Código de conducta:** Sé respetuoso. Esperamos comentarios constructivos en las PRs.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n## 📄 Licencia\n\nProyecto de código abierto distribuido bajo la **[Licencia MIT](LICENSE)**.\n\nEres libre de usar, modificar y distribuir este proyecto con fines educativos y comerciales.\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkteam01%2Fsistema_de_ventas_php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fworkteam01%2Fsistema_de_ventas_php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkteam01%2Fsistema_de_ventas_php/lists"}