# Модул ДДС (VAT) - Техническа документация

## Общ преглед

Модулът ДДС предоставя функционалност за управление на данък добавената стойност според българското законодателство (ЗДДС и ППЗДДС). Той включва:

- Създаване и управление на ДДС декларации по периоди
- Дневник продажби и дневник покупки
- Изчисляване на дължимия ДДС
- Експорт на файлове за НАП (DEKLAR.TXT, POKUPKI.TXT, PRODAJBI.TXT)

## Структура на базата данни

### Основни модели

#### VatReturn (`backend/src/models/vat_return.cr`)

Декларация ДДС за конкретен данъчен период.

**Полета:**
- `period_year` (Int32) - Година
- `period_month` (Int32) - Месец (1-12)
- `status` (String) - Статус: "draft", "calculated", "submitted"
- `result_json` (String?) - Резултат от изчислението като JSON

**Секция A - Начислен ДДС (продажби):**
- `cell_01_01` - Данъчна основа 20%
- `cell_01_02` - Начислен ДДС 20%
- `cell_01_03` - ДО при ВОП и чл.82 ал.2-5
- `cell_01_04` - Начислен ДДС при ВОП
- `cell_01_05` - ДО облагаеми доставки със ставка 9%
- `cell_01_06` - Начислен ДДС 9%
- `cell_01_07` - ДО облагаеми със ставка 0% по глава 3
- `cell_01_11` - ДО на ВОД (вътреобщностни доставки)
- `cell_01_12` - ДО доставки по чл.140, 146, 173
- `cell_01_13` - ДО на услуги по чл.21 ал.2
- `cell_01_14` - ДО по чл.69 ал.2
- `cell_01_15` - ДО по чл.69 ал.2 в друга ДЧ
- `cell_01_16` - ДО на освободени доставки по глава 4
- `cell_01_17` - ДДС за лични нужди по чл.6 ал.3
- `cell_01_18` - ДО при ВОП със ставка 9%

**Секция B - Данъчен кредит (покупки):**
- `cell_01_20` - ДО на получени доставки без право на ДК
- `cell_01_21` - ДО на получени доставки с право на пълен ДК
- `cell_01_22` - ДДС с право на пълен данъчен кредит
- `cell_01_23` - ДО на получени доставки с право на частичен ДК
- `cell_01_24` - ДДС с право на частичен данъчен кредит
- `cell_01_25` - Годишна корекция - ДО
- `cell_01_26` - Годишна корекция - ДДС
- `cell_01_30` - ДО по чл.163а ал.2 (златни изделия)
- `cell_01_31` - ДДС по чл.163а ал.2
- `cell_01_32` - ДО при ВОП
- `cell_01_33` - ДДС при ВОП

**Секция V - Резултат:**
- `cell_01_40` - Общо начислен ДДС
- `cell_01_41` - Данък за внасяне
- `cell_01_42` - ДДС за възстановяване
- `cell_01_43` - Ефективно внесен данък
- `cell_01_50` - ДДС за внасяне от предходен период
- `cell_01_51` - Данък за внасяне (01-41 + 01-50)
- `cell_01_52` - ДДС за възстановяване (01-42 - 01-50)
- `cell_01_60` - Данъчен кредит за приспадане

**Релации:**
- belongs_to company : Company
- has_many vat_journal_entries : VatJournalEntry

#### VatRate (`backend/src/models/vat_rate.cr`)

ДДС ставки.

**Полета:**
- `name` (String) - Име на ставката
- `percentage` (Float64) - Процент ( напр. 20.0)
- `code` (String) - Код
- `saft_tax_type` (String?) - SAF-T данъчен тип
- `saft_tax_code` (String?) - SAF-T данъчен код
- `effective_from` (Time?) - Валидна от
- `effective_to` (Time?) - Валидна до
- `is_active` (Bool) - Активна

