Doktally — фактуриране, ДДС и отчетност за малък бизнес

Накратко

Doktally е моят собствен SaaS за отчитане на време, договори, таксуване, фактуриране, банкови извлечения и ДДС. Разделен е на шест Spring Boot услуги зад Spring Cloud Gateway, с Keycloak за идентичност, RabbitMQ за фонова работа и Angular клиент. Ядрото му е механизъм за таксуване, който може да обясни всяка сума, която създава, и покрива българските особености (дневници за НАП, VIES, данни от БНБ, смяната към евро), които общите инструменти пропускат.

Подзаглавие

Multi-tenant платформа за фактуриране и ДДС за малки български фирми, изградена и поддържана от един човек.

Област

Фактуриране / ДДС / Малък бизнес

Потребители

Фрийлансъри, еднолични търговци и малки фирми в България, както и счетоводителите, които работят с тях.

Роля

Основател / продуктов инженер

Предизвикателство

Издаването на фактура е лесната част. Преди нея идват въпросите, които я правят вярна или грешна: кои часове се таксуват, по каква ставка в деня, в който са отработени, по кой договор, разпределени по кои проекти и дали някой от тях вече не е фактуриран. След нея идват плащанията, кредитните известия, напомнянията, покупките, дневниците по ДДС за НАП и въпросът колко всъщност е спечелила фирмата това тримесечие. Малките фирми отговарят на тези въпроси в няколко инструмента и таблици, а грешките излизат месеци по-късно.

За какво отговарях

Продуктови решения и поетапният план, дизайн на услугите, реализация на бекенда и интерфейса, интеграции с файловете на НАП, VIES, БНБ, банките и Keycloak, процесът на издаване, CI, внедряване с Docker, архиви и наблюдение.

Подход

Разделение на услуги по бизнес области, идентичност и лицензиране на входа, а бавната работа (PDF, имейли, експорти) – през RabbitMQ. В механизма за таксуване парите са BigDecimal, изчислените стойности стоят отделно от човешките корекции, издаденото се замразява, а всяко число може да се обясни от източниците си.

Резултати

Започнах Doktally през март 2024 г., за да водя документите на собствената си фирма, и той прерасна в цялостен продукт. Версия 1.0 (пролетта на 2026 г.) покриваше документи, покупки, внасяне на ДДС файлове, отчитане на време, табла, известия и лицензиране.

Фаза 1 след това го превърна в инструмент за таксуване за изпълнители изобщо: договори с условия по дати и дневник на промените, фиксирани цени, абонаменти с включени часове, периодични услуги, защити за верността на таксуването, документи на езика на клиента, номериране по юридическо лице, експорт на данните, съпоставяне на банкови извлечения и защитен линк към фактурата, който клиентът може да потвърди или оспори. Няколко фирми (tenants) работят в една инсталация, всяка със свои потребители, роли, номериране и лиценз.

Това е проект на един човек: аз решавам какво да влезе, проектирам услугите, пиша Java и Angular кода и поддържам продукционната среда.

Подробности

Обзор

Започнах Doktally през март 2024 г., за да водя документите на собствената си фирма, и той прерасна в цялостен продукт. Обработва фактури и други документи, банкови извлечения, покупки, дневници по ДДС, отчитане на време, договори, календар с падежи, табла и известия за няколко фирми (tenants) в една инсталация.

Това е проект на един човек: аз решавам какво да влезе, проектирам услугите, пиша Java и Angular кода и поддържам продукционната среда.


Архитектура

flowchart TD
    W[Angular 22 + PrimeNG клиент] --> G[Spring Cloud Gateway]
    G --> KC[Keycloak]
    G --> LIC[Licensing service]
    G --> INV[Invoice service]
    G --> USR[User service]
    G --> CAT[Catalog service]
    G --> NOT[Notification service]

    INV --> MQ[RabbitMQ]
    MQ --> NOT
    NOT --> MAIL[Имейл / в приложението / WebSocket]

    INV --> DB[(MongoDB + GridFS)]
    USR --> DB
    CAT --> DB
    LIC --> DB

Всичко работи на Java 25 и Spring Boot 4 с MongoDB. Angular клиентът използва PrimeNG и ECharts.


Изпращане на фактура

