SDEN Logistics Workspace

This repository hosts two Django 5 apps that support SDEN logistics operations:

• SimCore – a simulation sandbox for capacity planning and KPI what-if analysis.
• ControlTower – an operational dashboard focused on real data ingestion, reconciliation, and alerting.

Both apps share the same Django project (config/) and PostgreSQL database.

---

Prerequisites

• Python 3.11
• PostgreSQL 14+ (or SQLite for quick local tests)
• Recommended tools: pipenv or virtualenv, psql

Install Python dependencies:

python -m pip install -r requirements.txt

Database connection is read from the usual Django environment variables:

Variable	Default
POSTGRES_DB	simcore
POSTGRES_USER	simcore
POSTGRES_PASSWORD	simcore
POSTGRES_HOST	localhost
POSTGRES_PORT	5432

Override them in your environment or .env file before running migrations.

---

Initial Setup

# 1. Install requirements (see above)

# 2. Apply migrations
python manage.py migrate

# 3. Create an admin/staff account
python manage.py createsuperuser

# 4. (Optional) Seed SimCore sample data
python manage.py sim_seed

# 5. Start the development server
python manage.py runserver

Access the apps:

• SimCore dashboard: http://127.0.0.1:8000/sim/
• ControlTower dashboard: http://127.0.0.1:8000/ct/

Authentication is required for both (is_staff users only for ControlTower).

---

SimCore Recap

• Models for SKUs, warehouses, services, movements, runs, metrics, and events (simcore/models.py:15).
• Simulation engine with KPI calc and risk scoring (simcore/engine.py:14).
• Management commands:
  • python manage.py sim_seed
  • python manage.py sim_run --profile realistic --days 60 --seed 42
• Tailwind+Chart.js dashboards to launch runs, review metrics, inspect events.
• CSV exports for movements, metrics, and events.
• Unit tests covering illegal flow detection (simcore/tests/test_engine.py:30).

---

ControlTower Overview

ControlTower ingests real SDEN Excel/CSV files, runs reconciliation checks, highlights anomalies, and prepares exports/mails.

Data Model Highlights

• CTFile, MapColumn manage uploads and header mappings (controltower/models.py:18).
• Staging tables: StockSnap, Movement, OFAudit, InvoiceNST, ODL, ReqMaterial.
• Findings & settings: CTFinding, CTSetting, CTDDTAttachment.

Upload & Parsing

• Supported profiles: stock_sden, mov_sden, of_audit, req_materiali, fatture_nst, odl.
• Column mappings configurable in /ct/settings/. Required columns enforced per profile.
• Parsers handle CSV/XLSX via openpyxl (controltower/parsers.py:20).
• Raw files stored under media/controltower/uploads/.

Key Pages

URL	Purpose
/ct/	KPI cards, Chart.js micro charts, latest alerts, backlog cards.
/ct/uploads/	Upload new files, view ingestion history and parsing outcome.
/ct/reconcile/	Runs server-side checks (stock accuracy, red-tag serials, DdT, ODL, etc.) and lists findings.
/ct/ddt/	Serial/DdT review, OF audit status, quick actions (attach DdT, mark lost/available).
/ct/invoices/	Invoice vs movement matching (±2% threshold) with export.
/ct/exports/	CSV downloads (findings, DdT missing, seriali non tracciati, fatture) + HTML mail draft.
/ct/settings/	Column mapping CRUD and threshold overrides.

Reconciliation & KPI Logic

• Stock accuracy compares latest StockSnap vs net movements (7-day window).
• Serial red-tags detected for missing in, double install, returns without outbound (controltower/services.py:58).
• OF audit cross-check ensures DdT presence and follow-up for “In verifica SDEN”.
• Invoice matching flags discrepancies beyond TH_MATCH_FATTURE (default 0.02).
• Findings persisted in CTFinding (codes like stock-accuracy-gap, ddt-missing, fattura-scarto).
• CSV/email exports leverage these findings for rapid sharing.

Threshold Defaults

Stored in CTSetting (auto-created on first access, editable in /ct/settings/):

• TH_STOCK_ACCURACY_GAP = 0.05
• TH_RED_TAG = true
• TH_MATCH_FATTURE = 0.02

---

Testing

Run the full test suite:

python manage.py test

Key coverage:

• Parser normalization & mapping (controltower/tests/test_parsers.py:8).
• Red-tag detection (controltower/tests/test_services.py:13).
• Invoice discrepancy flagging (controltower/tests/test_services.py:32).
• SimCore engine sequence rules (simcore/tests/test_engine.py:30).

---

Media & File Storage

• Uploads saved under media/controltower/ with UUID-prefixed filenames.
• For PDF DdT attachments, the path is stored in CTDDTAttachment.
• Remember to add media/ to .gitignore (already handled).

---

Demo / Sample Data

• Use sim_seed for SimCore demo data.
• For ControlTower, upload representative CSV/XLSX files per profile to populate staging tables.
• Column mappings must match the uploaded file headers; configure them before ingest.

---

Next Steps & Ideas

• Persist daily KPI snapshots to feed historical charts.
• Extend ControlTower exports with XLSX packaging and direct email sending.
• Add role-based access (operations vs admin) and audit logs.
• Integrate external APIs for automatic OF / NST imports.

Happy monitoring! 🚀