#### VatJournalEntry (`backend/src/models/vat_journal_entry.cr`)

Запис в ДДС дневник (продажби или покупки).

**Общи полета:**
- `row_number` (Int32) - Пореден номер
- `document_type` (String) - Вид документ (01-95)
- `document_number` (String) - Номер на документа (20 символа)
- `document_date` (Time) - Дата на документа
- `counterpart_vat` (String?) - ИН на контрагента (15 символа)
- `counterpart_name` (String?) - Име на контрагента (50 символа)
- `goods_description` (String?) - Вид на стоката/услугата (30 символа)
- `delivery_code` (String?) - Колона 8а: 01,02,03,07,08,41,43,46,48,51,53,54,58
- `entry_type` (String) - "purchase" или "sales"

**Колони за покупки (POKUPKI.TXT):**
- `base_no_credit` - ДО без право на данъчен кредит
- `base_full_credit` - ДО с право на пълен данъчен кредит
- `vat_full_credit` - ДДС с право на пълен данъчен кредит
- `base_partial_credit` - ДО с право на частичен ДК
- `vat_partial_credit` - ДДС с право на частичен ДК
- `annual_adjustment_base` - Годишна корекция ДО
- `annual_adjustment_vat` - Годишна корекция ДДС
- `base_20` - ДО при ставка 20%
- `vat_20` - ДДС при ставка 20%
- `vop_base` - ДО при ВОП
- `vop_vat` - ДДС при ВОП
- `base_9` - ДО при 9% ставка
- `vat_9` - ДДС при 9% ставка

**Колони за продажби (PRODAJBI.TXT):**
- `total_base` - Общ размер на данъчната основа
- `total_vat` - Всичко начислен ДДС
- `sales_base_20` - ДО облагаеми със ставка 20%
- `sales_vat_20` - ДДС 20%
- `sales_base_vop` - ДО при ВОП и чл.82
- `sales_vat_vop` - ДДС при ВОП и чл.82
- `sales_base_9` - ДО облагаеми със ставка 9%
- `sales_vat_9` - ДДС 9%
- `sales_base_0_chapter3` - ДО облагаеми със ставка 0% по глава 3
- `sales_base_vod` - ДО на ВОД (вътреобщностни доставки)
- `sales_base_0_articles` - ДО по чл.140,146,173
- `sales_base_services_21` - Услуги по чл.21 ал.2
- `sales_base_69_2` - ДО по чл.69 ал.2
- `sales_base_69_2_eu` - ДО по чл.69 ал.2 към ЕС
- `sales_base_exempt` - Освободени доставки
- `sales_vat_personal` - ДДС за лични нужди
- `sales_base_vop_9` - ДО при ВОП със ставка 9%

### Миграции

```
backend/db/migrations/
├── 20250126000021_create_vat_returns.cr       # Създава VatReturn
├── 20250126000044_add_vat_fields_to_journal_entries.cr
├── 20250126000047_create_vat_journal_entries.cr
├── 20250126000048_extend_vat_returns.cr
├── 20250126000004_create_vat_rates.cr        # Създава VatRate
├── 20250129000004_add_vat_submission_fields.cr
└── 20250131000002_remove_branch_code_from_vat_journal_entries.cr
```

## API Endpoints

### VatReturns Controller

| Метод | Endpoint | Описание |
|-------|----------|----------|
| GET | `/api/companies/:company_id/vat_returns` | Списък с ДДС декларации |
| GET | `/api/companies/:company_id/vat_returns/:id` | Детайли за декларация |
| POST | `/api/companies/:company_id/vat_returns` | Създаване на декларация |
| PATCH | `/api/companies/:company_id/vat_returns/:id` | Редактиране на декларация |
| DELETE | `/api/companies/:company_id/vat_returns/:id` | Изтриване на декларация |
| GET | `/api/companies/:company_id/vat_returns/:id/entries` | Записи в дневника |
| POST | `/api/companies/:company_id/vat_returns/:id/import_from_journal` | Импорт от счетоводни записи |
| POST | `/api/companies/:company_id/vat_returns/:id/calculate` | Изчисляване на ДДС |
| GET | `/api/companies/:company_id/vat_returns/:id/export/:type` | Експорт (deklar/pokupki/prodajbi) |

