Zly vlk a API pro Krajský Energetický Managemant

Aplikace pracuje momentálně s daty z MariaDB a MinIO. V MariaDB jsou uložena data o jednotlivých neziskových organizacích Ústeckého kraje. Jako jsou:

  • informace o areálech organizace
  • IČO a adresy sídel
  • informace o budovách organizace
  • informace o odběrných místech organizace
  • informace o měřidlech
  • spotřeby komodit V MinIO jsou uloženy soubory organizace:
  • fotodokumentace
  • doklady
  • smlouvy

Spuštění aplikace

Je třeba vytvořit vyplněný .env soubor na základě .env.example.

Aplikace se následně spouští pomocí poetry

poetry shell
poetry install
poetry run uvicorn app.main:app --reload

Autentizace a Autorizace

Pro autentizaci uživatele slouží Keycloak, který na základě přihlašovacích údajů vrátí token, který z FrontEndu chodí v každém dotazu na API. Autorizaci obstarává autorizační modul v API, který na základě ověřeného tokenu filtruje data, ke kterým má uživatel přístup.

API endpointy

API je momentálně rozdělena na sekce podle jednotlivých databází.

  • dokumenty
  • kem2
  • subjekty
  • uzivatele
  • minio

Volání endpointu

Přístupový token musí být zahrnut v hlavičce každého požadavku na API jako Authorization: Bearer your-access-token.

curl -X 'GET' \
  'http://127.0.0.1:8000/v1/subjekty/subjekty/1' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI0aUc2R0tYdmVmQmxBbncydWN2SnBoLVptMDFiSVZRSTZibFNER3FqZ0VvIn0.eyJleHAiOjE3MTkyNTgxODksImlhdCI6MTcxOTIyMjE4OSwianRpIjoiNDg1NGMzNmYtNGQzMi00NzAzLTk4MGItM2FmZmE1MWQxNzVjIiwiaXNzIjoiaHR0cDovLzE5Mi4xNjguMjcuNTUvcmVhbG1zL1BvcnRhYm8iLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiOGFiN2U2YjctYzlkMy00ZDU4LThmODgtODNjNWIzNTU5OWY4IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoibG9yYXdhbi1hcGkiLCJzZXNzaW9uX3N0YXRlIjoiZWMyNzI5MDgtNGY4OC00ZDU3LTkzMDAtMjA3NGVlOThiMzQ4IiwiYWNyIjoiMSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIiwiYWRtaW5FbmVyZ28iLCJkZWZhdWx0LXJvbGVzLXBvcnRhYm8iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6ImVtYWlsIHByb2ZpbGUiLCJzaWQiOiJlYzI3MjkwOC00Zjg4LTRkNTctOTMwMC0yMDc0ZWU5OGIzNDgiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwicHJpc3R1cHlfa2xpbWFwcCI6WyJ7XCJJQ09cIjogXCJnYWxlcmllLXJvdWRuaWNlXCIsIFwiUEVSTUlTU0lPTlNcIjogW10sIFwiVVJMXCI6W1wiKlwiXX0iLCJ7XCJJQ09cIjogXCIwMDM2MDY0M1wiLCBcIlBFUk1JU1NJT05TXCI6IFtcImVkaXRvclwiXSwgXCJVUkxcIjpcIipcIn0iLCJ7XCJJQ09cIjogXCIwOTY1ODM1MVwiLCBcIlBFUk1JU1NJT05TXCI6IFtdLCBcIlVSTFwiOltcIipcIl19Il0sInByZWZlcnJlZF91c2VybmFtZSI6Im1hcmVrLnRyZW1lbCIsImVtYWlsIjoibWFyZWsudHJlbWVsQHBvcnRhYm8uY3oifQ.rQqoOoOuw41bdSlS3NwYxT6xJ7E_hKOlo6zsG9Efa_KR47VNcrE4KFrf4FWhOK-RR3G28H9gM8CnuKIoSbC2lCDCT3IsVVppsKFoE_swKDZwTDNA16JkSL0h_4AAykRe1II2dGsEVeJQEXLHbLWsOicS7vOspNTAdqbkANrjI_rToaJu9E1ssbnwjuM-SvS4yfVIldkXk8GXZ4ovUHZtgeghOLAMuDfRd01RwkJPWF7h61xO43RnR0BVJzabIrUtqY7A7h7Ek46misXDOhlXlq9bIy3yFpAuCtdRNAdb2sxMyoeXvvOpuEXG_xbz7L6CvzwjV993PJ_aq6167y36_w'

