Template-Especificación-Técnica

Ver en Git

---

Especificación Técnica: [Nombre del Feature]

Nota: Este es un template. Copiá esta página y reemplazá los placeholders con la información real, eliminar aquellas secciones que no corresponden.

📊 Información General

Proyecto: [Nombre del proyecto]

Epic/Feature: [Breve descripción]

Responsable del desarrollo: @username

Autor de la especificación: @username

---

🎯 Objetivo

[¿Qué problema resuelve este desarrollo? ¿Qué funcionalidad nueva aporta?]

---

🏗️ Componentes Principales

1. API Resources (Controllers)

Endpoints a crear/modificar:

POST /api/v1/recursos

Descripción: Crea un nuevo recurso (ejemplo)

Request body:

{
  "nombre": "string",
  "descripcion": "string",
  "tipo": "string"
}

Response (201 Created):

{
  "id": "uuid",
  "nombre": "string",
  "created_at": "2025-10-16T10:30:00Z"
}

Validaciones:

• nombre es requerido, máximo 255 caracteres
• tipo debe ser uno de: ['tipo1', 'tipo2', 'tipo3']
• etc

---

GET /api/v1/recursos/{id}

Descripción: Obtiene un recurso por ID

Response (200 OK):

{
  "id": "uuid",
  "nombre": "string",
  "descripcion": "string"
}

Errores posibles:

• 404: Recurso no encontrado
• 403: Sin permisos para acceder

---

2. Services (ejemplo)

RecursoService

Responsabilidades:

• Validación de reglas de negocio
• Orquestación de operaciones complejas
• Coordinación entre múltiples repositorios

Métodos principales:

• crear_recurso(usuario_id: str, data: dict) -> Recurso:
• procesar_recurso(recurso_id: str) -> dict:
  • [Describir la lógica de negocio]

---

3. Repositories (ejemplo)

RecursoRepository

Métodos principales:

• find_by_id(recurso_id: str) -> Recurso | None: Busca un recurso por ID
• find_by_usuario(usuario_id: str) -> List[Recurso]: Obtiene todos los recursos de un usuario
• create(recurso_data: dict) -> Recurso: Crea un nuevo recurso
• update(recurso_id: str, data: dict) -> Recurso: Actualiza un recurso existente
• delete(recurso_id: str) -> bool: Elimina un recurso (soft delete)

Consideraciones:

• [Indicar si usa soft delete, caché, paginación, etc.]

---

4. Models/Entities

Recurso (ejemplo)

class Recurso:
    id: UUID
    nombre: str
    descripcion: str
    estado: str
    usuario_id: UUID
    created_at: datetime
    updated_at: datetime
    
    # Relaciones
    usuario: Usuario

Comportamientos del modelo:

• [Indicar métodos, properties calculadas, validaciones a nivel modelo]

---

5. Schemas

Schema de entrada: RecursoCreateSchema

{
    "nombre": str (requerido, max 255),
    "descripcion": str (opcional, max 1000),
    "tipo": str (requerido, enum: ['tipo1', 'tipo2'])
}

Schema de salida: RecursoResponseSchema

{
    "id": str (UUID),
    "nombre": str,
    "descripcion": str,
    "estado": str,
    "created_at": str (ISO 8601),
    "usuario": {
        "id": str,
        "nombre": str
    }
}

Validaciones en los schemas:

• [Listar validaciones custom, transformaciones, campos calculados]

---

🗄️ Modelo de Datos

Importante: Incluir una imagen del diagrama del modelo de datos

Tabla: nombre_tabla_1

Propósito: [Explicar qué representa esta tabla y para qué se usa]

Campos:

• id (UUID): Identificador único del registro
• nombre (VARCHAR 255): Descripción del campo
• estado (VARCHAR 50): Estados posibles: 'activo', 'inactivo', 'pendiente'
• created_at (TIMESTAMP): Fecha de creación del registro
• updated_at (TIMESTAMP): Fecha de última modificación

Índices:

• PRIMARY KEY en id
• INDEX en estado (para consultas frecuentes por estado)

Relaciones:

• FK usuario_id → usuarios.id

---

Nota sobre modificaciones: Si estás modificando una tabla existente, especificá claramente:

• ➕ Campos que se agregan
• ✏️ Campos que se modifican
• ❌ Campos que se eliminan (si aplica)

---

Ejemplo

---

🔗 Referencias

ClickUp:

• Epic: [Link al Epic de ClickUp]
• Issues relacionados:
  • [Link al issue 1]
  • [Link al issue 2]

Figma:

• Diseños: [Link a Figma con los diseños de UI]

Documentación adicional:

• [Cualquier otro documento relevante]