### VatRates Controller

| Метод | Endpoint | Описание |
|-------|----------|----------|
| GET | `/api/companies/:company_id/vat_rates` | Списък с ДДС ставки |
| POST | `/api/companies/:company_id/vat_rates` | Създаване на ставка |
| PATCH | `/api/vat_rates/:id` | Редактиране на ставка |
| DELETE | `/api/vat_rates/:id` | Изтриване на ставка |

## Бизнес логика

### Изчисляване на ДДС (`calculate.cr`)

Процесът на изчисление:

1. **Взимане на информация за представител** - от настройките на фирмата (управител или упълномощено лице)

2. **Зареждане на записите** - всички VatJournalEntry за периода (покупки и продажби)

3. **Сумиране по клетки** - всяка клетка се сумира от съответните полета на записите

4. **Изключени документи** - кодове 04, 05, 11, 12, 13, 94 не се включват в обобщението

5. **Изчисляване на резултата:**
   - `cell_01_40` = cell_01_02 + cell_01_04 + cell_01_06 + cell_01_17 (общо начислен ДДС)
   - total_input_vat = cell_01_22 + cell_01_24 + cell_01_26 + cell_01_31 + cell_01_33
   - vat_result = cell_01_40 - total_input_vat (положителен = за внасяне, отрицателен = за възстановяване)

6. **Запазване на резултата** - всички клетки се записват в базата

### Импорт от счетоводни записи (`import_from_journal.cr`)

1. Зареждат се всички фактури за периода
2. Класифицират се като покупки или продажби според вида
3. Създават се VatJournalEntry записи с разпределение по ДДС ставки

## Кодове на документи

### За покупки (POKUPKI.TXT)

| Код | Описание |
|-----|----------|
| 01 | Фактура |
| 02 | Дебитно известие |
| 03 | Кредитно известие |
| 05 | Регистър стоки до поискване |
| 07 | Митническа декларация |
| 09 | Протокол |
| 11 | Фактура - касова отчетност |
| 12 | ДИ - касова отчетност |
| 13 | КИ - касова отчетност |
| 23 | КИ по чл.126б |
| 91 | Протокол чл.151в ал.3 |
| 92 | Протокол чл.151г ал.8 |
| 93 | Протокол чл.151в ал.7 (без режим) |
| 94 | Протокол чл.151в ал.7 (с режим) |

### За продажби (PRODAJBI.TXT)

| Код | Описание |
|-----|----------|
| 01 | Фактура |
| 02 | Дебитно известие |
| 03 | Кредитно известие |
| 04 | Регистър стоки до поискване |
| 09 | Протокол |
| 11 | Фактура - касова отчетност |
| 12 | ДИ - касова отчетност |
| 13 | КИ - касова отчетност |
| 29 | КИ по чл.126б |
| 50 | Известие за продажба |
| 81 | Отчет за извършени продажби |
| 82 | Отчет продажби чл.119 |
| 83 | Отчет за безвъзмездни доставки |
| 84 | Отчет за корекции на ДДС |
| 85 | Отчет доставки чл.163а |
| 95 | Протокол по чл.117 ал.4 |

### Кодове за доставка (колона 8а)

| Код | Описание |
|-----|----------|
| 01 | Доставка по част I Приложение 2 |
| 02 | Доставка по част II Приложение 2 |
| 03 | Внос по Приложение 3 |
| 07 | Доставка по чл.163а |
| 08 | Доставка по чл.163б |
| 41 | Изпращане стоки режим складиране |
| 43 | Замяна на лицето чл.15а ал.4 |
| 46 | Корекция грешен ИН |
| 48 | Връщане на стоки чл.15а ал.5 |
| 51 | Пристигане стоки режим складиране |
| 53 | Замяна без прекратяване |
| 54 | Брак/липса/унищожаване |
| 58 | Прекратяване на договора |

