MniamAI - Kompleksowa Dokumentacja

Spis treści

1. O Aplikacji

MniamAI to nowoczesna platforma do zarządzania zamówieniami żywności i cyklami dostaw, dedykowana dla lokalnych dostawców, klientów, operatorów i administratorów. System umożliwia efektywne zarządzanie produktami, składanie zamówień, obsługę cykli dostaw oraz pełną komunikację między wszystkimi uczestnikami platformy.

Główne cechy

2. Założenia Projektu

2.1. Cele Biznesowe

2.2. Założenia Techniczne

2.3. Reguły Biznesowe

2.4. Poza Zakresem MVP

3. Technologie i Architektura

3.1. Stack Technologiczny

Frontend / Mobile

  • React Native 0.81.5
  • Expo ~54.0.0
  • Expo Router ~6.0.21
  • TypeScript ~5.9.2
  • React 19.1.0
  • React Native Web ^0.21.0

Backend

  • Node.js
  • Express ^4.18.2
  • TypeScript ^5.3.3
  • Prisma ORM ^5.7.0
  • JWT ^9.0.2 (autentykacja)
  • bcryptjs ^2.4.3 (hashowanie haseł)
  • CORS ^2.8.5

Baza Danych

  • PostgreSQL
  • Prisma Client
  • Migracje Prisma Migrate

Deployment

  • Railway (backend)
  • OVH Hosting (frontend web)
  • Docker (PostgreSQL)
  • FTP (deployment web)

3.2. Architektura Aplikacji

MniamAI/
├── apps/
│   ├── backend/          # Node.js + Express + Prisma
│   │   ├── src/
│   │   │   ├── index.ts          # Entry point
│   │   │   ├── routes/           # API routes
│   │   │   ├── middleware/       # Auth middleware
│   │   │   └── utils/            # Utilities
│   │   ├── prisma/
│   │   │   ├── schema.prisma     # Database schema
│   │   │   └── migrations/       # Database migrations
│   │   └── package.json
│   │
│   └── mobile/           # React Native + Expo
│       ├── app/                  # Expo Router pages
│       ├── src/
│       │   ├── api/              # API calls
│       │   ├── components/       # Shared components
│       │   ├── screens/          # Screen components
│       │   └── guards/           # Route guards
│       ├── utils/                # Utilities
│       └── package.json
│
├── docs/                  # Documentation
├── www/                   # Web build output
└── start-dev.sh          # Development script

4. Role Użytkowników

KLIENT

Opis: Użytkownik końcowy, który przegląda produkty, składa zamówienia i śledzi ich status.

Uprawnienia:

  • Przeglądanie produktów i cykli
  • Składanie zamówień (tylko gdy status: approved)
  • Zarządzanie koszykiem
  • Śledzenie historii zamówień
  • Zgłaszanie uwag do stron
  • Komunikacja z administracją

Statusy: pending → approved → blocked

DOSTAWCA

Opis: Lokalny dostawca produktów, który zarządza swoimi produktami i śledzi zamówienia.

Uprawnienia:

  • Dodawanie nowych produktów
  • Edycja swoich produktów
  • Zarządzanie opisem profilu dostawcy
  • Śledzenie zamówień swoich produktów
  • Zarządzanie dostępnością produktów
  • Zgłaszanie uwag
  • Komunikacja z klientami i administracją

Statusy: pending → approved → blocked

OPERATOR

Opis: Osoba zarządzająca platformą, zatwierdzająca użytkowników i produkty, zarządzająca cyklami.

Uprawnienia:

  • Zarządzanie użytkownikami (klienci, dostawcy)
  • Zmiana statusów użytkowników (approve/block)
  • Zatwierdzanie produktów dodanych przez dostawców
  • Zarządzanie cyklami dostaw
  • Zarządzanie kategoriami produktów
  • Obsługa zamówień
  • Przeglądanie zamówień użytkowników
  • Odpowiadanie na uwagi użytkowników
  • Komunikacja z wszystkimi użytkownikami

ADMINISTRATOR

Opis: Najwyższy poziom dostępu z pełną kontrolą nad platformą.

Uprawnienia: Wszystkie uprawnienia operatora plus:

  • Zarządzanie wszystkimi użytkownikami (w tym operatorami)
  • Usuwanie użytkowników
  • Zarządzanie globalnymi ustawieniami systemu uwag
  • Impersonacja użytkowników (do debugowania)
  • Pełny dostęp do wszystkich danych
  • Zarządzanie wszystkimi uwagami

5. Instrukcje dla Użytkowników

5.1. Instrukcje dla Klienta

Rejestracja i Logowanie

  1. Otwórz aplikację MniamAI
  2. Kliknij "Zarejestruj się"
  3. Wprowadź adres e-mail i hasło
  4. Opcjonalnie dodaj numer telefonu
  5. Poczekaj na zatwierdzenie konta przez operatora (status: pending)
  6. Po zatwierdzeniu (status: approved) możesz składać zamówienia

