# Secure File Transfer (FTC) – Komplette Projektdokumentation

Produkt: **Secure File Transfer** (CUMAS365 / secure-file-transfer.io)  
Codebasis: Symfony-App unter `ftc/`

---

## 1. Überblick

Web-Anwendung zum sicheren Dateiaustausch mit:

- Datei-Upload / -Download (inkl. Chunk-Upload, Ordner, Gäste)
- Kontakte & Einladungen
- Lizenzen: **Free**, **Pro**, **Business**
- **SFT Sign** – PDF-Signatur-Workflow
- **SFT Collect** – Dateien einsammeln (Alben / Share-Links)
- Hilfe-Center
- Admin-Bereich (`/adm`) mit Statistik, Users, Explorer, Analytics
- Mehrsprachigkeit: DE / EN / ES / RU
- Google-Login, 2FA (E-Mail), Cookie-Consent, Branding (Hintergründe/Logo)

---

## 2. Tech-Stack

| Bereich | Technologie |
|--------|-------------|
| Backend | PHP ≥ 8.2, Symfony **6.4** |
| ORM | Doctrine ORM 2.x |
| Frontend | Twig, TypeScript, SCSS, Webpack Encore |
| UI | Bootstrap 5, Chart.js, Dropzone, DataTables, jQuery |
| Auth | Symfony Security, scheb/2fa, Google OAuth |
| Mail | Symfony Mailer |
| PDF/Sign | TCPDF, FPDI |
| Storage | Dateisystem unter `%upload_directory%` (außerhalb von `public/`) |

Wichtige Pfade:

- App-Root: `ftc/`
- Storage: `ftc/../../ftc_storage/` (Parameter `upload_directory`)
- Public: `ftc/public/`
- Assets Build: `ftc/public/build/`

---

## 3. Verzeichnisstruktur

```
ftc/
├── assets/                 # TS/SCSS (Webpack Encore Entries)
│   ├── adm/                # Admin-Frontend (Dashboard, Analytics, …)
│   ├── styles/             # SCSS (App, Marketing, Upload, Collect, …)
│   ├── dropzone.ts         # Upload Pro/Business
│   ├── dropzone.free.ts    # Upload Free
│   ├── analytics.ts        # Surfverhalten-Tracking (Client)
│   └── …
├── bin/console
├── config/                 # packages/, routes, services.yaml, security.yaml
├── docs/                   # Diese und Modul-Dokus
├── migrations/             # Vorhandene Historie – siehe Abschnitt Schema!
├── public/                 # Webroot (images, build, index.php)
├── src/
│   ├── Command/
│   ├── Controller/         # App + Guest + Public
│   ├── Controller/Adm/     # Admin
│   ├── Entity/
│   ├── Form/
│   ├── Repository/
│   ├── Security/
│   ├── Service/
│   ├── Twig/
│   └── EventListener/ / EventSubscriber/
├── templates/
├── translations/           # messages.{de,en,es,ru}.php
├── tests/
├── webpack.config.js
├── composer.json
└── package.json
```

Weitere Modul-Dokus:

- `docs/SFT_SIGN.md`
- `docs/SFT_COLLECT.md`
- `docs/help-center.md`
- `docs/google-login.md`

---

## 4. Lizenzen & Rollen

### Lizenzen (UserSettings / Produkt)

- **free** – eingeschränkt (Quota, Features)
- **pro**
- **business** – Teams / erweiterte Features

Upload-Assets:

- Free → `upload_free` + `dropzone_free`
- Pro **und** Business → `upload` + `dropzone`

### Security-Rollen

| Rolle | Nutzen |
|-------|--------|
| `ROLE_GUEST` | Gast-Upload `/guest` |
| `ROLE_STANDARD_USER` | App `/app` |
| `ROLE_ADMIN` | App-Admin im Mandanten |
| `ROLE_STATISTICS_ADMIN` | `/adm` Statistiken |
| `ROLE_GLOBAL_ADMIN` | volles Admin + Impersonation |

Hierarchie (Auszug): `ROLE_GLOBAL_ADMIN` → `ROLE_STATISTICS_ADMIN`

Access Control (vereinfacht):

- `/app` → eingeloggte App-User
- `/guest` → Gäste
- `/adm` → Statistics/Global Admin
- `/sign/`, `/collect/` → teilweise PUBLIC
- `/analytics/collect` → PUBLIC (Tracking-Beacon)

---

## 5. Kernmodule

### 5.1 Upload / Download / Sharing

- Controller: `UploadController`, `DownloadController`, `GuestController`
- Services: `UploadService`, `DownloadService`, `MessageService`
- Entities: `SharedFile`, `SharedFileGuest`, `UploadedFiles`, `Log`
- Features: Dropzone, Chunks, Ordner, Passwort/SMS/E-Mail-Benachrichtigung, Ablaufdaten
- UI: `templates/upload/`, `templates/download/`, `templates/guest/`

