Enterprise Asset and Workflow Management Platform

API REST para la gestion integral de activos empresariales, inventario, usuarios y auditoria en entornos corporativos.

Objetivo

Plataforma backend que permite a las empresas administrar sus activos tecnologicos (laptops, desktops, monitores, impresoras, servidores, etc.), controlar el inventario, asignar activos a empleados, gestionar usuarios con roles y mantener un registro completo de auditoria de todas las acciones realizadas en el sistema.

Stack Tecnologico

Capa	Tecnologia
Framework	FastAPI
Lenguaje	Python 3.14
Base de datos	PostgreSQL 16
ORM	SQLAlchemy
Migraciones	Alembic
Autenticacion	JWT (OAuth2 + bcrypt)
Validacion	Pydantic v2
Testing	pytest
Contenedores	Docker + Docker Compose

Arquitectura Hexagonal

El proyecto sigue una arquitectura hexagonal (puertos y adaptadores) con separacion clara de responsabilidades:

domain/           Nucleo puro: entidades, repositorios (ABC), excepciones
application/      Casos de uso y servicios
infrastructure/   Adaptadores: modelos SQLAlchemy, repositorios concretos
presentation/     Adaptadores HTTP: routers FastAPI, schemas Pydantic, mappers
core/             Configuracion transversal: DB, JWT, settings

Flujo de dependencias:

Presentation → Application → Domain ← Infrastructure

Estructura del Proyecto

.
├── main.py                              # Entry point FastAPI
├── .env                                 # Variables de entorno
├── alembic.ini                          # Configuracion Alembic
├── requirements.txt                     # Dependencias
├── Dockerfile                           # Imagen Docker
├── docker-compose.yml                   # Orquestacion
│
├── core/
│   ├── config.py                        # Settings con pydantic-settings
│   ├── database.py                      # Engine, SessionLocal, Base, get_db()
│   └── security.py                      # JWT + bcrypt
│
├── domain/
│   ├── entities/
│   │   ├── user.py                      # Entidad User
│   │   ├── asset.py                     # Entidades AssetEntity, AssetEntityUpdate
│   │   ├── stock.py                     # Entidad InventoryEntity
│   │   ├── audit_log.py                 # Entidad AuditLogEntity
│   │   └── form_request.py              # Entidad FormRequest
│   ├── repositories/
│   │   ├── user_repository.py           # ABC UserRepository
│   │   ├── asset_repository.py          # ABC AssetRepository
│   │   └── audit_log_repository.py      # ABC AuditLogRepository
│   └── exceptions/
│       ├── user.py                      # Excepciones de usuario
│       └── asset.py                     # Excepciones de activo
│
├── application/
│   ├── use_cases/
│   │   ├── user_cases.py                # CRUD de usuarios
│   │   ├── assets_cases.py              # CRUD de activos
│   │   ├── login_user.py                # Login y perfil
│   │   ├── auth_user.py                 # Autenticacion JWT
│   │   └── audit_log_cases.py           # Consulta de logs de auditoria
│   └── services/
│       └── asset_code_generator.py      # Generador de codigos AST-XXXXXXXX
│
├── infrastructure/
│   ├── data/models/
│   │   ├── user.py                      # Modelo SQLAlchemy users
│   │   ├── asset.py                     # Modelos: Asset, Brand, Model, Type, Status, Location
│   │   ├── stock.py                     # Modelo SQLAlchemy inventory
│   │   └── audit_log.py                 # Modelo SQLAlchemy audit_log + Enums
│   └── repositories/
│       ├── user_repositories.py         # SQLAlchemyUserRepository
│       ├── asset_repository.py          # SQLAlchemyAssetRepository
│       ├── stock_repository.py          # SQLAlchemyInventoryRepository
│       └── audit_log_repository.py      # SQLAlchemyAuditLogRepository
│
├── presentation/
│   ├── api/
│   │   ├── routers/
│   │   │   ├── auth.py                  # /login, /login/auth, /login/me
│   │   │   ├── users.py                 # /users/*
│   │   │   ├── asset.py                 # /assets/*
│   │   │   └── audit_log.py             # /audit-logs/*
│   │   └── schemas/
│   │       ├── user.py                  # Pydantic: UserCreate, UserResponseModel
│   │       ├── asset_schema.py          # Pydantic: AssetCreate, AssetPatch, AssetResponseModel
│   │       └── audit_log.py             # Pydantic: AuditLogResponseModel
│   └── mappers/
│       └── asset_mapper.py              # Mappers: schemas → entidades
│
├── alembic/
│   ├── env.py                           # Configuracion de migraciones
│   └── versions/
│       ├── 3c52cfd9a747_create_users_table.py
│       └── 45c4d54299f3_create_audit_log_table.py
│
├── scripts/
│   ├── seed_test.py                     # Seed: usuarios admin_test y customer_test
│   └── seed_test_assets.py              # Seed: marcas, modelos, tipos, status, ubicaciones
│
└── tests/
    ├── conftest.py                      # Fixtures y override de DB
    ├── helpers/
    │   └── auth_helpers.py              # get_admin_token()
    ├── application/
    │   ├── fakes/
    │   │   ├── fake_user_repository.py
    │   │   ├── fake_asset_repository.py
    │   │   ├── fake_stock_repository.py
    │   │   └── fake_audit_log_repository.py
    │   └── use_cases/
    │       ├── test_user_cases.py
    │       ├── test_asset_case.py
    │       ├── test_login_case.py
    │       ├── test_auth_case.py
    │       └── test_audit_log_case.py
    └── presentation/api/
        ├── test_user_api.py
        ├── test_asset_api.py
        ├── test_auth.py
        └── test_audit_log_api.py

Requisitos

• Python 3.14+
• PostgreSQL 16+
• Docker y Docker Compose (opcional)