Przeglądanie i Zamawianie Produktów

  1. Przejdź do sekcji "Produkty"
  2. Wybierz aktywny cykl dostaw
  3. Przeglądaj produkty pogrupowane według kategorii
  4. Dodaj produkty do koszyka wybierając ilość
  5. Przejdź do koszyka i sprawdź zamówienie
  6. Kliknij "Złóż zamówienie"
  7. Zamówienie zostanie utworzone i będziesz mógł śledzić jego status

Zarządzanie Zamówieniami

  1. Przejdź do sekcji "Moje zamówienia"
  2. Przeglądaj listę wszystkich zamówień
  3. Kliknij na zamówienie, aby zobaczyć szczegóły
  4. Zobacz status zamówienia i datę dostawy

Zgłaszanie Uwag

  1. Na dowolnej stronie kliknij przycisk "Zgłoś uwagę"
  2. Wypełnij formularz z opisem problemu
  3. Kliknij "Wyślij"
  4. Uwaga zostanie przesłana do administratorów
  5. Możesz śledzić status swojej uwagi i odpowiedzi

5.2. Instrukcje dla Dostawcy

Konfiguracja Profilu

  1. Zaloguj się jako dostawca
  2. Przejdź do ustawień profilu
  3. Dodaj opis swojej działalności (rich text)
  4. Zapisz zmiany

Dodawanie Produktów

  1. Przejdź do sekcji "Moje produkty"
  2. Kliknij "Dodaj produkt"
  3. Wypełnij formularz:
    • Nazwa produktu
    • Opis (opcjonalnie)
    • Kategoria
    • Jednostka (szt, kg, l)
    • Cykl dostaw
    • Dostępna ilość
  4. Kliknij "Dodaj"
  5. Produkt otrzyma status "pending" i wymaga zatwierdzenia przez operatora
  6. Po zatwierdzeniu produkt będzie widoczny dla klientów

Zarządzanie Produktami

  1. Przejdź do sekcji "Moje produkty"
  2. Wybierz produkt do edycji
  3. Zmodyfikuj dane produktu
  4. Zaktualizuj dostępną ilość
  5. Zapisz zmiany

Śledzenie Zamówień

  1. Przejdź do sekcji "Zamówienia moich produktów"
  2. Przeglądaj zamówienia zawierające Twoje produkty
  3. Sprawdź szczegóły każdego zamówienia
  4. Monitoruj dostępność produktów

5.3. Instrukcje dla Operatora

Zarządzanie Użytkownikami

  1. Przejdź do sekcji "Zarządzanie użytkownikami"
  2. Przeglądaj użytkowników pogrupowanych według ról
  3. Filtruj użytkowników według roli (klient, dostawca)
  4. Kliknij na użytkownika, aby zobaczyć szczegóły
  5. Zmień status użytkownika:
    • Approve - zatwierdź użytkownika (pozwala na korzystanie z platformy)
    • Block - zablokuj użytkownika
    • Unblock - odblokuj użytkownika

Zatwierdzanie Produktów

  1. Przejdź do sekcji "Produkty"
  2. Filtruj produkty według statusu "pending"
  3. Przeglądaj produkty oczekujące na zatwierdzenie
  4. Kliknij na produkt, aby zobaczyć szczegóły
  5. Zatwierdź lub odrzuć produkt

Zarządzanie Cyklami Dostaw

  1. Przejdź do sekcji "Cykle dostaw"
  2. Kliknij "Dodaj cykl"
  3. Wypełnij formularz:
    • Nazwa cyklu
    • Opis (opcjonalnie)
    • Data otwarcia (kiedy klienci mogą składać zamówienia)
    • Data zamknięcia (deadline dla zamówień)
    • Data dostawy
    • Data zakończenia cyklu
  4. Zapisz cykl
  5. Zarządzaj istniejącymi cyklami (edycja, deaktywacja)

Zarządzanie Kategoriami

  1. Przejdź do sekcji "Kategorie"
  2. Dodawaj, edytuj i deaktywuj kategorie
  3. Ustaw kolejność wyświetlania kategorii

Obsługa Uwag

  1. Przejdź do sekcji "Uwagi użytkowników"
  2. Przeglądaj otwarte uwagi
  3. Kliknij na uwagę, aby zobaczyć szczegóły
  4. Odpowiedz na uwagę lub zamknij ją z notatką
  5. Zarządzaj statusami uwag (open, answered, rejected, closed)

5.4. Instrukcje dla Administratora

Wszystkie Funkcje Operatora Plus:

  1. Zarządzanie wszystkimi użytkownikami: Możliwość zarządzania również operatorami
  2. Usuwanie użytkowników: Możliwość trwałego usunięcia kont użytkowników
  3. Globalne ustawienia uwag: Włączanie/wyłączanie systemu uwag globalnie lub per-strona
  4. Impersonacja: Możliwość logowania się jako inny użytkownik (do debugowania)
  5. Pełny dostęp: Dostęp do wszystkich funkcji i danych w systemie