### 5.2 Kontakte & Import

- `ContactController`, `ImportController`
- Entities: `Contact`, `ContactGuest`, `Import`
- Service: `ContactImportService`

### 5.3 User, Settings, Branding

- `UserController`, `UserSettingsController`, `AccountController`
- Entities: `User`, `UserSettings`
- Branding: Hintergrundbilder Login/Upload/Download, E-Mail-Logo → `public/images`
- Schreibrechte `public/images`: Service `SudoDirectoryPermissionFixer` (Fallback `SUDO_PASSWORD`)

### 5.4 Lizenzen & Zahlung

- `LicenseController`, `PaymentInformationController`, `PriceController`, `ProVersionController`
- Entities: `License`, `PaymentInformation`, `TrialVersion`, `PromoCode`
- Admin: License-, Trial-, Promo-Verwaltung

### 5.5 SFT Sign

- Owner: `SignController` unter `/app/.../sign`
- Gast: `SignGuestController` unter `/sign/...`
- Service: `SignService`
- Entities: `SignDocument`, `SignSigner`, `SignField`, `SignEvent`
- Details: `docs/SFT_SIGN.md`

### 5.6 SFT Collect

- Owner: `CollectController`
- Gast: `CollectGuestController`
- Service: `CollectService`, `CollectPreviewService`
- Entities: `CollectCollection`, `CollectFile`, `CollectShareLink`, `CollectMember`, `CollectEvent`, Ratings/Comments
- Details: `docs/SFT_COLLECT.md`

### 5.7 Hilfe-Center

- `HelpController`, `HelpAssistantController`, Seed/Import-Commands
- Entities: `HelpArticle`, `HelpCategory`, `HelpArticleFeedback`, `HelpSearchLog`
- Details: `docs/help-center.md`

### 5.8 Analytics (Surfverhalten / Absprünge)

Ziel: Bounce-Rate, Exit-Seiten, Verweildauer, Geräte, Referrer verstehen.

**Tracking (Client)**

- Entry: `analytics` → `assets/analytics.ts`
- Nur bei Cookie-Consent `cookie_analytics=true`
- Events: `pageview`, `page_update`, `conversion` (z. B. erfolgreicher Upload), `session_end`
- **Kein Tracking auf `/adm`**
- Upload-Conversion in `dropzone.ts` **und** `dropzone.free.ts` (Free / Pro / Business)

**Backend**

- `POST /analytics/collect` → `AnalyticsCollectController` + `AnalyticsTracker`
- Entities: `AnalyticsSession`, `AnalyticsPageView`
- Bounce: 1 Seite **ohne** Conversion; Upload setzt Bounce auf `false`

**Admin-UI**

- Route: `/adm/{_locale}/analytics` → `Adm\AnalyticsController`
- Entry: `adm_analytics` (Chart.js)
- Charts/Tabellen: Sessions & Bounce-Rate, Geräte, Exit-Gründe, Landingpage-Bounces (min. 5 Sessions), Verweildauer-Buckets, längste/schwächste Seitenbindung, Referrer
- Auswertungen filtern Pfade `LIKE '/adm%'` heraus

### 5.9 Admin-Bereich

Route-Prefix: `/adm/{_locale}`

| Bereich | Controller |
|---------|------------|
| Dashboard | `AdmController` |
| Analytics | `AnalyticsController` |
| Users | `AdmUserController` |
| Explorer / Files | `ExplorerController` |
| Used Resources | `UsedRessourcesController` |
| License / Promo / Trial | jeweilige Adm-Controller |
| Logins | `LogLoginController` |
| Fail2ban | `Fail2banController` |
| Help Articles/Categories | Help-* Adm-Controller |

---

## 6. Entities (vollständige Liste)

`AnalyticsPageView`, `AnalyticsSession`, `BlockedEmailDomains`, `CollectCollection`, `CollectEvent`, `CollectFile`, `CollectFileComment`, `CollectFileRating`, `CollectMember`, `CollectShareLink`, `Contact`, `ContactGuest`, `FailedLogin`, `HelpArticle`, `HelpArticleFeedback`, `HelpCategory`, `HelpSearchLog`, `Import`, `Invitation`, `License`, `Log`, `LogLogin`, `PaymentInformation`, `PromoCode`, `ResetPasswordRequest`, `SharedFile`, `SharedFileGuest`, `SignDocument`, `SignEvent`, `SignField`, `SignSigner`, `TrialVersion`, `TrustedDomain`, `TrustedIp`, `UploadedFiles`, `User`, `UserSettings`

---

## 7. Wichtige Services

