185 lines
6.7 KiB
Markdown
185 lines
6.7 KiB
Markdown
# AGENTS.md - AI Assistant Context
|
|
|
|
Dieses Dokument hilft AI-Assistenten (Amp, Copilot, etc.) das Projekt zu verstehen.
|
|
|
|
## Projekt-Überblick
|
|
|
|
**dgray.io** ist eine Kleinanzeigen-PWA mit Monero-Bezahlung.
|
|
|
|
- **Status**: Active Development (Frontend + Directus Backend)
|
|
- **Ziel**: Anonyme, dezentrale Marktplatz-Alternative
|
|
|
|
## Tech-Stack
|
|
|
|
| Layer | Technologie |
|
|
|-------|-------------|
|
|
| Frontend | Vanilla JS, Web Components, CSS Custom Properties |
|
|
| Routing | Hash-basierter Client-Side Router (`js/router.js`) |
|
|
| i18n | Custom System (`js/i18n.js`), JSON-Dateien in `/locales/` |
|
|
| Theming | CSS Variables, Dark/Light Mode |
|
|
| Backend | Directus (`api.dgray.io`) |
|
|
| Auth | UUID-basiert, anonym (`js/services/auth.js`) |
|
|
| E2E Crypto | TweetNaCl (self-hosted in `js/vendor/`), `box.before` + `secretbox` |
|
|
| PoW Captcha | PHP-Server (`pow.dgray.io`), Fallback auf lokal |
|
|
|
|
## Häufige Befehle
|
|
|
|
```bash
|
|
# Lokaler Entwicklungsserver
|
|
python3 -m http.server 8080
|
|
|
|
# Oder mit Live-Reload
|
|
npx live-server
|
|
|
|
# Tests ausführen (im Browser)
|
|
# Server starten, dann http://localhost:8080/tests/ öffnen
|
|
|
|
# Git Push (Token in URL)
|
|
git push origin master
|
|
```
|
|
|
|
## Commit-Konvention
|
|
|
|
Wenn der User nach **"commit text (en)"** oder **"commit text (de)"** fragt:
|
|
- Erstelle eine einzeilige Commit-Message im Format: `git commit -m "..."`
|
|
- Nutze [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
|
|
- Sprache entsprechend der Anfrage (en/de)
|
|
|
|
## Dateistruktur
|
|
|
|
```
|
|
js/
|
|
├── app.js # Entry, lädt i18n, dann Shell
|
|
├── router.js # Hash-Router mit :params
|
|
├── i18n.js # t('key'), subscribe(), updateDOM()
|
|
├── services/
|
|
│ ├── directus.js # Directus API Client (Core)
|
|
│ ├── auth.js # UUID-basierte Authentifizierung (SHA-256 Hash)
|
|
│ ├── listings.js # Listings Service (Filter)
|
|
│ ├── categories.js # Kategorien Service (Baum, Übersetzungen, Cache)
|
|
│ ├── locations.js # Standorte Service (Geo-Suche)
|
|
│ ├── conversations.js # Zero-Knowledge Chat (E2E verschlüsselt)
|
|
│ ├── crypto.js # NaCl Encryption
|
|
│ ├── currency.js # XMR/Fiat Umrechnung
|
|
│ ├── pow-captcha.js # Proof-of-Work Captcha (Challenge/Verify)
|
|
│ └── btcpay.js # BTCPay Server Integration (Invoice, Checkout, Polling)
|
|
└── components/
|
|
├── app-shell.js # Layout, registriert Routes
|
|
├── app-header.js # Header (Theme-Toggle, Lang-Dropdown, Profil-Dropdown)
|
|
├── app-footer.js # Footer
|
|
├── auth-modal.js # Login/Register Modal (mit PoW-Captcha)
|
|
├── pow-captcha.js # PoW-Captcha Web Component
|
|
├── chat-widget.js # E2E Chat Widget
|
|
└── pages/ # Seiten als Web Components
|
|
|
|
docs/
|
|
├── DIRECTUS-SETUP.md # Directus Backend Setup
|
|
├── DIRECTUS-SCHEMA.md # Collection-Strukturen & Permissions
|
|
├── MONETIZATION.md # Monetarisierung & Anti-Abuse
|
|
└── pow-server/ # PHP PoW-Captcha Server (pow.dgray.io)
|
|
|
|
css/
|
|
├── fonts.css # @font-face Definitionen (Inter, Space Grotesk)
|
|
├── variables.css # CSS Custom Properties (Farben, Spacing)
|
|
├── base.css # Reset, Container
|
|
└── components.css # UI-Komponenten (Buttons, Cards, etc.)
|
|
|
|
assets/
|
|
└── fonts/ # Self-hosted Fonts (Inter, Space Grotesk)
|
|
|
|
tests/
|
|
├── index.html # Test-Runner UI (im Browser öffnen)
|
|
├── test-runner.js # Minimaler Test-Framework
|
|
├── helpers.test.js # Unit Tests für helpers.js
|
|
├── i18n.test.js # Unit Tests für i18n.js
|
|
└── router.test.js # Unit Tests für router.js
|
|
|
|
locales/
|
|
├── de.json # Deutsch (Fallback)
|
|
├── en.json
|
|
└── fr.json
|
|
```
|
|
|
|
## Konventionen
|
|
|
|
### JavaScript
|
|
- **Keine Semikolons** am Zeilenende (außer in for-loops, CSS)
|
|
- **Englische Kommentare** im Code
|
|
- ES Modules mit `import/export`
|
|
|
|
### Web Components
|
|
- Custom Elements mit `class extends HTMLElement`
|
|
- Styles als `<style>` im `document.head` oder inline
|
|
- i18n: `render()` Methode, Subscribe auf Sprachwechsel
|
|
- Auth-Subscriber nur in `connectedCallback()`, nicht in `setupEventListeners()`
|
|
|
|
### CSS
|
|
- **Keine festen Farben** - immer `var(--color-*)` nutzen
|
|
- **Spacing**: `var(--space-xs|sm|md|lg|xl|2xl|3xl)`
|
|
- **Font-Size**: `var(--font-size-xs|sm|base|lg|xl|2xl|3xl)`
|
|
- **Font-Family**: `var(--font-family)` für Body, `var(--font-family-heading)` für Headlines
|
|
- **Border-Radius**: `var(--radius-sm|md|lg|xl|full)`
|
|
- **Breakpoint**: `@media (max-width: 768px)` - einziger Mobile-Breakpoint für alle Komponenten
|
|
|
|
### i18n
|
|
- Schlüssel: `section.key` (z.B. `home.title`)
|
|
- Im HTML: `data-i18n="key"` oder `${t('key')}`
|
|
- Placeholder: `data-i18n-placeholder="key"`
|
|
- Neue Texte in **allen 3 Sprachen** hinzufügen
|
|
|
|
## Aktuelle Probleme / Hinweise
|
|
|
|
1. **SSH funktioniert nicht** mit diesem Repo auf gitea.pro - HTTPS mit Token nutzen
|
|
2. **Service Worker** kann lokale Änderungen cachen - bei Problemen Cache leeren
|
|
3. **i18n muss vor Shell laden** - siehe `app.js` (dynamischer Import)
|
|
|
|
## Nächste Schritte
|
|
|
|
1. ~~Seiten für Profil-Dropdown~~ ✅ Fertig
|
|
2. ~~Suchseite mit Filtern~~ ✅ Merged in `page-home.js`
|
|
3. ~~Listings bearbeiten~~ ✅ Edit-Modus via `#/edit/:id`
|
|
4. ~~PoW-Captcha server-seitig~~ ✅ PHP-Server auf `pow.dgray.io`
|
|
5. ~~TweetNaCl self-hosted~~ ✅ In `js/vendor/`
|
|
6. ~~Chat-Crypto fix~~ ✅ `box.before` + `secretbox`
|
|
7. ~~Payment-Integration mit BTCpay Server~~ ✅ Proxy auf `pow.dgray.io`, Frontend-Service `btcpay.js`
|
|
8. Reputation-System (5/15/50 Deals Stufen)
|
|
9. Push-Benachrichtigungen für neue Nachrichten
|
|
|
|
## Directus Berechtigungen (Public-Rolle)
|
|
|
|
| Collection | Read | Create | Update | Hinweise |
|
|
|------------|------|--------|--------|----------|
|
|
| `listings` | ✓ | ✓ | - | Nur `status=published` lesen |
|
|
| `listings_files` | ✓ | ✓ | - | Junction-Table für Bilder |
|
|
| `directus_files` | ✓ | ✓ | - | Für Assets/Bilder |
|
|
| `categories` | ✓ | - | - | Nur `status=published` |
|
|
| `categories_translations` | ✓ | - | - | Für i18n |
|
|
| `locations` | ✓ | ✓ | - | User kann neue Orte anlegen |
|
|
| `languages` | ✓ | - | - | Für Sprachen-Liste |
|
|
| `conversations` | ✓ | ✓ | ✓ | Filter via `participant_hash`, Update nur `status` |
|
|
| `messages` | ✓ | ✓ | - | Filter via `conversation` ID |
|
|
|
|
Siehe `docs/DIRECTUS-SCHEMA.md` für vollständiges Schema.
|
|
|
|
## Farbpalette
|
|
|
|
```
|
|
Monochrome Theme - reine Graustufen
|
|
|
|
Light Mode:
|
|
- BG: #FAFAFA
|
|
- Text: #1A1A1A
|
|
- Primary: #555555
|
|
- Border: #D0D0D0
|
|
|
|
Dark Mode:
|
|
- BG: #141414
|
|
- Text: #F0F0F0
|
|
- Primary: #AAAAAA
|
|
- Border: #3A3A3A
|
|
```
|
|
|
|
## Ansprechpartner
|
|
|
|
- Repo: https://gitea.pro/schmidt1024/dgray
|