srnj01-sp

[jakubsrnka]

srnj01 - Zadávací dokumentace

Úvod

Tato webová aplikace slouží pro podniky, které nechtějí přijímat platby kartou, ale chtějí mít i možnost bezhotovostní platby ve svých pobočkách. Využívá funkce českého internetového bankovnictví a konkrétně funkce okamžitá platba v podání QR kódů.

Momentálně je na trhu pro generování QR kódů prakticky jen služba qr-platba.cz, která v tuto chvíli nepodporuje generování QR kódu s okamžitou platbou. V dokumentaci od České bankovní asociace možnost příznaku pro okamžitou platbu existuje, ale v aplikaci od qr-platba.cz není možnost využití tohoto příznaku, tudíž součástí této aplikace je i vlastní generátor QR kódů dle specifikace ČBA.

Popis stakeholderů a názvosloví

Jelikož v aplikaci figurují stakeholdeři jiní, než v běžných aplikacích, je potřeba popis jednotlivých rolí:

• admin → například hlavní správce aplikace
  • zajímá ho, jaké všechny firmy aplikaci využívají,
  • na tuto roli se nelze zvenku zaregistrovat;
• klient → kavárna, nebo třeba hamburgerový stánek,
• prodejce → barista nebo prodavač ve stánku,
• kupující → člověk kupující si kávu nebo hamburger;
  • tento uživatel se do aplikace nikdy nepřihlašuje a interaguje s ní pouze skrz skenování QR kódu a následně zaplacením ve svém mobilním bankovnictví.

Popis základních funkcí

Jak bude fungovat platba?

Cílem aplikace je hlavně jednoduchost rozhraní pro prodejce a jejich generování platebního QR kódu. Jednoduchý formulář, který dovolí několik možností pro generování:

• variabilní symbol
  • výběr z již existující řady nebo vlastní, max desetimístné číslo,
• částka (CZK).

Po vygenerování QR kódu má prodejce možnost platbu zrušit kliknutím na tlačítko (tím se v systému zaznamená jako zrušená, ale její variabilní symbol znovu již nebude pro stejné číslo účtu k dispozici), nebo počká, než kupující QR kód naskenuje svým internetovým bankovnictvím, platbu pošle a v aplikaci prodejce se ukáže rovnou platba jako zaplacená (tato výměna by měla za normálních okolností trvat do 30 sekund). Aplikace má propojení na FIO banku, momentálně prakticky jedinou banku v ČR, která poskytuje dobré API.

Celý tento interface je možný po otevření odkazu s tajným hashem, který si může prodejce uložit například na domovskou obrazovku nebo do záložek na svém mobilním telefonu, aby měl rozhraní vždy k dispozici.

Admin pro klienty

Každý klient si může otevřít svůj vlastní admin panel, díky kterému může spravovat odkazy pro své prodejce (například pobočky, ale klidně i pro jednotlivé zaměstnance), čísla účtů a má přehled o přijatých platbách na svůj účet a celkový poplatek (ve výši 0,5 % přijatých plateb).

V admin panelu je možné vytvořit propojení s FIO bankou, kam má možnost přidat až 15 API klíčů pro každý účet (FIO banka limituje svůj přístup na jeden za 30 sekund pro každý API token, takže každým dalším se zrychlí prodejní proces).

Do admin panelu je možný lokální login a OAuth.

Admin panel na správu klientů

Admin panel pro správce samotné aplikace. Možnosti vypsání klientů a jejich celkových poplatků.

Architektura

• PHP backend (REST API)
• SvelteKit + Tailwind CSS frontend
• Databáze MySQL

Stránky

• část pro prodejce
  • formulář na vygenerování platby
  • QR platba
  • seznam provedených plateb se stránkováním rozděleným na jednotlivé dny
• část pro klienty
  • registrace
  • login
  • dashboard s poplatky a celkovými sumami
  • seznam všech prodejců a jejich odkazy
  • seznam všech účtů
  • seznam všech plateb se součtem a filtrací podle prodejců, stránkování na jednotlivé dny
• admin panel na správu klientů
  • login
  • seznam všech klientů se součtem jejich poplatků

Diagramy

Usecase diagram

Procesní diagram (Část pro prodejce)