## Експорт за НАП

### DEKLAR.TXT

Главна ДДС декларация - фиксиран формат 590 знака + CRLF.

**Структура:**
- 00-01: ИН по ЗДДС с BG (15)
- 00-02: Наименование (50)
- 00-03: Данъчен период YYYYMM (6)
- 00-04: Лице подаващо данните (50)
- 00-05: Брой документи продажби (15)
- 00-06: Брой документи покупки (15)
- 01-01 до 01-82: Клетки на декларацията (по 15 знака всяка)

### POKUPKI.TXT

Дневник покупки - фиксиран формат, един ред на документ.

**Колони:**
- 03-01: ИН по ЗДДС с BG (15)
- 03-02: Данъчен период YYYYMM (6)
- 03-03: Клон/поделение (4)
- 03-04: Пореден номер (15)
- 03-05: Вид документ (2)
- 03-06: Номер документ (20)
- 03-07: Дата (10)
- 03-08: ИН доставчик (15)
- 03-09: Име доставчик (50)
- 03-10: Вид стока (30)
- 03-30 до 03-44: Суми (по 15 знака)
- 03-45: Код доставка (2)

### PRODAJBI.TXT

Дневник продажби - фиксиран формат, един ред на документ.

**Колони:**
- 02-01: ИН по ЗДДС с BG (15)
- 02-02: Данъчен период YYYYMM (6)
- 02-03: Клон/поделение (4)
- 02-04: Пореден номер (15)
- 02-05: Вид документ (2)
- 02-06: Номер документ (20)
- 02-07: Дата (10)
- 02-08: ИН клиент (15)
- 02-09: Име клиент (50)
- 02-10: Вид стока (30)
- 02-10 до 02-26: Суми (по 15 знака)
- 02-27: Код доставка (2)

### Кодиране

Всички файлове се конвертират от UTF-8 към Windows-1251 чрез gnu-iconv преди изтегляне.

## Frontend (Leptos)

### Страници

**`leptos/src/pages/vat_returns.rs`**

Основната страница за управление на ДДС декларации.

**Функционалност:**
- Списък с декларации по период
- Създаване на нова декларация
- Преглед на детайли
- Импорт от счетоводни записи
- Изчисляване на ДДС
- Експорт (печат PDF, Excel)
- Изтриване на записи

**Табове:**
1. **Обобщение** - общи суми и резултат
2. **Дневник покупки** - записи от покупки
3. **Дневник продажби** - записи от продажби
4. **Декларация** - преглед на всички клетки
5. **VIES** - (резервирано за бъдещо развитие)

### Константи

**`leptos/src/constants/vat_codes.rs`**

Дефиниции на всички кодове (видове документи, доставки), валидация на ДДС номера.

## Интеграции

### SAF-T

Данните от VatJournalEntry се използват при генериране на SAF-T XML за НАП.

### Контролизи

Импортът от Контролизи автоматично създава VatJournalEntry записи.

## Workflow

```
1. Създаване на ДДС период (месец/година)
         ↓
2. Импорт от счетоводни записи или ръчно добавяне
         ↓
3. Преглед и корекция на записите в дневниците
         ↓
4. Изчисляване на ДДС (автоматично сумиране по клетки)
         ↓
5. Преглед на обобщението и декларацията
         ↓
6. Експорт на файлове за НАП
         ↓
7. Подаване в НАП (ръчно или API)
         ↓
8. Маркиране като "submitted"
```

## Тестване

Тестовете се намират в `backend/spec/`.

```bash
cd backend
lucky spec
```

---

**Последна актуализация:** 16 Март 2026
