Metadata-Version: 2.4
Name: xync-db
Version: 0.1.2
Summary: Xync DB schema: Tortoise ORM models, enums, pydantic DTOs.
Author-email: Mike Artemiev <mixartemev@gmail.com>
License: LicenseRef-EULA
Requires-Python: >=3.12
Requires-Dist: cryptography
Requires-Dist: pg-channel
Requires-Dist: pillow
Requires-Dist: pydantic-settings>=2.4
Requires-Dist: pypng
Requires-Dist: pyrogram-client
Requires-Dist: python-dotenv
Requires-Dist: qrcode[pil]
Requires-Dist: tortoise-orm[asyncpg]>=1.0
Requires-Dist: xn-auth
Description-Content-Type: text/markdown

# XyncDB
TortoiseORM models, enums, pydantic DTOs, and migrations для аггрегатора бирж/платформ p2p-торговли.
Single source of truth for data shape across the monorepo.

### Основные db сущности:
- Ex: p2p биржа/платформа

- Person: сущность живого человека / физического лица
- User: Person являющийся нашим юзером (зареганный на нашей платформе xync)
- Actor: Person являющийся любым юзером на Ex (как 3-и лица: наши контрагенты в p2p-сделках, так и наши агенты)
- Agent: Actor xync-юзера с auth-доступами к Ex, может слать запросы. Сущность с помощью которой наши Users совершают действия на Ex. (Связь с User через Actor -> Person)
- Username: telegram id, nick-и, и возможно телефоны наших User-ов

