Autoparts-DB/docs/FASES_IMPLEMENTADAS.md

Nexus POS — Resumen de Fases Implementadas

Fecha: 2026-06-15 Versión DB: v4.3 Tests: 93/93 pasando (pytest: 61 consola + 20 Facturapi; POS requieren PostgreSQL) Commit: 6aff32f (HEAD + cambios sin commitear)

---

FASE 1-2: Fundamentos (pre-existente)

• ✅ CFDI 4.0 con Facturapi
• ✅ VIN Decoder (NHTSA)
• ✅ Lookup por placas mexicanas
• ✅ Carrito unificado multi-bodega
• ✅ Cotizaciones digitales → WhatsApp
• ✅ Auth JWT + roles

FASE 3: Multi-sucursal + Alertas + Garantías

Feature	Archivos	Endpoints
Multi-sucursal	inventory_engine.py, inventory_bp.py	GET /pos/api/inventory/stock-by-branch, POST /pos/api/inventory/transfers, POST /pos/api/inventory/sync-prices
Alertas de Reorden	reorder_engine.py	POST /pos/api/inventory/generate-alerts, GET /pos/api/inventory/reorder-alerts, PUT /pos/api/inventory/reorder-alerts/:id/acknowledge, PUT /pos/api/inventory/reorder-alerts/:id/resolve, GET /pos/api/inventory/reorder-suggest-po
Garantías / RMA	warranty_engine.py, warranty_bp.py	POST /pos/api/warranties, GET /pos/api/warranties, GET /pos/api/warranties/:id, GET /pos/api/customers/:id/warranties, POST /pos/api/warranty-claims, PUT /pos/api/warranty-claims/:id/resolve, PUT /pos/api/warranty-claims/:id/close

FASE 4: Infraestructura + Escalabilidad

Feature	Archivos	Infra
Redis Cache	redis_stock_cache.py, inventory_engine.py	Redis 8.0.2, TTL 300s, fallback a PostgreSQL
Multi-moneda	currency.py, pos_engine.py, cfdi_builder.py	MXN base, USD soporte, contabilidad siempre en MXN
Proveedores + POs	supplier_engine.py, supplier_bp.py	11 endpoints: CRUD proveedores + workflow PO completo
Meilisearch	meili_search.py, catalog_service.py, sync_meilisearch.py	Docker, 1.5M+ partes indexadas, búsqueda 4ms
Metabase KPIs	setup_metabase.py, docker-compose.metabase.yml	Docker v0.53, dashboard auto-generado

FASE 5: CRM + Service Orders + Imágenes

Feature	Archivos	Capacidades
CRM Mejorado	crm_engine.py, crm_bp.py	Activities timeline, tags de segmentación, loyalty program (bronze/silver/gold/platinum), analytics (LTV, churn risk, categorías favoritas)
Imágenes de Partes	image_service.py, image_bp.py	Upload multipart/URL, resize 1200px, thumbnail 300x300, WebP, bulk import
Órdenes de Servicio	service_order_engine.py, service_order_bp.py	Kanban: received→diagnosis→waiting_parts→repair→quality_check→ready→delivered, items (refacciones), labor (mano de obra), historial de status
WhatsApp	whatsapp_service.py, whatsapp_bp.py	Webhook Baileys, AI chatbot, cotizaciones, voz, imágenes
Flotillas	fleet_bp.py	CRUD vehículos, maintenance schedules, logs, alerts, stats
BNPL stub	bnpl_engine.py	Arquitectura APLAZO/Kueski/Clip
ERP Sync stub	erp_sync_engine.py	Arquitectura Aspel/Contpaqi/SAP/Odoo

FASE 6: Notificaciones + Ahorro + Logística + API Pública

Feature	Archivos	Capacidades
Notificaciones	notification_engine.py, notification_bp.py	Templates por evento+canal, dispatch automático (push/WhatsApp/email/in-app), logs con estados, eventos: low_stock, order_ready, maintenance_due, new_sale, po_received, reorder_alert, warranty_expiring
Reportes de Ahorro	savings_engine.py, savings_bp.py	Campo retail_price en inventory, cálculo automático en checkout, reporte por cliente (LTV ahorro, desglose mensual), reporte global (top clientes, promedio por orden)
Logística + Tracking	logistics_engine.py, logistics_bp.py	6 couriers pre-cargados (DHL, FedEx, Estafeta, 99min, Uber, Pickup), envíos vinculados a ventas/SO/PO, tracking URL auto-generada, historial de estatus
API Pública	public_api_engine.py, public_api_bp.py	API keys seguras (SHA-256), scopes (read/write/admin), rate limiting por minuto/día con headers, logging de requests, endpoints: /api/v1/health, /api/v1/catalog/search, /api/v1/catalog/parts/:id