Sekvenční diagram (Admin pro klienty)

Databáze

Table users {
  id integer [primary key]
  name varchar
  email varchar
  password varchar
  role enum [note: 'admin | client']
  created_at timestamp
}

Table clients {
  id integer [primary key]
  name varchar
  active bool
  fee float
  created_at timestamp
}

Table accounts {
  id integer [primary key]
  name varchar
  client integer
  number varchar
  sequence integer [null]
  created_at timestamp
}

Table api_keys {
  id integer [primary key]
  key varchar
  account integer
  created_at timestamp
}

Table sequences {
  id integer [primary key]
  generator varchar
  last_used varchar
  created_at timestamp
}

Table sellers {
  id integer [primary key]
  name varchar
  hash varchar
  active boolean
  client integer
  created_at timestamp
}

Table generated {
  id integer
  amount float
  variable_symbol varchar
  seller integer
  account integer
  success boolean
  created_at timestamp
}

Ref: users.id <> clients.id

Ref: accounts.client > clients.id

Ref: api_keys.account > accounts.id

Ref: accounts.sequence < sequences.id

Ref: sellers.id <> accounts.id

Ref: sellers.client > clients.id

Ref: generated.account > accounts.id

Ref: generated.seller > sellers.id

Zdroje

https://cbaonline.cz/format-pro-sdileni-platebnich-udaju-v-czk-qr-kody

https://qr-platba.cz/pro-vyvojare/restful-api/

[nvbach91]

• v cem se lisi normalni qr platba od okamzite qr platby? ten okamzity qr kod ma neco navic o proti normalnimu qr kodu?
• myslim ze mate zmatek v tom kdo dela co - na co je klientum seznam prodejcu? proc klienti vytvareji pro sebe ty prodejce?
• prodejci se musi zaregistrovat, aby mohl spravovat sve pohledavky, naopak klienti nepotrebuji dalsi zpusob overovani zda jim platba odesla, ciselne rady (tabulka sequences) by mely byt spise pro prodejce a ne pro klienty

...

pravdepodobne mate zmatek v nazvoslovi ale kdyz uplne odstranite tabulku clients tak to teprve zacne davat smysl (ale vztahy budou porad spatne), tj. jak bych to videl ja:

NEJPRVE

• prodejci se zaregistruji ucet ve vasi aplikaci
• prodejci si nastavi spojeni bankovnich uctu pres Fio API keys
• prodejci si pro kazdy ucet nastavi ciselne rady pro inkrementalni variabilni symboly, tj. s kazdou novou QR platbou se vygeneruje novy unikatni variabilni symbol podle posledniho variabilniho symbolu
• prodejci jsou ready jet do terenu a zacnou generovat QR platby, behem ktere si zvoli nejakou ciselnou radu a prijmovy bankovni ucet, tj. na ktery ucet maji jejich klienti posilat

A PAK

• klienti (tj. ti co budou platit) tu QR platbu uhradi a automaticky se u prodejce pak zaktualizuje stav te zadane platby pokud skutecne byla castka pripsana na ucet
• klienti vubec nepotrebuji se zaregistrovat - na co?

TO ZNAMENA

• pro prodejce potrebujete evidovat jeho
  • bankovni ucty, v nichz potrebujete minimalne:
    • cislo uctu,
    • nazev uctu a
    • Fio API klic
    • ciselne rady (countery), v nichz potrebujete:
      • posledni cislo variabilniho symbolu
  • vygenerovane QR platby, v nichz potrebujete evidovat minimanle
    • variabilni symbol,
    • cislo prijmoveho bankovniho uctu
    • castku

[jakubsrnka]

Upravil jsem Úvod a přidal jsem Popis stakeholderů a názvosloví.

Rozdíl mezi normálním QR kódem a QR kódem pro okamžitou platbu je příznak pro okamžitou QR platbu, vizte upravený Úvod.

Do DB schámatu jsem přidal tabulku users, kam patří všichni admin a client entity (aby mohla kavárna mít třeba dva managery, kteří spravují oba dva tu stejnou kavárnu). Zároveň toto zjednodušuje přístup a kódování adminů, kteří mají přístup ke všem klientům.

Doufám, že to takto dává větší smysl.