workspace-v1/shared/knowledge-base/reference/erp-inmobiliaria-legacy

📚 REFERENCE - Código de Referencia

Propósito: Esta carpeta contiene proyectos y código de referencia para análisis, comparación y mejora del desarrollo actual.

---

🎯 USO

Para Architecture-Analyst

• Analizar implementaciones de referencia de Odoo y OCA
• Comparar patrones arquitectónicos
• Documentar mejores prácticas observadas
• Proponer mejoras basadas en referencias

Para Agentes de Desarrollo

• Consultar implementaciones de funcionalidades similares
• Comparar enfoques de diseño en módulos Odoo
• Reutilizar patrones probados
• Entender mejores prácticas de desarrollo Python/Odoo

Para Claude Code Cloud

• Acceso a código de referencia desde cualquier instancia
• Comparaciones automáticas con código actual
• Análisis de implementaciones

---

📂 ESTRUCTURA

reference/
├── README.md                     # Este archivo
├── odoo/                         # Código Odoo de referencia
│   └── README.md
├── gamilit/                      # Proyecto GAMILIT (arquitectura educativa)
│   ├── README.md
│   ├── _MAP.md                   # Mapa completo del proyecto
│   ├── backend/                  # Backend Node.js + TypeScript
│   ├── frontend/                 # Frontend React + TypeScript
│   ├── database/                 # PostgreSQL schemas y DDL
│   └── devops/                   # Scripts DevOps y validación
├── odoo-modules/                 # Módulos Odoo de referencia (futuro)
│   ├── oca-account/              # Módulos contables de OCA
│   │   ├── __manifest__.py
│   │   ├── models/
│   │   └── README.md
│   └── custom-modules/           # Módulos personalizados de ejemplo
├── python-patterns/              # Patrones Python de referencia (futuro)
│   ├── design-patterns/
│   └── best-practices/
└── integrations/                 # Integraciones de referencia (futuro)
    ├── api-examples/
    └── external-services/

---

⚠️ IMPORTANTE - Qué Versionar

✅ SÍ versionar (INCLUIR):

• Código fuente Python (.py)
• Archivos de manifiesto (manifest.py, init.py)
• Archivos de configuración (requirements.txt, setup.py)
• Documentación (.md files, .rst files)
• Esquemas de base de datos (.sql files, .xml files)
• Archivos de vista (.xml)
• Archivos de datos (.csv, .xml para datos)
• README y documentación

❌ NO versionar (IGNORADO automáticamente):

• pycache/
• *.pyc
• *.pyo
• .eggs/
• venv/
• env/
• .venv/
• node_modules/ (si hay frontend)
• dist/
• build/
• .next/ (si hay Next.js)
• coverage/
• *.log
• *.tmp
• *.cache
• .DS_Store

Razón: Solo versionamos código fuente. Las dependencias Python se pueden regenerar con pip install -r requirements.txt.

---

📋 DIRECTRICES

Al Agregar Proyectos de Referencia

1. Limpiar antes de agregar:

   # Eliminar cache Python y virtual environments
   cd reference/nuevo-proyecto
   find . -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null
   find . -name "*.pyc" -delete
   find . -name "*.pyo" -delete
   rm -rf venv env .venv
   

2. Verificar que está limpio:

   # No debe mostrar carpetas de cache o virtual environments
   du -sh reference/nuevo-proyecto/*
   

3. Agregar README del proyecto:

   # Proyecto: {nombre}
   
   **Fuente:** {URL o descripción}
   **Propósito:** ¿Por qué se incluye como referencia?
   **Aspectos relevantes:** ¿Qué podemos aprender?
   
   ## Instalación (para probar localmente)
   ```bash
   cd reference/{nombre}
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   

   Aspectos destacables

   • Feature 1: Descripción
   • Pattern 2: Descripción

4. Commit con mensaje descriptivo:

   git add reference/nuevo-proyecto
   git commit -m "ref: agregar proyecto {nombre} como referencia para {propósito}"
   

---

🔍 VALIDACIÓN

Verificar que reference/ está en el repo:

# Debe devolver vacío (no ignorado)
git check-ignore reference/

# Debe mostrar archivos de reference/
git ls-files reference/

Verificar que pycache está ignorado dentro de reference/:

# Debe devolver: reference/proyecto/__pycache__/
git check-ignore reference/proyecto/__pycache__/

Verificar que venv está ignorado dentro de reference/:

# Debe devolver: reference/proyecto/venv/
git check-ignore reference/proyecto/venv/

Ejecutar validación automática:

bash orchestration/scripts/validate-gitignore.sh

Debe mostrar:

✅ reference/ NO está ignorado (correcto)
✅ reference/**/__pycache__/ está ignorado (correcto)
✅ reference/**/venv/ está ignorado (correcto)

