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

​

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

​

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

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

​

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

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 задним числом

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

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

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

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)

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-кошелька.