Instalacion Local

1. Clonar el repositorio

git clone https://github.com/tu-usuario/ProyectoGestionActivos.git
cd ProyectoGestionActivos

2. Crear entorno virtual

python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

3. Instalar dependencias

pip install -r requirements.txt

4. Configurar variables de entorno

Crear un archivo .env en la raiz del proyecto:

DATABASE_URL=postgresql+psycopg://postgres:1234@localhost:5432/asset_db_test
JWT_SECRET_KEY=tu-clave-secreta-aqui
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

5. Crear la base de datos

CREATE DATABASE asset_db_test;

6. Ejecutar migraciones

alembic upgrade head

7. Poblar datos iniciales (opcional)

python scripts/seed_test.py
python scripts/seed_test_assets.py

8. Iniciar el servidor

uvicorn main:app --reload --port 8000

La API estara disponible en http://localhost:8000

Documentacion interactiva en http://localhost:8000/docs

Instalacion con Docker

docker compose up --build

Esto levanta:

• PostgreSQL en el puerto 5432
• API FastAPI en el puerto 8000
• Ejecuta alembic upgrade head automaticamente al iniciar

Para detener:

docker compose down

Para eliminar volumenes de datos:

docker compose down -v

Credenciales de Prueba

Despues de ejecutar los seeds, el sistema viene con:

Usuario	Contrasena	Rol
admin_test	1234	admin
customer_test	1234	Employee

Endpoints

Autenticacion

Metodo	Ruta	Autenticacion	Descripcion
POST	/login	No	Iniciar sesion (OAuth2 form)
POST	/login/auth	Si	Validar token y obtener usuario
GET	/login/me	Si	Obtener perfil del usuario logueado

Usuarios

Metodo	Ruta	Autenticacion	Descripcion
POST	/users/register	No	Registrar usuario
GET	/users/	No	Listar todos los usuarios
PUT	/users/{id}	Admin	Actualizar usuario
DELETE	/users/{id}	Admin	Desactivar usuario (soft delete)
PATCH	/users/make-admin/{id}	Admin	Promover a admin
PATCH	/users/remove-admin/{id}	Admin	Remover rol de admin

Activos

Metodo	Ruta	Autenticacion	Descripcion
POST	/assets/register	Si	Registrar activo
GET	/assets/	Si	Listar todos los activos
GET	/assets/{id}	Si	Obtener activo por ID
PATCH	/assets/{id}	Admin	Actualizar activo
DELETE	/assets/{id}	Admin	Desactivar activo
PUT	/assets/active/{id}	Admin	Activar activo
PATCH	/assets/{asset_id}/assign	Admin	Asignar activo a usuario
PATCH	/assets/{asset_id}/return	Admin	Devolver activo

Auditoria

Metodo	Ruta	Autenticacion	Descripcion
GET	/audit-logs/	Admin	Obtener todos los logs
GET	/audit-logs/user/{user_id}	Admin	Logs por usuario
GET	/audit-logs/entity/{entity_type}	Admin	Logs por tipo (asset, user, inventory)

Entities de Auditoria

El sistema registra automaticamente las siguientes acciones:

Entity	Acciones
user	CREATE, UPDATE, DELETE, LOGIN_SUCCESS, LOGIN_FAILED, ADMIN_PROMOTED, ADMIN_REMOVED
asset	CREATE, UPDATE, DEACTIVATE, ACTIVATE, ASSIGN, RETURN

Cada log incluye: entity_type, entity_id, action, user_id, details, timestamp.

Comandos Utiles

# Servidor en desarrollo
uvicorn main:app --reload --port 8000

# Ejecutar todos los tests
python -m pytest tests/ -v

# Tests unitarios (sin DB)
python -m pytest tests/application/ -v

# Tests de integracion (con DB)
python -m pytest tests/presentation/ -v

# Tests de un archivo especifico
python -m pytest tests/application/use_cases/test_asset_case.py -v

# Generar migracion (requiere DB corriendo)
alembic revision --autogenerate -m "descripcion del cambio"

# Aplicar migraciones
alembic upgrade head

# Rollback de la ultima migracion
alembic downgrade -1

# Ver historial de migraciones
alembic history

# Poblar datos de prueba
python scripts/seed_test.py
python scripts/seed_test_assets.py

# Docker
docker compose up --build
docker compose down
docker compose down -v

Base de Datos

Tablas

Tabla	Descripcion
users	Usuarios del sistema (id, username, email, password, role, is_active, created_at, deleted_at)
assets	Activos empresariales (id, name, description, asset_code, serial_number, FKs a catalogos)
asset_type	Catalogo de tipos: Laptop, Desktop, Monitor, Printer, Scanner, Server, etc.
brand	Catalogo de marcas: Dell, HP, Lenovo, Apple, Asus, etc.
model	Catalogo de modelos por marca
status	Estados del activo: active, inactive, assigned, maintenance
location	Ubicaciones: Head Office, IT Department, Server Room, etc.
inventory	Stock por modelo de activo
audit_log	Registro de auditoria de todas las acciones

Diagrama de Relaciones

users ─────────────< assets (assigned_to)
assets ────────────> asset_type (FK)
assets ────────────> status (FK)
assets ────────────> location (FK)
assets ────────────> model (FK)
model ─────────────> brand (FK)
inventory ─────────> model (FK)
audit_log ─────────> users (FK, user_id)

Seguridad

• Autenticacion via OAuth2 + JWT
• Passwords hasheados con bcrypt
• Endpoints protegidos por roles (admin_required, auth_user)
• Soft delete para usuarios (no se eliminan fisicamente)
• La tabla audit_log registra cada accion con timestamp y usuario

Licencia

Este proyecto es privado. Todos los derechos reservados.