sequenceDiagram
    participant U as Потребител
    participant UI as Angular клиент
    participant GW as Gateway
    participant INV as Invoice service
    participant MQ as RabbitMQ
    participant N as Notification service

    U->>UI: Изпрати фактура
    UI->>GW: POST заявка (JWT)
    GW->>GW: Проверка на лиценза за модула
    GW->>INV: Препращане
    INV->>INV: PDF, записан в GridFS
    INV->>MQ: Събитие за изпращане
    INV-->>UI: Приета (статус: изпраща се)
    MQ->>N: Доставяне на събитието
    N->>N: Шаблон, изпращане на имейл
    N-->>INV: Статус на доставката
    INV->>INV: Смяна на статуса + запис в историята
    N-->>U: Известие в приложението

Заявката връща отговор веднага щом работата е поставена в опашката. PDF-ът и имейлът се правят във фонов режим, а статусът и историята на документа се обновяват, когато пристигне резултатът. Съобщенията минават през outbox с потвърждение от брокера, получателите са идемпотентни, а неуспешните доставки отиват в dead-letter опашки, вместо да изчезнат. Документът пази и на кого, как и кога е изпратен, така че по-късни промени в контактите на клиента не пренаписват тази история.


От часовете до фактура, която се обяснява сама

Повечето скорошна работа е в механизма за таксуване, защото там малките грешки струват истински пари.


Българската част

Общите програми за фактуриране не познават файловете, които българските фирми обменят с НАП. Doktally внася дневниците за продажби и покупки, справките-декларации по ДДС и VIES декларациите, подадени към НАП, премахва дублираните записи по бизнес ключ и ги превръща в справка по ДДС с проверки: нетна позиция по ДДС, начислен срещу приспаднат данък по периоди, дневници за покупки и продажби и месеците, в които дневниците, справката и VIES се разминават. ДДС номерата се проверяват във VIES, българските банки се разпознават по IBAN, а курсовете идват от БНБ. Фактури, кредитни и дебитни известия и имейлите към тях се издават на езика на клиента.


След версия 1.0: пари навън и навътре

Всяко от тях е описано със снимки на отделна страница: решения за Doktally.


Решения, които имаха значение

Парите са BigDecimal навсякъде. Първоначално ключовете при импорт използваха Double; те бяха мигрирани към BigDecimal заедно с останалия финансов модел. Сумите в различни валути се превалутират изрично и се показват по валути.

Изчисленото и коригираното стоят отделно. Създаденият ред пази това, което казват времето и ставката. Промяната от човек е отделна корекция с причина, така че двете винаги могат да се сравнят и изградят наново.

Издадено значи замразено. Издаването на фактура записва клиента, артикулите, ДДС и обяснението на всеки ред. Преименуване на клиента, смяна на ставка или анекс към договора по-късно никога не променят изпратеното; приложението показва какво се е променило и предлага кредитно или дебитно известие.

Документите имат state machine и история. Преходите между статуси са изрични и настройваеми, а всяка промяна (полета, редове, прикачени файлове, плащания, връщания за таксуване) се записва със старата и новата стойност. Потребителите могат да добавят бележки към записите в историята, което помага, когато счетоводителят пита защо нещо е променено.

Регресионни тестове за пътищата на парите. Всеки важен за таксуването сценарий има свой тест от край до край върху малък набор от данни, отбелязан така, че целият набор за таксуване и договори се пуска с една команда. Самите демо данни също се проверяват, че създават и издават фактурите си без грешки.

Бавната работа минава през опашката. PDF файловете, имейлите и експортите никога не блокират заявка. Потребителят получава известие, когато файлът е готов.

Ограничаване по фирма в слоя за данни. Търсенията минават през заявки, съобразени с фирмата, като findByIdAndTenantId, така че данните на една фирма не могат да изтекат към друга заради пропуснат филтър. Ролите (собственик, администратор, счетоводител, потребител) се налагат в API-то и се виждат в менюто.

Лицензиране на входа. Gateway-ят решава кои модули и функции може да извиква дадена фирма, така че бизнес услугите не съдържат проверки за лицензи. Лицензите се проверяват наново на всеки 30 секунди, така че спирането на лиценз действа почти веднага.

Поддържан от един човек. Един Docker Compose файл за продукция с Caddy за HTTPS, скриптове за архивиране и възстановяване на MongoDB, метрики в Prometheus и превключвател, който зарежда пълно демо. Всяко внедряване е манифест на издание от независимо версионирани услуги, всяка като непроменим образ, изграден веднъж.


Следващи стъпки

Технологии

Java 25, Spring Boot 4, Spring Cloud Gateway, Angular 22, PrimeNG, ECharts, MongoDB, RabbitMQ, Keycloak, Docker, Caddy, Prometheus

Ангажимент

PERSONAL_PRODUCT

Период

2024-03 – досега

Решения