FiveTech Support Forums

"github.copilot.chat.experimental.projectContext": {
    "enabled": true,
    "files": [
      ".vscode/instructions.md",
      ".vscode/copilot-context.md"
    ],
    "directories": [
      "C:/fw/source/classes",
      "C:/fw/source/function",
      "C:/fw/source/winapi"
    ]
  },

# Instrucciones para IA - Proyecto 

## Descripción del Proyecto

Sistema desarrollado en **Harbour/xHarbour** con interfaz gráfica **FiveWin** y librerías adicionales por ActiveX **Chilkat** y **Codejock** 

## Arquitectura Técnica

### Lenguajes y Frameworks
- **Lenguaje Principal**: Harbour/xHarbour (dialecto de Clipper)
- **GUI Framework**: FiveWin (framework para Windows)
- **Librerías importantes**: Chilkat y Codejock
- **Base de Datos**: DBF/CDX (dBase compatible)
- **ORM** : ORM Propio
- **Compilador**: Harbour + Borland/Embarcadero C++
- 
### Codificación
- **Codepage**: ESWIN (Windows-1252 español)
- **Caracteres especiales**: Usar funciones de conversión UTF-8 apropiadas
- **Base de datos**: DBF con índices CDX


### Estructura de Directorios

```
proyecto/
│── PRG/             # Código fuente principal (.prg)
├── siclases/            # Clases específicas del sistema
├── clases32/            # Librerías y componentes externos
├── lib32/               # Librerías compiladas
├── inc/                 # Archivos de inclusión
├── sifuncs/             # Funciones del sistema
├── VFuncs/              # Funciones adicionales
└── iconos/              # Recursos gráficos
```
## Convenciones de Código

### Sintaxis Harbour
```harbour
// Definición de función
Function Main(cParametros)
  // código
Return (nil)

// Definición de clase
CLASS TExample
    EXPORTED:
        DATA cProperty AS Character INIT ""
        METHOD New() CONSTRUCTOR
        METHOD SomeMethod()
    PROTECTED:
        DATA lPrivate AS Logical INIT .F.
END CLASS

// Uso de objetos
WITH OBJECT oApp := TGestion():New()
    :Method1()
    :Method2()
END WITH
```

### Convenciones de Nombres
- **Variables**: camelCase con prefijo tipo (`cString`, `nNumber`, `lLogical`, `oObject`, `aArray`)
- **Funciones**: PascalCase (`Main`, `IniciaGestion`)
- **Métodos**: PascalCase (`:New()`, `:BuildMainWindow()`)
- **Clases**: PascalCase con prefijo T (`TApplication`)
- **Modelos**: PascalCase con prefijo M ( `MSeries`)

### Gestión de Errores
- Uso de objetos con propiedades `:Success` y `:Fail()`
- Logs detallados en archivos `.log`
- Mensajes al usuario con `MsgAlert()`, `MsgInfo()`

### Base de Datos
- Modelos de datos con prefijo `m` (ej: `mCliente`, `mFactura`)
- Uso de índices CDX para búsquedas
- ORM propio integrado en `TORMModel.prg`. Documentación del ORM en .\Servicios\Database\ORM2.0\README.md

## 🎯 Estándares de Desarrollo y Mejores Prácticas

### Clean Code Principles
- **Nombres descriptivos**: Variables y funciones deben explicarse por sí mismas
- **Funciones pequeñas**: Máximo 50 líneas por función/método
- **Responsabilidad única**: Cada clase/función debe tener un solo propósito
- **Comentarios útiles**: Solo cuando el código no sea auto-explicativo
- **Evitar código duplicado**: Refactorizar en funciones comunes

### Gestión de Errores Robusta
```harbour
// ✅ SIEMPRE validar parámetros de entrada
METHOD ProcessDocument(oDocument) CLASS TExample
    
    If oDocument == Nil .Or. oDocument:Fail()
        Self:__oReturn:Success := .F.
        Self:__oReturn:Log := 'Documento inválido o no encontrado'
        Return ( Self )
    Endif
    
    // Lógica del método...
    
Return ( Self )
```

### Refactoring Guidelines
- **Extraer métodos**: Cuando hay bloques de código repetidos
- **Simplificar condiciones**: Usar variables booleanas descriptivas
- **Eliminar parámetros innecesarios**: Máximo 3-4 parámetros por función
- **Usar objetos de configuración**: Para múltiples parámetros relacionados

### Testing y Validación
- **Validar datos de entrada**: Siempre verificar tipos y rangos
- **Testing de casos extremos**: Valores null, vacíos, muy grandes
- **Logs detallados**: Para debugging en producción
- **Rollback de transacciones**: En operaciones críticas de BD

### Performance Best Practices
```harbour
// ✅ Usar índices CDX eficientemente
oModel:Find(nID, 'ID')  // Busca por índice principal

// ✅ Cerrar recursos explícitamente
WITH OBJECT oFile := TFileReader():New(cFileName)
    :Process()
    :Close()  // Liberar recursos
END WITH

// ✅ Minimizar consultas a BD en bucles
aClientes := mCliente():New():GetCollection()  // Una sola consulta
FOR EACH oCliente IN aClientes
    // Procesar en memoria
NEXT
```

