---
title: "Архітектура Refcodes"
description: "Cookie атрибуції, PostgreSQL ledger, UUPS minter та інтеграція з PaymentConductor і ERP"
locale: "uk"
---
# Архітектура Refcodes

> **EN canonical:** повна діаграма та ролі контракту — [Refcodes architecture (EN)](/docs/architecture/refcodes.md)

## Компоненти

```mermaid
flowchart LR
    Proxy["proxy.ts ?ref="]
    Orders["POST /api/store/orders"]
    WFP["WayForPay webhook"]
    Credit["credit payment"]
    Pipeline["settlement-pipeline"]
    Rewards["ReferralRewardService"]
    DB[("PostgreSQL")]
    Chain["ReferralRewards"]

    Proxy --> Orders
    Orders --> DB
    WFP --> Pipeline
    WFP --> Rewards
    Credit --> Pipeline
    Credit --> Rewards
    Pipeline --> DB
    Rewards --> DB
    Rewards --> Chain
```

| Модуль | Шлях | Роль |
|--------|------|------|
| Cookie | `proxy.ts` | `ring_ref` + `ring_ref_visible` |
| Коди | `refcode-service.ts` | CRUD кодів |
| Атрибуція | `attribution-service.ts` | Guards, visits, signup `referredBy` |
| Винагороди | `referral-reward-service.ts` | Fiat/credit/membership |
| Mint | `reward-minter.ts` | viem `payReferral` |
| ERP ledger | `settlement-pipeline.ts` | `settlements`, `erp_sales_assists` |

## Ідемпотентність

| Шар | Ключ |
|-----|------|
| PostgreSQL | Unique `orderReference` на `referral_rewards` |
| Сервіс | `rewardExistsForOrder` |
| Контракт | `paidOrders[orderRef]` |

## Cron і beacon

- `POST /api/refcodes/track` — `visits++` на документі refcode.
- `GET /api/cron/refcodes-mint` — `Authorization: Bearer $CRON_SECRET`.

## Бази даних клонів

| Середовище | БД |
|------------|-----|
| ring-platform.org dev | `ring_platform` |
| ring-connect-software | `ring_connect_software_dev` |
| ring-ringdom-org | `ring_ringdom_org` |

Міграції: `005_refcodes_schema.sql`, `007_settlements_schema.sql`.

## Пов’язане

- [Refcodes (функція)](/docs/features/refcodes.md)
- [PaymentConductor](/docs/architecture/payment-conductor.md)
- [ERP комісії](/docs/features/erp/commissions.md)