Upcoming Payments — Πλήρες Documentation

Perfex CRM Module · MECE · v1.0.0 Τελευταία ενημέρωση: 2026-06-25

Πίνακας περιεχομένων

1. Επισκόπηση
2. Scope — τι κάνει / τι ΔΕΝ κάνει
3. Κατάσταση φάσεων
4. Οδηγός χρήσης ανά καρτέλα
5. Σενάρια τεστ για συνεργάτη
6. Αυτοματισμοί (Cron)
7. Τεχνικό παράρτημα
8. Known limitations / εκκρεμότητες
9. Πρόσβαση για τεστ

1. Επισκόπηση

Το Upcoming Payments είναι αυτόνομο Perfex CRM module για τη διαχείριση αναμενόμενων εισπράξεων του λογιστηρίου. Αντικαθιστά ένα core-hack (eleni #21139) που υπήρχε απευθείας στο Perfex, μεταφέρει ανέπαφα ~1.128 υπάρχουσες εγγραφές, και επεκτείνεται με αυτοματισμούς είσπραξης.

Ποιο πρόβλημα λύνει

Το γραφείο κόβει τιμολόγια σε πελάτες. Μεταξύ έκδοσης τιμολογίου και πραγματικής είσπραξης μεσολαβεί χρόνος — συχνά εβδομάδες ή μήνες. Το module καταγράφει πότε αναμένεται να εισπραχθεί κάθε ποσό, παρακολουθεί αν τηρείται το πλάνο, στέλνει αυτόματες υπενθυμίσεις/οχλήσεις στους πελάτες που αργούν, και δίνει dashboard εικόνα της ταμειακής ροής.

Σε ποιον απευθύνεται

2. Scope

✅ ΤΙ ΚΑΝΕΙ

• Καταγραφή αναμενόμενης είσπραξης ανά τιμολόγιο (ποσό, ημερομηνία, σημείωση, status)
• Αυτόματη μετάβαση status μέσω cron (Σε αναμονή → Προς Έλεγχο → Έχει λήξει)
• Δημιουργία εσωτερικής task «Έλεγχος Πληρωμής» όταν λήγει η προθεσμία
• Dunning ladder: αυτόματες υπενθυμίσεις/οχλήσεις σε πελάτες (email, SMS, in-app) βάσει ρυθμιζόμενων κανόνων
• Dashboard με KPIs (DSO, CEI, ADD, MDD), εβδομαδιαίο chart, aging buckets, top-20 πελάτες
• Collections: λίστα πελατών εκτός πλάνου, ανάθεση υπεύθυνου είσπραξης, follow-up log, legal marker
• Inbox: τιμολόγια με υπόλοιπο που δεν έχουν προγραμματισμένη πληρωμή
• Auto-split: αυτόματη δημιουργία νέας επερχόμενης για το υπόλοιπο μετά από μερική πληρωμή (off by default)
• Εξαιρέσεις πελατών (exempt list) από αυτοματισμούς
• CSV export, PDF receipt, αποστολή email πληρωμής σε πελάτη
• Πλήρες audit log κάθε αλλαγής
• Bank transactions data layer (sync από NBG collector — data μόνο, χωρίς matching)

❌ ΤΙ ΔΕΝ ΚΑΝΕΙ

• ΑΑΔΕ ρυθμίσεις / φορολογικές δόσεις προς το κράτος / myDATA
• Payment plans / δόσεις πελατών (Φ4 — δεν έχει ξεκινήσει)
• Auto-matching τραπεζικής κίνησης με τιμολόγιο (Φ2 bank matching — planned)
• Promise-to-pay tracking / dispute management (planned Φ3+)
• Client-portal ορατότητα / online payment links
• Διαχείριση modules/sales_tower (συνυπάρχει στο repo ως ξεχωριστό module)

3. Κατάσταση φάσεων (Φ0–Φ4)

Υπόμνημα statuses

Τα 6 core statuses (αμετάβλητα — προστατευμένα από διαγραφή/μετονομασία):

4. Οδηγός χρήσης ανά καρτέλα

Πρόσβαση: Sidebar → «Upcoming Payments» (εικονίδιο credit card). 5 υπό-μενού: Dashboard · Inbox · Λίστα · Collections · Ρυθμίσεις.

Το sidebar badge (κόκκινος αριθμός) δείχνει τα τιμολόγια στο Inbox που δεν έχουν κάλυψη. Ανανεώνεται κάθε 15 λεπτά (ή μετά από cron run).

4.1 Dashboard

URL: ?group=dashboard

Η καρτέλα «σύνοψης» — ιδανική για το πρωινό check-in του manager.

Τι βλέπει ο χρήστης:

Month Picker

Πλοήγηση με < / > ανά μήνα. Κουμπί 📅 επιστρέφει στον τρέχοντα μήνα. Αλλαγή μήνα → AJAX reload KPIs + chart + clients (χωρίς reload σελίδας).

3 KPI Cards

Κάθε card δείχνει ποσό, πλήθος εγγραφών, και trend % vs προηγούμενο μήνα (↑/↓ ή «—» αν δεν υπάρχει ιστορικό).

Εβδομαδιαίο Bar Chart (W1–W5)

Σύγκριση αναμενόμενων / εισπραχθέντων / εκτός πλάνου ανά εβδομάδα μήνα. Χρησιμοποιεί Chart.js — fallback σε CSS bars αν δεν φορτωθεί.

Top-20 Πελάτες

Πίνακας με τους 20 πελάτες με το μεγαλύτερο υπόλοιπο (αναμενόμενα − εισπραχθέντα) για τον μήνα. Ταξινόμηση κατά υπόλοιπο φθίνον.

DSO/CEI/Aging Strip (μωβ panel)

Δεδομένα από forecast snapshot (νυχτερινός cron ή χειροκίνητο trigger). ΔΕΝ αλλάζει με το month picker — δείχνει πάντα την τελευταία ημερήσια εικόνα.

Aging buckets: τρέχον / 1–30 / 31–60 / 61–90 / 90+ ημέρες, με horizontal bar chart.

Κουμπί «Ανανέωση Snapshot» (για edit/configure permission): εκτελεί χειροκίνητα το forecast.

4.2 Inbox (Προς Καταχώρηση)

URL: ?group=inbox

Τιμολόγια που έχουν υπόλοιπο αλλά δεν καλύπτονται πλήρως από upcoming payments. Αυτά χρειάζονται προγραμματισμό.

Στήλες DataTable:

• Αριθμός τιμολογίου (link → τιμολόγιο)
• Πελάτης
• Σύνολο τιμολογίου
• Υπόλοιπο (total − πληρωμές)
• % Καλυμμένο (progress bar: upcoming/υπόλοιπο)
• Ημερομηνία τιμολογίου (color-coded: καθυστερημένο = κόκκινο)
• Ενέργειες: «Πρόσθεσε Πληρωμή»

Φίλτρα: Πελάτης · Ημερομηνία Από–Έως.

Ροή χρήσης:

1. Ο λογιστής ανοίγει το Inbox
2. Βλέπει τα ανοιχτά τιμολόγια χωρίς κάλυψη
3. Κλικ «Πρόσθεσε Πληρωμή» → modal με φόρμα batch καταχώρησης
4. Καταχωρεί ποσό + ημερομηνία αναμενόμενης είσπραξης (μπορεί περισσότερες γραμμές)
5. Submit → εγγραφές στο tblupcomingpayments + activity log

4.3 Λίστα (Όλες οι Επερχόμενες)

URL: ?group=list

Πλήρης λίστα όλων των upcoming payments με πλούσια φίλτρα, bulk actions, και CSV export.

Φίλτρα:

• Status (dropdown με τα 6+custom statuses)
• Πελάτης
• Ημερομηνία Από–Έως
• Υπεύθυνος (assigned)
• Ελάχιστο/μέγιστο ποσό
• Quick filters (1-click): «Σε αναμονή», «Έχει λήξει», «Σήμερα»

Στήλες DataTable:

• Αριθμός, Τιμολόγιο, Status (χρωματιστό badge), Πελάτης, Ποσό, Ημερομηνία, Ενέργειες

Ενέργειες ανά γραμμή:

• Προβολή / Επεξεργασία upcoming payment
• Αλλαγή status (AJAX)
• Διαγραφή (delete permission)

Bulk Actions (επιλογή πολλαπλών):

• change_status: μαζική αλλαγή κατάστασης
• assign: μαζική ανάθεση υπευθύνου

CSV Export: «Εξαγωγή CSV» εξάγει τα τρέχοντα φιλτραρισμένα αποτελέσματα. Περιλαμβάνει BOM για σωστά ελληνικά σε Excel.

Drill-down ανά τιμολόγιο: Κλικ στον αριθμό τιμολογίου → σελίδα invoice_upcoming/{id} με όλες οι upcoming + timeline δραστηριότητας + επισυναπτόμενα.

4.4 Ρυθμίσεις (Settings)

URL: ?group=settings — ορατό μόνο σε χρήστες με edit permission

Dunning Banner

Αν το dunning engine είναι ανενεργό, εμφανίζεται banner προειδοποίησης με κουμπί «Ενεργοποίηση Test Mode». Αν είναι σε test mode, εμφανίζεται info banner. Όταν ενεργοποιηθεί production, τα banner εξαφανίζονται.

Γενικές Ρυθμίσεις (αριστερά panel)

Καταστάσεις (δεξί panel)

Διαχείριση statuses: add/edit (χρώμα + σειρά). Τα 6 system statuses είναι προστατευμένα (σήμα «system» — επιτρέπεται μόνο αλλαγή χρώματος/σειράς, ΟΧΙ μετονομασία ή διαγραφή). Custom statuses: πλήρης CRUD.

Dunning Ladder (κάτω panel)

Πίνακας κανόνων ειδοποίησης. Default ladder (seed αν άδειο):

Ενέργειες ladder:

• Προσθήκη/επεξεργασία κανόνα (modal): stage name, offset days, direction (before/after), channel (email/sms/inapp), template id, sender role, active toggle, order
• Διαγραφή κανόνα
• «Δοκιμαστικό Τρέξιμο»: manual trigger dunning engine (logs only, ΔΕΝ στέλνει)
• «Απενεργοποίηση Production»: επιστρέφει σε test mode

Error Log

Εμφανίζεται μόνο αν υπάρχουν errors στην τελευταία ώρα. Δείχνει τα 5 τελευταία errors με timestamp, automation, και μήνυμα σφάλματος.

4.5 Collections (Εκτός Πλάνου)

URL: ?group=collections

Εργαλείο είσπραξης: πελάτες με overdue upcoming payments (status «Έχει λήξει»), ανατεθειμένοι σε υπεύθυνους, με follow-up tracking.

Φίλτρα

• Ημέρες καθυστέρησης: οποιοδήποτε / 30+ / 60+ / 90+
• Ελάχιστο ποσό: αριθμητική είσοδος
• Υπεύθυνος: dropdown staff

Sub-tabs

«Εκτός Πλάνου» (default): Όλοι οι πελάτες με overdue, ταξινομημένοι κατά συνολικό overdue ποσό (φθίνον). Ανεξάρτητο της ανάθεσης.

«Worklist μου»: Μόνο πελάτες με assigned_collector = τρέχων_χρήστης. Προσωπική λίστα εισπράκτορα.

Στήλες DataTable (server-side)

4 Κουμπιά Ενεργειών

1. «Ανάθεση» (Assign):

• Ανοίγει modal με dropdown staff
• Αναθέτει τον collector σε όλα τα overdue upcoming του πελάτη
• 0 = αφαίρεση ανάθεσης

2. «Follow-up» (📞):

• Ανοίγει modal καταχώρησης επαφής
• Πεδία: Τύπος (τηλέφωνο/email/συνάντηση/sms) · Αποτέλεσμα (textarea) · Επόμενη ημερομηνία δράσης
• Αποθηκεύεται στο tblupcomingpayments_followups — ενημερώνει «Τελευταία Επαφή»

3. «Νέο Πλάνο» (link):

• Ανοίγει τη σελίδα invoices του πελάτη (νέα καρτέλα) για δημιουργία νέου upcoming

4. «Νομικά» (⚖️):

• Toggle mark/unmark legal referral
• Κίτρινο badge αν marked → σήμα ότι ο πελάτης πήγε σε νομική δράση
• Placeholder: δεν ξεκινά αυτόματα νομική διαδικασία (η λογική αυτή είναι planned)

5. Σενάρια τεστ

Για τον συνεργάτη: Δοκιμάστε στο https://c3.mece.app. Ο λογαριασμός σας έχει admin δικαιώματα. Email/SMS αποστολή είναι κομμένη στο clone — τα logs γράφονται κανονικά.

Σενάριο 1 — Πλοήγηση & sidebar badge

Βήματα:

1. Login ως admin
2. Ανοίξτε το sidebar και εντοπίστε το «Upcoming Payments»
3. Παρατηρήστε τον κόκκινο αριθμό badge
4. Κάντε κλικ → φορτώνει dashboard (default landing)
5. Δοκιμάστε κλικ σε κάθε submenu (Dashboard · Inbox · Λίστα · Collections · Ρυθμίσεις)

Αναμενόμενο: Κάθε καρτέλα φορτώνει χωρίς error. Badge = αριθμός εγγραφών Inbox.

Σενάριο 2 — Καταχώρηση επερχόμενης πληρωμής από Inbox

Βήματα:

1. Πηγαίνετε στο Inbox
2. Βρείτε ένα τιμολόγιο με % καλυμμένο < 100%
3. Κλικ «Πρόσθεσε Πληρωμή»
4. Στο modal: καταχωρήστε ποσό = π.χ. 500 και ημερομηνία 30 ημέρες από σήμερα
5. Submit

Αναμενόμενο: Alert «Επερχόμενες πληρωμές καταχωρήθηκαν επιτυχώς». Το τιμολόγιο εμφανίζεται με ενημερωμένο % στο Inbox (ή εξαφανίζεται αν 100%). Στη Λίστα εμφανίζεται η νέα εγγραφή με status «Σε αναμονή».

Σενάριο 3 — Φίλτρα & export στη Λίστα

Βήματα:

1. Πηγαίνετε στη Λίστα
2. Επιλέξτε status «Έχει λήξει»
3. Επιλέξτε ένα συγκεκριμένο πελάτη
4. Κλικ «Εφαρμογή Φίλτρων» (ή Enter)
5. Κλικ «Εξαγωγή CSV»

Αναμενόμενο: Το datatable φιλτράρει. Το CSV κατεβαίνει με τα φιλτραρισμένα δεδομένα. Τα ελληνικά εμφανίζονται σωστά στο Excel (BOM).

Σενάριο 4 — Αλλαγή status (μεμονωμένη)

Βήματα:

1. Στη Λίστα, βρείτε μια εγγραφή «Σε αναμονή»
2. Κλικ στο εικονίδιο ενεργειών → «Αλλαγή κατάστασης» → «Ολοκληρωμένη»

Αναμενόμενο: AJAX response, το badge status αλλάζει αμέσως. Στο audit log (tblupcomingpayments_audit) υπάρχει νέα εγγραφή με action status_change.

Σενάριο 5 — Bulk actions

Βήματα:

1. Στη Λίστα, επιλέξτε 3–4 γραμμές (checkbox)
2. Dropdown «Μαζικές ενέργειες» → «Αλλαγή κατάστασης» → status = «Με υπόλοιπο»
3. Confirm

Αναμενόμενο: Alert «X εγγραφές ενημερώθηκαν». Οι επιλεγμένες γραμμές αλλάζουν status.

Σενάριο 6 — Dashboard: navigation + KPIs

Βήματα:

1. Πηγαίνετε στο Dashboard
2. Παρατηρήστε τα 3 KPI cards για τον τρέχοντα μήνα
3. Κλικ < για τον προηγούμενο μήνα
4. Παρατηρήστε ότι οι αριθμοί αλλάζουν (AJAX) χωρίς reload
5. Κλικ 📅 για επιστροφή στον τρέχοντα μήνα

Αναμενόμενο: Ομαλή AJAX πλοήγηση. Τα KPIs, chart, και clients table ανανεώνονται.

Σενάριο 7 — DSO/CEI Aging Strip

Βήματα:

1. Στο Dashboard, κοιτάξτε το μωβ panel «Ταμειακή Πρόβλεψη»
2. Αν λέει «Δεν υπάρχει snapshot», κλικ «Ανανέωση Snapshot»
3. Επιβεβαιώστε το confirm dialog

Αναμενόμενο: Alert επιτυχίας. Το panel εμφανίζει DSO/CEI/ADD/MDD και aging bars με ημερομηνία snapshot σήμερα.

Σενάριο 8 — Ρυθμίσεις: dunning ladder

Βήματα:

1. Πηγαίνετε στις Ρυθμίσεις
2. Δείτε το dunning banner (αν engine off) — κλικ «Ενεργοποίηση Test Mode»
3. Δείτε τον πίνακα dunning rules
4. Κλικ «+ Νέος Κανόνας» → modal: stage = «Test Rule», offset = 7, direction = after, channel = email, active ✅
5. Save
6. Βεβαιωθείτε ότι εμφανίζεται στον πίνακα
7. Κλικ «Δοκιμαστικό Τρέξιμο» → confirm

Αναμενόμενο: Νέος κανόνας εμφανίζεται. Alert «Δοκιμαστικό τρέξιμο ολοκληρώθηκε — X εγγραφές run log». ΔΕΝ έχουν σταλεί πραγματικά emails.

Σενάριο 9 — Εξαίρεση πελάτη από αυτοματισμούς

Βήματα:

1. Ρυθμίσεις → «Εξαιρέσεις Πελατών»
2. Επιλέξτε ένα πελάτη (π.χ. «Test Client»)
3. Save
4. Βεβαιωθείτε ότι ο πελάτης εμφανίζεται επιλεγμένος μετά το reload

Αναμενόμενο: Αποθηκεύεται ως JSON array στο settings. Ο cron ΔΕΝ θα δημιουργεί task για αυτόν τον πελάτη (μόνο αλλάζει status). Το dunning engine τον παρακάμπτει.

Σενάριο 10 — Collections: ανάθεση & follow-up

Βήματα:

1. Πηγαίνετε στο Collections
2. Βρείτε έναν πελάτη στο «Εκτός Πλάνου» tab
3. Κλικ «Ανάθεση» → modal → επιλέξτε έναν staff → «Αποθήκευση»
4. Κλικ «Follow-up» → modal → τύπος «τηλέφωνο», outcome «Ο πελάτης υποσχέθηκε να πληρώσει εντός 5 ημερών», next_action_date = 5 ημέρες → Save

Αναμενόμενο: Η στήλη «Υπεύθυνος» ενημερώνεται. Η στήλη «Τελευταία Επαφή» δείχνει τώρα. Worklist tab δείχνει τον πελάτη αν ο τρέχων χρήστης είναι ο assigned collector.

Σενάριο 11 — Legal marker

Βήματα:

1. Στο Collections, βρείτε έναν πελάτη με μεγάλη οφειλή
2. Κλικ «Νομικά» (εικονίδιο σφυρί)

Αναμενόμενο: Κουμπί αλλάζει χρώμα σε κίτρινο (marked). Δεύτερο κλικ → ξαναγίνεται γκρι (unmark). Audit log καταγράφει την αλλαγή.

Σενάριο 12 — Worklist (προσωπική λίστα)

Βήματα:

1. Στο Collections, κλικ sub-tab «Worklist μου»
2. Βεβαιωθείτε ότι εμφανίζονται μόνο πελάτες assigned στον τρέχοντα χρήστη

Αναμενόμενο: Αν δεν είναι ανατεθειμένος κανείς → κενή λίστα. Αν έγινε ανάθεση στο Σενάριο 10 με τον τρέχοντα χρήστη → εμφανίζεται εκεί.

Σενάριο 13 — Invoice integration (per-invoice tab)

Βήματα:

1. Πηγαίνετε σε οποιοδήποτε τιμολόγιο (Invoices → προβολή)
2. Δείτε το button «+ Επερχόμενες Πληρωμές» επάνω δεξιά
3. Κλικ → modal batch καταχώρησης
4. Δείτε το tab «Επερχόμενες Πληρωμές» στο τιμολόγιο (badge με πλήθος εγγραφών)

Αναμενόμενο: Το button και το tab εμφανίζονται μέσω hooks (χωρίς core template hacks). Οι εγγραφές εμφανίζονται και στη Λίστα του module.

Σενάριο 14 — Statuses: add custom + προστασία system

Βήματα:

1. Ρυθμίσεις → «+ Νέα Κατάσταση» → name = «Σε Διαπραγμάτευση», color = #673AB7
2. Save → εμφανίζεται στον πίνακα
3. Δοκιμάστε επεξεργασία ενός system status (π.χ. «Έχει λήξει») → αλλάξτε χρώμα
4. Δοκιμάστε διαγραφή system status

Αναμενόμενο: Custom status: δημιουργία/επεξεργασία/διαγραφή OK. System status: αλλαγή χρώματος ΟΚ, μετονομασία αδύνατη, διαγραφή αδύνατη (warning alert).

6. Αυτοματισμοί (Cron)

Τρεις cron tasks — τρέχουν αυτόματα από τον Perfex native cron (per-minute via /cron/index).

6.1 upcoming_payments_cron — Auto-Status Lifecycle

Πότε τρέχει: Κάθε cron cycle, αλλά εκτελεί transitions μόνο στην ορισμένη ώρα (default: 9:00 π.μ., ρυθμιζόμενο από Ρυθμίσεις).

Τι κάνει:

1. Σε αναμονή → Προς Έλεγχο: upcoming με date = σήμερα και status «Σε αναμονή» μεταβαίνουν σε «Προς Έλεγχο»
2. Προς Έλεγχο → Έχει λήξει: upcoming με date = χθες και status «Προς Έλεγχο» μεταβαίνουν σε «Έχει λήξει»
3. Auto-task: για κάθε νέα «Έχει λήξει» (εκτός εξαιρούμενων πελατών), δημιουργεί Perfex task:
   • Όνομα: «Έλεγχος Πληρωμής»
   • Deadline: +8 ημέρες
   • Assignee: default_assignee από Ρυθμίσεις (fallback: staff id 23)
   • Follower: staff id 19
4. Dunning engine run (run_dunning_cron): ελέγχει active κανόνες vs target dates
5. Badge cache refresh: ανανεώνει το sidebar badge

Ρύθμιση ώρας: Ρυθμίσεις → «Ώρα εκτέλεσης αυτοματισμών» (0–23). Αποθηκεύεται στο tbloptions.upcomingpayments_auto_operations_hour.

6.2 upcoming_payments_forecast_snapshot_cron — Νυχτερινό Snapshot

Πότε τρέχει: Κάθε cron cycle, αλλά εκτελεί μόνο μεταξύ 00:00–05:59 (νυχτερινό window). Idempotent (UPSERT ανά ημέρα).

Τι κάνει: Υπολογίζει και αποθηκεύει στο tblupcomingpayments_forecast_snapshots:

Χειροκίνητο trigger: Dashboard → «Ανανέωση Snapshot» (edit/configure permission).

6.3 bank_transactions_sync — Τραπεζικός Συγχρονισμός

Πότε τρέχει: Κάθε cron cycle, αλλά με throttle ≥ 6 ώρες από το τελευταίο επιτυχές run.

Τι κάνει: POST στον NBG bank collector (PC 10.0.0.10:8044) → κατεβάζει κινήσεις → INSERT IGNORE στο tblbanktransactions (dedupe by transaction_id + source). Timeout 120 δευτερόλεπτα.

Απαιτεί ρύθμιση: tbloptions: bank_collector_url, bank_collector_key, bank_nbg_username, bank_nbg_password — διαμορφώνεται χειροκίνητα (δεν υπάρχει UI ακόμα).

⚠️ Σε clone (c3): Τα credentials δεν είναι configured → ο cron κάνει skip αθόρυβα.

7. Τεχνικό παράρτημα

7.1 Αρχιτεκτονική (MVC)

modules/upcoming_payments/
├── upcoming_payments.php          # Init file — hooks, menu, cron registration
├── install.php                    # Idempotent schema (ADOPT + ALTER + CREATE IF NOT EXISTS)
├── uninstall.php                  # Drop module-only tables (ΠΟΤΕ core tables)
├── controllers/
│   └── Upcoming_payments.php     # AdminController — 30+ endpoints
├── models/
│   ├── Upcoming_payments_model.php  # Business logic (~2140 γραμμές)
│   └── Bank_transactions_model.php  # Bank sync data layer
├── views/
│   ├── manage.php                 # Main tabbed container
│   ├── tabs/
│   │   ├── inbox.php              # Καρτέλα 1
│   │   ├── list.php               # Καρτέλα 2
│   │   ├── settings.php           # Καρτέλα 3
│   │   ├── dashboard.php          # Καρτέλα 4
│   │   └── collections.php        # Καρτέλα 5
│   ├── tables/
│   │   ├── upcoming_payments_table.php   # DataTable config (Λίστα)
│   │   └── inbox_table.php               # DataTable config (Inbox)
│   ├── invoices/
│   │   ├── invoice_upcomingpayments_tab.php  # Per-invoice tab content
│   │   └── record_upcomingpayment_template.php  # Per-invoice batch modal
│   ├── invoice_drilldown.php      # Drill-down σελίδα ανά τιμολόγιο
│   ├── upcoming_payment_view.php  # Single upcoming payment view
│   ├── status_modal.php           # Add/edit status modal
│   └── dunning_rule_modal.php     # Add/edit dunning rule modal
├── assets/
│   └── js/upcoming_payments.js   # Client-side: DataTables, AJAX, modals, Chart.js
├── helpers/
│   └── upcoming_payments_helper.php  # get_upcomingpayments_status_by_id()
├── libraries/merge_fields/
│   ├── Upcomingpayment_merge_fields.php
│   └── Upcomingpayments_list_merge_fields.php
└── language/
    ├── greek/upcoming_payments_lang.php
    └── english/upcoming_payments_lang.php

7.2 Endpoints (Route → Method → Σκοπός)

Βάση URL: admin/upcoming_payments/

7.3 DB Schema

Adopted (υπάρχοντες πίνακες — ΠΟΤΕ drop)

tblupcomingpayments — κύριος πίνακας

id              INT(11) PK AUTO_INCREMENT
invoiceid       INT(11) FK → tblinvoices.id
amount          DECIMAL(15,2)
date            DATE                          -- αναμενόμενη ημερομηνία είσπραξης
daterecorded    DATETIME
note            TEXT
status          INT(11) FK → tblupcomingpayments_status.id
assigned        INT(11) NULL                  -- Φ0: νέο column (ALTER)
assigned_collector INT(11) NULL              -- Φ3: εισπράκτορας (ALTER)
legal_marker    TINYINT(1) DEFAULT 0          -- Φ3: νομική παραπομπή (ALTER)

tblupcomingpayments_status — καταστάσεις

id              INT(11) PK AUTO_INCREMENT
name            VARCHAR(191)
color           VARCHAR(7)
status_order    INT(11) DEFAULT 0             -- Φ0: νέο column (ALTER)

Νέοι πίνακες (CREATE IF NOT EXISTS)

tblupcomingpayments_settings — ρυθμίσεις module

id    INT(11) PK AUTO_INCREMENT
name  VARCHAR(191) UNIQUE KEY
value LONGTEXT

tblupcomingpayments_dunning_rules — ladder κανόνων

id           INT(11) PK
stage        VARCHAR(191)           -- περιγραφή σταδίου
offset_days  INT(11)
direction    VARCHAR(10)            -- 'before' | 'after'
channel      VARCHAR(20)            -- 'email' | 'sms' | 'inapp'
template_id  INT(11) NULL
sender_role  VARCHAR(100) NULL
active       TINYINT(1)
rule_order   INT(11)

tblupcomingpayments_audit — audit log

id         INT(11) PK
entity     VARCHAR(64)     -- 'upcoming_payment', 'settings', 'client_collector', κλπ
entity_id  INT(11)
action     VARCHAR(32)     -- 'create', 'update', 'delete', 'status_change', 'auto_split', κλπ
old_value  JSON NULL
new_value  JSON NULL
user_id    INT(11) NULL    -- 0 αν cron
ts         DATETIME

tblupcomingpayments_run_log — dunning execution history

id                   INT(11) PK
rule_id              INT(11)
upcomingpayment_id   INT(11)
channel              VARCHAR(20)
action_type          VARCHAR(50)     -- 'test_log' | 'send_email' | 'send_sms' | 'send_inapp'
sent_at              DATETIME
payload              JSON NULL
status               VARCHAR(20)     -- 'logged' | 'sent' | 'failed' | 'skipped'

tblupcomingpayments_error_log — automation errors

id          INT(11) PK
automation  VARCHAR(100)    -- 'dunning_cron'
error       JSON NULL
ts          DATETIME

tblupcomingpayments_forecast_snapshots — DSO/CEI/aging

snap_date   DATE          \
kpi         VARCHAR(64)    > PK(snap_date, kpi) -- UPSERT daily
value       DECIMAL(15,2)
payload     JSON NULL       -- extra context (π.χ. components του DSO)
created_at  DATETIME

tblupcomingpayments_followups — follow-up log (Collections)

id                   INT(11) PK
upcomingpayment_id   INT(11)
staff_id             INT(11)
type                 ENUM('τηλέφωνο','email','συνάντηση','sms')
outcome              TEXT NULL
next_action_date     DATE NULL
call_log_id          INT(11) NULL      -- placeholder για 3CX integration
created_at           DATETIME

tblbanktransactions — bank transactions (Φ1 data layer)

id                  INT(11) PK
transaction_id      VARCHAR(255)    \
source              VARCHAR(50)      > UNIQUE KEY — dedupe
txn_date            DATE
amount              DECIMAL(15,2)
currency            VARCHAR(10)
credit_debit        VARCHAR(10)
counter_party       VARCHAR(500) NULL
related_account     VARCHAR(100) NULL
description         TEXT NULL
accounting_balance  DECIMAL(15,2) NULL
raw_json            JSON NULL
match_status        ENUM('unmatched','suggested','approved','rejected','manual')
match_type          ENUM(...) NULL     -- Φ2 placeholder
match_ref_id        INT(11) NULL       -- Φ2 placeholder
match_confidence    TINYINT NULL       -- Φ2 placeholder
matched_by          INT(11) NULL       -- Φ2 placeholder
matched_at          DATETIME NULL      -- Φ2 placeholder
harvested_at        DATETIME
created_at          DATETIME

tbloptions (Perfex native)

7.4 Permissions (feature slug: upcomingpayments)

7.5 Hooks & Integrations

7.6 Εξωτερικές Εξαρτήσεις

7.7 Deploy Flow

1. Ανάπτυξη: τοπικό bench (MECE_BENCH=1, http://127.0.0.1:3301)
2. Commit σε branch feat/* → push
3. PR review (Niko approval)
4. Deploy σε clone: mece-deploy c3
5. Authenticated HTTP verify (c3.mece.app)
6. Merge → deploy live: mece-deploy live

Απόλυτοι κανόνες deploy:

• ΠΟΤΕ manual scp/rsync στο docroot (αφήνει dirs 750 → Apache 500)
• mece-deploy χειρίζεται owner/permissions αυτόματα
• Verify πάντα μέσω authenticated browser (logged-in), ΟΧΙ με curl/cron

8. Known Limitations / Εκκρεμότητες

Λειτουργικά

Τεχνικά

Ρίσκα deployment

• Ο default_assignee = 23 είναι hardcoded fallback — βεβαιωθείτε ότι υπάρχει staff id 23 στο target σύστημα ή αλλάξτε το default από Ρυθμίσεις πριν ενεργοποιήσετε το cron
• Τα 6 core statuses ΔΕΝ πρέπει να διαγραφούν ή μετονομαστούν — το cron τα αναζητά by name
• dunning_engine_enabled είναι off by default — χρειάζεται ρητή ενεργοποίηση

9. Πρόσβαση για τεστ

Μετά το τεστ: Οι αλλαγές σας στο c3 δεν μεταφέρονται αυτόματα στο live (mece.app). Κάθε deploy στο live γίνεται μέσω PR + mece-deploy live.

DOC READY: 851