86 lines
5.3 KiB
Markdown
86 lines
5.3 KiB
Markdown
# FinlyticApp — Architecture Guidelines & Engineering Standards
|
||
|
||
Dieses Dokument definiert die verbindlichen Architektur- und Entwicklungsstandards für die **FinlyticApp** (Dart / Flutter Cross-Platform Client für Android, iOS und Web).
|
||
|
||
---
|
||
|
||
## 1. Grundprinzipien & Dateistruktur
|
||
|
||
Das Projekt folgt einer strengen **Feature-Driven Clean Architecture**. Dadurch wird eine vollständige Entkopplung von Benutzeroberfläche, Geschäftslogik und Datenquellen gewährleistet.
|
||
|
||
### 📏 Dateigröße & Struktur-Limits
|
||
* **Maximal 150 bis 200 Zeilen pro Datei:** Wenn eine Datei diese Grenze überschreitet, muss sie in kleinere, fokussierte Einheiten refactored werden (*Single Responsibility Principle*).
|
||
* **Eine Hauptklasse pro Datei:** Helper-Klassen gehören in eigene Dateien, es sei denn, sie sind `private` und ausschließlich lokal relevant.
|
||
* **Kompakte `build()`-Methoden:** Die `build()`-Methode dient nur der Anordnung von Sub-Widgets und darf selten länger als 30–40 Zeilen sein.
|
||
|
||
### 📁 Verzeichnisstruktur (`lib/`)
|
||
|
||
```text
|
||
lib/
|
||
├── core/
|
||
│ ├── network/ # ApiClient, MQTT-Service, WebSockets
|
||
│ ├── theme/ # Finlytic Dark Glassmorphism, Typography, Colors
|
||
│ ├── utils/ # Formatierer (Währungen, Prozentangaben, Datum)
|
||
│ └── widgets/ # App-weit genutzte UI-Komponenten (Buttons, Modals)
|
||
├── features/
|
||
│ ├── dashboard/ # Dashboard-Overview, Analytics-Cards
|
||
│ ├── news/ # Feed, Pagination, Sentiment-Analysen
|
||
│ ├── favorites/ # Favoriten-Grid, Watchlist
|
||
│ ├── calendar/ # Corporate Calendar, Earnings, Dividenden
|
||
│ ├── trades/ # Trade-Signale, Automatische Trades
|
||
│ ├── admin/ # User-Verwaltung, System-Settings (Admin-Only)
|
||
│ └── asset_detail/ # Fundamentaldaten, TA-Chart, Finance-Metrics
|
||
└── main.dart # Entry Point & Service Locator Initialization
|
||
|
||
2. Clean Architecture Layering
|
||
Jedes Feature im features/-Ordner wird intern strikt in drei Layer unterteilt:LayerVerantwortlichkeitErlaubte Abhängigkeiten1. PresentationUI-Komponenten, Screen-Layouts, Consumer von States.Greift nur auf Logic (BLoC/Notifier) zu. Keine direkten API/DB-Calls!2. Domain / LogicBusiness-Logik, State Management, UseCases, Entities.Absolut frei von flutter/material.dart! Nutzt Repositories als Abstraktion.3. DataAPI-Clients, DTOs, Local Caching, MQTT-Stream Handlers.Implementiert Repository-Interfaces aus dem Domain Layer.
|
||
|
||
3. Widget-Architektur & Sub-Widget Auslagerung
|
||
❌ VERBOTEN: Helper-Methoden für Widgets (_buildX())Unter keinen Umständen dürfen Methoden innerhalb von Widget-Klassen definiert werden, die ein Widget zurückgeben:Dart// ❌ FALSCH: Baut keinen eigenen BuildContext/Lifecycle auf und erfordert Rebuilding des gesamten Mutter-Widgets!
|
||
Widget _buildHeader() {
|
||
return Container(
|
||
padding: const EdgeInsets.all(16),
|
||
child: const Text('Dashboard'),
|
||
);
|
||
}
|
||
✅ PFLICHT: Auslagerung in eigene StatelessWidget KlassenJedes logische Teilsegment der Benutzeroberfläche muss als eigene Klasse ausgegliedert werden:Dart// ✅ KORREKT: Saubere Performance, eigener BuildContext, optimierter Element-Tree
|
||
class DashboardHeader extends StatelessWidget {
|
||
const DashboardHeader({super.key});
|
||
|
||
@override
|
||
Widget build(BuildContext context) {
|
||
return Container(
|
||
padding: const EdgeInsets.all(16),
|
||
child: const Text('Dashboard'),
|
||
);
|
||
}
|
||
}
|
||
⚡ Performance-Regeln für Widgets:const Konstruktoren: Jedes Sub-Widget muss wenn möglich einen const Konstruktor haben, um unnötige Re-Renders im Widget-Tree zu verhindern.Keine Business-Logik im UI-Widget: Widgets reagieren ausschließlich auf übergebene Daten oder States und leiten Nutzerinteraktionen über Callbacks / BLoC-Events weiter.
|
||
|
||
4. Data Classes & Code-Generierung
|
||
Immutability: Alle Models, DTOs und States müssen unbeeinflussbar (immutable) sein.Freezed & JSON Serializable: Das manuelle Schreiben von fromJson, toJson oder copyWith ist untersagt. Es wird freezed zusammen mit build_runner eingesetzt.Dartimport 'package:freezed_annotation/freezed_annotation.dart';
|
||
|
||
part 'asset_model.freezed.dart';
|
||
part 'asset_model.g.dart';
|
||
|
||
@freezed
|
||
class Asset with _$Asset {
|
||
const factory Asset({
|
||
required String isin,
|
||
required String name,
|
||
required double currentPrice,
|
||
required String currency,
|
||
}) = _Asset;
|
||
|
||
factory Asset.fromJson(Map<String, dynamic> json) => _$AssetFromJson(json);
|
||
}
|
||
5. Responsive & Adaptive Navigation LayoutFinlyticApp wird plattformübergreifend betrieben und muss sich dem Screen-Format anpassen:Mobile Breakpoint (< 800px): Anforderung von Material NavigationBar (Android) / Cupertino Tab Bar (iOS) am unteren Bildschirmrand.Web / Desktop Breakpoint (>= 800px): Automatische Skalierung auf ein linkes Tab-Menü (NavigationRail / Sidebar).Keine starren Dimensionen: Nutzung von LayoutBuilder, Flexible und Expanded, um Überläufe (Pixel Overflow) auf schmalen Displays zu verhindern.6. Linter Standard (analysis_options.yaml)Alle Entwickler müssen die folgenden Linter-Regeln in der analysis_options.yaml einhalten:YAMLlinter:
|
||
rules:
|
||
- prefer_const_constructors
|
||
- prefer_const_declarations
|
||
- prefer_final_fields
|
||
- prefer_final_locals
|
||
- avoid_unnecessary_containers
|
||
- sizedbox_for_whitespace
|
||
- use_build_context_synchronously
|
||
- always_declare_return_types |