- Cur: Фиатные(банковские) валюты
- CurEx: Cur на конкретной Ex, c minimum размером сделки в этой валюте, и ее десятичный scale-ом на этой Ex
- Coin: Крипто монеты
- CoinEx: Coin на конкретной Ex, c minimum размером сделки по этой монете, и ее десятичный scale-ом на этой Ex
- Pair: Все торговые пары Coin/Cur какие бывают
- PairEx: Pair которые есть на конкретной Ex
- PairSide: Направления is_sell(продажа или покупка) по каждой Pair
- Pm: Платежные системы (банки, кошельки, и тд) фиатных валют
- PmEx: Pm на конкретной бирже (содержимое таблицы pmex говорит о том, через какие Pm какие Ex поддерживают оплату сделок)
- PmCur: Пары Pm-Cur (таблица pmcur говорит какие Pm поддерживают какие Cur
- Cred: платежные реквизиты Person-a по конкретному PmCur
- Fiat: сумма на балансе конкретного Cred
- Addr: адрес по которому лежит определенный Coin конкретного Actor-a
- Asset: сумма, которая лежит на определенном Addr

- Ad: объявление maker-a (Actor) по PairSide (т.е: о покупке или продаже Coin за Cur) для конкретных Pm
- MyAd: Ad нашего Agent-a (Actor) по конкретным Fiat-ам
- Cond: текстовое описание условий сделки по Ad
- Order: сделка открытая taker-ом (Actor) по Ad, на определенную сумму на конкретный Cred того Actor-a, кто является продавцом в сделке
- Transfer: денежный перевод определенной сумму (amount) по конкретному Order-у
- Transaction: внутренний денежный перевод (на платформе xync) от User-а sender User-у receiver

### Relations
```mermaid
classDiagram
direction BT
class Actor {
   uint8 exid
   uint1 ex_id
   varchar(63) name
   integer person_id
   integer id
}
class Ad {
   uint8 exid
   uint4 price
   integer premium
   uint4 amount
   uint8 quantity
   uint4 min_fiat
   uint4 max_fiat
   smallint status
   boolean filtered
   integer cond_id
   integer maker_id
   smallint pair_side_id
   integer id
}
class ad_pm {
   integer ad_id
   integer pm_id
}
class Addr {
   integer actor_id
   smallint coin_id
   integer id
}
class agent {
   integer actor_id
   jsonb auth
   integer expire_at
   smallint status
   uint1 same_dir_ad
   integer id
}
class Asset {
   smallint typ
   uint8 free
   uint8 freeze
   uint8 lock
   uint8 target
   integer addr_id
   integer id
}
class coin {
   varchar(15) ticker
   uint1 scale
   smallint typ
   smallint id
}
class CoinEx {
   varchar(32) exid
   uint1 ex_id
   smallint coin_id
   bigint minimum
   uint1 scale
   boolean p2p
   integer id
}
class cond {
   varchar(4095) raw_txt
   integer id
}
class Cred {
   varchar(255) detail
   varchar(127) name
   integer pmcur_id
   integer person_id
   varchar(255) extra
   integer ovr_pm_id
   integer id
}
class CredEx {
   uint8 exid
   uint1 ex_id
   integer cred_id
   integer id
}
class Cur {
   varchar(3) ticker
   uint1 scale
   uint1 id
}
class CurEx {
   varchar(32) exid
   uint1 cur_id
   uint1 ex_id
   uint4 minimum
   uint1 scale
   integer id
}
class Ex {
   varchar(31) name
   varchar(63) host
   smallint typ
   smallint status
   varchar(511) logo
   uint1 id
}
class Fiat {
   uint4 amount
   uint4 target
   uint4 min_deposit
   integer cred_id
   integer id
}
class my_ad {
   integer ad_id
   uint1 target_place
   bytea hex
   timestamp(0) shared_at
   boolean blocked
   integer id
}
class myad_cred {
   integer my_ad_id
   integer credex_id
}
class Order {
   uint8 exid
   uint4 amount
   uint8 quantity
   smallint status
   integer ad_id
   integer cred_id
   integer taker_id
   uint2 maker_topic
   uint2 taker_topic
   timestamp updated_at
   integer id
}
class Pair {
   smallint coin_id
   uint1 cur_id
   bigint rate
   smallint id
}
class pair_side {
   smallint pair_id
   boolean is_sell
   smallint id
}
class PairEx {
   smallint pair_id
   uint1 ex_id
   smallint fee
   integer id
}
class person {
   varchar(127) name
   integer user_id
   smallint status
   varchar(255) note
   integer id
}
class Pm {
   varchar(255) norm
   varchar(7) acronym
   varchar(63) alias
   boolean ok
   boolean bank
   boolean qr
   uint2 fee
   smallint typ
   integer id
}
class PmCur {
   uint1 cur_id
   integer pm_id
   integer id
}
class pmex {
   varchar(63) exid
   uint1 ex_id
   integer pm_id
   varchar(255) name
   integer id
}
class transaction {
   uint4 amount
   smallint status
   bytea proof
   integer ts
   uint1 cur_id
   integer receiver_id
   integer sender_id
   uuid id
}
class transfer {
   uint4 amount
   varchar(32) pmid
   varchar(63) sender_acc
   integer order_id
   integer file_id
   integer id
}
class user {
   varchar(63) first_name
   varchar(31) last_name
   varchar(127) pic
   boolean blocked
   smallint lang
   smallint role
   smallint status
   uint2 bonus
   smallint tz
   bytea prv
   bytea pub
   integer ref_id
   bigint username_id
   integer id
}
class username {
   varchar(127) username
   uint8 phone
   bigint id
}

Actor  -->  Ex : ex_id->ex.id
Actor  -->  person : person_id->person.id
Ad  -->  Actor : maker_id->maker.id
Ad  -->  cond : cond_id->cond.id
Ad  -->  pair_side : pair_side_id->pair_side.id
ad_pm  -->  Ad : ad_id->ad.id
ad_pm  -->  Pm : pm_id->pm.id
Addr  -->  Actor : actor_id->actor.id
Addr  -->  coin : coin_id->coin.id
agent  -->  Actor : actor_id->actor.id
Asset  -->  Addr : addr_id->addr.id
Asset  -->  agent : agent_id->agent.id
CoinEx  -->  coin : coin_id->coin.id
CoinEx  -->  Ex : ex_id->ex.id
Cred  -->  person : person_id->person.id
Cred  -->  Pm : ovr_pm_id->ovr_pm.id
Cred  -->  PmCur : pmcur_id->pmcur.id
CredEx  -->  Cred : cred_id->cred.id
CredEx  -->  Ex : ex_id->ex.id
CurEx  -->  Cur : cur_id->cur.id
CurEx  -->  Ex : ex_id->ex.id
Fiat  -->  Cred : cred_id->cred.id
my_ad  -->  Ad : ad_id->ad.id
myad_cred  -->  CredEx : credex_id->credex.id
myad_cred  -->  my_ad : my_ad_id->my_ad.id
Order  -->  Actor : taker_id->taker.id
Order  -->  Ad : ad_id->ad.id
Order  -->  Cred : cred_id->cred.id
Pair  -->  coin : coin_id->coin.id
Pair  -->  Cur : cur_id->cur.id
pair_side  -->  Pair : pair_id->pair.id
PairEx  -->  Ex : ex_id->ex.id
PairEx  -->  Pair : pair_id->pair.id
person  -->  user : user_id->user.id
Pm  -->  Cur : df_cur_id->df_cur.id
PmCur  -->  Cur : cur_id->cur.id
PmCur  -->  Pm : pm_id->pm.id
pmex  -->  Ex : ex_id->ex.id
pmex  -->  Pm : pm_id->pm.id
transaction  -->  Cur : cur_id->cur.id
transaction  -->  user : sender_id->sender.id
transaction  -->  user : receiver_id->receiver.id
transfer  -->  Order : order_id->order.id
user  -->  user : ref_id->ref.id
user  -->  username : username_id->username.id
```

###### Общее правило для всех сущностей, которые относятся к конкретной Ex:
`[Actor, CoinEx, CurEx, PmEx, CredEx, Ad, Order]`
- `id` - id сущности в нашей системе (в xync)
- `exid` - id сущности на этом `Ex`
- `ex_id` - id `Ex`-a которому принадлежит сущность

Исключение `Ad` и `Order`:
- в `Ad` нет непосредственно `ex_id`, у него есть `maker_id`, через которого получаем `actor.ex_id`
- а в `Order` соответственно через `ad_id` получаем `ad.actor.ex_id`


## Migrations (native Tortoise CLI — no aerich)
```bash
cd packages/xync-db
tortoise init              # only once
tortoise makemigrations    # detect changes
tortoise migrate           # apply
tortoise downgrade models 0001_initial   # roll back
tortoise sqlmigrate models 0001_initial  # preview SQL
```
Config lives in this package's `pyproject.toml` under `[tool.tortoise]`.