### Security & Data Integrity
- **Sanitización de inputs**: Especialmente para XML/SQL
- **Validación de permisos**: Verificar acceso antes de operaciones
- **Encriptación**: Para datos sensibles (usar Chilkat)
- **Backup automático**: Antes de operaciones de riesgo

### Code Review Checklist
1. **¿El código es auto-explicativo?**
2. **¿Se manejan todos los casos de error?**
3. **¿Hay código duplicado que pueda refactorizarse?**
4. **¿Las variables tienen nombres descriptivos?**
5. **¿Se liberan correctamente los recursos?**
6. **¿Se respetan las convenciones del proyecto?**
7. **¿Funciona correctamente en casos extremos?**

### Harbour/xHarbour Specific Rules
- **Usar WITH OBJECT**: Para múltiples llamadas al mismo objeto
- **Inicializar variables**: Siempre declarar tipo y valor inicial
- **Gestionar memoria**: Cerrar archivos, liberar objetos grandes
- **Codepage consistente**: ESWIN en todo el proyecto

## Consideraciones Especiales

### Codificación de Caracteres
- Problemas comunes con caracteres especiales (ñ, tildes)
- Usar `hb_StrToUTF8()` para conversiones
- Sanear caracteres de control antes de XML

### Compatibilidad
- Sistema legacy con alta compatibilidad requerida
- Soporte Windows 7/8/10/11
- Integración con hardware específico (impresoras, cajones)

## Tareas Comunes para IA

1. **Debugging de codificación**: Solucionar caracteres extraños en XML/textos
2. **Optimización de consultas**: Mejorar rendimiento de base de datos

## 🤖 Directrices para Asistencia de IA

### Enfoque Obligatorio
- **SIEMPRE** aplicar principios de Clean Code
- **SIEMPRE** sugerir refactoring cuando detectes código duplicado
- **SIEMPRE** validar robustamente errores y casos extremos
- **SIEMPRE** considerar el rendimiento y la memoria

### Al Analizar Código
1. **Identificar problemas**: Código duplicado, funciones largas, nombres poco claros
2. **Sugerir mejoras**: Refactoring, optimizaciones, mejor estructura
3. **Validar errores**: ¿Se manejan todos los casos de fallo?
4. **Verificar convenciones**: ¿Sigue el estilo del proyecto?
5. **Considerar mantenibilidad**: ¿Será fácil de mantener en el futuro?

### Al Crear Código Nuevo
```harbour
// ✅ ESTRUCTURA OBLIGATORIA para nuevos métodos/funciones
METHOD ExampleMethod(cParam1, nParam2) CLASS TExample
    
    // 1. Validación de parámetros SIEMPRE
    If cParam1:Empty() .Or. nParam2 <= 0
        Self:__oReturn:Success := .F.
        Self:__oReturn:Log := 'Parámetros inválidos en ExampleMethod'
        Return ( Self )
    Endif
    
    // 2. Variables locales con tipo explícito
    Local oResult as Object := Nil
    Local lSuccess as Logical := .T.
    
    // 3. Lógica principal con manejo de errores
    TRY
        // Lógica aquí...
        
    CATCH oError
        Self:__oReturn:Success := .F.
        Self:__oReturn:Log := 'Error en ExampleMethod: ' + oError:Description
        lSuccess := .F.
    END
    
    // 4. Logging para debugging
    If lSuccess
        Self:__oReturn:Log := 'ExampleMethod ejecutado correctamente'
    Endif
    
Return ( Self )
```

### Prioridades de Sugerencias
1. **🔴 CRÍTICO**: Seguridad, pérdida de datos, errores fatales
2. **🟡 ALTO**: Performance, memoria, casos no manejados  
3. **🟢 MEDIO**: Clean code, refactoring, mantenibilidad
4. **🔵 BAJO**: Estilo, comentarios, optimizaciones menores

### Respuestas Esperadas
- **Explicar el "por qué"**: No solo qué cambiar, sino por qué es mejor
- **Mostrar antes/después**: Código original vs mejorado
- **Considerar impacto**: ¿Afecta a otras partes del sistema?
- **Sugerir testing**: Cómo verificar que funciona correctamente

## Comandos de Desarrollo

### Compilación
```bash
# Compilar
h.bat 
# Compilar con debug
h.bat debug
```

# Configuración de Contexto del Proyecto

Este archivo asegura que GitHub Copilot siempre tenga acceso al contexto del proyecto Completo.

## Archivos de Referencia Obligatorios
- `.vscode/instructions.md` - Guía completa del proyecto 

## Configuración Aplicada
La configuración en `settings.json` incluye:
- Soporte para archivos `.prg` (Harbour)
- Contexto del proyecto habilitado
- Locale en español
- Referencias automáticas a las instrucciones del proyecto

## Uso
Cuando uses GitHub Copilot Chat en este workspace, automáticamente tendrá acceso a:
- Las instrucciones específicas del proyecto
- Convenciones de código Harbour
- Arquitectura del ERP
- Patrones de desarrollo del proyecto