FASE 7: Performance Optimización

Sub-fase	Archivos	Optimizaciones
7a — Quick Wins Frontend	nginx/nexus-pos.conf, pos/templates/*.html, pos/static/js/catalog.js	gzip nginx, defer en scripts, fix innerHTML += (8 lugares), event delegation cart, AbortController, sessionStorage cache years/brands
7b — DB Performance	pos/tenant_db.py, pos/services/inventory_engine.py, pos/services/pos_engine.py, pos/migrations/v3.2_db_performance.sql	Connection pooling (psycopg2.pool), tabla inventory_stock_summary + triggers O(1), fix N+1 process_sale, índices críticos
7c — Redis + Gthread	pos/services/catalog_service.py, pos/gunicorn.conf.py	_classify_cache en Redis (hit 6%→80%), vehicle info cache en smart_search(), gunicorn gthread (4 workers × 4 threads)
7d — Lazy Load + Minify	pos/static/js/catalog.js, nginx/nexus-pos.conf, scripts/minify-assets.sh	loading="lazy" en imágenes, minificación auto-serve vía nginx, cache warming script
7e — CSS Inline Extraction	scripts/extract-inline-css.py, 28 templates HTML, 28 archivos .css/.min.css	CSS inline extraído de 15 templates POS + 13 templates Dashboard a archivos externos, minificación, nginx auto-serve

Impacto acumulado FASE 7:

• Transferencia: -40–60%
• TTI: -200–500ms
• Stock lookups: O(n) → O(1)
• Ventas 20 ítems: 21 queries → 1 query
• Cache hit rate: 6% → 80%+

Opción C — Consolidación Técnica (COMPLETADA)

Item	Estado	Commit
C1: MV part_vehicle_preview	✅ En producción, refresh automático vía systemd timer (03:00 UTC)	f893391
C2: Cache warming script	✅ Autónomo con auto-sudo fallback, args CLI	f893391
C3: CSS dinámico residual	✅ sidebar.js → sidebar.css, pos-utils.js → common.css	042acd6
C4: Load testing script	✅ scripts/load_test.py con locust	042acd6
C5: Docs audit	✅ FASES_IMPLEMENTADAS.md, performance_audit_2026.md	042acd6

Opción A — Arquitectura Avanzada (COMPLETADA)

Item	Estado	Commit
A1: orjson como JSON provider	✅ Hereda DefaultJSONProvider, fix indent en pos_bp.py	a1be8dd
A2: Virtual scroll	✅ inventory.js, customers.js, fleet.js	a1be8dd
A3: Celery worker queue	✅ celery_app.py, tasks.py, tasks_bp.py, systemd service activo	a1be8dd
A4: Quart + asyncpg PoC	✅ async_catalog.py en puerto 5002, benchmark script	a1be8dd
A5: Particionamiento vehicle_parts	✅ Script partition_vehicle_parts.py listo (HASH 16 particiones, dry-run)	a1be8dd

IA por Voz — Chalán de Nexus (COMPLETADA)

Componente	Estado
STT (Speech-to-Text)	✅ POS + Dashboard público, es-MX, auto-send, animación micrófono
TTS (Text-to-Speech)	✅ Botón 🔊 en burbujas de IA, speechSynthesis, preferencia guardada en localStorage
Cobertura templates POS	✅ 14/14 templates tienen chat widget
Dashboard público	✅ Chat público con voz completa (sin cámara)

QWEN 3.6 AI Vehicle Fitment (COMPLETADA)

Componente	Archivo	Descripción
Servicio QWEN	pos/services/qwen_fitment.py	Consulta API OpenAI-compatible (qwen3.6) con part_number + name + brand; parsea JSON robusto (vehicles/confidence/notes); valida contra model_year_engine
Integración Inventario	pos/blueprints/inventory_bp.py	create_item() llama QWEN después de TecDoc auto-match; inserta en inventory_vehicle_compat con source='qwen_ai'
UI	pos/static/js/inventory.js, pos/templates/inventory.html	Toast muestra count de vehículos asignados por IA; tabla de compatibilidad muestra columna "Origen"
Retry / Fallback	qwen_fitment.py	3 reintentos ante respuesta vacía; fallback sin filtro de motor (descripciones de motor rara vez coinciden entre QWEN y TecDB); búsqueda parcial de modelo (%Corolla%) para nombres TecDoc

Flujo:

1. Usuario crea ítem de inventario (part_number, name, brand)
2. TecDoc auto-match ejecuta primero (si hay coincidencia exacta)
3. QWEN 3.6 recibe los datos y devuelve lista de vehículos compatibles en JSON
4. Cada vehículo se busca en la DB maestra (fuzzy match por modelo, fallback sin motor)
5. Los model_year_engine_id válidos se insertan en inventory_vehicle_compat con source='qwen_ai'
6. Frontend muestra toast: "27 vehículo(s) asignado(s) por IA"

Fail-safe: Si QWEN no está configurado o la API falla, el ítem se crea normalmente; la asignación de vehículos se omite silenciosamente.

---

Infraestructura Desplegada

Servicio	Versión	Puerto	Estado
PostgreSQL	17	5432	✅ Optimizado (8GB shared_buffers, 64MB work_mem, 8GB max_wal_size)
Redis	8.0.2	6379	✅ Stock cache + classify cache
Meilisearch	v1.12	7700	✅ 1,546,976 documentos
Metabase	v0.53	3000	✅ Dashboard ID 2
Nginx	—	80/443	✅ gzip, cache 6M, auto-serve .min
Gunicorn POS	—	5001	✅ systemd nexus-pos.service, gthread 4×4
Gunicorn Dashboard	—	5000	✅ systemd nexus.service
Quart Catalog	—	5002	✅ systemd nexus-quart.service, hypercorn
Celery	—	—	✅ 4 prefork workers, broker redis://localhost:6379/1
Prometheus	v2.51	9090	✅ Docker, node/postgres/redis exporters
Grafana	v10.4	3001	✅ Docker, auto-provisioned Prometheus datasource

---

Variables de Entorno Requeridas

# Base
MASTER_DB_URL=postgresql://user:pass@host/nexus_autoparts
TENANT_DB_URL_TEMPLATE=postgresql://user:pass@host/{db_name}
POS_JWT_SECRET=<32+ bytes hex>

# Redis
REDIS_URL=redis://localhost:6379/0
REDIS_ENABLED=true
REDIS_STOCK_TTL=300

# Meilisearch
MEILI_URL=http://localhost:7700
MEILI_API_KEY=nexus-master-key-change-me
MEILI_ENABLED=true

# Multi-moneda
DEFAULT_CURRENCY=MXN
EXCHANGE_RATE_USD_MXN=17.5

# WhatsApp (opcional)
WHATSAPP_BRIDGE_URL=http://localhost:21465
WHATSAPP_BRIDGE_KEY=

# AI (opcional)
OPENROUTER_API_KEY=

# QWEN AI Fitment (opcional)
QWEN_API_URL=https://api.nan.builders/v1
QWEN_API_KEY=
QWEN_MODEL=qwen3.6

# Metabase (opcional)
METABASE_DB_PASS=
METABASE_URL=http://localhost:3000

---

✅ Completados recientemente

#	Mejora	Fecha	Commit
—	Particionar vehicle_parts en producción	2026-04-26	f24f25e
—	Quart async catalog en producción	2026-04-26	b829e4f
—	Arreglar scripts/minify-assets.sh	2026-04-26	b829e4f
—	Dashboard outage fix (env vars + static files)	2026-04-26	27cb4ee
—	IA por Voz (STT + TTS) en POS y Dashboard	2026-04-26	afb3b24
—	Fix chat.js null reference (chatTtsToggle)	2026-04-29	44c3a6c
—	Optimizar PostgreSQL config + restart	2026-04-29	—
—	Cache warming systemd timer	2026-04-29	c766571
—	Monitoreo Prometheus + Grafana	2026-04-29	4b3b0f8
—	PWA install prompt	2026-04-29	3b8224d
—	Playwright E2E tests	2026-04-29	c4db5e7
—	Dashboard in-app charts	2026-04-29	12989e3
—	Stubs BNPL / ERP / WhatsApp Cloud / Supplier Portal	2026-04-29	2cfe4b3
—	nexus-pos.service systemd	2026-04-29	c766571
—	QWEN 3.6 AI Vehicle Fitment	2026-04-29	623c57b
—	Migración CFDI de Horux a Facturapi	2026-06-14	8796cad
—	Setup/estado masivo de organizaciones Facturapi	2026-06-15	—

FASE 7: Precios de Proveedor + Multi-sucursal + Factura Global

Commit: 2b73c2c (2026-06-11)

7.1 Lista de Precios de Proveedor

Feature	Archivos	Capacidades
Precios por proveedor	supplier_catalog_prices (master DB)	Precio, moneda, vigencia (effective_from/to), activo/inactivo
Upload masivo	supplier_catalog_bp.py	CSV/Excel con supplier_name, sku, price, currency
Visualización	catalog.js, catalog_service.py	supplier_price + supplier_currency en tarjetas y búsqueda
Endpoints	supplier_catalog_bp.py	GET/POST/PUT/DELETE /pos/api/supplier-catalog/prices/*

7.2 Multi-sucursal Completo

Feature	Archivos	Capacidades
Schema migration v4.0	v4.0_multi_branch.sql	inventory.branch_id=NULL (catálogo compartido), tabla inventory_stock
Datos fiscales por sucursal	branches (tenant DB)	rfc, razon_social, regimen_fiscal, codigo_postal, serie_cfdi, folio_inicial, licencia_fiscal, certificado_pem, llave_pem, is_main
Sincronización de stock	Trigger trg_update_inventory_stock	inventory_operations → inventory_stock automático
Backend branches	config_bp.py	CRUD completo con campos fiscales, validación de única sucursal is_main
Backend inventario	inventory_bp.py, inventory_engine.py, pos_bp.py	Stock por sucursal vía inventory_stock, catálogo compartido, verificación de stock en POS
Backend facturación	invoicing_bp.py	CFDI usa datos fiscales de la sucursal de la venta (_get_issuer_config)
Frontend config	config.html, config.js	Modal de sucursal expandido con todos los campos fiscales, edición inline

7.3 Factura Global Mensual

Feature	Archivos	Capacidades
Schema migration v4.1	v4.1_global_invoice.sql	global_invoice_sales, sales.global_invoiced_at
Builder CFDI global	cfdi_builder.py	build_global_invoice_xml() con InformacionGlobal SAT-compliant (Periodicidad="04")
Servicio	global_invoice.py	Agrupa ventas PUE ≤$2,000 sin CFDI individual del mes/año solicitado
Endpoints	invoicing_bp.py	POST /global-invoice, GET /global-invoice/<id>, GET /global-invoice/eligible-sales
Frontend	invoicing.html, invoicing.js	Botón "Factura Global" con modal de año/mes + vista previa de ventas elegibles

7.4 Mercado Libre — Mejoras

Feature	Archivos	Capacidades
Importar publicaciones existentes	meli_service.py, marketplace_external_service.py	get_user_items() + import_existing_listings() — importa items del vendedor a marketplace_listings intentando match por SKU/part_number
Sync stock POS → ML	inventory_engine.py, marketplace_external_service.py	Trigger en inventory_operations inserta en meli_sync_queue; process_meli_sync_queue() actualiza available_quantity en ML vía API
Sync órdenes ML → POS	marketplace_external_bp.py	POST /orders/sync para sincronización manual; webhook /webhook/meli ya maneja notificaciones de órdenes vía Celery
Migration v4.2	v4.2_meli_sync_queue.sql	Tabla meli_sync_queue para encolar actualizaciones de stock

---

FASE 8: Migración CFDI a Facturapi

Commit: 8796cad (2026-06-14)
Migración DB: v4.3_facturapi.sql

Feature	Archivos	Capacidades
Timbrado vía Facturapi	facturapi_service.py, cfdi_facturapi_builder.py, cfdi_queue.py	Payloads JSON para Facturapi en lugar de XML unsigned; timbrado, descarga XML/PDF, cancelación SAT
Organizaciones Facturapi	invoicing_bp.py	POST /pos/api/invoicing/facturapi/setup crea/liga organización; GET /pos/api/invoicing/facturapi/status muestra estado del PAC
Subida de CSD	invoicing_bp.py, invoicing.html, invoicing.js	Upload de .cer y .key con contraseña directo a Facturapi
Migración de datos	v4.3_facturapi.sql, scripts/apply_facturapi_to_all_tenants.py	Renombra xml_unsigned → payload_unsigned, agrega external_id, inserta keys de config
Setup masivo	scripts/setup_facturapi_orgs.py	Crea organizaciones Facturapi para todos los tenants activos usando FACTURAPI_USER_KEY
Status masivo	scripts/check_facturapi_tenants.py	Reporte tabular/JSON/CSV del estado de configuración Facturapi por tenant
Tests unitarios	pos/tests/test_facturapi_service.py	20 tests con mocks; sin llamadas a red ni PostgreSQL
CI	.github/workflows/ci.yml	Lint con ruff sobre archivos cambiados + tests de consola en Python 3.11 y 3.13

Variables de entorno

# Modo automático (recomendado para multi-tenant)
FACTURAPI_USER_KEY=sk_user_xxxxxxxxxxxxxxxx

# Modo manual por tenant (sobreescribe lo anterior)
# Se almacena en tenant_config: cfdi_facturapi_key, cfdi_facturapi_org_id

Uso

# 1. Aplicar migración y key a todos los tenants
export FACTURAPI_SECRET_KEY=sk_user_xxx
python3 scripts/apply_facturapi_to_all_tenants.py

# 2. Crear organizaciones Facturapi
export FACTURAPI_USER_KEY=sk_user_xxx
python3 scripts/setup_facturapi_orgs.py

# 3. Ver estado
python3 scripts/check_facturapi_tenants.py

---

Mejoras Pendientes (Roadmap Actualizado)

🔴 Crítico — Deuda Técnica

Sin items críticos pendientes.

🟠 Alto — Features de Negocio (requieren integración con terceros)

#	Mejora	Descripción	Esfuerzo	Notas
1	WhatsApp Business API (Meta Cloud) real	Migrar de Baileys a Meta Cloud API. Requiere verificación de cuenta Meta, Business Manager, número de teléfono verificado.	2-3 semanas	Stub creado (whatsapp_cloud_bp.py)
2	BNPL real	Integrar APLAZO/Kueski/Clip con credenciales de sandbox/producción.	2 semanas	Stub creado (bnpl_bp.py)
3	ERP Sync real	Conectar Aspel/CONTPAQi/SAP/Odoo vía API o archivos de intercambio.	2-3 semanas	Stub creado (erp_bp.py)
4	Mercado Libre / Amazon sync	Publicar inventario de bodegas en marketplaces. API de ML Seller + Amazon SP-API.	3 semanas	Parcialmente listo — ver Fase 7.4

🟡 Medio — Diferenciadores

#	Mejora	Descripción	Esfuerzo
5	App móvil nativa (Capacitor)	Wrap del POS como app iOS/Android. Camera nativa, push notifications, biometrics.	3-4 semanas
6	Crédito basado en comportamiento	Evaluación automática de línea de crédito por historial de pagos del cliente.	2 semanas
7	Programa de embajadores	Referidos con recompensas, tracking de conversiones.	1 semana

🟢 Bajo — Polish

#	Mejora	Descripción
8	Backup automatizado	Último backup 2026-04-27. Automatizar con cron + S3/GCS.
9	Grafana dashboards predefinidos	Actualmente solo datasource auto-provisionado. Falta crear dashboards JSON para PostgreSQL, Redis, Gunicorn.
10	Alertas Prometheus	Alertmanager para notificaciones cuando PostgreSQL, Redis o Gunicorn fallen.
11	Tests E2E adicionales	Playwright: checkout, búsqueda de catálogo, flujo de inventario.
12	Service Worker mejorado	Background sync real para carrito offline, notificaciones push.

---

Backup

Último backup: /home/Autopartes/backups/nexus_backup_20260427_045859.tar.gz (1.3 GB)