Použité knihovny

  • python = "^3.12"
  • fastapi = "^0.111.0"
  • sqlalchemy = "^2.0.31"
  • pymysql = "^1.1.1"
  • ruff = "^0.4.10"
  • toml = "^0.10.2"
  • pydantic-settings = "^2.3.4"
  • cachetools = "^5.3.3"
  • requests = "^2.32.3"
  • pyjwt = "^2.8.0"
  • cryptography = "^42.0.8"
  • fastapi-pagination = "^0.12.26"
  • minio = "^7.2.7"

Práva v aplikaci

Autorizační modul v API se skládá z několika tabulek: uzivatel, pristupy, opravneni a role.

  • Tabulka uzivatel obsahuje základní informace o uživateli jako jméno, příjmení a emeail a také unikátní identifikátor z Keycloaku (SUB)
  • Tabulka opravneni obsahuje stromovou strukturu oprávnění. Sloupce tabulky jsou: id_opravneni, odbor, organizace, areal, objekt, om, meridlo
    • id_opravneni: primární klíč tabulky
    • odbor: id odboru na které má uživatel právo - pokud má uživatel přístup na celý odbor, víc se v tabulce nevyplňuje
    • organizace: id organizace na kterou má uživatel právo - pokud má uživatel právo na celou organizaci, odbor a ostatní sloupečky se nevyplňují
    • areal: Uživatel může mít přístup na jeden z areálů organizace a všechny budovy, odběrná místa a měřidla v něm. Pro takový přístup je nutné vyplnit sloupec organizace a areal
    • objekt: Sloupec udává přístup k určitému objektu/budově. TODO Je otázka, jak bude vyplňovat předchozí sloupec areál. Budova nemusí být přiřazena v žádném areálu, tudíž sloupec areal zůstane prázdný, ale pokud je budova zařazena do areálu, nevyplnění tohoto sloupce znamená, že se uživatel na budovu proklikne pouze přes záložku Budovy na frontendu, nikoli přes areál ve kterém je budova zařazena
    • om: Sloupec udává odběrné místo, na které má uživatel přístup. TODO Stejně jako u objektu nastává otázka, zda vyplňovat předchozí sloupce.
    • meridlo: Sloupec udává, k jakému měřidlu má uživatel přístup. V databázi se měřidlem může myslet vozidlo ve vozovém parku. Vozový park se tváří jako OM. Pro přístup na jedno měřidlo je třeba vyplnit sloupec *om pod které měřidlo spadá.
  • Tabulka role obsahuje číselník rolí se sloupci, editor a create_user, které udávají, zda uživatel může editovat záznamy a vytvářet další uživatele. Aktuální seznam rolí: management, technický pracovník, admin ecuk, vedoucí odboru
  • Tabulka pristupy je relační tabulka, která propojuje tabulky uzivatel, opravneni a role. Dále obsahuje sloupce active a created, které udávají, jestli je daný záznam aktivní a kdy byl vytvořen.

Příklad práv

  • technický pracovník, má přístup k jednomu areálu v organizaci tabulka opravneni

    id_opravneni odbor organizace areal objekt om meridlo
    1 NULL 1 1 NULL NULL NULL

    obdobně pro ostatní sloupce dle popisu výše

  • management organizace

    id_opravneni odbor organizace areal objekt om meridlo
    1 NULL 1 NULL NULL NULL NULL

  • vedoucí odboru

    id_opravneni odbor organizace areal objekt om meridlo
    1 1 NULL NULL NULL NULL NULL

  • ECUK admin

    • zde si nejsem moc jistý, napadly mě 2 varianty, jak zapisovat takového uživtale TODO
    • Př 1: \ tabulka opravneni
    id_opravneni odbor organizace areal objekt om meridlo
    1 id_odbor pro ECUK NULL NULL NULL NULL NULL

    tabulka pristupy

    id_pristup id_uzivatel id_opravneni active created id_role
    1 1 1 1 2024-08-15 12:02:29.000 id_role pro admin ECUK
    • Př 2:

    tabulka pristupy

    id_pristup id_uzivatel id_opravneni active created id_role
    1 1 NULL 1 2024-08-15 12:02:29.000 id_role pro admin ECUK

Potřebná dokumentace - TODO

Ke každému projektu je zapotřebí vytvořit dokumentaci:

  1. Komunikační matice
  2. High level Design
  3. Popis jak danou aplikaci spustit

Bez této dokumentace se aplikace nedostane ani na testovací server! Pokud nevíte jak dané věci vytvořit, tak se poraďte se svým nadřízeným.