Zarządzanie Ustawieniami Systemu

  1. Przejdź do sekcji "Ustawienia systemu"
  2. Włącz/wyłącz globalnie system uwag
  3. Konfiguruj system uwag dla poszczególnych stron
  4. Zarządzaj dostępnością funkcji na różnych stronach

6. Funkcjonalności

6.1. System Uwago i Feedback

Użytkownicy mogą zgłaszać uwagi dotyczące funkcjonalności stron. System umożliwia:

6.2. System Komunikacji

Platforma oferuje pełny system wiadomości między użytkownikami:

6.3. Koszyk Zakupów

6.4. Cykle Dostaw

6.5. Zarządzanie Produktami

7. Architektura Systemu

7.1. Baza Danych

System używa PostgreSQL z Prisma ORM. Główne tabele:

Tabela Opis
User Użytkownicy systemu (klienci, dostawcy, operatorzy, administratorzy)
Cycle Cykle dostaw z datami otwarcia, zamknięcia i dostawy
Category Kategorie produktów
Product Produkty z dostępnością, kategorią i dostawcą
Order Zamówienia powiązane z użytkownikiem i cyklem
OrderItem Pozycje zamówienia (produkt + ilość)
Concern Uwagi zgłaszane przez użytkowników
ConcernMessage Wiadomości w ramach uwag
Conversation Konwersacje między użytkownikami
Message Wiadomości w konwersacjach

7.2. Middleware i Autentykacja

7.3. Frontend Architektura

8. Bezpieczeństwo

8.1. Autentykacja i Autoryzacja

8.2. Ochrona Danych

8.3. Walidacja Biznesowa

9. API

9.1. Endpointy Autentykacji

POST /auth/register
Body: { email, password, phone? }
Response: { token, user }

POST /auth/login
Body: { email, password }
Response: { token, user }

GET /auth/me
Headers: Authorization: Bearer {token}
Response: { user }

9.2. Endpointy Produktów

GET /products
Response: Products grouped by cycles

GET /products/:id
Response: Product details

POST /products (supplier only)
Body: { name, description, unit, cycleId, categoryId, availableQty }
Response: { product }

PUT /products/:id (supplier only)
Body: { name, description, availableQty, ... }
Response: { product }

9.3. Endpointy Zamówień

POST /orders
Body: { items: [{ productId, qty }] }
Response: { order }

GET /orders
Response: User orders

GET /orders/:id
Response: Order details

9.4. Endpointy Cykli

GET /cycles
Response: List of cycles

POST /cycles (operator/admin only)
Body: { name, description, openDate, lockDate, deliveryDate, endDate }
Response: { cycle }

PUT /cycles/:id (operator/admin only)
Body: { ... }
Response: { cycle }

9.5. Endpointy Użytkowników

GET /users (operator/admin only)
Response: List of users grouped by roles

GET /users/:id (operator/admin only)
Response: User details

PUT /users/:id/status (operator/admin only)
Body: { status: 'approved' | 'blocked' }
Response: { user }

DELETE /users/:id (admin only)
Response: { success }

9.6. Endpointy Uwag

GET /concerns/config?pageKey={pageKey}
Response: { enabled, pageConfig }

GET /concerns/mine
Response: User concerns

POST /concerns
Body: { pageKey, pagePath, title, body }
Response: { concern }

GET /concerns/:id
Response: Concern details

POST /concerns/:id/messages
Body: { body }
Response: { message }

10. Wdrażanie

10.1. Backend (Railway)

  1. Połącz repozytorium z Railway
  2. Ustaw zmienne środowiskowe:
    • DATABASE_URL - URL do bazy PostgreSQL
    • JWT_SECRET - sekretny klucz dla JWT
    • PORT - port serwera (domyślnie 3000)
  3. Railway automatycznie uruchomi migracje Prisma
  4. Backend będzie dostępny pod adresem Railway

10.2. Frontend Web (OVH Hosting)

  1. Zbuduj aplikację web:
    cd apps/mobile
    npx expo export --platform web --output-dir ../../www
  2. Zaktualizuj www/index.html z URL backendu
  3. Prześlij pliki na FTP używając skryptu deploy_ftp_curl.sh
  4. Struktura na serwerze:
    • /www/ - root folder (fizyczny folder na FTP)
    • /index.html - strona główna
    • /app/ - aplikacja
    • /documentation.html - dokumentacja

10.3. Mobile (iOS/Android)

  1. iOS (TestFlight):
    • Zbuduj aplikację: eas build --platform ios
    • Prześlij do TestFlight przez Expo
  2. Android (Google Play):
    • Zbuduj aplikację: eas build --platform android
    • Prześlij APK/AAB do Google Play Console