Guías de Desarrollo

Este directorio contiene guías y mejores prácticas para desarrollar en el sistema de microservicios.

Contenido

Getting Started

Developer Setup Guide - 🚀 Configuración inicial para nuevos desarrolladores

Gestión de Producto

Product Owner Guide - Manual del Product Owner con Kanban
Kanban Guide - Guía de Kanban para el equipo
Project Config Usage - 📊 Uso de project_config.yaml para métricas
Idea to Task Flow - Flujo de ideas a tareas ejecutables
ClickUp Integration - Integración con ClickUp
🤖 Quick Start: Procesador de Ideas - Guía rápida de 5 minutos
🔄 Integración del Procesador - Workflows híbridos y mejores prácticas
🚀 GitHub Actions Setup - Procesamiento automático con GitHub Actions

Control de Versiones y Cambios

Version Control Workflow - 🌳 Estrategia de Trunk-Based Development
Version Control Comparison - 📊 Comparación de estrategias y guía de decisión
Git Quick Reference - 📋 Comandos rápidos para el día a día
Feature Flags Guide - 🚩 Gestión de feature toggles
Code Review Guidelines - 👥 Proceso de revisión de código
CI/CD Pipeline - 🚀 Pipeline de integración y despliegue continuo

Patrones Arquitectónicos

Saga Pattern - Transacciones distribuidas
CQRS Pattern - Separación de comandos y consultas
Event-Driven Patterns - Patrones de comunicación por eventos

Observabilidad (NEW) 🔍

Observability Best Practices - 🎯 Guía completa de observabilidad con OpenTelemetry, Prometheus, Grafana, Jaeger y Loki

Infraestructura

IIS Configuration - Configuración de IIS para microservicios
Event Bus Setup - Configuración de RabbitMQ/Service Bus
Database Migrations - Gestión de migraciones

Desarrollo

Coding Standards - Estándares de código .NET
API Design - Diseño de APIs REST
Error Handling - Manejo de errores
Logging - Estrategia de logging estructurado

Testing

Testing Strategy - Estrategia general de testing
Unit Testing - Testing de unidades
Integration Testing - Testing de integración
Contract Testing - Testing de contratos de eventos

Operaciones

Deployment - Proceso de despliegue
Observability Best Practices - 🔍 Stack completo de observabilidad (traces, metrics, logs)
Monitoring - Monitoreo y observabilidad
Troubleshooting - Resolución de problemas comunes

Seguridad

Security Guidelines - Guías de seguridad
PCI Compliance - Cumplimiento PCI para pagos

BIT Components

BIT Components - Desarrollo con BIT
Versioning Strategy - Estrategia de versionado

Principios Generales

1. SOLID Principles

Single Responsibility: Cada clase tiene una sola razón para cambiar
Open/Closed: Abierto para extensión, cerrado para modificación
Liskov Substitution: Las subclases deben ser sustituibles por sus clases base
Interface Segregation: Interfaces específicas mejor que generales
Dependency Inversion: Depender de abstracciones, no de concreciones

2. DRY (Don't Repeat Yourself)

Extraer código repetido a funciones/clases
Usar BIT components para compartir código entre servicios
Crear utilidades comunes en shared libraries

3. KISS (Keep It Simple, Stupid)

La solución más simple que funcione
No sobre-ingeniería
Código fácil de entender

4. YAGNI (You Aren't Gonna Need It)

No implementar funcionalidad hasta que sea necesaria
Evitar "prepararse para el futuro"
Iterar basado en necesidades reales

Flujo de Desarrollo

1. Planning

Revisar arquitectura existente
Documentar decisiones (ADRs si es significativo)
Diseñar eventos si es necesario

2. Development

Crear branch desde main siguiendo Version Control Workflow
Seguir coding standards
Escribir tests
Actualizar documentación
Usar Feature Flags para trabajo incompleto

3. Testing

Unit tests (mínimo 80% coverage)
Integration tests para flujos críticos
Contract tests para eventos

4. Code Review

Seguir Code Review Guidelines
Al menos 1 approval requerido (2 para cambios críticos)
Verificar que sigue estándares
Validar tests

5. Deployment

CI/CD automático a dev
Manual promotion a staging
Approval requerido para production

Convenciones de Código

Naming

C# / .NET

PascalCase para clases, métodos, propiedades
camelCase para variables locales y parámetros
Interfaces con prefijo I (ej: IOrderRepository)
Async methods con sufijo Async (ej: GetOrderAsync)

Archivos

Nombre de archivo = nombre de clase principal
Un tipo público por archivo (excepto nested types)

Bases de datos

PascalCase para tablas
PascalCase para columnas
Plural para tablas de entidades (ej: Orders, Products)

Organización de Código

// NOTA: Ejemplo conceptual de estructura
namespace Company.Service.Layer
{
    // 1. Using statements (ordenados)
    using System;
    using System.Collections.Generic;
    using Company.Shared;

    // 2. Clase con XML comments
    /// <summary>
    /// Description of the class
    /// </summary>
    public class MyClass
    {
        // 3. Fields (private)
        private readonly IService _service;

        // 4. Constructor
        public MyClass(IService service)
        {
            _service = service;
        }

        // 5. Properties
        public string Name { get; set; }

        // 6. Public methods
        public void PublicMethod()
        {
            // Implementation
        }

        // 7. Private methods
        private void PrivateMethod()
        {
            // Implementation
        }
    }
}

Git Workflow

Utilizamos Trunk-Based Development como estrategia principal de control de versiones.

Branches

main: Producción (siempre desplegable)
feature/TASK-XXX-description: Ramas de características (1-3 días máximo)
hotfix/FIX-description: Correcciones urgentes (< 1 día)
Release tags: vX.Y.Z (no ramas)

Commits

Formato de commit messages siguiendo Conventional Commits:

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: Nueva feature
fix: Bug fix
docs: Documentación
style: Formato (no afecta lógica)
refactor: Refactorización
test: Tests
chore: Mantenimiento

Ejemplo:

feat(orders): add order cancellation endpoint

Implement POST /api/orders/{id}/cancel endpoint
that allows users to cancel their pending orders.

Closes TASK-123

Flujo Completo

Ver Version Control Workflow para guía detallada de:

Creación de branches
Proceso de commit y push
Mantenimiento de branches actualizados
Proceso de Pull Request
Gestión de releases
Proceso de hotfixes
Resolución de conflictos
Mejores prácticas

Feature Flags

Para permitir merge de trabajo incompleto sin afectar producción, utilizamos feature flags. Ver Feature Flags Guide para detalles completos.

FilesExpand file tree

README.md

Latest commit

History