---

📊 TAMAÑO RECOMENDADO

Máximo recomendado: ~100MB por proyecto (solo código fuente)

Si un proyecto excede este tamaño:

• Considerar incluir solo las partes relevantes
• Crear subcarpeta con implementaciones específicas
• Documentar ubicación del proyecto completo (URL)

---

🎓 EJEMPLOS DE USO

Ejemplo 1: Analizar Módulo Contable de OCA

**Tarea:** Implementar gestión de ejercicios fiscales

**Agente:** Architecture-Analyst

**Proceso:**
1. Revisar `reference/odoo-modules/oca-account/account_fiscal_year/`
2. Analizar modelos de datos y vistas
3. Comparar con implementación actual
4. Documentar mejoras en `docs/adr/ADR-XXX.md`

Ejemplo 2: Implementar Feature Similar

**Tarea:** Implementar templates de asientos contables

**Agente:** Backend-Agent

**Proceso:**
1. Consultar `reference/odoo-modules/oca-account/account_move_template/`
2. Revisar modelos de datos y lógica de negocio
3. Adaptar patrones al proyecto actual
4. Implementar con mejores prácticas observadas

Ejemplo 3: Comparar Arquitectura

**Tarea:** Refactorizar estructura de módulos Odoo

**Agente:** Architecture-Analyst

**Proceso:**
1. Analizar `reference/odoo-modules/best-practices/`
2. Comparar con estructura actual
3. Proponer mejoras arquitectónicas
4. Crear plan de refactorización

---

🎯 CASOS DE USO ESPECÍFICOS

Proyecto GAMILIT (Referencia Arquitectónica)

Relevancia: Sistema educativo gamificado con arquitectura moderna y prácticas recomendadas

Aspectos destacables:

• Monorepo TypeScript con backend (Node.js/Express) y frontend (React/Vite)
• Arquitectura de base de datos multi-schema (9 schemas, 44 tablas)
• Sistema de constantes SSOT (Single Source of Truth)
• Feature-Sliced Design en frontend
• Path aliases consistentes
• Scripts de validación y sincronización automática

Aplicable para:

• Patrones de arquitectura de software
• Estructura de monorepo
• Sincronización Backend ↔ Frontend
• Organización de base de datos PostgreSQL
• Testing y validación automática

Ver: reference/gamilit/README.md y reference/gamilit/_MAP.md

---

Proyectos Odoo de Referencia

Tipos de proyectos a incluir:
- Módulos OCA (Odoo Community Association)
- Módulos core de Odoo con implementaciones ejemplares
- Módulos personalizados con patrones útiles
- Integraciones con servicios externos
- Implementaciones de reportes complejos

Patrones Python

Tipos de patrones a incluir:
- Design patterns (Singleton, Factory, etc.)
- Patrones de testing
- Patrones de API design
- Patrones de manejo de datos

---

📚 REFERENCIAS

• DIRECTIVA-GESTION-BACKUPS-GITIGNORE.md - Sección 1.5
• PROMPT-ARCHITECTURE-ANALYST.md
• .gitignore - Sección REFERENCE

---

✅ CHECKLIST ANTES DE COMMIT

Antes de agregar un nuevo proyecto de referencia:

• Eliminar pycache/, *.pyc, *.pyo
• Eliminar venv/, env/, .venv/
• Eliminar node_modules/ (si aplica)
• Verificar que solo hay código fuente
• Agregar README del proyecto explicando propósito
• Verificar tamaño total (< 100MB recomendado)
• Documentar aspectos relevantes del proyecto
• Commit con mensaje descriptivo

---

🔗 RECURSOS ÚTILES

Repositorios OCA

• OCA Account Financial Tools
• OCA Account Invoicing
• OCA Server Tools
• OCA Web Tools

Documentación Odoo

• Odoo Developer Documentation
• Odoo ORM Guide

---

Última actualización: 2025-11-23 Mantenido por: Architecture-Analyst, Workspace-Manager Directiva: DIRECTIVA-GESTION-BACKUPS-GITIGNORE.md sección 1.5