todoapp-vgv7cg/README-es.md
2025-06-19 00:18:08 +00:00

11 KiB

API Simple de Tareas (Todo)

Una aplicación simple de tareas construida con FastAPI y SQLite.

Características

  • Crear, leer, actualizar y eliminar tareas
  • Base de datos SQLite con ORM SQLAlchemy
  • Migraciones de base de datos con Alembic
  • FastAPI con documentación automática OpenAPI
  • CORS habilitado para todos los orígenes
  • Endpoint de verificación de salud
  • Sistema de categorías - Clasificación simple de tareas
  • Sistema de etiquetas - Etiquetado múltiple flexible
  • Sistema de subtareas - Descomposición jerárquica de tareas
  • Sistema de proyectos - Agrupación de tareas con metadatos
  • Niveles de prioridad - Prioridades alta, media y baja
  • Paginación avanzada - Con metadatos de respuesta
  • Búsqueda y filtrado - Múltiples criterios de filtrado

Endpoints de la API

Endpoints Principales

  • GET / - Endpoint raíz con información básica
  • GET /health - Endpoint de verificación de salud
  • GET /docs - Documentación interactiva de la API (Swagger UI)
  • GET /redoc - Documentación alternativa de la API

Gestión de Tareas (/api/v1/todos)

  • GET /api/v1/todos - Obtener todas las tareas con filtrado y paginación
  • POST /api/v1/todos - Crear una nueva tarea
  • GET /api/v1/todos/{todo_id} - Obtener una tarea específica
  • PUT /api/v1/todos/{todo_id} - Actualizar una tarea específica
  • DELETE /api/v1/todos/{todo_id} - Eliminar una tarea específica

Gestión de Categorías (/api/v1/categories)

  • GET /api/v1/categories - Listar todas las categorías
  • POST /api/v1/categories - Crear nueva categoría
  • GET /api/v1/categories/{category_id} - Obtener categoría específica
  • PUT /api/v1/categories/{category_id} - Actualizar categoría
  • DELETE /api/v1/categories/{category_id} - Eliminar categoría

Gestión de Etiquetas (/api/v1/tags)

  • GET /api/v1/tags - Listar todas las etiquetas
  • POST /api/v1/tags - Crear nueva etiqueta
  • GET /api/v1/tags/{tag_id} - Obtener etiqueta específica
  • PUT /api/v1/tags/{tag_id} - Actualizar etiqueta
  • DELETE /api/v1/tags/{tag_id} - Eliminar etiqueta
  • POST /api/v1/tags/{tag_id}/todos/{todo_id} - Agregar etiqueta a tarea
  • DELETE /api/v1/tags/{tag_id}/todos/{todo_id} - Quitar etiqueta de tarea
  • GET /api/v1/tags/{tag_id}/todos - Obtener tareas por etiqueta

Gestión de Proyectos (/api/v1/projects)

  • GET /api/v1/projects - Listar todos los proyectos
  • POST /api/v1/projects - Crear nuevo proyecto
  • GET /api/v1/projects/{project_id} - Obtener proyecto específico
  • PUT /api/v1/projects/{project_id} - Actualizar proyecto
  • DELETE /api/v1/projects/{project_id} - Eliminar proyecto
  • GET /api/v1/projects/{project_id}/todos - Obtener tareas del proyecto
  • PUT /api/v1/projects/{project_id}/archive - Archivar proyecto

Gestión de Subtareas

  • POST /api/v1/todos/{todo_id}/subtasks - Crear subtarea
  • GET /api/v1/todos/{todo_id}/subtasks - Obtener subtareas
  • PUT /api/v1/subtasks/{subtask_id}/move - Mover subtarea

Instalación

  1. Instalar las dependencias:
pip install -r requirements.txt
  1. Configurar variables de entorno:
cp .env.example .env
# Editar .env con tu configuración local
  1. Ejecutar migraciones de base de datos:
alembic upgrade head
  1. Iniciar la aplicación:
uvicorn main:app --reload

La API estará disponible en http://localhost:8000

Filtrado y Búsqueda Avanzados

Parámetros de Consulta Disponibles

La API soporta filtrado y búsqueda sofisticados:

GET /api/v1/todos?page=1&per_page=10&completed=false&priority=high&category_id=1&project_id=2&search=urgente&parent_id=null

Parámetros:

  • page - Número de página (predeterminado: 1)
  • per_page - Elementos por página (predeterminado: 10, máximo: 100)
  • completed - Filtrar por estado de completado (true/false)
  • priority - Filtrar por prioridad (high/medium/low)
  • category_id - Filtrar por categoría
  • project_id - Filtrar por proyecto
  • search - Buscar en título y descripción
  • parent_id - Filtrar por tarea padre (null para tareas principales)

Formato de Respuesta con Paginación

{
  "items": [...tareas...],
  "total": 25,
  "page": 1,
  "per_page": 10,
  "has_next": true,
  "has_prev": false
}

Estructura del Proyecto

├── app/
│   ├── api/
│   │   └── v1/
│   │       ├── __init__.py
│   │       ├── todos.py
│   │       ├── categories.py
│   │       ├── tags.py
│   │       └── projects.py
│   ├── crud/
│   │   ├── __init__.py
│   │   ├── todo.py
│   │   ├── category.py
│   │   ├── tag.py
│   │   └── project.py
│   ├── db/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── session.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── todo.py
│   │   ├── category.py
│   │   ├── tag.py
│   │   ├── todo_tag.py
│   │   └── project.py
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── todo.py
│   │   ├── category.py
│   │   ├── tag.py
│   │   └── project.py
│   └── __init__.py
├── alembic/
│   ├── versions/
│   │   ├── 001_initial_todo_table.py
│   │   ├── 002_add_priority_field.py
│   │   ├── 003_add_categories.py
│   │   ├── 004_add_projects.py
│   │   ├── 005_add_tags.py
│   │   └── 006_add_subtasks.py
│   ├── env.py
│   └── script.py.mako
├── .github/
│   └── pull_request_template.md
├── alembic.ini
├── main.py
├── requirements.txt
├── .env.example
├── LICENSE
├── CONTRIBUTING.md
├── README.md
└── README-es.md

