Whatsapp AndroidToIphone Copilot Rules — CoPilot Rules
    Neura Market
    Neura Market
    /CoPilot
    Marketplace
    Directories
    Resources
    CoPilot
    ChatGPTChatGPTClaudeClaudeGeminiGeminiCursorCursorGrokGrokPerplexityPerplexityDeepSeekDeepSeekCoPilotCoPilotStable DiffusionStable DiffusionMidjourneyMidjourney
    OverviewRulesPromptsMCPsAgentsGamesBlogVideosGuidesCoursesCommunityPluginsTrending
    CoPilotRulesWhatsapp AndroidToIphone Copilot Rules
    Back to Rules

    Whatsapp AndroidToIphone Copilot Rules

    handresc1127 April 16, 2026
    0 copies 0 downloads
    Rule Content
    <!-- .github/copilot-instructions.md -->
    # Contexto del Proyecto Green-POS
    
    ## 📋 Descripción General
    Green-POS es un Sistema de Punto de Venta completo desarrollado en Flask que incluye gestión de inventario, facturación, clientes y servicios de mascotas (grooming, veterinaria).
    
    ## 🤖 Sistema de Copilot Agents Especializados
    
    Este proyecto utiliza **tres agents ejecutables en Copilot Agent Mode** para desarrollo modular:
    
    ### Agents Disponibles (VS Code Insiders)
    
    - **🎨 @green-pos-frontend** (`.github/agents/green-pos-frontend.agent.md`)
      - Templates Jinja2, Bootstrap 5.3+, JavaScript Vanilla
      - Componentes UI, responsive design, validación cliente
      - **Subagents**: scaffold_page, table_datatable, accessibility_audit
    
    - **🐍 @green-pos-backend** (`.github/agents/green-pos-backend.agent.md`)
      - Rutas Flask, lógica de negocio, APIs JSON
      - Autenticación, validación servidor, transacciones
      - **Subagents**: generate_crud, add_validation, create_api
    
    - **🗄️ @green-pos-database** (`.github/agents/green-pos-database.agent.md`)
      - Modelos SQLAlchemy, relaciones, migraciones
      - Optimización queries, constraints, índices
      - **Subagents**: generate_model, create_migration, optimize_queries
    
    **Guías de uso**:
    - Completa: `.github/agents/README.md`
    - Referencia rápida: `.github/agents/QUICK_REFERENCE.md`
    
    **Documentación técnica** (para humanos):
    - Frontend: `.github/instructions/frontend-html-agent.instructions.md`
    - Backend: `.github/instructions/backend-python-agent.instructions.md`
    - Database: `.github/instructions/database-sqlite-agent.instructions.md`
    
    ### Cómo Invocar los Agents
    
    **Uso básico**:
    ```
    @green-pos-frontend crea templates/suppliers/list.html con DataTable
    @green-pos-backend implementa CRUD completo para Supplier
    @green-pos-database crea modelo Supplier con relación a Product
    ```
    
    **Con subagents**:
    ```
    @green-pos-frontend
    #runSubagent <subagent_scaffold_page> pathOut=templates/reports/sales.html pageTitle="Ventas"
    
    @green-pos-backend
    #runSubagent <subagent_generate_crud> entityName=Supplier routePrefix=suppliers
    
    @green-pos-database
    #runSubagent <subagent_generate_model> entityName=Category fields=[...]
    ```
    
    **Workflow multi-agent** (CRUD completo):
    ```bash
    # Paso 1: Crear modelo
    @green-pos-database crea modelo Supplier con campos code, name, phone, email
    
    # Paso 2: Crear rutas
    @green-pos-backend implementa CRUD para Supplier con validación
    
    # Paso 3: Crear vistas
    @green-pos-frontend crea templates/suppliers/list.html, form.html, view.html
    ```
    
    ## 🏗️ Stack Tecnológico Principal
    - **Backend**: Flask 3.0+ + SQLAlchemy + Flask-Login
    - **Frontend**: HTML5 + Bootstrap 5.3+ (sin jQuery) + Vanilla JavaScript
    - **Base de Datos**: SQLite (desarrollo) con soporte PostgreSQL/MySQL
    - **Servidor**: Waitress (Windows) / Gunicorn (Linux)
    - **Reportes**: ReportLab para PDFs (facturas, consentimientos)
    - **Zona Horaria**: America/Bogota (CO_TZ) - pytz
    - **Iconos**: Bootstrap Icons (`bi-*`)
    
    ## � Constraints Tecnológicos
    
    ### Limitaciones de SQLite
    **CRÍTICO - Restricciones de Producción:**
    
    1. **Concurrencia Limitada**:
       - SQLite NO soporta escrituras concurrentes
       - Un solo writer a la vez (readers múltiples permitidos)
       - Timeout configurado a 30 segundos para locks
       - **Solución**: Para alta concurrencia → PostgreSQL/MySQL
    
    2. **Transacciones Explícitas**:
       ```python
       # OBLIGATORIO: Siempre usar try-except con rollback
       try:
           db.session.add(entity)
           db.session.commit()
       except Exception as e:
           db.session.rollback()
           app.logger.error(f"Error: {e}")
           raise
       ```
    
    3. **Tipos de Datos**:
       - No tiene tipo DATE/TIME nativo (usa TEXT/INTEGER)
       - `DateTime` se almacena como TEXT ISO 8601
       - Boolean se almacena como INTEGER (0/1)
       - No tiene tipo DECIMAL (usa REAL o TEXT)
    
    4. **Tamaño de Base de Datos**:
       - Límite teórico: 140 TB
       - Límite práctico: 1-2 GB para rendimiento óptimo
       - Para más: migrar a PostgreSQL
    
    5. **Backups**:
       - NO tiene backup en caliente nativo
       - Requiere copiar archivo completo
       - Recomendado: Backup nocturno automatizado
    
    ### Restricciones de Codificación UTF-8
    
    **CRÍTICO - Servidor de Producción Windows:**
    
    1. **NO usar emojis en código Python**:
       - Servidor de producción tiene problemas con emojis (✅ ❌ 🔄 ⚠️ 📝 etc.)
       - Error relacionado con codificación UTF-8 al imprimir
       - Impacta: Scripts de migración, verificación, mensajes de consola
    
    2. **Alternativas permitidas**:
       ```python
       # ❌ INCORRECTO: Usar emojis
       print("✅ Migración exitosa")
       print("❌ Error en migración")
       print("🔄 Procesando...")
    
       # ✅ CORRECTO: Usar prefijos de texto
       print("[OK] Migracion exitosa")
       print("[ERROR] Error en migracion")
       print("[INFO] Procesando...")
    
       # Prefijos estándar:
       # [OK]      - Operación exitosa (verde)
       # [ERROR]   - Error crítico (rojo)
       # [WARNING] - Advertencia (amarillo)
       # [INFO]    - Información (cyan)
       # [DELETE]  - Operación de borrado
       ```
    
    3. **Caracteres acentuados**:
       - EVITAR acentos en mensajes de consola (ó, á, é, í, ú, ñ)
       - Usar versiones sin acento: (o, a, e, i, u, n)
       - OK en templates HTML y base de datos (soportan UTF-8)
    
    4. **Archivos afectados**:
       - Scripts de migración (`migrate_*.py`)
       - Scripts de verificación (`verify_*.py`)
       - Funciones de logging y print statements
       - Mensajes de error/éxito en consola
    
    ### Scripts de Migración (migrations/)
    
    **CRÍTICO - Patrón de Resolución de Paths:**
    
    1. **NUNCA usar rutas relativas simples**:
       ```python
       # ❌ INCORRECTO: Depende del CWD (Current Working Directory)
       open('archivo.sql')
       sqlite3.connect('instance/app.db')
       db_path = os.path.join('instance', 'app.db')
    
       # ✅ CORRECTO: Ruta relativa al script (funciona desde cualquier CWD)
       from pathlib import Path
    
       SCRIPT_DIR = Path(__file__).parent
       PROJECT_ROOT = SCRIPT_DIR.parent
    
       sql_file = SCRIPT_DIR / 'archivo.sql'
       db_path = PROJECT_ROOT / 'instance' / 'app.db'
       ```
    
    2. **Usar template estándar**:
       - Base: `migrations/TEMPLATE_MIGRATION.py`
       - Copiar template y personalizar para nueva migración
       - Incluye: Path resolution, backup automático, fallback SQL, verificación
       - Logging con prefijos [OK], [ERROR], [WARN], [INFO]
    
    3. **Verificar desde diferentes directorios**:
       ```powershell
       # SIEMPRE probar desde raíz del proyecto (caso común en producción)
       python migrations/migration_nombre.py
    
       # También probar desde directorio migrations/
       cd migrations && python migration_nombre.py
    
       # Verificar con ruta absoluta
       python D:\ruta\completa\migrations\migration_nombre.py
       ```
       **Resultado esperado**: Script funciona en todos los casos sin FileNotFoundError
    
    4. **Archivos afectados**:
       - Scripts de migración (`migrate_*.py`, `migration_*.py`)
       - Scripts de verificación (`verify_*.py`)
       - Scripts de consulta (`query_*.py`)
       - Cualquier script standalone en `migrations/`
    
    5. **Por qué es importante**:
       - Python resuelve `open('archivo')` relativo al CWD, NO a la ubicación del script
       - En producción, scripts se ejecutan desde raíz: `python migrations/script.py`
       - Sin `Path(__file__).parent`, script busca en raíz en lugar de `migrations/`
       - Resultado: `FileNotFoundError` aunque archivo exista
    
    6. **Ejemplo del problema**:
       ```
       Green-POS/                          <-- CWD al ejecutar: python migrations/script.py
       ├── migrations/
       │   ├── script.py                   <-- Script ejecutado
       │   └── archivo.sql                 <-- Archivo real AQUÍ
       └── archivo.sql                     <-- Python busca AQUÍ (no existe) ❌
       ```
    
    7. **Fix aplicado**:
       - Commit `2d412fc`: Fix en `migration_add_inventory_flag.py`
       - Investigación completa: `docs/research/2025-11-24-causa-raiz-filenotfounderror-migracion-produccion.md`
       - Documento dedicado: `docs/FIX_FILENOTFOUNDERROR_MIGRATION_PATHS.md`
    
    ### Restricciones de Flask
    
    1. **Single-threaded por defecto**:
       - Waitress usa 4 threads (configurado)
       - NO usar variables globales mutables
       - Thread-safety con `current_app`, `g`, `session`
    
    2. **Manejo de Archivos**:
       - Max upload size: Configurar en nginx/apache
       - Validar extensiones permitidas
       - Sanitizar nombres de archivo
    
    3. **Sesiones**:
       - Por defecto: Cookie-based (client-side)
       - Max 4KB de datos
       - Firmadas pero NO encriptadas
       - Sensibles: Usar Flask-Session con Redis
    
    ### Restricciones de Bootstrap 5
    
    1. **Sin jQuery**:
       - NO usar plugins jQuery legacy
       - Vanilla JS para interacciones
       - Bootstrap Bundle incluye Popper.js
    
    2. **Navegadores Soportados**:
       - Chrome, Firefox, Safari (últimas 2 versiones)
       - Edge Chromium
       - NO soporta IE11
    
    3. **Responsive Breakpoints**:
       ```scss
       // Obligatorio respetar estos breakpoints
       xs: <576px   (mobile)
       sm: ≥576px   (mobile landscape)
       md: ≥768px   (tablet)
       lg: ≥992px   (desktop)
       xl: ≥1200px  (large desktop)
       xxl: ≥1400px (extra large)
       ```
    
    ### Restricciones de Zona Horaria
    
    1. **Appointments (Citas)**:
       - `scheduled_at`: Timezone-naive (hora local)
       - NO convertir a UTC
       - Usuario programa → guarda → muestra (sin transformación)
    
    2. **Invoices (Facturas)**:
       - `date`: Timezone-aware (UTC storage)
       - Convertir a CO_TZ para display
       - Usar filtro `format_time_co`
    
    3. **Timestamps de Sistema**:
       - `created_at`, `updated_at`: UTC
       - Conversión automática en queries
       - `datetime.now(timezone.utc)` para consistency
    
    ### Restricciones de ReportLab (PDFs)
    
    1. **Fuentes**:
       - Usar fuentes built-in (Helvetica, Times, Courier)
       - Custom fonts requieren archivo .ttf
       - Unicode requiere configuración especial
    
    2. **Tamaño de Página**:
       - Facturas: Optimizado para 80mm térmicas
       - A4 para reportes estándar
       - Letter para US
    
    3. **Imágenes**:
       - PNG, JPEG soportados
       - GIF requiere conversión
       - Tamaño máximo: 10MB recomendado
    
    ## 🎯 Patrones de Diseño Implementados
    
    ### 1. Repository Pattern (Parcial)
    
    **Uso**: Acceso a datos centralizado
    
    ```python
    # Patrón usado en queries complejas
    class ProductRepository:
        @staticmethod
        def get_with_sales_count():
            """Obtiene productos con conteo de ventas."""
            return db.session.query(
                Product,
                func.count(InvoiceItem.id).label('sales_count')
            ).outerjoin(InvoiceItem).group_by(Product.id).all()
    
        @staticmethod
        def search(query_text, sort_by='name', sort_order='asc'):
            """Búsqueda con ordenamiento dinámico."""
            q = Product.query.filter(
                or_(
                    Product.name.ilike(f'%{query_text}%'),
                    Product.code.ilike(f'%{query_text}%')
                )
            )
            return q.order_by(getattr(Product, sort_by).desc()
                             if sort_order == 'desc'
                             else getattr(Product, sort_by).asc()).all()
    ```
    
    **Ventajas**:
    - Lógica de queries centralizada
    - Reutilización de código
    - Testing más fácil
    
    ### 2. Decorator Pattern
    
    **Uso**: Autorización y autenticación
    
    ```python
    from functools import wraps
    from flask_login import current_user
    from flask import flash, redirect, url_for
    
    def role_required(role):
        """Decorator para validar rol del usuario."""
        def decorator(f):
            @wraps(f)
            def decorated_function(*args, **kwargs):
                if not current_user.is_authenticated:
                    flash('Debe iniciar sesión', 'warning')
                    return redirect(url_for('login'))
    
                if current_user.role != role and current_user.role != 'admin':
                    flash('Acceso denegado', 'danger')
                    return redirect(url_for('index'))
    
                return f(*args, **kwargs)
            return decorated_function
        return decorator
    
    # Uso:
    @app.route('/products/new')
    @login_required
    @role_required('admin')
    def product_new():
        # Solo admin puede crear productos
        pass
    ```
    
    **Ventajas**:
    - Código declarativo
    - Reutilizable en todas las rutas
    - Separación de concerns
    
    ### 3. Factory Pattern
    
    **Uso**: Creación de usuarios por defecto
    
    ```python
    class User(db.Model):
        # ...
    
        @staticmethod
        def create_defaults():
            """Factory para crear usuarios iniciales."""
            existing = User.query.count()
            if existing == 0:
                users = [
                    ('admin', 'admin', 'admin'),
                    ('vendedor', 'vendedor', 'vendedor'),
                ]
                for username, password, role in users:
                    user = User(username=username, role=role)
                    user.set_password(password)
                    db.session.add(user)
                db.session.commit()
    ```
    
    ### 4. Observer Pattern (Implicit)
    
    **Uso**: Hooks de SQLAlchemy para audit logs
    
    ```python
    class ProductStockLog(db.Model):
        """Log de cambios - patrón Observer implícito."""
        # Al cambiar Product.stock, se crea automáticamente un log
    
    # Implementación en product_edit():
    @app.route('/products/edit/<int:id>', methods=['GET', 'POST'])
    def product_edit(id):
        product = Product.query.get_or_404(id)
    
        if request.method == 'POST':
            new_stock = int(request.form.get('stock', 0))
            old_stock = product.stock
    
            if new_stock != old_stock:
                # "Notificar" al observer creando log
                log = ProductStockLog(
                    product_id=product.id,
                    user_id=current_user.id,
                    quantity=abs(new_stock - old_stock),
                    movement_type='addition' if new_stock > old_stock else 'subtraction',
                    reason=request.form['stock_reason'],
                    previous_stock=old_stock,
                    new_stock=new_stock
                )
                db.session.add(log)
    ```
    
    **Ventajas**:
    - Trazabilidad automática
    - Auditoría completa
    - Desacoplado del modelo principal
    
    ### 5. Strategy Pattern
    
    **Uso**: Métodos de pago en facturas
    
    ```python
    class Invoice(db.Model):
        payment_method = db.Column(db.String(50), default='cash')
        # Valores: 'cash', 'transfer', 'card', 'mixed'
    
    # Estrategia de procesamiento según método
    def process_payment(invoice):
        strategies = {
            'cash': process_cash_payment,
            'transfer': process_transfer_payment,
            'card': process_card_payment,
            'mixed': process_mixed_payment
        }
    
        processor = strategies.get(invoice.payment_method)
        return processor(invoice) if processor else None
    ```
    
    ### 6. Template Method Pattern
    
    **Uso**: Rutas CRUD estándar
    
    ```python
    # Plantilla común para CRUD operations
    def crud_list(model_class, template, **filters):
        """Template method para listar entidades."""
        query = model_class.query
    
        # Hook: aplicar filtros
        for key, value in filters.items():
            if value:
                query = query.filter(getattr(model_class, key).ilike(f'%{value}%'))
    
        # Hook: ordenar
        items = query.order_by(model_class.created_at.desc()).all()
    
        # Hook: renderizar
        return render_template(template, items=items)
    
    # Especialización:
    @app.route('/products')
    def product_list():
        return crud_list(
            Product,
            'products/list.html',
            name=request.args.get('query')
        )
    ```
    
    ### 7. Builder Pattern
    
    **Uso**: Construcción de mensajes WhatsApp
    
    ```python
    class WhatsAppMessageBuilder:
        """Builder para crear mensajes WhatsApp estructurados."""
    
        def __init__(self):
            self.parts = []
    
        def add_greeting(self, name):
            self.parts.append(f"Hola {name}!")
            return self
    
        def add_business(self, business_name):
            self.parts.append(f"Te saludamos desde *{business_name}*")
            return self
    
        def add_appointment_info(self, pet_name, date, time):
            self.parts.append(
                f"Recuerda la cita con nuestra groomer para *{pet_name}*\n\n"
                f"Fecha: {date}\n"
                f"Hora: {time}"
            )
            return self
    
        def add_closing(self):
            self.parts.append("Gracias por preferirnos!")
            return self
    
        def build(self):
            return "%0A".join(self.parts)
    
    # Uso en template:
    {% set mensaje = WhatsAppMessageBuilder()
        .add_greeting(first_name)
        .add_business("Pet Verde")
        .add_appointment_info(pet_name, fecha, hora)
        .add_closing()
        .build() %}
    ```
    
    ### 8. Adapter Pattern
    
    **Uso**: Adaptador de zona horaria
    
    ```python
    class TimezoneAdapter:
        """Adapta datetime UTC a timezone local."""
    
        @staticmethod
        def to_local(utc_datetime, tz=CO_TZ):
            """Convierte UTC a timezone local."""
            if utc_datetime.tzinfo is None:
                utc_datetime = utc_datetime.replace(tzinfo=timezone.utc)
            return utc_datetime.astimezone(tz)
    
        @staticmethod
        def to_utc(local_datetime, tz=CO_TZ):
            """Convierte local a UTC."""
            if local_datetime.tzinfo is None:
                local_datetime = tz.localize(local_datetime)
            return local_datetime.astimezone(timezone.utc)
    
    # Filtro Jinja2:
    @app.template_filter('format_time_co')
    def format_time_co(dt):
        """Adapta y formatea datetime a hora Colombia."""
        if not dt:
            return ''
        local_dt = TimezoneAdapter.to_local(dt)
        return local_dt.strftime('%I:%M %p')
    ```
    
    ### 9. Composite Pattern
    
    **Uso**: Estructura jerárquica de servicios
    
    ```python
    class Appointment(db.Model):
        """Composite: Agrupa múltiples servicios."""
        services = db.relationship('PetService', backref='appointment',
                                  lazy='dynamic', cascade='all, delete-orphan')
    
        def recompute_total(self):
            """Calcula total recursivamente de todos los servicios."""
            self.total_price = sum(s.price or 0 for s in self.services)
            self.total_services = self.services.count()
    
    class PetService(db.Model):
        """Leaf: Servicio individual."""
        appointment_id = db.Column(db.Integer, db.ForeignKey('appointment.id'))
        service_type_id = db.Column(db.Integer, db.ForeignKey('service_type.id'))
        price = db.Column(db.Float, nullable=False)
    ```
    
    ### 10. State Pattern
    
    **Uso**: Estados de citas y facturas
    
    ```python
    class AppointmentState:
        """Estado de una cita con transiciones válidas."""
    
        PENDING = 'pending'
        DONE = 'done'
        CANCELLED = 'cancelled'
    
        TRANSITIONS = {
            PENDING: [DONE, CANCELLED],
            DONE: [],  # Estado final
            CANCELLED: []  # Estado final
        }
    
        @classmethod
        def can_transition(cls, from_state, to_state):
            """Valida si la transición es permitida."""
            return to_state in cls.TRANSITIONS.get(from_state, [])
    
    # Uso en ruta:
    @app.route('/appointments/<int:id>/cancel', methods=['POST'])
    def appointment_cancel(id):
        appointment = Appointment.query.get_or_404(id)
    
        if not AppointmentState.can_transition(appointment.status, 'cancelled'):
            flash('No se puede cancelar esta cita', 'error')
            return redirect(url_for('appointment_view', id=id))
    
        appointment.status = AppointmentState.CANCELLED
        db.session.commit()
        flash('Cita cancelada exitosamente', 'success')
        return redirect(url_for('appointment_list'))
    ```
    
    ### 11. Module Pattern (JavaScript)
    
    **Uso**: Encapsulación de funcionalidad frontend
    
    ```javascript
    // Pattern IIFE - Módulo de formulario de servicios
    window.ServiceForm = (function() {
        // Variables privadas
        let selectedServices = [];
        let totalPrice = 0;
    
        // Métodos privados
        function calculateTotal() {
            totalPrice = selectedServices.reduce((sum, s) => sum + s.price, 0);
            updateDisplay();
        }
    
        function updateDisplay() {
            document.getElementById('total').textContent =
                formatCurrency(totalPrice);
        }
    
        // API pública
        return {
            init: function() {
                bindEvents();
                loadSelectedServices();
            },
    
            addService: function(serviceId, price) {
                selectedServices.push({ id: serviceId, price: price });
                calculateTotal();
            },
    
            removeService: function(serviceId) {
                selectedServices = selectedServices.filter(s => s.id !== serviceId);
                calculateTotal();
            },
    
            getTotal: function() {
                return totalPrice;
            }
        };
    })();
    
    // Uso:
    ServiceForm.init();
    ServiceForm.addService(1, 50000);
    ```
    
    ## 🏛️ Arquitectura por Capas
    
    ```
    ┌─────────────────────────────────────────┐
    │         Presentation Layer              │
    │  (Templates Jinja2 + Bootstrap + JS)   │
    │  - layout.html                          │
    │  - list/form/view templates             │
    │  - Validación cliente                   │
    └────────────┬────────────────────────────┘
                 │
    ┌────────────▼────────────────────────────┐
    │         Application Layer               │
    │  (Flask Routes - app.py)                │
    │  - Autorización (@decorators)           │
    │  - Validación servidor                  │
    │  - Orquestación lógica de negocio       │
    │  - Flash messages                       │
    └────────────┬────────────────────────────┘
                 │
    ┌────────────▼────────────────────────────┐
    │         Business Logic Layer            │
    │  (Models + Methods)                     │
    │  - Reglas de negocio                    │
    │  - Cálculos (totales, stocks)           │
    │  - Validaciones complejas               │
    │  - State transitions                    │
    └────────────┬────────────────────────────┘
                 │
    ┌────────────▼────────────────────────────┐
    │         Data Access Layer               │
    │  (SQLAlchemy ORM)                       │
    │  - CRUD operations                      │
    │  - Queries complejas                    │
    │  - Transacciones                        │
    │  - Relationships                        │
    └────────────┬────────────────────────────┘
                 │
    ┌────────────▼────────────────────────────┐
    │         Database Layer                  │
    │  (SQLite / PostgreSQL)                  │
    │  - Persistencia                         │
    │  - Constraints                          │
    │  - Indexes                              │
    └─────────────────────────────────────────┘
    ```
    
    ## 🔄 Flujo de Datos
    
    ### Request Flow (Entrada)
    ```
    1. Usuario → HTTP Request
       ↓
    2. Flask App → Route Matching (@app.route)
       ↓
    3. Decorators → Autenticación/Autorización
       ↓
    4. Route Handler → Validación de datos
       ↓
    5. Business Logic → Procesamiento
       ↓
    6. ORM (SQLAlchemy) → Queries
       ↓
    7. Database → Persistencia
       ↓
    8. Response → Template Rendering
       ↓
    9. HTTP Response → Usuario
    ```
    
    ### Data Flow Example (Crear Cita)
    ```python
    # 1. Request
    POST /services/new
    {
        customer_id: 1,
        pet_id: 2,
        service_types: [1, 3],
        scheduled_at: '2025-10-22 14:30'
    }
    
    # 2. Route + Validation
    @app.route('/services/new', methods=['POST'])
    @login_required
    def service_new():
        # 3. Create Appointment (Business Logic)
        appointment = Appointment(
            customer_id=request.form['customer_id'],
            pet_id=request.form['pet_id'],
            scheduled_at=datetime.strptime(...)
        )
    
        # 4. Add Services (Composite Pattern)
        for service_type_id in request.form.getlist('service_types'):
            service = PetService(
                service_type_id=service_type_id,
                price=get_service_price(service_type_id)
            )
            appointment.services.append(service)
    
        # 5. Recompute Total (Business Logic)
        appointment.recompute_total()
    
        # 6. Persist (Data Layer)
        db.session.add(appointment)
        db.session.commit()
    
        # 7. Response
        flash('Cita creada exitosamente', 'success')
        return redirect(url_for('appointment_view', id=appointment.id))
    ```
    
    ## 📐 Principios SOLID Aplicados
    
    ### Single Responsibility Principle (SRP)
    ```python
    # ✅ CORRECTO: Cada clase una responsabilidad
    class User(db.Model):
        """Solo maneja datos de usuario."""
        username = db.Column(db.String(50))
    
        def set_password(self, password):
            """Responsabilidad: hash de contraseña."""
            self.password_hash = generate_password_hash(password)
    
    class UserRepository:
        """Solo maneja acceso a datos de usuario."""
        @staticmethod
        def find_by_username(username):
            return User.query.filter_by(username=username).first()
    
    class AuthService:
        """Solo maneja autenticación."""
        @staticmethod
        def authenticate(username, password):
            user = UserRepository.find_by_username(username)
            if user and user.check_password(password):
                login_user(user)
                return True
            return False
    ```
    
    ### Open/Closed Principle (OCP)
    ```python
    # ✅ CORRECTO: Abierto para extensión, cerrado para modificación
    class PaymentProcessor:
        """Base para procesadores de pago."""
        def process(self, invoice):
            raise NotImplementedError
    
    class CashPaymentProcessor(PaymentProcessor):
        def process(self, invoice):
            # Lógica específica para efectivo
            pass
    
    class TransferPaymentProcessor(PaymentProcessor):
        def process(self, invoice):
            # Lógica específica para transferencia
            pass
    
    # Agregar nuevos métodos sin modificar código existente
    class CardPaymentProcessor(PaymentProcessor):
        def process(self, invoice):
            # Nueva funcionalidad
            pass
    ```
    
    ### Liskov Substitution Principle (LSP)
    ```python
    # ✅ CORRECTO: Subclases intercambiables
    class Document(db.Model):
        """Documento base."""
        __abstract__ = True
        number = db.Column(db.String(30))
        date = db.Column(db.DateTime)
        total = db.Column(db.Float)
    
        def calculate_total(self):
            """Debe ser implementado por subclases."""
            raise NotImplementedError
    
    class Invoice(Document):
        """Factura - puede sustituir Document."""
        def calculate_total(self):
            self.total = self.subtotal + self.tax
    
    class Receipt(Document):
        """Recibo - puede sustituir Document."""
        def calculate_total(self):
            self.total = self.amount
    ```
    
    ### Interface Segregation Principle (ISP)
    ```python
    # ✅ CORRECTO: Interfaces específicas
    class Searchable:
        """Interface para entidades buscables."""
        def search(self, query):
            raise NotImplementedError
    
    class Sortable:
        """Interface para entidades ordenables."""
        def sort_by(self, field, order='asc'):
            raise NotImplementedError
    
    class Product(db.Model, Searchable, Sortable):
        """Implementa solo lo que necesita."""
        def search(self, query):
            return Product.query.filter(
                Product.name.ilike(f'%{query}%')
            ).all()
    
        def sort_by(self, field, order='asc'):
            return Product.query.order_by(
                getattr(Product, field).desc() if order == 'desc'
                else getattr(Product, field).asc()
            ).all()
    ```
    
    ### Dependency Inversion Principle (DIP)
    ```python
    # ✅ CORRECTO: Depender de abstracciones
    class Repository:
        """Abstracción de acceso a datos."""
        def get(self, id):
            raise NotImplementedError
    
        def save(self, entity):
            raise NotImplementedError
    
    class SQLAlchemyRepository(Repository):
        """Implementación concreta con SQLAlchemy."""
        def __init__(self, model):
            self.model = model
    
        def get(self, id):
            return self.model.query.get(id)
    
        def save(self, entity):
            db.session.add(entity)
            db.session.commit()
    
    # Service depende de abstracción, no de implementación
    class ProductService:
        def __init__(self, repository: Repository):
            self.repository = repository
    
        def get_product(self, id):
            return self.repository.get(id)
    ```
    
    ## 🔐 Seguridad y Best Practices
    
    ### 1. SQL Injection Prevention
    ```python
    # ✅ CORRECTO: Usar ORM parametrizado
    users = User.query.filter(User.username == username).all()
    
    # ✅ CORRECTO: Queries raw con parámetros
    db.session.execute(
        "SELECT * FROM users WHERE username = :username",
        {"username": username}
    )
    
    # ❌ INCORRECTO: Concatenación de strings
    db.session.execute(f"SELECT * FROM users WHERE username = '{username}'")
    ```
    
    ### 2. XSS Prevention
    ```html
    <!-- ✅ CORRECTO: Jinja2 escapa automáticamente -->
    <p>{{ user.name }}</p>
    
    <!-- ✅ CORRECTO: Usar |safe solo con contenido confiable -->
    <div>{{ content|safe }}</div>
    
    <!-- ❌ INCORRECTO: Insertar HTML no escapado -->
    <script>var data = {{ data }};</script>
    ```
    
    ### 3. CSRF Protection
    ```python
    # ✅ CORRECTO: Flask-WTF incluye token CSRF
    from flask_wtf.csrf import CSRFProtect
    
    csrf = CSRFProtect(app)
    
    # En templates:
    <form method="post">
        {{ csrf_token() }}
        <!-- campos -->
    </form>
    ```
    
    ### 4. Password Hashing
    ```python
    # ✅ CORRECTO: Usar werkzeug con salt automático
    from werkzeug.security import generate_password_hash, check_password_hash
    
    # Hash con salt automático (bcrypt-like)
    hash = generate_password_hash('password', method='pbkdf2:sha256')
    
    # ❌ INCORRECTO: Hash simple sin salt
    import hashlib
    hash = hashlib.sha256('password'.encode()).hexdigest()
    ```
    
    ### 5. Session Management
    ```python
    # ✅ CORRECTO: Configuración segura
    app.config['SESSION_COOKIE_SECURE'] = True  # Solo HTTPS
    app.config['SESSION_COOKIE_HTTPONLY'] = True  # No JS access
    app.config['SESSION_COOKIE_SAMESITE'] = 'Lax'  # CSRF protection
    app.config['PERMANENT_SESSION_LIFETIME'] = timedelta(hours=2)
    ```
    
    ## �📁 Estructura de Archivos Clave
    ```
    Green-POS/
    ├── app.py                      # Aplicación Flask principal (~2000 líneas)
    ├── models/
    │   └── models.py              # Modelos SQLAlchemy (User, Customer, Pet, Product, Invoice, Appointment, etc.)
    ├── templates/
    │   ├── layout.html            # Plantilla base con navbar y sidebar
    │   ├── appointments/          # Sistema de citas
    │   │   ├── list.html         # Lista agrupada por fecha
    │   │   ├── form.html         # Crear cita (tarjetas interactivas)
    │   │   ├── edit.html         # Editar cita (mismo diseño que form)
    │   │   └── view.html         # Detalle con impresión de consentimiento
    │   ├── customers/            # Gestión de clientes
    │   ├── invoices/             # Facturación
    │   │   └── list.html        # Agrupación por fecha con totales por método de pago
    │   ├── products/             # Inventario
    │   │   ├── stock_history.html  # Historial de movimientos
    │   │   └── form.html         # Con campo de razón para cambios de stock
    │   ├── services/             # Servicios (ahora citas)
    │   │   └── types/           # Tipos de servicio
    │   │       ├── config.html  # CRUD de tipos
    │   │       └── form.html    # Modal para crear/editar
    │   └── pets/                # Mascotas
    ├── static/
    │   ├── css/
    │   ├── js/
    │   │   └── main.js          # JavaScript principal
    │   └── uploads/
    │       └── logo.png         # Logo del negocio
    ├── instance/
    │   └── app.db               # Base de datos SQLite
    └── requirements.txt
    ```
    
    ## 🎯 Requisitos de Estilo de Código
    
    ### Python/Flask
    - **Type hints**: Obligatorios en funciones nuevas (Python 3.10+)
    - **PEP 8**: Seguir rigurosamente
    - **Docstrings**: Google style para funciones públicas
      ```python
      def appointment_update(id: int) -> Response:
          """Actualiza una cita existente con validación de cambios.
    
          Args:
              id: ID de la cita a actualizar
    
          Returns:
              Response: Redirect a vista de cita o formulario con errores
    
          Raises:
              404: Si la cita no existe
          """
      ```
    - **Zona horaria**: `datetime.now(CO_TZ)` para timestamps locales
    - **Validación**: Backend SIEMPRE + frontend para UX
    - **Transacciones**: `db.session` con rollback en excepciones
    - **Logging**: `app.logger.error()` para errores críticos solamente
    
    ### Filosofía de Desarrollo y Debugging
    **CRÍTICO - Ciclo de Desarrollo con Limpieza:**
    
    1. **Durante Desarrollo**:
       - Crear logs extensivos con marcadores
       - Comentarios de debug explícitos
       - Prints temporales marcados
       - Tests de validación inline
    
    2. **Durante Testing**:
       - Mantener elementos de debugging
       - Validar todas las rutas CRUD
       - Probar casos edge
    
    3. **Antes de Producción**:
       - **ELIMINAR** completamente código de debugging
       - Remover todos los `print()`, `console.log()` temporales
       - Eliminar comentarios `# TODO`, `# DEBUG`, `# TEMP`, `# FIXME`, `# TEST`
       - Limpiar logs no esenciales
       - Remover código comentado
       - Eliminar variables/imports no utilizados
    
    **Regla de Oro**: El código productivo debe estar limpio, sin rastros de debugging temporal
    
    **OBLIGATORIO - Marcado de Código Temporal:**
    ```python
    # DEBUG: imprimir valores para troubleshooting
    print(f"Debug: usuario = {user}")
    
    # TODO: optimizar esta query con joins
    debug_var = "temporal"  # TEMP: variable de prueba
    
    # FIXME: revisar lógica de validación de stock
    import pdb; pdb.set_trace()  # DEBUG: breakpoint temporal
    
    # TEST: función solo para pruebas unitarias
    def test_function():
        pass
    ```
    
    ```javascript
    // DEBUG: verificar valores del formulario
    console.log("Debug info:", data);
    
    // TODO: implementar validación real
    // TEMP: función de prueba para testing
    function debugFunction() { alert("Test"); }  // DEBUG
    
    // FIXME: corregir cálculo de total
    let debugTotal = 0;  // TEMP
    ```
    
    **Marcadores Estándar para Limpieza:**
    - `# DEBUG:` / `// DEBUG:` → Código de debugging temporal
    - `# TODO:` / `// TODO:` → Tareas pendientes
    - `# TEMP:` / `// TEMP:` → Código experimental
    - `# FIXME:` / `// FIXME:` → Código que necesita corrección
    - `# TEST:` / `// TEST:` → Solo para testing
    
    **📋 IMPORTANTE**: Ver guía completa de limpieza en `.github/instructions/code-clean.instructions.md`
    
    ### HTML/Templates (Jinja2)
    - **Plantilla base**: Siempre extender `layout.html`
    - **Bootstrap 5.3+**: Uso exclusivo (sin jQuery)
    - **Breadcrumbs**: Obligatorios en vistas internas
      ```html
      <nav aria-label="breadcrumb">
        <ol class="breadcrumb">
          <li class="breadcrumb-item"><a href="{{ url_for('index') }}">Inicio</a></li>
          <li class="breadcrumb-item"><a href="{{ url_for('appointment_list') }}">Citas</a></li>
          <li class="breadcrumb-item active">Detalle</li>
        </ol>
      </nav>
      ```
    - **Mensajes flash**: Renderizar en layout.html automáticamente
    - **Responsive**: Mobile-first con Bootstrap grid
    - **Iconos**: Bootstrap Icons (`<i class="bi bi-*">`)
    
    ### JavaScript (Vanilla JS)
    - **NO usar jQuery**: Migración completa a Vanilla JS
    - **Módulos**: Usar pattern IIFE cuando sea apropiado
      ```javascript
      window.ServiceForm = (function(){
        // ... funciones privadas
        return {
          publicFunction1,
          publicFunction2
        };
      })();
      ```
    - **Event Listeners**: `addEventListener()` en lugar de onclick inline
    - **Fetch API**: Para llamadas AJAX (no XMLHttpRequest)
    - **Validación**: HTML5 + JavaScript custom
    - **Autocompletado**: Implementar con debounce (300ms)
    
    ### Limpieza de Código Frontend
    **Antes de Producción Eliminar:**
    - `console.log()`, `console.debug()`, `console.warn()` temporales
    - `alert()` de testing
    - Comentarios `// TODO`, `// DEBUG`, `// FIXME`, `// TEMP`, `// TEST`
    - Funciones de test temporales
    - Variables no utilizadas
    - CSS/HTML comentado o experimental
    - Atributos `data-*` de debugging
    
    ## 🔧 Patrones de Arquitectura Específicos
    
    ### Rutas Flask (app.py)
    **Patrón CRUD estándar**:
    ```python
    @app.route('/entity')                    # GET  - Listar (con filtros opcionales)
    @app.route('/entity/new')                # GET  - Formulario crear
    @app.route('/entity/create', POST)       # POST - Procesar creación (deprecated: usar /new POST)
    @app.route('/entity/<id>')               # GET  - Ver detalle
    @app.route('/entity/<id>/edit')          # GET  - Formulario editar
    @app.route('/entity/<id>/update', POST)  # POST - Procesar actualización
    @app.route('/entity/<id>/delete', POST)  # POST - Eliminar (con confirmación)
    ```
    
    **Patrón moderno preferido** (reducir rutas):
    ```python
    @app.route('/entity', methods=['GET'])           # Listar
    @app.route('/entity/new', methods=['GET','POST']) # Crear (form + procesar)
    @app.route('/entity/<id>')                       # Ver
    @app.route('/entity/<id>/edit', methods=['GET','POST'])  # Editar (form + procesar)
    @app.route('/entity/<id>/delete', methods=['POST'])      # Eliminar
    ```
    
    **Ejemplo real del proyecto**:
    ```python
    @app.route('/appointments/<int:id>/edit', methods=['GET', 'POST'])
    @login_required
    def appointment_edit(id: int):
        """Edita una cita existente.
    
        Restricción: No permite editar citas con factura generada.
        """
        appointment = Appointment.query.get_or_404(id)
    
        # Validación de permisos/estado
        if appointment.invoice_id:
            flash('No se puede editar una cita que ya tiene factura generada', 'error')
            return redirect(url_for('appointment_view', id=id))
    
        if request.method == 'POST':
            try:
                # Procesar actualización
                # ... lógica de negocio
                db.session.commit()
                flash('Cita actualizada exitosamente', 'success')
                return redirect(url_for('appointment_view', id=id))
            except Exception as e:
                db.session.rollback()
                app.logger.error(f"Error actualizando cita: {e}")
                flash('Error al actualizar la cita', 'error')
    
        # GET - Mostrar formulario
        return render_template('appointments/edit.html',
                             appointment=appointment,
                             service_types=ServiceType.query.filter_by(is_active=True).all())
    ```
    
    ### Modelos de Base de Datos (SQLAlchemy)
    
    **Patrón de timestamps**:
    ```python
    class BaseModel(db.Model):
        __abstract__ = True
        created_at = db.Column(db.DateTime, default=lambda: datetime.now(CO_TZ))
        updated_at = db.Column(db.DateTime, default=lambda: datetime.now(CO_TZ),
                              onupdate=lambda: datetime.now(CO_TZ))
    ```
    
    **Relaciones estándar**:
    ```python
    class Appointment(db.Model):
        id = db.Column(db.Integer, primary_key=True)
        customer_id = db.Column(db.Integer, db.ForeignKey('customer.id'))
        pet_id = db.Column(db.Integer, db.ForeignKey('pet.id'))
    
        # Relaciones con backref
        customer = db.relationship('Customer', backref='appointments')
        pet = db.relationship('Pet', backref='appointments')
    
        # Relación uno a muchos
        services = db.relationship('PetService', backref='appointment',
                                  lazy='dynamic', cascade='all, delete-orphan')
    ```
    
    **Métodos útiles**:
    ```python
    class Appointment(db.Model):
        # ...
    
        def recompute_total(self):
            """Recalcula el total de la cita basado en sus servicios."""
            self.total_price = sum(s.price or 0 for s in self.services)
            self.total_services = self.services.count()
    
        def to_dict(self):
            """Serializa el modelo a diccionario para JSON."""
            return {
                'id': self.id,
                'customer': self.customer.name if self.customer else None,
                'pet': self.pet.name if self.pet else None,
                'total': float(self.total_price or 0),
                'status': self.status
            }
    ```
    
    **Sistema de logs de inventario** (implementado):
    ```python
    class ProductStockLog(db.Model):
        """Registra todos los movimientos de inventario para trazabilidad."""
        id = db.Column(db.Integer, primary_key=True)
        product_id = db.Column(db.Integer, db.ForeignKey('product.id'), nullable=False)
        user_id = db.Column(db.Integer, db.ForeignKey('user.id'), nullable=False)
        quantity = db.Column(db.Integer, nullable=False)  # Valor absoluto
        movement_type = db.Column(db.String(20), nullable=False)  # 'addition' o 'subtraction'
        reason = db.Column(db.Text, nullable=False)  # Razón obligatoria
        previous_stock = db.Column(db.Integer, nullable=False)
        new_stock = db.Column(db.Integer, nullable=False)
        created_at = db.Column(db.DateTime, default=lambda: datetime.now(CO_TZ))
    
        product = db.relationship('Product', backref='stock_logs')
        user = db.relationship('User', backref='stock_changes')
    ```
    
    **Sistema de códigos alternativos** (implementado Nov 2025):
    ```python
    class ProductCode(db.Model):
        """Códigos alternativos de productos para soportar consolidación.
    
        Permite que un producto tenga múltiples códigos (EAN, SKU, códigos legacy)
        manteniendo el código principal en Product.code.
    
        Tipos de código (code_type):
        - 'alternative': Código alternativo genérico
        - 'legacy': Código de producto consolidado
        - 'barcode': Código de barras (EAN, UPC)
        - 'supplier_sku': SKU del proveedor
        """
        id = db.Column(db.Integer, primary_key=True)
        product_id = db.Column(db.Integer, db.ForeignKey('product.id', ondelete='CASCADE'), nullable=False)
        code = db.Column(db.String(20), unique=True, nullable=False, index=True)
        code_type = db.Column(db.String(20), default='alternative', nullable=False)
        created_at = db.Column(db.DateTime, default=datetime.utcnow)
        created_by = db.Column(db.Integer, db.ForeignKey('user.id'))
        notes = db.Column(db.Text)
    
        # Relaciones
        product = db.relationship('Product', backref=db.backref('alternative_codes',
                                  lazy='dynamic', cascade='all, delete-orphan'))
        user = db.relationship('User')
    
    # Métodos en Product para códigos alternativos
    def get_all_codes(self):
        """Retorna lista de todos los códigos del producto."""
        codes = [{'code': self.code, 'type': 'principal', 'is_primary': True}]
        codes.extend([{'code': ac.code, 'type': ac.code_type, 'is_primary': False}
                      for ac in self.alternative_codes.all()])
        return codes
    
    @staticmethod
    def search_by_any_code(code_query):
        """Busca producto por código principal o alternativo."""
        product = Product.query.filter_by(code=code_query).first()
        if not product:
            alt_code = ProductCode.query.filter_by(code=code_query).first()
            if alt_code:
                return alt_code.product
        return product
    ```
    
    ### Autenticación y Seguridad
    
    **Decoradores de autorización**:
    ```python
    from functools import wraps
    
    def admin_required(f):
        @wraps(f)
        def decorated_function(*args, **kwargs):
            if not current_user.is_authenticated or current_user.role != 'admin':
                flash('Acceso denegado. Requiere permisos de administrador.', 'error')
                return redirect(url_for('index'))
            return f(*args, **kwargs)
        return decorated_function
    
    # Uso:
    @app.route('/settings')
    @login_required
    @admin_required
    def settings():
        # Solo admins
        pass
    ```
    
    **Roles del sistema**:
    - `admin`: Acceso total, configuración, reportes
    - `vendedor`: Ventas, inventario (solo lectura de productos), clientes
    
    **Hasheo de contraseñas**:
    ```python
    from werkzeug.security import generate_password_hash, check_password_hash
    
    # Al crear usuario
    user.password_hash = generate_password_hash(password)
    
    # Al validar login
    if check_password_hash(user.password_hash, password):
        login_user(user)
    ```
    
    ## 📊 Funcionalidades Específicas
    
    ### Sistema de Facturación
    - **Numeración secuencial**: Tabla `Setting` con campo `next_invoice_number`
    - **Métodos de pago**: `cash`, `transfer`, `card`, `mixed`
    - **Generación PDF**: ReportLab optimizado para impresoras térmicas (58mm/80mm)
    - **Asociación con citas**: `Invoice.appointment_id` (opcional, puede ser venta directa)
    - **Items de factura**: Tabla intermedia `InvoiceItem` con productos/servicios
    - **Cálculo automático**: Total, subtotal, descuentos, IVA
    
    **Flujo de facturación desde citas**:
    1. Crear cita → NO genera factura
    2. Finalizar cita → Genera factura automáticamente
    3. Asocia todos los servicios de la cita a la factura
    4. Marca servicios como `done`
    5. Actualiza estado de cita a `done`
    
    ### Gestión de Inventario con Trazabilidad
    **Sistema de logs implementado**:
    - Cada cambio de stock requiere razón obligatoria
    - Registro automático en `ProductStockLog`
    - Historial completo por producto
    - Información capturada:
      - Usuario responsable
      - Cantidad (positiva o negativa)
      - Tipo de movimiento (ingreso/egreso)
      - Stock anterior y nuevo
      - Razón detallada
      - Timestamp
    
    **Ejemplo de uso**:
    ```python
    # Al editar producto y cambiar stock
    if new_stock != old_stock:
        reason = request.form.get('stock_reason', '').strip()
        if not reason:
            flash('Debe proporcionar una razón para el cambio de stock', 'error')
            return render_template(...)
    
        # Crear log
        log = ProductStockLog(
            product_id=product.id,
            user_id=current_user.id,
            quantity=abs(new_stock - old_stock),
            movement_type='addition' if new_stock > old_stock else 'subtraction',
            reason=reason,
            previous_stock=old_stock,
            new_stock=new_stock
        )
        db.session.add(log)
    ```
    
    ### Sistema de Citas (Appointments)
    **Características**:
    - **Tarjetas interactivas**: Selección visual de servicios
    - **Precios dinámicos**: Servicios con precio fijo o variable
    - **Consentimiento informado**: Template personalizable
    - **Programación**: Fecha y hora opcional
    - **Estados**: `pending`, `done`, `cancelled`
    - **Edición**: Permitida solo en estado `pending` y sin factura
    - **WhatsApp**: Integración para confirmación de citas
    - **Impresión**: PDF del consentimiento informado con logo
    
    **Flujo completo**:
    ```
    1. Crear cita (/services/new)
       - Seleccionar cliente y mascota
       - Elegir servicios (tarjetas clickeables)
       - Agregar notas y consentimiento
       - Programar fecha/hora (opcional)
       → Guarda Appointment + PetService (sin Invoice)
    
    2. Ver cita (/appointments/<id>)
       - Información completa
       - Notas y consentimiento
       - Lista de servicios
       - Botones de acción según estado
    
    3. Editar cita (/appointments/<id>/edit)
       - Solo si estado = pending
       - Solo si NO tiene factura
       - Misma UI que creación
       - Puede agregar/quitar servicios
    
    4. Finalizar cita (POST /appointments/<id>/finish)
       - Genera Invoice automáticamente
       - Asocia servicios a la factura
       - Marca servicios como done
       - Actualiza estado a done
       → Redirige a Invoice para cobro/impresión
    
    5. Cancelar cita (POST /appointments/<id>/cancel)
       - Solo si estado = pending
       - Marca como cancelled
    ```
    
    ### Tipos de Servicio Configurables
    **Modelo `ServiceType`**:
    - Nombre y descripción
    - Código único
    - Precio base
    - Modo de precio: `fixed` (fijo) o `variable`
    - Duración estimada (minutos)
    - Estado activo/inactivo
    
    **CRUD completo**:
    - Lista en modal: `/services/types/config`
    - Crear/Editar: `/services/types/new` y `/services/types/<id>/edit`
    - Eliminar: Validación de servicios asociados
    
    ### Integración WhatsApp
    **Implementado en lista de citas**:
    ```html
    <a href="https://wa.me/+57{{ phone_clean }}?text={{ mensaje }}"
       class="btn btn-sm btn-outline-success"
       target="_blank"
       title="Confirmar cita por WhatsApp">
       <i class="bi bi-whatsapp"></i>
    </a>
    ```
    
    **Mensaje personalizado**:
    ```
    Hola [Nombre]!
    Te saludamos desde *Pet Verde*
    
    Recuerda la cita con nuestra groomer para *[Mascota]*
    
    Fecha: 17/10/2025
    Hora: 2:30 PM
    
    Gracias por preferirnos!
    ```
    
    ## 🚨 Restricciones y Consideraciones
    
    ### Base de Datos
    - **Transacciones**: SIEMPRE usar try-except con rollback
      ```python
      try:
          # operaciones
          db.session.commit()
      except Exception as e:
          db.session.rollback()
          app.logger.error(f"Error: {e}")
          flash('Error al guardar', 'error')
      ```
    - **SQLite locks**: Timeout de 30 segundos configurado
    - **Backups**: Recomendado backup diario de `app.db`
    - **Migraciones**: Evitar cambios breaking en schema
    
    ### Rendimiento
    - **Paginación**: Implementar en listas > 50 items
    - **Lazy loading**: Usar `lazy='dynamic'` en relaciones grandes
    - **Índices**: En campos de búsqueda frecuente (customer.document, product.code)
    - **Queries N+1**: Usar `joinedload()` cuando sea necesario
    
    ### Zona Horaria y Timestamps
    **CRÍTICO**:
    - `scheduled_at` en Appointment: Hora LOCAL (sin conversión)
    - Usuario programa en hora local → Se guarda en hora local → Se muestra tal cual
    - `created_at`, `updated_at`: Usar `datetime.now(CO_TZ)`
    - En templates: Usar formato `strftime()` directamente
    - NO convertir UTC→Local en appointments (ya están en local)
    
    **Ejemplo correcto**:
    ```python
    # Crear cita con hora programada
    appointment.scheduled_at = datetime.strptime(
        f"{date_str} {time_str}",
        '%Y-%m-%d %H:%M'
    )  # Sin timezone, es hora local
    
    # Mostrar en template
    {{ appointment.scheduled_at.strftime('%I:%M %p') }}  # 2:30 PM
    ```
    
    ### Credenciales por Defecto
    - Admin: `admin` / `admin123`
    - Vendedor: `vendedor` / `vendedor123`
    - **CAMBIAR EN PRODUCCIÓN**
    
    ## 🎨 Convenciones UI/UX
    
    ### Bootstrap 5 Components
    
    **Cards para contenido agrupado**:
    ```html
    <div class="card mb-3">
      <div class="card-header bg-light">
        <h5 class="mb-0">Título</h5>
      </div>
      <div class="card-body">
        <!-- Contenido -->
      </div>
      <div class="card-footer text-end">
        <button class="btn btn-primary">Guardar</button>
      </div>
    </div>
    ```
    
    **Tables responsive**:
    ```html
    <div class="table-responsive">
      <table class="table table-hover table-sm align-middle mb-0">
        <thead>
          <tr>
            <th>Columna</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>Dato</td>
          </tr>
        </tbody>
      </table>
    </div>
    ```
    
    **Modals para CRUD rápido**:
    ```html
    <!-- Modal de eliminación -->
    <div class="modal fade" id="deleteModal" tabindex="-1">
      <div class="modal-dialog">
        <div class="modal-content">
          <div class="modal-header">
            <h5 class="modal-title">Confirmar Eliminación</h5>
            <button type="button" class="btn-close" data-bs-dismiss="modal"></button>
          </div>
          <div class="modal-body">
            ¿Está seguro de eliminar este registro?
          </div>
          <div class="modal-footer">
            <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Cancelar</button>
            <form method="post" action="{{ url_for('entity_delete', id=item.id) }}">
              <button type="submit" class="btn btn-danger">Eliminar</button>
            </form>
          </div>
        </div>
      </div>
    </div>
    ```
    
    **Agrupación por fecha** (patrón usado en invoices y appointments):
    ```html
    {% for date, items in items_by_date.items() %}
    <div class="card mb-4">
      <div class="card-header bg-light">
        <h5 class="mb-0">
          <button class="btn btn-link collapsed" data-bs-toggle="collapse"
                  data-bs-target="#collapse-{{ loop.index }}">
            <span class="formatted-date" data-date="{{ date }}">{{ date }}</span>
            <i class="bi bi-chevron-down collapse-icon"></i>
          </button>
          <small class="text-muted ms-2">
            ({{ items|length }} items)
            <span class="ms-2">Total: {{ items|sum(attribute='total')|currency_co }}</span>
          </small>
        </h5>
      </div>
      <div id="collapse-{{ loop.index }}" class="collapse{{ ' show' if loop.index == 1 }}">
        <div class="card-body p-0">
          <div class="table-responsive">
            <table class="table table-hover table-sm align-middle mb-0">
              <!-- Tabla de items -->
            </table>
          </div>
        </div>
      </div>
    </div>
    {% endfor %}
    ```
    
    ### Iconografía (Bootstrap Icons)
    **Acciones estándar**:
    - Crear: `bi-plus-circle` (verde)
    - Editar: `bi-pencil-square` (amarillo/naranja)
    - Eliminar: `bi-trash` (rojo)
    - Ver: `bi-eye` (azul)
    - Guardar: `bi-save`
    - Volver: `bi-arrow-left`
    - Configurar: `bi-gear`
    - WhatsApp: `bi-whatsapp` (verde)
    - Factura: `bi-receipt-cutoff`
    - Imprimir: `bi-printer`
    
    **Estados con iconos**:
    ```html
    {% if appointment.status == 'done' %}
      <i class="bi bi-check-circle-fill text-success" title="Finalizada"></i>
    {% elif appointment.status == 'cancelled' %}
      <i class="bi bi-x-circle-fill text-danger" title="Cancelada"></i>
    {% else %}
      <i class="bi bi-hourglass-split text-secondary" title="Pendiente"></i>
    {% endif %}
    ```
    
    **Colores semánticos**:
    - Success (verde): Completado, guardar, confirmaciones
    - Warning (amarillo): Pendiente, advertencias
    - Danger (rojo): Eliminar, cancelar, errores
    - Primary (azul): Acciones principales, ver
    - Secondary (gris): Volver, acciones secundarias
    - Info (cyan): Información adicional
    
    ### Formularios
    **Validación HTML5 + JavaScript**:
    ```html
    <form method="post" novalidate>
      <div class="mb-3">
        <label for="name" class="form-label">Nombre <span class="text-danger">*</span></label>
        <input type="text" class="form-control" id="name" name="name" required>
        <div class="invalid-feedback">
          Este campo es requerido
        </div>
      </div>
    
      <div class="mb-3">
        <label for="stock" class="form-label">Existencias</label>
        <input type="number" class="form-control" id="stock" name="stock" min="0">
      </div>
    
      <button type="submit" class="btn btn-primary">
        <i class="bi bi-save"></i> Guardar
      </button>
    </form>
    ```
    
    **Campo de razón para cambios de stock** (implementado):
    ```html
    <div id="stockReasonGroup" class="mb-3" style="display: none;">
      <label for="stock_reason" class="form-label">
        Razón del Cambio de Stock <span class="text-danger">*</span>
      </label>
      <textarea class="form-control" id="stock_reason" name="stock_reason" rows="3"
                placeholder="Ej: Nueva compra factura #1234 del proveedor Italcol - 20/10/2025"></textarea>
      <small class="text-muted">
        Este cambio quedará registrado en el historial de inventario
      </small>
    </div>
    
    <script>
    const originalStock = {{ product.stock if product else 0 }};
    document.getElementById('stock').addEventListener('input', function() {
      const newStock = parseInt(this.value) || 0;
      const reasonGroup = document.getElementById('stockReasonGroup');
    
      if (newStock !== originalStock) {
        reasonGroup.style.display = 'block';
        document.getElementById('stock_reason').required = true;
      } else {
        reasonGroup.style.display = 'none';
        document.getElementById('stock_reason').required = false;
      }
    });
    </script>
    ```
    
    ## 📋 APIs y Endpoints Existentes
    
    ### APIs JSON (prefijo /api/)
    ```python
    @app.route('/api/customers/search')
    def api_customers_search():
        """Búsqueda de clientes para autocompletado."""
        q = request.args.get('q', '')
        customers = Customer.query.filter(
            Customer.name.ilike(f'%{q}%')
        ).limit(10).all()
        return jsonify([c.to_dict() for c in customers])
    
    @app.route('/api/products/search')
    def api_products_search():
        """Búsqueda de productos por nombre o código."""
        # Similar a customers
        pass
    
    @app.route('/api/dashboard/stats')
    @login_required
    def api_dashboard_stats():
        """Estadísticas del dashboard en JSON."""
        return jsonify({
            'sales_today': total_sales,
            'pending_appointments': pending_count,
            'low_stock_products': low_stock_count
        })
    ```
    
    ### Páginas Principales
    - `/` - Dashboard con estadísticas
    - `/customers` - Gestión de clientes
    - `/customers/<id>/pets` - Mascotas del cliente
    - `/products` - Gestión de inventario
    - `/products/<id>/stock-history` - **Historial de movimientos** (nuevo)
    - `/invoices` - Facturación con agrupación por fecha
    - `/services` - Redirige a appointments
    - `/appointments` - Sistema de citas agrupadas por fecha
    - `/appointments/<id>/edit` - Edición de cita
    - `/appointments/<id>/finish` - Finalizar y generar factura
    - `/services/types/config` - Configuración de tipos de servicio
    - `/reports` - **Módulo de reportes y análisis de ventas** (nuevo)
    - `/settings` - Configuración del negocio (admin only)
    
    ### Rutas de Impresión
    - `/invoices/<id>/print` - PDF de factura (ReportLab)
    - Impresión de consentimiento: JavaScript `window.print()` en `/appointments/<id>`
    
    ## 🔄 Workflow de Desarrollo
    
    ### Testing Manual Requerido
    1. **Login/logout** de admin y vendedor
    2. **CRUD completo** de clientes, productos, mascotas
    3. **Gestión de inventario** con cambios de stock y verificación de logs
    4. **Proceso completo de citas**:
       - Crear cita sin factura
       - Editar cita pendiente
       - Finalizar cita → Generar factura
       - Verificar que no se puede editar después
    5. **Facturación**:
       - Venta directa (sin cita)
       - Desde cita finalizada
       - Métodos de pago
       - Impresión PDF
    6. **Configuración**:
       - Tipos de servicio (CRUD)
       - Settings del negocio
       - Logo y datos de contacto
    
    ### Debugging
    **Logs permitidos en desarrollo**:
    ```python
    # DEBUG: solo en desarrollo
    print(f"Debug: appointment = {appointment.to_dict()}")
    app.logger.debug(f"Services count: {len(services)}")
    ```
    
    **Logs requeridos en producción**:
    ```python
    # Errores críticos
    app.logger.error(f"Error al crear factura: {str(e)}")
    
    # Acciones de seguridad
    app.logger.warning(f"Intento de acceso denegado: {current_user.username}")
    
    # Transacciones importantes
    app.logger.info(f"Factura {invoice.number} creada por {current_user.username}")
    ```
    
    **Flash messages para feedback**:
    ```python
    flash('Cita creada exitosamente', 'success')
    flash('No se puede editar una cita con factura', 'error')
    flash('Campo requerido: razón del cambio de stock', 'warning')
    flash('Producto actualizado', 'info')
    ```
    
    **Console logs en JavaScript**:
    ```javascript
    // DEBUG: solo en desarrollo
    console.log("Debug: selected services =", selectedServices);
    
    // NUNCA en producción
    // console.log(), alert(), debugger
    ```
    
    ### Proceso de Limpieza Pre-Producción
    
    **OBLIGATORIO antes de deploy:**
    
    1. **Revisar y limpiar logs temporales**:
    ```bash
    # Buscar todos los prints temporales
    grep -rn "print(" --include="*.py" app.py
    
    # Buscar console.log
    grep -rn "console\.log\|console\.debug" --include="*.js" static/
    
    # Buscar marcadores de debugging
    grep -rn "# DEBUG\|# TODO\|# TEMP\|# FIXME\|# TEST" --include="*.py" .
    grep -rn "// DEBUG\|// TODO\|// TEMP\|// FIXME\|// TEST" --include="*.js" .
    ```
    
    2. **Eliminar código comentado**:
    ```python
    # ELIMINAR:
    # old_function()  # TODO: eliminar deprecated
    # if debug_mode:  # DEBUG: lógica temporal
    ```
    
    3. **Limpiar imports no usados**:
    ```python
    # ELIMINAR:
    import pdb  # DEBUG: breakpoint library
    from pprint import pprint  # TEMP: debugging
    ```
    
    4. **Remover variables de test**:
    ```python
    # ELIMINAR:
    debug_var = "test"  # TEMP
    test_data = []  # TEST
    ```
    
    5. **Limpiar JavaScript temporal**:
    ```javascript
    // ELIMINAR:
    console.log("Debug info");  // DEBUG
    // alert("Test");  // TEST
    debugVar = "test";  // TEMP
    ```
    
    6. **Verificar templates**:
    ```html
    <!-- ELIMINAR comentarios de debugging -->
    <!-- DEBUG: verificar este valor -->
    <!-- TODO: mejorar este diseño -->
    ```
    
    ## 🚀 Deployment
    
    ### Desarrollo Local
    ```powershell
    # Windows
    .\run.ps1
    
    # O con Waitress
    python -m waitress --listen=127.0.0.1:5000 app:app
    ```
    
    ### Producción Windows
    1. **Servidor WSGI**: Waitress
       ```python
       # run.py
       from waitress import serve
       from app import app
    
       if __name__ == '__main__':
           serve(app, host='0.0.0.0', port=5000, threads=4)
       ```
    
    2. **Variables de entorno** (`.env`):
       ```env
       FLASK_ENV=production
       SECRET_KEY=your-secret-key-here
       DATABASE_URL=sqlite:///instance/app.db
       ```
    
    3. **Servicio Windows con NSSM**:
       ```powershell
       nssm install GreenPOS "C:\Python313\python.exe" "D:\Path\run.py"
       nssm set GreenPOS AppDirectory "D:\Path\Green-POS"
       nssm start GreenPOS
       ```
    
    4. **Backup automático**:
       ```powershell
       # Script PowerShell para backup diario
       Copy-Item "D:\Path\instance\app.db" "D:\Backups\app_$(Get-Date -Format 'yyyyMMdd').db"
       ```
    
    ## ✅ Checklist de Limpieza Pre-Producción
    
    ### OBLIGATORIO - Limpieza de Código de Debugging
    
    **Python/Backend:**
    - [ ] Todos los `print()` temporales (buscar `# DEBUG:`)
    - [ ] `app.logger.debug()` no esenciales
    - [ ] Comentarios `# TODO`, `# DEBUG`, `# TEMP`, `# FIXME`, `# TEST`
    - [ ] Imports: `pdb`, `pprint` con marcadores
    - [ ] Variables: `debug_var`, `test_data` marcadas `# TEMP:`
    - [ ] Código comentado: `# old_function()` con `# TODO:`
    - [ ] Funciones de test: `def test_*()` con `# TEST:`
    - [ ] **EMOJIS en print statements** (✅ ❌ 🔄 ⚠️ etc.) - Usar prefijos [OK], [ERROR], [INFO]
    - [ ] **Acentos en mensajes de consola** - Usar versiones sin acento
    
    **Frontend/JavaScript:**
    - [ ] `console.log()`, `console.debug()`, `console.warn()` con `// DEBUG:`
    - [ ] `alert()` de testing con `// TEST:`
    - [ ] Comentarios `// TODO`, `// DEBUG`, `// FIXME`, `// TEMP`, `// TEST`
    - [ ] Variables JS no utilizadas: `// TEMP:`
    - [ ] Código CSS/HTML comentado
    - [ ] Funciones de test JS: `// TEST:`
    - [ ] `debugger;` statements
    
    **Templates/HTML:**
    - [ ] Comentarios HTML de debugging: `<!-- DEBUG: -->`
    - [ ] Elementos `display: none` de testing
    - [ ] Atributos `data-debug-*`
    - [ ] Código experimental comentado
    
    **Configuración:**
    - [ ] Credenciales por defecto cambiadas
    - [ ] `SECRET_KEY` generado aleatoriamente
    - [ ] Debug mode desactivado: `FLASK_ENV=production`
    - [ ] URLs de desarrollo removidas
    - [ ] Claves API de testing
    
    **Comandos de Verificación:**
    ```bash
    # Python
    grep -rn "# DEBUG\|# TODO\|# TEMP\|# FIXME\|# TEST" --include="*.py" .
    grep -rn "print(" --include="*.py" app.py models/
    
    # JavaScript
    grep -rn "// DEBUG\|// TODO\|// TEMP\|// FIXME\|// TEST" --include="*.js" .
    grep -rn "console\.log\|console\.debug\|debugger" --include="*.js" static/
    
    # Templates
    grep -rn "<!-- DEBUG\|<!-- TODO\|<!-- TEMP" --include="*.html" templates/
    ```
    
    ### Logs Permitidos en Producción
    **SOLO mantener logs de:**
    - Errores críticos: `app.logger.error()`
    - Acciones de seguridad: login fallidos, accesos denegados
    - Transacciones importantes: facturas creadas, citas finalizadas
    - Performance crítica: queries lentas (si se implementa)
    
    **Ejemplo de log productivo**:
    ```python
    # ✅ MANTENER
    app.logger.error(f"Error al generar factura {invoice.id}: {str(e)}")
    app.logger.info(f"Factura {invoice.number} creada por {current_user.username}")
    app.logger.warning(f"Acceso denegado a /settings por usuario {current_user.username}")
    
    # ❌ ELIMINAR
    print(f"Debug: servicios = {services}")  # DEBUG
    app.logger.debug(f"Valor de variable x: {x}")  # DEBUG
    ```
    
    ---
    
    ## ⚠️ Anti-Patrones Comunes (Errores al Trabajar con IA)
    
    ### 1. Context Dump (Volcado de Contexto Masivo)
    **Problema**: Pegar archivos enormes completos esperando que la IA "entienda" todo automáticamente.
    
    **Por qué falla**:
    - La IA tiene límite de tokens y pierde contexto importante
    - Información irrelevante diluye los detalles críticos
    - Mayor latencia y costo de procesamiento
    - Resultados imprecisos o genéricos
    
    **❌ Incorrecto**:
    ```python
    # Usuario pega TODO el archivo app.py (1500+ líneas)
    # "Ayúdame a debuggear este código"
    ```
    
    **✅ Correcto**:
    ```python
    # Usuario comparte solo el método relevante con contexto:
    """
    Tengo un error en la ruta product_edit() cuando cambio el stock.
    El ProductStockLog no se está creando.
    
    Contexto:
    - product_edit() está en app.py líneas 355-402
    - ProductStockLog modelo está en models/models.py líneas 276-295
    - Relación: Product tiene backref 'stock_logs'
    
    Aquí está el método que falla:
    [código específico del método con 20-30 líneas]
    """
    ```
    
    **Regla de Oro**:
    - Máximo 50-100 líneas de código por prompt
    - Incluir solo métodos/clases directamente relevantes
    - Explicar el rol de cada parte compartida
    
    ### 2. Implicit Context (Contexto Implícito)
    **Problema**: Asumir que la IA "ya sabe" tu arquitectura, convenciones o decisiones previas.
    
    **Por qué falla**:
    - Cada conversación empieza con contexto limitado
    - La IA no tiene memoria persistente entre sesiones
    - Términos específicos del negocio son ambiguos sin definición
    
    **❌ Incorrecto**:
    ```
    Usuario: "Actualiza el appointment para que valide el status"
    IA: No sabe qué validaciones específicas necesitas
    ```
    
    **✅ Correcto**:
    ```
    Usuario: "En Green-POS, Appointment tiene campo 'status' con valores:
    - 'pending': puede editarse
    - 'done': inmutable, tiene factura asociada
    - 'cancelled': inmutable
    
    Quiero agregar validación en appointment_edit() para que:
    1. Si status='done' Y existe invoice_id → mostrar error
    2. Si status='cancelled' → mostrar error
    3. Si status='pending' → permitir edición normal
    
    Patrón usado: State Pattern (ver copilot-instructions.md línea 650)"
    ```
    
    **Regla de Oro**:
    - Siempre explica términos del dominio (`appointment`, `invoice`, `status`)
    - Menciona restricciones de negocio explícitamente
    - Referencia patrones/decisiones arquitectónicas cuando aplique
    
    ### 3. Set and Forget (Crear y Olvidar)
    **Problema**: Crear archivo de instrucciones una vez y nunca actualizarlo a medida que el proyecto evoluciona.
    
    **Por qué falla**:
    - El código cambia pero las instrucciones no
    - Nuevos patrones no documentados → inconsistencia
    - La IA sigue reglas obsoletas
    
    **❌ Incorrecto**:
    ```markdown
    # copilot-instructions.md creado hace 6 meses
    # Proyecto ahora usa:
    # - Nuevo patrón de validación de stock
    # - Sistema de logs de inventario
    # - Zona horaria CO_TZ
    # Pero instrucciones NO reflejan estos cambios
    ```
    
    **✅ Correcto**:
    ```markdown
    # Actualizar copilot-instructions.md en cada milestone:
    - Nueva feature implementada → documentar patrón usado
    - Cambio arquitectónico → actualizar sección de constraints
    - Bug fix importante → agregar a "Lessons Learned"
    
    Ejemplo de actualización:
    "## Sistema de Trazabilidad de Inventario (Oct 2025)
    - Implementado modelo ProductStockLog
    - Campo obligatorio stock_reason al cambiar existencias
    - Validación backend + frontend
    - Ver: app.py líneas 355-402"
    ```
    
    **Regla de Oro**:
    - Revisar copilot-instructions.md en cada Definition of Done
    - Actualizar cuando agregas: nuevos modelos, patrones, constraints, dependencias
    - Versionar el archivo con git para tracking de cambios
    
    ### 4. One Size Fits All (Contexto Único Para Todo)
    **Problema**: Usar el mismo nivel de contexto para debugging, features nuevas y análisis de código.
    
    **Por qué falla**:
    - Debugging necesita detalles técnicos (logs, stack traces)
    - Features necesitan contexto de negocio (requisitos, UI/UX)
    - Análisis necesita visión arquitectónica (patrones, dependencias)
    
    **❌ Incorrecto**:
    ```
    # Mismo prompt genérico para todo:
    "Revisa este código y dime si está bien"
    ```
    
    **✅ Correcto - Debugging**:
    ```
    "DEBUGGING: Error en product_edit() al guardar ProductStockLog
    
    Síntomas:
    - No se crea registro en stock_logs
    - No hay error en consola
    - Stock del producto SÍ se actualiza
    
    Contexto técnico:
    - app.py líneas 380-395 (creación de log)
    - db.session.add(log) ejecutándose
    - Relación: Product.stock_logs (backref)
    
    Stack trace: [pegar error completo si existe]
    Logs: [pegar líneas relevantes de app.log]
    
    Pregunta: ¿Por qué no se persiste el log?"
    ```
    
    **✅ Correcto - Feature Nueva**:
    ```
    "FEATURE: Sistema de descuentos en facturas
    
    Requisitos de negocio:
    - Descuento % o valor fijo por factura
    - Aplicable a total antes de IVA
    - Razón obligatoria si descuento > 10%
    - Solo admin puede aplicar
    
    Restricciones:
    - Invoice modelo ya existe (models.py línea 200)
    - Usar patrón State para validar aplicación
    - Frontend: Bootstrap 5, campo con validación
    
    Pregunta: ¿Cómo estructuro el modelo y la lógica?"
    ```
    
    **✅ Correcto - Análisis Arquitectónico**:
    ```
    "ANÁLISIS: Evaluar migración de SQLite a PostgreSQL
    
    Contexto actual:
    - 50 usuarios concurrentes
    - 1000 facturas/mes
    - SQLite con timeouts ocasionales
    - Backups manuales diarios
    
    Necesito:
    1. Pros/contras de migración
    2. Cambios requeridos en código
    3. Plan de migración sin downtime
    4. Estimación de esfuerzo
    
    Ver constraints: copilot-instructions.md líneas 20-100"
    ```
    
    **Regla de Oro**:
    - **Debugging**: Síntomas + logs + stack traces + código específico
    - **Features**: Requisitos + restricciones + contexto UI/UX + patrones esperados
    - **Análisis**: Visión arquitectónica + trade-offs + impacto + constraints
    
    ### 5. Instruction Drift (Deriva de Instrucciones)
    **Problema**: Tener múltiples archivos con reglas contradictorias o redundantes en diferentes lugares.
    
    **Por qué falla**:
    - README.md dice "usar pytest"
    - .github/copilot-instructions.md dice "usar unittest"
    - La IA recibe señales contradictorias
    
    **❌ Incorrecto**:
    ```
    Proyecto tiene:
    - README.md: "Usamos Bootstrap 4"
    - copilot-instructions.md: "Bootstrap 5.3+ sin jQuery"
    - CONTRIBUTING.md: "Puedes usar jQuery si quieres"
    → Inconsistencia total
    ```
    
    **✅ Correcto**:
    ```markdown
    # .github/copilot-instructions.md (FUENTE CANÓNICA)
    ## Stack Tecnológico Principal
    - Frontend: Bootstrap 5.3+ (sin jQuery) + Vanilla JavaScript
    - Backend: Flask 3.0+ + SQLAlchemy
    - Database: SQLite (dev) → PostgreSQL (prod)
    
    # README.md (REFERENCIA A FUENTE)
    ## Tecnologías
    Ver especificaciones técnicas completas en:
    `.github/copilot-instructions.md`
    
    Stack resumido:
    - Flask 3.0+
    - Bootstrap 5.3+
    - SQLite/PostgreSQL
    
    # CONTRIBUTING.md (REFERENCIA A FUENTE)
    ## Estándares de Código
    Seguir guidelines en `.github/copilot-instructions.md`:
    - Sección "Requisitos de Estilo de Código"
    - Patrones de diseño implementados
    - Constraints tecnológicos
    ```
    
    **Regla de Oro**:
    - **UN SOLO archivo fuente de verdad**: `.github/copilot-instructions.md`
    - Otros archivos REFERENCIAN, no duplican
    - Actualizar solo la fuente canónica
    - Si hay conflicto → el archivo de instrucciones gana
    
    ### 6. Domain Ambiguity (Ambigüedad de Dominio)
    **Problema**: Usar términos ambiguos que significan cosas diferentes según el contexto.
    
    **Por qué falla**:
    - "Account" = ¿cliente o tenant?
    - "Service" = ¿servicio de grooming o microservicio?
    - "Item" = ¿producto o línea de factura?
    - La IA no puede resolver ambigüedad sin contexto
    
    **❌ Incorrecto**:
    ```python
    # Código usa términos ambiguos sin aclarar
    class Service(db.Model):  # ¿Qué tipo de servicio?
        pass
    
    class Account(db.Model):  # ¿Cliente o cuenta de usuario?
        pass
    
    # Usuario pregunta:
    "Cómo creo un nuevo Service?"
    # IA no sabe si hablas de PetService o ServiceType
    ```
    
    **✅ Correcto - Glosario de Dominio**:
    ```markdown
    ## 📖 Glosario de Dominio (Green-POS)
    
    ### Entidades Principales
    
    **Customer (Cliente)**:
    - Persona que trae mascotas para servicios
    - Tiene: nombre, documento, teléfono, dirección
    - Modelo: `Customer` (models.py línea 100)
    - Relación: Un Customer tiene muchos Pets
    
    **Pet (Mascota)**:
    - Animal propiedad de un Customer
    - Tiene: nombre, especie, raza, edad
    - Modelo: `Pet` (models.py línea 130)
    - Relación: Pet pertenece a Customer
    
    **Appointment (Cita)**:
    - Agendamiento de servicios para una Pet
    - Tiene: fecha, hora, Customer, Pet, servicios, status
    - Modelo: `Appointment` (models.py línea 200)
    - Estados: 'pending', 'done', 'cancelled'
    - Relación: Appointment tiene muchos PetService
    
    **PetService (Servicio de Mascota)**:
    - Instancia de un ServiceType aplicado en una Appointment
    - Tiene: tipo, precio, notas
    - Modelo: `PetService` (models.py línea 240)
    - Relación: PetService pertenece a Appointment
    
    **ServiceType (Tipo de Servicio)**:
    - Catálogo de servicios ofrecidos (grooming, veterinaria)
    - Tiene: nombre, código, precio base, duración
    - Modelo: `ServiceType` (models.py línea 270)
    - Modo precio: 'fixed' (fijo) o 'variable'
    
    **Invoice (Factura)**:
    - Documento de cobro por servicios/productos
    - Tiene: número, fecha, total, método de pago
    - Modelo: `Invoice` (models.py línea 180)
    - Puede asociarse a Appointment (opcional)
    
    **Product (Producto)**:
    - Artículo de inventario vendible
    - Tiene: código, nombre, precio, stock
    - Modelo: `Product` (models.py línea 35)
    
    **User (Usuario del Sistema)**:
    - Empleado con acceso al sistema
    - Roles: 'admin', 'vendedor'
    - Modelo: `User` (models.py línea 250)
    
    ### Términos Técnicos
    
    **Stock**: Cantidad de Product disponible en inventario
    **Status**: Estado de Appointment ('pending', 'done', 'cancelled')
    **Payment Method**: Método de pago ('cash', 'transfer', 'card', 'mixed')
    **CO_TZ**: Timezone de Colombia (America/Bogota) usado en timestamps
    
    ### Anti-Patrón Común:
    ❌ "Agregar un service" → Ambiguo
    ✅ "Agregar un PetService a la Appointment" → Específico
    ✅ "Crear un ServiceType nuevo en catálogo" → Específico
    ```
    
    **Regla de Oro**:
    - Crear sección de Glosario en copilot-instructions.md
    - Definir cada entidad con: propósito, campos clave, relaciones, estados
    - Usar nombres específicos en prompts ("PetService" no "service")
    - Aclarar términos sobrecargados con contexto
    
    ### 7. Missing Definition of Done (Falta Criterio de Completitud)
    **Problema**: No especificar qué significa "terminado" para una tarea, causando implementaciones incompletas.
    
    **Por qué falla**:
    - IA implementa solo lo explícito
    - Falta validación, logging, tests, docs
    - Usuario asume que "obviedades" están incluidas
    
    **❌ Incorrecto**:
    ```
    Usuario: "Agrega un campo de email al Customer"
    IA: Agrega solo el campo al modelo
    Faltan: validación, unique constraint, migración, actualizar forms
    ```
    
    **✅ Correcto**:
    ```
    Usuario: "Agrega campo email al Customer con Definition of Done:
    
    Modelo (models.py):
    - Campo: email (String 120, nullable, unique)
    - Validación: formato email válido
    - Index en columna email
    
    Ruta (app.py):
    - Actualizar customer_edit() para incluir email
    - Validación backend con regex
    - Flash message si email duplicado
    
    Template (customers/form.html):
    - Input type="email" con validación HTML5
    - Placeholder: ejemplo@dominio.com
    - Campo opcional
    
    Migración:
    - Crear script de migración manual si necesario
    - Default NULL para registros existentes
    
    Documentación:
    - Actualizar copilot-instructions.md en sección Customer
    - Agregar a glosario de dominio
    
    Testing:
    - Validar creación con email válido
    - Validar rechazo de email inválido
    - Validar unique constraint"
    ```
    
    **Regla de Oro**:
    - Siempre especificar Definition of Done con:
      * Cambios en modelo + validaciones
      * Cambios en rutas + lógica de negocio
      * Cambios en templates + UX
      * Migración de datos si aplica
      * Actualización de documentación
      * Criterios de testing
    
    ---
    
    ## 📝 Notas de Implementación Recientes
    
    ### Refactorización Completa a Blueprints (Nov 2025) 🎉
    **ESTADO**: ✅ **100% COMPLETADO**
    
    #### Transformación Arquitectónica
    - **Antes**: 1 archivo monolítico (app.py: 2107 líneas)
    - **Después**: 11 blueprints modulares (~200 líneas c/u)
    - **Tiempo**: ~4.5 horas de refactorización asistida
    
    #### Blueprints Implementados (11/11)
    1. **auth.py** - Login, logout, profile
    2. **dashboard.py** - Dashboard principal con estadísticas
    3. **api.py** - Endpoints JSON para búsquedas AJAX
    4. **products.py** - CRUD productos + historial de stock
    5. **suppliers.py** - CRUD proveedores
    6. **customers.py** - CRUD clientes
    7. **pets.py** - CRUD mascotas
    8. **invoices.py** - Sistema de facturación completo
    9. **services.py** - Servicios, citas y tipos de servicio (618 líneas - más complejo)
    10. **reports.py** - Análisis y reportes de ventas
    11. **settings.py** - Configuración del negocio
    
    #### Archivos Clave
    - `app.py` - Aplicación principal con Factory Pattern (201 líneas)
    - `config.py` - Configuración por ambientes
    - `extensions.py` - db, login_manager compartidos
    - `utils/` - filtros, decoradores, constantes
    - `routes/` - 11 blueprints modulares
    
    #### Limpieza Post-Refactor
    - ✅ Eliminados comentarios TODO/DEBUG/TEMP
    - ✅ Código comentado duplicado eliminado
    - ✅ Archivos temporales archivados en `docs/archive/`
    - ✅ Caché Python limpiado
    - ✅ Templates actualizados (150+ referencias url_for)
    
    #### Beneficios Logrados
    - **Mantenibilidad**: +250% (código modular vs monolítico)
    - **Testabilidad**: +500% (blueprints independientes testeable)
    - **Escalabilidad**: Arquitectura preparada para crecimiento
    - **Código Limpio**: 100% sin código temporal o debugging
    
    #### Documentación
    - `docs/CLEANUP_SUMMARY.md` - Resumen completo de limpieza
    - `docs/REFACTORING.md` - Guía de refactorización
    - `README.md` - Actualizado con arquitectura de blueprints
    
    **Referencias Legacy** (solo consulta histórica):
    - `docs/archive/app.py.backup` - Original monolítico (2107 líneas)
    - `docs/archive/app_old.py` - Pre-limpieza
    
    ### Sistema de Unificación de Productos con Multi-Código (Nov 2025) 🆕
    **ESTADO**: ✅ **100% COMPLETADO**
    
    #### Característica Implementada
    Sistema completo de consolidación de productos duplicados con soporte para múltiples códigos alternativos (EAN, SKU, códigos legacy).
    
    #### Componentes Implementados
    
    **1. Tabla ProductCode** (Base de Datos):
    - Nueva tabla `product_code` para códigos alternativos ilimitados
    - Relación One-to-Many con Product (1 producto → N códigos)
    - Tipos soportados: `alternative`, `legacy`, `barcode`, `supplier_sku`
    - Índices en `code`, `product_id`, `code_type` para búsqueda eficiente
    - Migración: `migrations/migration_add_product_codes.py` ✅
    
    **2. Modelo ProductCode** (models/models.py):
    - Clase `ProductCode` con relación a Product (cascade delete)
    - Métodos en Product:
      * `get_all_codes()` - Retorna código principal + alternativos
      * `search_by_any_code(code)` - Busca por código principal o alternativo
    - Backref `Product.alternative_codes` (lazy='dynamic')
    
    **3. Script de Consolidación** (migrations/merge_products.py):
    - Función `merge_products(source_ids, target_id, user_id)`
    - **7 pasos de consolidación**:
      1. Migra ventas (InvoiceItem)
      2. Migra logs de stock (ProductStockLog) - **TODOS**, sin pérdida
      3. Consolida stock (suma)
      4. Crea log de consolidación
      5. Migra códigos a ProductCode (type='legacy')
      6. Migra proveedores (product_supplier)
      7. Elimina productos origen
    - Backup automático con timestamp
    - Modo CLI interactivo y API programática
    - Transacciones con rollback en error
    
    **4. Búsqueda Multi-Código** (routes/products.py, routes/api.py):
    - Lista de productos: `outerjoin(ProductCode)` para búsqueda en códigos alternativos
    - Nueva API: `/api/products/search?q=<query>` con soporte multi-código
    - Búsqueda encuentra productos por:
      * Código principal (Product.code)
      * Nombre (Product.name)
      * Cualquier código alternativo (ProductCode.code)
    - `.distinct()` para evitar duplicados por join
    
    **5. Interfaz de Consolidación** (templates/products/merge.html):
    - Ruta: `/products/merge` (solo admin)
    - Selector de producto destino
    - Búsqueda en vivo de productos origen
    - Preview dinámico de consolidación:
      * Productos a consolidar
      * Stock total estimado
      * Códigos legacy que se crearán
    - Confirmación manual antes de ejecutar
    - Botón "Consolidar Productos" en lista de productos
    
    #### Beneficios
    - ✅ Ilimitados códigos por producto (vs. 1 código anterior)
    - ✅ Búsqueda por cualquier código (principal, EAN, SKU, legacy)
    - ✅ Consolidación completa sin pérdida de datos
    - ✅ Trazabilidad total (user_id, created_at, notes en códigos)
    - ✅ Backups automáticos en consolidación
    - ✅ Script reutilizable para cualquier producto
    
    #### Uso
    ```python
    # Consolidar productos 101, 102, 103 en producto 100
    from migrations.merge_products import merge_products
    
    stats = merge_products(
        source_product_ids=[101, 102, 103],
        target_product_id=100,
        user_id=1  # ID del usuario admin
    )
    # Retorna: {'invoice_items': 15, 'stock_logs': 8, 'stock_consolidated': 50, ...}
    ```
    
    #### Documentación
    - Investigación completa: `docs/research/2025-11-24-unificacion-productos-solucion-completa.md`
    - Análisis de búsqueda: `docs/PRODUCT_SEARCH_ANALYSIS_MULTICODE.md`
    - Migración SQL: `migrations/migration_add_product_codes.sql`
    
    #### Performance
    - Impacto en búsqueda: +5-7ms (con índices) - Despreciable
    - Consolidación: ~2-5 segundos para 3-5 productos
    - Backup automático: ~1 segundo
    
    ### Sistema de Trazabilidad de Inventario (Oct 2025)
    - Implementado modelo `ProductStockLog`
    - Ruta `/products/<id>/stock-history` para ver historial
    - Campo obligatorio `stock_reason` al cambiar existencias
    - JavaScript muestra/oculta campo según cambios
    - Validación backend de razón antes de guardar
    - Logs incluyen: usuario, cantidad, tipo, razón, stocks anterior/nuevo
    
    ### Sistema de Citas Mejorado (Oct 2025)
    - Migrado formulario de creación a tarjetas interactivas
    - Unificado diseño entre creación y edición
    - Factura se genera SOLO al finalizar cita (no al crear)
    - Implementado historial completo de citas por fecha
    - Integración WhatsApp para confirmación
    - Impresión de consentimiento con logo del negocio
    
    ### Agrupación por Fecha (Oct 2025)
    - Facturas agrupadas con totales por método de pago
    - Citas agrupadas con conteo de servicios
    - Expandir/colapsar acordeones
    - Primera fecha expandida por defecto
    
    ### Módulo de Reportes (Oct 2025)
    - **Ruta principal**: `/reports` con filtros de fecha (start_date, end_date)
    - **Métricas calculadas**:
      * Número total de ventas (facturas) en el período
      * Ingresos totales (suma de Invoice.total)
      * Utilidades: `(precio_venta - precio_compra) * cantidad` por cada InvoiceItem
      * Margen de utilidad (%) = utilidades / ingresos * 100
      * Ticket promedio = ingresos / número de ventas
      * Valor del inventario (stock * precio_compra)
      * Potencial de ventas (stock * precio_venta)
    - **Análisis por método de pago**: Agrupación con count, total y porcentaje
    - **Horas pico de ventas**: Top 5 horas con más ventas (agrupado por hora local CO_TZ)
    - **Top 10 productos más vendidos**: Cantidad vendida e ingresos generados
    - **Productos con stock bajo**: Listado de productos con <= 3 unidades
    - **Últimas 20 facturas** del período con detalles
    - **UI**: Cards para métricas, tablas responsivas, filtros de fecha, botón de impresión
    - **Patrón**: Repository Pattern con queries complejas usando SQLAlchemy func
    - **Acceso**: Disponible para todos los usuarios autenticados (admin y vendedor)
    
    ---
    
    **Última actualización**: 22 de octubre de 2025
    **Versión del proyecto**: 2.0
    **Contacto**: Sistema Green-POS - Pet Services Management
    
    ---
    
    *Este archivo se actualiza automáticamente en cada conversación de Copilot para proporcionar contexto consistente del proyecto.*

    Comments

    More Rules

    View all

    QPrisma Copilot Rules

    A
    alexandergg

    Site Casanova Limaemedeiros Copilot Rules

    V
    victormedeeeiros-design

    Mosl Custom Chart Copilot Rules

    R
    riviangeralt

    InOut App Copilot Rules

    J
    jeanvq

    Fastfood Express Copilot Rules

    J
    jersonjjcr

    Pds Pre View Copilot Rules

    E
    eiriksgata

    Neura weekly digest

    Stay up to date

    The week's most-read AI news, trending AI tools and new automation workflows, in one email. At most once a week. Free, and you can unsubscribe in one click.

    Neura Market LogoNeura Market

    Discover the best AI prompts, plugins, and resources for CoPilot and more.

    Content Types

    • Rules
    • Prompts
    • MCPs
    • Agents
    • Games
    • Blog
    • Videos
    • Guides
    • Courses
    • Community
    • Plugins

    Platforms

    • ChatGPT Directory
    • Claude Directory
    • Gemini Directory
    • Cursor Directory
    • Grok Directory
    • Perplexity Directory
    • DeepSeek Directory
    • CoPilot Directory
    • Stable Diffusion Directory
    • Midjourney Directory
    • All Directories

    Resources

    • Blog
    • Documentation
    • Help Center
    • Marketplace

    Legal

    • Privacy Policy
    • Terms of Service

    © 2026 Neura Market. All rights reserved.

    |

    Not affiliated with any AI platform vendors.

    Neura Market

    Custom AI Systems & Services

    Our team of experienced AI builders will help build custom AI systems, workflows, and solutions.

    Request custom work

    Ready-made automations for this

    Workflows from the Neura Market marketplace related to this CoPilot resource

    • Build RAG-Powered WhatsApp Chatbots for Docs with GPT-4-mini and MongoDBn8n · $24.99 · Related topic
    • Automating WhatsApp Replies Using GoHighLevel with Redis and Anthropicn8n · $24.99 · Related topic
    • Automated WhatsApp Group Weekly Team Reports with Gemini AI Summarizationn8n · $24.99 · Related topic
    • Multi-Service Task Automation with AI-Powered Agent System via WhatsAppn8n · $24.99 · Related topic
    Browse all workflows