| Service | Aufgabe |
|---------|---------|
| `UploadService` | Upload/Chunks/Assemble |
| `DownloadService` | Download-Flows |
| `MessageService` | E-Mails / SMS-Anbindung |
| `LicenseService` | Lizenzlogik |
| `SignService` | Signatur-Workflow |
| `CollectService` | Collect-Workflow |
| `InvitationService` | Team-Einladungen |
| `AnalyticsTracker` | Session-/Page-/Conversion-Ingest |
| `SudoDirectoryPermissionFixer` | `public/images` beschreibbar machen |
| `SudoStorageRemover` / `SudoFileReader` | Storage/Logs mit sudo-Fallback |
| `StorageRecalculateService` | Speicherverbrauch |
| `AdditionalService` | Hilfen (u. a. Background löschen) |

---

## 8. Console-Commands

| Command | Zweck |
|---------|--------|
| `app:collect:expire` | Collect ablaufen lassen |
| `app:collect:generate-previews` | Vorschauen |
| `app:recalculate-storage` | Storage neu berechnen |
| `app:help:seed` / import / validate | Hilfe-Inhalte |
| `app:cache-reset` | Cache (ggf. sudo) |
| weitere Delete/Verify-Commands | Wartung |

---

## 9. Frontend / Webpack Encore

Build:

```bash
cd ftc
npm install
npm run build          # production
npm run watch          # optional
```

Wichtige Entries (Auszug aus `webpack.config.js`):

- App/Marketing: `app`, `home`, `marketing`, `login`, `register`, …
- Upload: `upload`, `upload_free`, `dropzone`, `dropzone_free`
- Sign/Collect: `sign`, `sign_guest`, `collect`, `collect_guest`
- Admin: `adm_dashboard`, `adm_analytics`, `adm_users`, …
- Tracking: `analytics`

Templates binden Assets mit `encore_entry_script_tags` / `encore_entry_link_tags`.

---

## 10. Datenbank-Schema – WICHTIG

### Keine Doctrine-Migrationen für Deploy/Schema-Updates

In diesem Projekt wird das Schema **nicht** über `doctrine:migrations:migrate` ausgerollt.

Stattdessen nach Entity-Änderungen:

```bash
cd ftc
php bin/console doctrine:schema:update --force
```

Optional vorher prüfen:

```bash
php bin/console doctrine:schema:update --dump-sql
```

**Nicht verwenden (für dieses Projekt):**

```bash
# NEIN
php bin/console doctrine:migrations:migrate
php bin/console make:migration
```

Der Ordner `migrations/` kann historische Dateien enthalten; für laufende Schema-Anpassungen (z. B. Analytics-Tabellen) gilt ausschließlich `schema:update --force`.

Nach Schema-Update Cache leeren:

```bash
php bin/console cache:clear
```

---

## 11. Typischer Deploy-Ablauf

```bash
cd ftc

# Dependencies
composer install --no-dev --optimize-autoloader
npm ci
npm run build

# Schema aus Entities (KEINE Migration)
php bin/console doctrine:schema:update --force

# Cache
php bin/console cache:clear --env=prod

# Rechte public/images (falls nötig)
# www-data braucht Schreibrechte; App kann per SUDO_PASSWORD nachhelfen
```

Umgebung (`.env` / `.env.local`):

- `APP_ENV`, `APP_SECRET`
- `DATABASE_URL`
- `MAILER_DSN`
- `SUDO_PASSWORD` (optional, für Rechte/Storage/Logs)
- Google OAuth: `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`
- Help-/URL-Parameter siehe `config/services.yaml`

---

## 12. Produktionshinweise

- Live-DocumentRoot (Beispiel): `filetransfercloud_wip/ftc/public` auf secure-file-transfer.io
- Storage außerhalb Webroot (`ftc_storage`)
- `public/images` muss für PHP/`www-data` beschreibbar sein (Branding-Uploads)
- Analytics respektiert Cookie-Consent; Admin-Bereich wird nicht getrackt
- ModSecurity-Warnungen „Missing target“ sind oft unkritisch und blockieren Requests nicht zwingend

---

## 13. Tests / Qualität

- PHPUnit unter `tests/`
- Coding: `declare(strict_types=1);`, Constructor Injection, Symfony Attributes (`#[Route]`, `#[IsGranted]`)
- Frontend: TypeScript, Encore-Production-Build vor Deploy

---

## 14. Kurz-Checkliste Analytics (aktueller Stand)

1. Entities `AnalyticsSession` / `AnalyticsPageView` vorhanden  
2. Schema: `php bin/console doctrine:schema:update --force`  
3. Assets gebaut (`analytics`, `adm_analytics`, Dropzone-Entries)  
4. Admin-Menü → **Analytics**  
5. Consent + Surf → Daten; Upload → kein Bounce  

---

*Stand: Projektdokumentation der FTC/SFT-Codebasis. Moduldetails siehe die speziellen Docs unter `ftc/docs/`.*