Base de Datos

La aplicación utiliza una base de datos SQLite almacenada en /app/storage/db/db.sqlite. El esquema de la base de datos se gestiona usando migraciones de Alembic.

Esquema de Base de Datos

Tabla todos (Principal)

  • id: Identificador único (generado automáticamente)
  • title: Título de la tarea (requerido, máximo 200 caracteres)
  • description: Descripción de la tarea (opcional, máximo 500 caracteres)
  • completed: Estado de completado (booleano, predeterminado: false)
  • priority: Nivel de prioridad (high/medium/low, predeterminado: medium)
  • category_id: Referencia a categoría (opcional)
  • project_id: Referencia a proyecto (opcional)
  • parent_id: Referencia a tarea padre para subtareas (opcional)
  • created_at: Marca de tiempo de creación
  • updated_at: Marca de tiempo de última actualización

Tabla categories

  • id: Identificador único
  • name: Nombre de la categoría (único, máximo 100 caracteres)
  • description: Descripción de la categoría (opcional)
  • color: Código de color hexadecimal (opcional)
  • created_at, updated_at: Marcas de tiempo

Tabla tags

  • id: Identificador único
  • name: Nombre de la etiqueta (único, máximo 50 caracteres)
  • color: Código de color hexadecimal (opcional)
  • created_at: Marca de tiempo de creación

Tabla projects

  • id: Identificador único
  • name: Nombre del proyecto (máximo 200 caracteres)
  • description: Descripción del proyecto (opcional)
  • status: Estado del proyecto (active/archived)
  • created_at, updated_at: Marcas de tiempo

Tabla todo_tags (Asociación)

  • todo_id: Referencia a tarea
  • tag_id: Referencia a etiqueta
  • Relación muchos-a-muchos entre tareas y etiquetas

Ejemplos de Uso

Crear una Categoría

curl -X POST "http://localhost:8000/api/v1/categories" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Trabajo",
       "description": "Tareas relacionadas con el trabajo",
       "color": "#FF6B6B"
     }'

Crear un Proyecto

curl -X POST "http://localhost:8000/api/v1/projects" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Rediseño del Sitio Web",
       "description": "Proyecto completo de rediseño"
     }'

Crear una Tarea con Categoría y Proyecto

curl -X POST "http://localhost:8000/api/v1/todos" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "Revisar presentación",
       "description": "Revisar la presentación del cliente",
       "priority": "high",
       "category_id": 1,
       "project_id": 1
     }'

Crear Etiquetas y Asignarlas

# Crear etiqueta
curl -X POST "http://localhost:8000/api/v1/tags" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "urgente",
       "color": "#FF0000"
     }'

# Asignar etiqueta a tarea
curl -X POST "http://localhost:8000/api/v1/tags/1/todos/1"

Crear Subtarea

curl -X POST "http://localhost:8000/api/v1/todos/1/subtasks" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "Revisar sección de introducción",
       "priority": "medium"
     }'

Filtrar Tareas

# Obtener tareas de alta prioridad en proyecto específico
curl "http://localhost:8000/api/v1/todos?project_id=1&priority=high&completed=false"

# Buscar tareas con texto específico
curl "http://localhost:8000/api/v1/todos?search=revisar&category_id=1"

# Obtener solo tareas principales (sin subtareas)
curl "http://localhost:8000/api/v1/todos?parent_id=null"

Variables de Entorno

Consulta .env.example para ver todas las variables de configuración disponibles:

  • DATABASE_URL: URL de la base de datos SQLite
  • APP_TITLE: Título de la aplicación
  • CORS_ORIGINS: Orígenes permitidos para CORS
  • HOST y PORT: Configuración del servidor
  • LOG_LEVEL: Nivel de logging

Contribuir

Por favor, lee CONTRIBUTING.md para obtener detalles sobre nuestro código de conducta y el proceso para enviar pull requests.

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Características Técnicas

  • FastAPI: Framework web moderno y rápido
  • SQLAlchemy: ORM potente para Python
  • Alembic: Gestión de migraciones de base de datos
  • Pydantic: Validación de datos y serialización
  • Ruff: Formateador y linter de código
  • SQLite: Base de datos ligera y confiable

Arquitectura

La aplicación sigue un patrón de arquitectura en capas:

  1. Capa de API (app/api/): Endpoints de FastAPI y manejo de requests
  2. Capa de Esquemas (app/schemas/): Validación de datos con Pydantic
  3. Capa de CRUD (app/crud/): Operaciones de base de datos
  4. Capa de Modelos (app/models/): Modelos de SQLAlchemy
  5. Capa de Base de Datos (app/db/): Configuración de conexión

Esta arquitectura proporciona separación clara de responsabilidades y facilita el mantenimiento y las pruebas.

Desarrollo

Para desarrollo local:

  1. Clonar el repositorio
  2. Configurar entorno virtual
  3. Instalar dependencias
  4. Configurar variables de entorno
  5. Ejecutar migraciones
  6. Iniciar servidor de desarrollo

La aplicación incluye recarga automática durante el desarrollo y documentación interactiva disponible en /docs.