Schema de base de datos

ERP DLM usa PostgreSQL 16 con SQLAlchemy 2.0 async. Todas las entidades de negocio heredan de BaseModel, definido en backend/app/core/models.py.

Convenciones generales

Convención	Detalle
Clave primaria	UUID v4 (uuid.uuid4) generado por la aplicación
Timestamps	created_at y updated_at TIMESTAMPTZ, automáticos
Soft delete	No es consistente en todo el proyecto: verifica cada tabla
Nombres de columna	snake_case en inglés
Multi-empresa	company_id FK a companies.id cuando aplica

Mixins del core

class BaseModel(Base, TimeStampedMixin, UUIDMixin):
    """Base model con UUID PK + timestamps."""

• UUIDMixin → id: UUID PK.
• TimeStampedMixin → created_at, updated_at.
• SoftDeleteMixin → deleted_at (NULL = activo).
• AuditableMixin → created_by, updated_by.

Soft delete: advertencia importante

No todas las tablas usan el mismo mecanismo de borrado lógico. Antes de filtrar por is_deleted, consulta el esquema real de la tabla (\d <tabla> en psql) o revisa el modelo SQLAlchemy.

Mecanismo	Tablas de ejemplo
is_deleted BOOLEAN DEFAULT false	sales_invoices
is_active BOOLEAN DEFAULT true	clients, products, suppliers, agents, accounts, subaccounts
deleted_at TIMESTAMPTZ	Varias tablas que usan SoftDeleteMixin

Mapeo de nombres reales

Las siguientes tablas y columnas están verificadas contra el código y el esquema real:

Tabla	Columnas principales	Notas
companies	name, tax_id, email, phone, address, city, state, zip_code, country, is_active	Empresa multi-tenant
clients	name, tax_id, email, phone, address, city, postal_code, province, country_code, client_type, is_active, registration_date, discount_percent, credit_limit, agent_id	NO first_name/last_name
suppliers	name, tax_id, email, phone, address, is_active	Similar a clients
agents	first_name, last_name, code, is_active, commission_percent	SÍ tiene first_name/last_name
products	reference, description, sale_price, cost_price, is_active, family_id, subfamily_id, brand_id	NO is_deleted
accounts	code, description, account_type, is_active	Plan contable
subaccounts	code, description, account_code, is_active	Subcuentas
entry_lines	entry_id, subaccount_code, debit, credit, description, is_active	Numeric(20,2)
sales_invoices	date, document_number, total_amount, grand_total, net_total, tax_total, surcharge_total, irpf_percent, irpf_amount, status, is_deleted	Única tabla de documentos con is_deleted
bank_accounts	code, description, iban, subaccount_code, initial_balance, is_active	Tesorería
customer_receipts	invoice_id, receipt_number, amount, paid_amount, issue_date, due_date, status	Cobros
families	code, name	Familias de producto
fiscal_years	code, name, start_date, end_date, is_active	Ejercicios fiscales

Relaciones multi-empresa

• Cada fila de tenant en saas_manager (base de datos separada) define db_name, db_user, db_password y status.
• Dentro de la BD del tenant, muchas tablas de negocio incluyen company_id para separar empresas.
• Si company_id es NULL, el registro se considera global o compartido (depende del módulo).

Tipos comunes

Tipo de dato	Uso
UUID	Claves primarias y claves foráneas
TIMESTAMPTZ	Fechas con hora y zona
DATE	Fechas sin hora (vencimientos, ejercicios)
NUMERIC(20,2)	Importes monetarios
TEXT	Notas largas
JSONB	Campos flexibles / metadatos
BOOLEAN	Flags activo/eliminado

Buenas prácticas al añadir tablas

1. Hereda de BaseModel para UUID y timestamps automáticos.
2. Decide el mecanismo de borrado lógico y mantenlo consistente dentro del módulo.
3. Añade índices en columnas de búsqueda frecuente (name, tax_id, code).
4. Usa company_id cuando el dato pertenezca a una empresa concreta.
5. Crea la migración Alembic correspondiente.