1. Przegląd Projektu
Klient to firma handlowo-budowlana, która prowadziła klientów, transakcje, płatności i codzienną sprzedaż w KeepinCRM. CRM był wygodnym interfejsem operacyjnym, ale logika finansowa istniała obok: ręczne kontrole, decyzje managerów, kasa, długi, zaliczki i zgody kierownictwa
CRM nie potrafił sam rozksięgować płatności na najstarsze otwarte zadłużenia, policzyć przeterminowania, odróżnić klienta zdrowego od ryzykownego, zatrzymać niebezpiecznego kroku wysyłki ani dać właścicielowi czystego widoku rozrachunków
Moim zadaniem było zbudowanie financial control layer wokół CRM: middleware, który czyta KeepinCRM przez API, stosuje reguły biznesowe, prowadzi własny dziennik audytu, zapisuje wynik z powrotem do CRM, kontroluje zadłużenie, generuje raporty i łączy proces kasowy z fizycznym urządzeniem fiskalnym
To nie była zwykła integracja API. To był żywy proces pieniędzy, długów, kasy, managerów i decyzji właścicielskich, który trzeba było uporządkować
2. Z Czym Przyszedł Klient
•Płatności nie rozksięgowywały się automatycznie: klient mógł zapłacić na poziomie kontrahenta, ale biznes potrzebował automatycznego zamykania najstarszych otwartych transakcji
•Dług i zaliczka nie były systemowe: bieżące zadłużenie, nadpłata, saldo transakcji i przeterminowanie miały być widoczne w CRM, ale CRM nie dawał tej logiki out of the box
•Kontrola kredytowa była ręczna: manager mógł pchać transakcję dalej nawet wtedy, gdy klient przekroczył limit lub miał przeterminowane zadłużenie
•Kierownictwo potrzebowało raportu rozrachunków: salda, wysyłki, płatności, końcowy dług, zaliczka, przeterminowanie i status
•Kasa była fizyczna i legacy: stanowisko kasjera działało na Windows 7, a urządzenie fiskalne było lokalne
•1C/RDP i kasa musiały współistnieć: agent nie mógł trzymać urządzenia cały czas, tylko przejmować je na moment wydruku
•Duplikaty były realnym ryzykiem: ponowne przetworzenie płatności albo drugi wydruk paragonu oznaczały realny błąd finansowy
3. Zakres
•Zaprojektować middleware między KeepinCRM a regułami finansowymi biznesu
•Zaimplementować FIFO allocation: najstarsze zadłużenia spłacane są pierwsze
•Obsłużyć płatności częściowe, nadpłaty, zaliczki i klientów bez otwartych transakcji
•Liczyć dług, zaliczkę, przeterminowanie, status klienta i wykorzystanie limitu
•Wprowadzić statusy OK / RISK / BLOCK
•Blokować krytyczne działania biznesowe przy przekroczeniu limitu lub przeterminowaniu
•Dać kierownictwu ręczny unblock z audytem
•Zbudować raport rozrachunków z filtrami i eksportem Excel
•Zbudować kolejkę paragonów i lokalnego agenta kasowego
•Dodać background radar dla nowych płatności i zmian transakcji
4. Rozwiązanie
Financial Middleware Architecture
•KeepinCRM został interfejsem dla zespołu, a logika finansowa trafiła do FastAPI middleware
•Middleware czyta dane przez API, mapuje je do modelu finansowego i zapisuje kontrolowane wyniki z powrotem do CRM
•Serwis podzielono na moduły: CRM client, allocation engine, debt calculator, blocker, receivables reporter, receipt queue, local-agent endpoints i SQLite journal
•SQLite działa jako dziennik kontroli dla allocations, recalculations, block events, receipts, processed payments, agent status i agent logs
FIFO Payment Allocation
•System pobiera otwarte transakcje klienta, wybiera te z długiem, sortuje po dacie i zamyka najstarsze zadłużenie jako pierwsze
•Częściowa płatność zostawia jasne saldo, nadpłata staje się zaliczką, a brak otwartych transakcji nie gubi pieniędzy w komentarzu
•Ponowne przetworzenie tego samego payment ID jest blokowane przez idempotency i dziennik alokacji
Debt Control & Blocking
•System liczy dług, zaliczkę, przeterminowanie, utilization i status klienta
•Statusy OK / RISK / BLOCK zamieniają liczby w operacyjną decyzję
•BLOCK zatrzymuje ryzykowny ruch transakcji, a manager nie może po cichu przepchnąć wysyłki
•Kierownik może zdjąć blokadę, ale tylko z powodem i zapisem w block_log
Reporting & Cash Register
•Raport rozrachunków liczy opening balance, charges, payments, closing balance, advance, overdue days i debt status
•Eksport Excel daje kierownictwu praktyczny plik do kontroli
•Receipt queue łączy CRM z fizyczną kasą przez statusy pending, completed i failed
•Lokalny Windows agent pobiera paragon, drukuje go na urządzeniu fiskalnym i odsyła wynik
•Agent działa z legacy stanowiskiem, przejmuje urządzenie tylko na czas wydruku i zwalnia je dla innych programów
Radar & Background Processing
•Background radar wykrywa nowe płatności i zmiany transakcji
•Nowa płatność uruchamia allocation flow i kontrolę blokad
•Zmiana transakcji uruchamia ponowne sprawdzenie klienta
•Daily recalculation wykrywa przeterminowanie nawet bez aktywności managera
5. Rezultat
•CRM stał się interfejsem do kontrolowanego procesu finansowego
•Płatności zaczęły rozliczać się według jasnej reguły FIFO
•Dług, zaliczka, przeterminowanie i status klienta stały się wyliczalne
•Ryzykowni klienci dostali automatyczne stop-points
•Kierownictwo otrzymało override z logiem
•Raporty rozrachunków są dostępne przez API/UI i Excel
•Kasa została połączona z CRM przez kolejkę, statusy i lokalnego agenta
•Legacy Windows 7 i fizyczne urządzenie fiskalne zostały zintegrowane bez wymiany stanowiska kasjera
6. Wynik Techniczny
Powstał financial control layer dla KeepinCRM:
•KeepinCRM API integration
•Receivables reporter z Excel export
7. Dlaczego To Było Trudne
Projekt był trudny, bo łączył CRM, reguły finansowe i fizyczne urządzenie fiskalne na starym stanowisku Windows
Trzeba było zachować znany interfejs CRM, dać kierownictwu kontrolę, uniknąć duplikacji płatności i paragonów, pokazać realne długi i nie zepsuć pracy kasjera. To nie była integracja dla integracji, tylko operacyjny system kontroli pieniędzy wokół CRM
