Home Assistant API

Link do aplikacji: https://ti.matra.cc logowanie: admin admin123

Link do repozytorium: https://github.com/fmatrac/home-assistant-api

Aplikacja do zarządzania domem i życiem osobistym napisana w języku Go z wbudowanym interfejsem webowym. System umożliwia zarządzanie kalendarzem wydarzeń, przypomnieniami, produktami, listami zakupów oraz stanami magazynowymi.

Uwaga: Cała inicjalizacja bazy danych (schemat, tabele, typy) znajduje się w folderze migrations/.

1. Wprowadzanie danych

System obsługuje następujące metody wprowadzania danych:

1.1 Wprowadzanie ręczne (główna metoda)

Podstawowym sposobem wprowadzania danych jest interfejs webowy aplikacji. Użytkownik może ręcznie dodawać, edytować i usuwać dane poprzez formularze modalne dostępne w każdej sekcji aplikacji:

Wydarzenia kalendarzowe - formularze z polami: tytuł, opis, priorytet, data rozpoczęcia/zakończenia, miejsce
Przypomnienia - formularze z polami: tytuł, opis, status, data uruchomienia, powiązanie z wydarzeniem
Produkty - formularze z polami: nazwa, kategoria, ulubiony, link do zakupu
Listy zakupów - formularze z polami: nazwa, status listy
Pozycje list zakupów - formularze z polami: produkt, ilość, notatka
Stany magazynowe - formularze z polami: produkt, stan (ok/mało/brak)

1.2 Wprowadzanie przez API (automatyczne/programowe)

System udostępnia REST API umożliwiające automatyczne wprowadzanie danych przez zewnętrzne aplikacje lub skrypty:

# Przykład dodania produktu przez API
curl -X POST http://localhost:8000/api/produkty \
  -H "Content-Type: application/json" \
  -d '{"nazwa": "Mleko", "kategoria": "Nabiał", "ulubiony": true}'

1.3 Import danych (SQL)

Dane można importować bezpośrednio do bazy PostgreSQL za pomocą skryptów SQL. Przykładowe skrypty znajdują się w katalogu scripts/:

# Import danych z pliku SQL
psql -h localhost -U home_assistant_user -d home_assistant -f scripts/seed_produkty.sql

1.4 Podsumowanie metod wprowadzania danych

Metoda	Typ	Opis
Interfejs webowy	Ręczne	Formularze modalne w przeglądarce
REST API	Automatyczne	Żądania HTTP JSON
Skrypty SQL	Import	Bezpośredni import do bazy danych

2. Dokumentacja użytkownika

2.1 Wymagania systemowe

Docker i Docker Compose (zalecane)
Lub: Go 1.24+, PostgreSQL 18+

2.2 Instalacja i uruchomienie

Metoda 1: Docker Compose (zalecana)

# Klonowanie repozytorium
git clone <url-repozytorium>
cd home-assistant-api

# Uruchomienie aplikacji
docker compose up -d

# Aplikacja dostępna pod adresem:
# http://localhost:8000

Metoda 2: Uruchomienie lokalne

# Instalacja zależności
go mod download

# Konfiguracja bazy danych (PostgreSQL)
# Edytuj config/config.yaml z danymi połączenia

# Uruchomienie migracji
goose -dir migrations postgres "postgres://user:pass@localhost:5432/home_assistant" up

# Uruchomienie aplikacji
go run cmd/main.go

3. Dokumentacja techniczna

3.1 Architektura systemu

Aplikacja wykorzystuje architekturę warstwową:

┌─────────────────────────────────────────┐
│           Frontend (SPA)                │
│    HTML + CSS + Vanilla JavaScript      │
├─────────────────────────────────────────┤
│          HTTP Server (api.go)           │
│         Routing i middleware            │
├─────────────────────────────────────────┤
│      Application (application.go)       │
│      Handlery HTTP, logika biznesowa    │
├─────────────────────────────────────────┤
│         Repositories (*_repository.go)  │
│         Warstwa dostępu do danych       │
├─────────────────────────────────────────┤
│            PostgreSQL 18                │
│         Schemat: home_assistant         │
└─────────────────────────────────────────┘

3.2 Stos technologiczny

Komponent	Technologia	Wersja
Backend	Go	1.24.5
Baza danych	PostgreSQL	18
Frontend	HTML/CSS/JavaScript	-
Logowanie	Logrus	1.9.3
Konfiguracja	Viper	1.21.0
Migracje	Goose	-
Konteneryzacja	Docker	-

