Erste Schritte

Direkte Antwort

Führen Sie die Astro-Site und die Phoenix-Kontrollebene local aus und durchlaufen Sie dann schrittweise den aktuellen Alpha-Workflow.

Seiteninhalt

# Erste Schritte

TextTree ist in zwei Anwendungen unterteilt:

- `apps/site` für die öffentliche Astro-Site
– `apps/web` für die Phoenix-App, Entwickler-API, Webhooks und MCP-Endpunkte

## Lokaler Workflow

1. Installieren Sie Node 22+, Elixir 1.19+, Erlang/OTP 28+ und PostgreSQL.
2. Kopieren Sie `apps/web/.env.example` nach `apps/web/.env.local`.
3. Kopieren Sie `apps/site/.env.example` nach `apps/site/.env.local`.
4. Generieren Sie ein Proton SMTP-Übermittlungstoken, bevor Sie tatsächliche lokale E-Mails senden.
5. Führen Sie `pnpm setup` im Stammverzeichnis des Repositorys aus.
6. Starten Sie Astro mit `pnpm --dir apps/site dev`.
7. Starten Sie Phoenix mit `cd apps/web && mix phx.server`.

## Lokale URLs

- Öffentliche Astro-Website: `http://localhost:4321`
- Phoenix-Anwendung und API: `http://localhost:4001`

## Umgebungsgruppen

Umgebungsvariablen sind nach Verantwortlichkeiten organisiert:

- Lokale Ausführungsumgebung von Phoenix: `apps/web/.env.local`
- Lokale öffentliche Astro-Konfiguration: `apps/site/.env.local`
- Produktionsmanagement/Bereitstellungsvorgänge: `devops/env/prod.env.local`
- Testbereitstellungs-/Verwaltungsvorgänge: `devops/env/test.env.local`

Verwenden Sie keine Env-Dateien im Stammverzeichnis. Pro Bereich werden nur Beispieldateien versioniert.

## Authentifizierungsmodus

Legen Sie `TEXTREE_AUTH_MODE` in der Phoenix-Laufzeit fest, um auszuwählen, welche
Registrierungs- und Anmeldemethoden sind sichtbar.

| Wert | Registrierungs-/Login-Schnittstelle | Hinter den Kulissen aktiviert | Ist eine Postzustellung erforderlich? | Typische Verwendung |
| --- | --- | --- | --- | --- |
| `magic_link_or_ethereum` | Nur magischer Link per E-Mail und Ethereum-Wallet. Solana, Google und E-Mail/Passwort sind ausgeblendet. | Magischer Link per E-Mail, E-Mail/Passwort und Ethereum-Wallet. | Ja, SMTP konfigurieren. | Aktueller Standard-Startmodus. |
| `wallet_only` | Nur Ethereum- und Solana-Wallet-Buttons. Magischer Link per E-Mail, Google und E-Mail/Passwort werden ausgeblendet. | Ethereum- und Solana-Wallet. | Nein. | Nur-Krypto-Veröffentlichung oder nicht verifizierte E-Mail-Zustellung. |
| `wallet_first` | Wallet-Buttons, Google, magischer Link per E-Mail und E-Mail/Passwort. | Wallets, Google, Magic Link per E-Mail und E-Mail/Passwort. | Ja, SMTP konfigurieren. | Große Authentifizierungsoberfläche nach der E-Mail- und OAuth-Verifizierung. |
| `full` | Google, Mail Magic Link, E-Mail/Passwort und Wallet-Buttons. | Google, magischer Link per E-Mail, E-Mail/Passwort und Wallets. | Ja, SMTP konfigurieren. | Vollständige Authentifizierungsoberfläche im Browser für spätere Versionen. |

Für jeden Modus, der magische Links per E-Mail anzeigt, legen Sie `TEXTREE_MAILER_ADAPTER=smtp` fest
und die `TEXTREE_SMTP_*`-Variablen vor dem Start und führen Sie sie dann aus
`mix textree.email.test recipient@example.com`.

## Erster Alpha-Workflow

Sobald der Stack betriebsbereit ist:

1. Registrieren oder melden Sie sich über TextTree unter `/signup` oder `/login` an oder erstellen Sie ein
   Headless-Agent-Konto mit `POST /api/v1/accounts` oder `POST /mcp/accounts`.
2. Öffnen Sie `/app`.
3. Erstellen oder rufen Sie mit `messages:write` ein TextTree-Inhaber-Zugriffstoken `txt_...` ab.
4. Fügen Sie ein Prepaid-SMS-Guthaben mit einer USDC-Finanzierungsrechnung hinzu.
5. Überprüfen Sie den Status der Rechnung, bis der Restbetrag gutgeschrieben ist.
6. Stellen Sie sicher, dass für den Empfänger kein Arbeitsbereich gelöscht wird.
7. Verwenden Sie das TextTree-Bearer-Zugriffstoken für `POST /api/v1/messages`.
8. Überprüfen Sie `GET /api/v1/messages/:id` oder überprüfen Sie `/app` auf Lieferanten- und Finanzierungsstatus.

## Programmatisches Onboarding

Die aktuelle API stellt Konto-Bootstrap- und Starteinstellungen für authentifizierte Benutzer und Agenten bereit:

- `POST /api/v1/accounts` zum Erstellen von Headless-Konten mit Benutzername/Passwort
– `POST /mcp/accounts` für denselben Headless-Bootstrap im gesamten MCP-Namespace
- `GET /api/v1/onboarding` mit `onboarding:read`
- `POST /api/v1/onboarding/api-key` mit `onboarding:write`, um ein Inhabertoken `txt_...` mit Bereichen auszustellen
- `POST /api/v1/onboarding/funding-invoices` mit `onboarding:write`
- `GET /api/v1/onboarding/funding-invoices/:id` mit `onboarding:read`
- `POST /api/v1/onboarding/branded-request` mit `onboarding:write`

Headless Bootstrap gibt einmalige Backup-Codes und ein Bearer-Token `txt_...` zurück
von TextTree mit API/MCP-Bereichen. Der gleiche Finanzierungsstatus steht Agenten über zur Verfügung
die MCP-Tools `onboarding.status`, `onboarding.create_invoice` und
`onboarding.invoice_status`.

## Verifizierungsbefehle

- `pnpm test`
- `pnpm verify`
- `pnpm app:test`
- `pnpm www:check`
- `pnpm www:build`

## Was die aktuelle Alpha-Version garantiert

- Stabile Routen-Namespaces
- Neonfähiges Ecto-Setup
- Oban-Warteschlangen für Kurierdienste und Webhooks
- native Phoenix-Authentifizierung und lokale Identitätsnormalisierung
- Löschungen von Arbeitsbereichen und Kampagnen anwenden
- Lieferanten-STOP/Ausschluss-Abstimmung bei Arbeitsbereichslöschungen
- Spesengenehmigung vor Ausführung beim Lieferanten
- Verifizierte Aufnahme von Messaging- und Finanzierungs-Webhooks
- MCP-Ausführungsprüfungen, Quoten und Wartezeitrichtlinien

## Was noch nicht öffentlich ist

Die aktuelle Alpha-Version behält stattdessen immer noch einen Teil der kritischen Konfiguration in der authentifizierten App bei
Öffentliche API-Endpunkte:

- Verwaltung von Arbeitsbereichs-/Kampagnenlöschungen
- Verwaltung der Ausgabenlimits
- Fallback-Coderotation im Browser nach dem ersten Headless-Bootstrap