> ## Documentation Index
> Fetch the complete documentation index at: https://whalescorp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# План реализации

## Фаза 1 — Готовность к production (P0)

### 1.1 — Генерация PDF invoice

Файлы: `api/lib/pdf-invoice.ts` (новый), `api/routes/instance-admin.ts`\
UI: кнопка `Download PDF` в диалоге деталей `InvoiceSection`

### 1.2 — Отметка invoice как оплаченного

```text theme={null}
ALTER TABLE invoices ADD COLUMN paid_at TIMESTAMPTZ;
ALTER TABLE invoices ADD COLUMN payment_ref TEXT;
```

Файлы: `api/routes/instance-admin.ts`, действие `mark_invoice_paid`\
\
UI: кнопка `Mark as Paid` в `InvoiceSection`, только для `owner/admin`

### 1.3 — Заполнение `billing_period` задним числом

```text theme={null}
UPDATE fee_ledger SET billing_period = DATE_TRUNC('month', created_at)::DATE
WHERE billing_period IS NULL;
```

## Фаза 2 — Credit notes и dunning (P1)

### 2.1 — Credit notes

```text theme={null}
CREATE TABLE credit_notes (
  id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  instance_id    UUID NOT NULL REFERENCES instances(id),
  invoice_id     UUID NOT NULL REFERENCES invoices(id),
  credit_number  TEXT NOT NULL,
  amount_usdc    NUMERIC(18,6) NOT NULL,
  reason         TEXT NOT NULL,
  status         TEXT DEFAULT 'draft' CHECK (status IN ('draft','issued','applied','void')),
  issued_at      TIMESTAMPTZ,
  created_at     TIMESTAMPTZ DEFAULT NOW()
);
```

### 2.2 — Cron для overdue + email

Файлы: `api/queue/billing-cron.ts`, ночная задача\
\
Файлы: `api/routes/instance-admin.ts`, отправка email при `finalize_invoice`

## Фаза 3 — Distribution model (P0 для distribution-сценариев)

### 3.1 — Поля distribution для merchant

```text theme={null}
ALTER TABLE merchants
  ADD COLUMN merchant_type TEXT DEFAULT 'standard'
    CHECK (merchant_type IN ('standard','agent','reseller')),
  ADD COLUMN agent_commission_pct NUMERIC(5,3) DEFAULT 0,
  ADD COLUMN settlement_currency TEXT DEFAULT 'USD',
  ADD COLUMN settlement_period_days INT DEFAULT 30,
  ADD COLUMN country TEXT;
```

### 3.2 — Уровни distribution

```text theme={null}
ALTER TABLE fee_tiers
  ADD COLUMN rebate_pct NUMERIC(5,3) DEFAULT 0,
  ADD COLUMN rebate_volume_tiers JSONB DEFAULT '[]',
  ADD COLUMN rebate_settlement_delay_days INT DEFAULT 7;
```

### 3.3 — Таблицы settlement и rebate

Миграция `044`: `merchant_settlements` и `merchant_rebates`, полный `DDL` см. в §6

### 3.4 — Settlement API actions

Новые действия в `instance-admin.ts`:

* `generate_settlement` — создать settlement statement для merchant и периода\\
* `finalize_settlement` — выпустить документ для merchant\\
* `mark_settlement_paid` — зафиксировать оплату и запустить расчет rebate\\
* `list_settlements` — постраничный список по инстансу\\
* `get_settlement` — детали и line items\\
* `list_rebates` — rebate notices по инстансу\\
* `mark_rebate_paid` — зафиксировать выплату rebate и `tx_hash`\\

### 3.5 — Settlement UI

Новые подвкладки в `RevenueTab`:

* `Settlements` — statements по мерчантам, генерация, выпуск и отметка оплаты\\
* `Rebates` — rebate notices, статусы и фиксация выплат\\

## Фаза 4 — Автоматизация сбора комиссий (P1)

### 4.1 — Очередь повторных попыток сбора

Повторная задача использует `next_retry_at` и `collection_attempts`. Применяется exponential backoff по формуле `1h × 2^attempts`. Максимум 5 попыток, после чего статус становится `abandoned`.

### 4.2 — Enforcement для `billing_mode`

В `collectCreationFee()`: если `instance.settings.billing_mode === 'invoice'`, то нужно установить `collection_status = 'invoiced'` и пропустить on-chain перевод.

## Фаза 5 — Аналитика и сверка (P2)

### 5.1 — Ночная задача сверки

Сравнивает суммы в `fee_ledger` с ожидаемыми значениями на основе количества чеков.

### 5.2 — Автообновление volume tier

Ежемесячная проверка относительно `volume_threshold_monthly`.

### 5.3 — Графики выручки

Скользящий 12-месячный тренд в `AdminB2BDashboardTab`.

## Фаза 6 — Документирование курса USDC (P1)

```text theme={null}
ALTER TABLE invoices
  ADD COLUMN rate_at_invoice NUMERIC(12,6) DEFAULT 1.0,
  ADD COLUMN rate_source TEXT DEFAULT 'assumed_peg',
  ADD COLUMN subtotal_usd NUMERIC(18,6),
  ADD COLUMN total_usd NUMERIC(18,6);

ALTER TABLE fee_ledger
  ADD COLUMN usdc_rate_at_collection NUMERIC(12,6),
  ADD COLUMN usd_fmv NUMERIC(12,6);
```

## Фаза 7 — Брендированный PDF через Gotenberg (P2)

Добавить контейнер `gotenberg/gotenberg:8` в `docker-compose.yml`. Создать `api/templates/` с HTML-шаблонами invoice и settlement, поддерживающими брендинг инстанса: логотип, цвета и QR-код USDC-кошелька.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.