3.3 Struktura projektu

home-assistant-api/
├── cmd/
│   └── main.go                 # Punkt wejścia aplikacji
├── pkg/
│   ├── api/
│   │   └── api.go              # Serwer HTTP, rejestracja tras
│   ├── application/
│   │   └── application.go      # Handlery HTTP, logika biznesowa
│   ├── postgres/
│   │   ├── models.go           # Modele danych (struktury Go)
│   │   ├── types.go            # Interfejs DB i enumy
│   │   ├── repository_interface.go  # Interfejsy repozytoriów
│   │   ├── produkty_repository.go
│   │   ├── listy_zakupow_repository.go
│   │   ├── pozycje_listy_zakupow_repository.go
│   │   ├── stany_magazynowe_repository.go
│   │   ├── historia_stanu_zapasow_repository.go
│   │   ├── przypomnienia_repository.go
│   │   └── wydarzenia_kalendarz_repository.go
│   └── logger/
│       └── logger.go           # Wrapper Logrus
├── web/
│   ├── embed.go                # Deklaracja embedded FS
│   ├── index.html              # Główny interfejs HTML
│   ├── js/
│   │   ├── api.js              # Warstwa klienta API
│   │   └── app.js              # Logika frontendu
│   └── css/
│       └── style.css           # Style CSS
├── config/
│   ├── config.go               # Ładowanie konfiguracji
│   └── config.yaml             # Plik konfiguracyjny
├── migrations/
│   └── 00001_initialize_db.sql # Schemat bazy danych
├── db-init/
│   └── 01-init-schema.sql      # Inicjalizacja schematu (Docker)
├── compose.yaml                # Konfiguracja Docker Compose
├── Dockerfile                  # Multi-stage build
├── go.mod                      # Zależności Go
└── Makefile                    # Komendy build/clean

3.4 Model danych

3.4.1 Diagram ERD

wydarzenia_kalendarz          przypomnienia
┌──────────────────┐         ┌──────────────────────┐
│ id (PK)          │◄───────┤│ id (PK)              │
│ tytul            │         │ id_wydarzenia (FK)   │
│ opis             │         │ tytul                │
│ priorytet        │         │ opis                 │
│ data_startu      │         │ status               │
│ data_zakonczenia │         │ nastepne_uruchomienie│
│ miejsce          │         │ utworzono            │
│ utworzono        │         └──────────────────────┘
└──────────────────┘

produkty                      listy_zakupow
┌──────────────────┐         ┌──────────────────┐
│ id (PK)          │         │ id (PK)          │
│ nazwa            │         │ nazwa            │
│ kategoria        │         │ status           │
│ ulubiony         │         │ utworzono        │
│ link_do_kupna    │         └────────┬─────────┘
│ utworzono        │                  │
└────────┬─────────┘                  │
         │                            │
         │    pozycje_listy_zakupow   │
         │   ┌──────────────────────┐ │
         └──►│ id (PK)              │◄┘
             │ id_listy_zakupow (FK)│
             │ id_produktu (FK)     │
             │ ilosc                │
             │ notatka              │
             │ czy_kupione          │
             └──────────────────────┘

produkty                     stany_magazynowe
┌──────────────────┐        ┌─────────────────────┐
│ id (PK)          │◄──────┤│ id (PK)             │
└──────────────────┘        │ id_produktu (FK)    │
         │                  │ stan                │
         │                  │ ostatnio_sprawdzono │
         │                  └─────────────────────┘
         │
         │   historia_stanu_zapasow
         │  ┌──────────────────┐
         └─►│ id (PK)          │
            │ id_produktu (FK) │
            │ stan             │
            │ data_zmiany      │
            │ notatka          │
            └──────────────────┘

3.4.2 Typy wyliczeniowe (ENUM)

-- Priorytet wydarzenia
priorytet: 'maly', 'sredni', 'duzy'

-- Status przypomnienia
status_przypomnienia: 'aktywne', 'zrealizowane', 'zapauzowane'

-- Status listy zakupów
status_listy_zakupow: 'otwarta', 'zamknieta'

-- Stan zapasów
stan_zapasow: 'ok', 'malo', 'brak'

3.5 API REST - Dokumentacja endpointów

Serwer nasłuchuje na porcie 8000 (konfigurowalny w config.yaml).

3.5.1 Health Check

Metoda	Endpoint	Opis
GET	`/health`	Sprawdzenie stanu aplikacji

Odpowiedź: {"status": "OK"}