305 lines
14 KiB
Markdown
305 lines
14 KiB
Markdown
# Flujo del Proceso — ComercioNet
|
||
|
||
## Visión General
|
||
|
||
```
|
||
[Emisor (Walmart, etc.)]
|
||
│
|
||
│ Envía XML OC vía AS2 / SFTP
|
||
▼
|
||
┌─────────────────┐
|
||
│ data/input/ │ ← Carpeta de llegada
|
||
└────────┬────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────────────────┐
|
||
│ main.py │
|
||
│ (servicio NSSM, loop con schedule) │
|
||
│ │
|
||
│ Lun–Dom 08:00–18:00 → cada 10 min │
|
||
│ Lun–Dom 18:00–23:00 → cada 1 hora │
|
||
│ Fuera de horario → dormido │
|
||
└────────┬─────────────────────────────────────────┘
|
||
│ importa service.py
|
||
▼
|
||
┌─────────────────────────────────────────────────-─┐
|
||
│ service.py │
|
||
│ │
|
||
│ 1. Leer XML de data/input/ │
|
||
│ 2. Parsear (strip ns → extraer campos) │
|
||
│ 3. Calcular descuentos secuenciales │
|
||
│ 4. Generar JSON intermedio → data/output/ │
|
||
│ 5. Generar HTML visual → data/html/ │
|
||
│ 6. SAP: resolver CardCode, catálogo, precios │
|
||
│ 7. Generar email HTML → data/html/*_email.html │
|
||
│ 8. Construir payload Draft │
|
||
│ 9. Validar precios contra SAP (todas las líneas) │
|
||
│ ├── Todo OK → POST /Orders │
|
||
│ └── Diferencias → log + envío email │
|
||
│ 10. Mover XML a data/processed/ │
|
||
└────────┬──────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────┐
|
||
│ data/sap_b1/ │ ← payload Draft (*_sap.json)
|
||
│ (siempre se crea) │
|
||
└─────────────────────┘
|
||
```
|
||
|
||
## Archivos del sistema
|
||
|
||
```
|
||
comercio-net/
|
||
├── main.py ← Entry point del servicio NSSM
|
||
├── logger_manager.py ← Configuración de logging jerárquico con formato de árbol
|
||
├── service.py ← Lógica: parseo, descuentos, JSON, HTML, SAP
|
||
├── sapb1_manager.py ← Conexión SAP B1 Service Layer (login, create_orders)
|
||
├── sapb1_mapper.py ← Transforma JSON intermedio → payload Draft SAP
|
||
├── sql_manager.py ← Conexión SQL Server (catálogo OSCN, precios ITM1, CardCode)
|
||
├── email_reporter.py ← Genera HTML para correo con validación de precios
|
||
├── mail_sender.py ← Envío SMTP de correos (texto plano + HTML)
|
||
├── template.html ← Plantilla HTML flat (Jinja2)
|
||
├── .env ← Credenciales SAP B1, SQL Server y correo
|
||
├── .gitignore ← Excluye logs/, __pycache__/, .env, .DS_Store
|
||
├── requirements.txt ← Dependencias Python
|
||
│
|
||
├── data/
|
||
│ ├── input/ ← XML entrantes (el servicio vacía esta carpeta)
|
||
│ ├── processed/ ← XML ya procesados (backup)
|
||
│ ├── output/ ← JSON intermedio generado
|
||
│ ├── html/ ← HTML visual + HTML para correo (*_email.html)
|
||
│ ├── sap_b1/ ← Payload Draft SAP (*_sap.json, siempre generado)
|
||
│ └── errors/ ← XML que fallaron (ej: socio de negocios no encontrado)
|
||
│
|
||
├── logs/ ← Logs rotativos diarios (30 días de respaldo)
|
||
│ └── comercio-net.log
|
||
│
|
||
├── test/
|
||
│ ├── b1.json ← Plantilla de payload SAP para pruebas
|
||
│ └── sl.http ← Peticiones HTTP para VS Code REST Client
|
||
│
|
||
└── docs/
|
||
├── parser_spec.md ← Especificación detallada del parseo XML
|
||
├── logging_spec.md ← Especificación del sistema de logging
|
||
└── flujo.md ← Este documento
|
||
```
|
||
|
||
## Flujo detallado del servicio
|
||
|
||
### 1. Inicio (`main.py`)
|
||
|
||
```
|
||
main()
|
||
├── signal.signal(SIGINT/SIGTERM) → _running = False
|
||
├── Loop infinito while _running:
|
||
│ ├── ¿Día activo? (Lun–Dom, todos los días)
|
||
│ │ └── No → dormir hasta próximo día activo
|
||
│ ├── ¿Dentro de horario?
|
||
│ │ ├── 08:00–18:00 → intervalo = 600s (10 min)
|
||
│ │ ├── 18:00–23:00 → intervalo = 3600s (1 hora)
|
||
│ │ └── Fuera → dormir hasta las 08:00
|
||
│ ├── Ejecutar process_all()
|
||
│ └── Dormir intervalo
|
||
```
|
||
|
||
### 2. Procesamiento (`service.py`)
|
||
|
||
```
|
||
process_all()
|
||
├── Crea data/input/ si no existe
|
||
├── Leer archivos de data/input/
|
||
├── Por cada archivo:
|
||
│ ├── process_file(xml_path)
|
||
│ │ ├── parse_order(xml_bytes) → dict (JSON intermedio)
|
||
│ │ ├── write_json(data, output/*.json)
|
||
│ │ ├── write_html(data, html/*.html)
|
||
│ │ ├── [SAP habilitado]:
|
||
│ │ │ ├── get_client_by_gln(emisor, lugar) → {CardCode, City, County}
|
||
│ │ │ │ └── Si no encontrado → send_mail() + mover a data/errors/
|
||
│ │ │ ├── get_item_catalog(cardcode) → {UPC: ItemCode}
|
||
│ │ │ ├── get_price_list(cardcode) → ListNum
|
||
│ │ │ ├── get_prices(ListNum) → {ItemCode: Price}
|
||
│ │ │ ├── get_card_name(cardcode) → CardName
|
||
│ │ │ ├── generate_email_html() → html/*_email.html
|
||
│ │ │ ├── to_draft_payload() → payload Draft
|
||
│ │ │ ├── write_json(payload, sap_b1/*_sap.json)
|
||
│ │ │ ├── Validar todas las líneas (precio XML vs SAP)
|
||
│ │ │ │ ├── Todas OK → create_orders(payload)
|
||
│ │ │ │ └── Diferencias → send_validation_email() + omitir envío
|
||
│ │ │ └── (errores no bloquean, se loguean)
|
||
│ │ └── move a data/processed/
|
||
│ └── Si error → log + continúa con siguiente
|
||
```
|
||
|
||
### 3. Parseo del XML (`service.py.parse_order`)
|
||
|
||
```
|
||
parse_order(xml_bytes, filename)
|
||
├── _strip_ns(root) ← Elimina namespaces (soporta con/sin prefijo)
|
||
├── Extraer cabecera:
|
||
│ ├── Emisor / Receptor
|
||
│ ├── N° OC (uniqueCreatorIdentification)
|
||
│ ├── Fechas (creationDate, movementDate)
|
||
│ ├── Condiciones de pago (paymentTerms)
|
||
│ ├── Lugar de entrega (shipParty GLN)
|
||
│ ├── Dpto. ventas, Tipo OC, Promoción, Proveedor
|
||
│ └── Transporte (mainCarrierTransport)
|
||
├── Por cada lineItem:
|
||
│ ├── Precio, Cantidad (CS/CSC), Unid/empaque (SIN)
|
||
│ ├── GTIN, Item (buyer), Cód. Prov. (vendor)
|
||
│ ├── Color / Talla
|
||
│ ├── allowanceCharge (0..N)
|
||
│ ├── apply_allowances(netPrice, qty, allowances) → total calculado
|
||
│ └── precio_efectivo = total_calculado / qty
|
||
├── Calcular totales (suma de importes)
|
||
└── Devolver dict con metadata, cabecera, detalle, totales
|
||
```
|
||
|
||
### 4. Algoritmo de descuentos (`service.py.apply_allowances`)
|
||
|
||
```
|
||
base_total = netPrice × requestedQuantity
|
||
|
||
Para cada allowanceCharge con percentage > 0:
|
||
descuento = redondear(base_total × % / 100)
|
||
base_total = base_total - descuento
|
||
|
||
totalAmount = base_total
|
||
```
|
||
|
||
- Los descuentos se aplican **secuencialmente** sobre el saldo restante
|
||
- El redondeo es a entero (.5 hacia arriba)
|
||
- El resultado debe coincidir con `totalAmount` del XML
|
||
|
||
## Formatos de salida
|
||
|
||
### JSON intermedio (`data/output/*.json`)
|
||
|
||
```json
|
||
{
|
||
"metadata": {
|
||
"archivo": "925485K200...xml",
|
||
"procesado": "2026-07-21T10:00:00"
|
||
},
|
||
"cabecera": {
|
||
"emisor": "925485K200",
|
||
"receptor": "7800AD0CL0001",
|
||
"numero_oc": "780790022025012792230",
|
||
"fecha_generacion": "2026-07-14T00:00:00",
|
||
"fecha_embarque": "2026-07-17",
|
||
"condiciones_pago": "NET 60 días desde fecha de factura",
|
||
"lugar_entrega": "7807900001686",
|
||
"dpto_ventas": "92",
|
||
"tipo_oc": "20",
|
||
"promocion": "POS REPLEN",
|
||
"numero_proveedor": "006205920",
|
||
"observaciones": "NO PRETICKET"
|
||
},
|
||
"detalle": [
|
||
{
|
||
"linea": "000001",
|
||
"cod_upc": "17730976822923",
|
||
"item": "000706071",
|
||
"cod_prov": "PONT2292",
|
||
"color_talla_um": "CAJ / 520GR",
|
||
"descripcion": "PURE DE TOMATE CJ",
|
||
"precio_original": 8148,
|
||
"moneda": "CLP",
|
||
"allowances": [],
|
||
"precio_efectivo": 8148,
|
||
"empaques": 510,
|
||
"unidad_empaque": "CSC",
|
||
"unid_empaque": 12,
|
||
"cantidad_unid": 6120,
|
||
"importe": 4155480
|
||
}
|
||
],
|
||
"totales": {
|
||
"importe_total": 31590312,
|
||
"moneda": "CLP"
|
||
}
|
||
}
|
||
```
|
||
|
||
### HTML visual (`data/html/*.html`)
|
||
|
||
Renderiza la misma información en una tabla plana auto-contenida, sin dependencias externas. Usa Jinja2 con la plantilla `template.html`.
|
||
|
||
### HTML para correo (`data/html/*_email.html`)
|
||
|
||
Generado por `email_reporter.generate_email_html()`. Incluye:
|
||
|
||
- **Cabecera**: N° OC, Fecha Entrega, Cliente (CardCode — CardName)
|
||
- **Tabla detalle**: cod_upc, empaques, color_talla_um, unid_empaque, cantidad_unid, Importe, precio_unidad, ItemCode, Precio SAP, Texto, descripción
|
||
- **Columna Texto**: indica si el ítem tiene catálogo, precio SAP, y si el precio XML difiere del SAP
|
||
|
||
### Payload SAP Draft (`data/sap_b1/*_sap.json`)
|
||
|
||
Generado por `sapb1_mapper.to_draft_payload()`. Se crea **siempre** (incluso si hay diferencias de precio). Solo se envía a SAP si todas las líneas pasan la validación de precios.
|
||
|
||
## Módulos SAP
|
||
|
||
| Módulo | Función |
|
||
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `sql_manager.py` | Conexión SQL Server vía `pymssql`. Queries a CRD1 (CardCode/City/County por GLN), OSCN (catálogo por BP), OCRD (lista precios, CardName), ITM1 (precios) |
|
||
| `sapb1_mapper.py` | `to_draft_payload()` — transforma JSON intermedio + datos resueltos → payload Draft SAP B1 (incluye AddressExtension con City/County) |
|
||
| `sapb1_manager.py` | `login()` + `create_orders()` — autenticación Service Layer y POST /Orders |
|
||
| `email_reporter.py` | `generate_email_html()` — genera HTML para correo con tabla de validación |
|
||
| `mail_sender.py` | `send_mail()` + `send_validation_email()` — envío SMTP de notificaciones y validación de precios |
|
||
|
||
## Funciones SQL (`sql_manager.py`)
|
||
|
||
| Función | Retorna | Descripción |
|
||
| ---------------------- | --------------- | -------------------------------------------------------- |
|
||
| `get_client_by_gln()` | `{CardCode, City, County}` | Busca socio de negocios por GLN en CRD1 (dirección envío) |
|
||
| `get_item_catalog()` | `{UPC: ItemCode}` | Catálogo de sustitutos (UPC → código SAP) |
|
||
| `get_price_list()` | `int` o `None` | Número de lista de precios del socio de negocios |
|
||
| `get_prices()` | `{ItemCode: Price}` | Todos los precios de una lista dada |
|
||
| `get_card_name()` | `str` o `None` | Nombre del socio de negocios |
|
||
|
||
## Funciones correo (`mail_sender.py`)
|
||
|
||
| Función | Descripción |
|
||
| ------------------------ | ------------------------------------------------------------------------ |
|
||
| `send_mail()` | Envía correo de texto plano (notificación de error, ej: CardCode no encontrado) |
|
||
| `send_validation_email()`| Envía correo HTML con tabla de validación de precios y catálogo |
|
||
|
||
## Validación de precios
|
||
|
||
Por cada línea del detalle se calcula `precio_xml = importe / cantidad_unid` y se compara con `Precio SAP` (desde ITM1):
|
||
|
||
- **Sin catálogo**: el UPC no tiene Substitute en OSCN
|
||
- **Sin precio SAP**: el ItemCode no tiene precio en ITM1
|
||
- **Precio difiere**: precio XML ≠ precio SAP
|
||
- **OK**: todo coincide
|
||
|
||
Si **alguna** línea tiene diferencia, se envía correo de validación (pero el payload y el email HTML se generan igual). El envío a SAP (`create_orders`) se omite.
|
||
|
||
## Errores y carpetas
|
||
|
||
| Escenario | Acción |
|
||
| -------------------------------- | --------------------------------------------------- |
|
||
| XML malformado o sin `<order>` | Se loguea error, se continúa con siguiente archivo |
|
||
| CardCode no encontrado en CRD1 | Se envía `send_mail()`, se mueve XML a `data/errors/` |
|
||
| Error de conexión SAP/SQL | Se loguea, no bloquea procesamiento de siguientes archivos |
|
||
|
||
## Schedule del servicio
|
||
|
||
| Días | Rato | Intervalo |
|
||
| ------- | ------------- | ---------- |
|
||
| Lun–Dom | 08:00 – 18:00 | 10 minutos |
|
||
| Lun–Dom | 18:00 – 23:00 | 1 hora |
|
||
| Lun–Dom | 23:00 – 08:00 | Dormido |
|
||
|
||
> **Nota**: El servicio está activo **todos los días** de la semana (lunes a domingo).
|
||
|
||
## Notas
|
||
|
||
- El nombre del archivo XML no determina el contenido; todos los datos se extraen del XML.
|
||
- El archivo se mueve a `processed/` solo después de generar exitosamente JSON, HTML visual, email HTML y payload SAP.
|
||
- Si un archivo falla (XML mal formado, sin elemento `<order>`, etc.), se loguea el error y se continúa con el siguiente.
|
||
- Los errores de conexión SAP o SQL Server no bloquean el procesamiento de archivos posteriores.
|
||
- Las variables de entorno están en `.env` (no `.env.dev`).
|
||
- `INPUT_DIR` puede ser ruta absoluta (ej: `C:\Comercionet\IN` en producción) o relativa (`data/input` por defecto).
|
||
- El payload SAP incluye `AddressExtension` con `BillToCity` y `BillToCounty` obtenidos de CRD1.
|