Primeros pasos

Respuesta directa

Ejecuta el sitio de Astro y el plano de control de Phoenix localmente, y luego recorre el flujo de trabajo alfa actual.

Contenido de la página

# Primeros pasos

TextTree está dividido en dos aplicaciones:

- `apps/site` para el sitio público de Astro
- `apps/web` para la aplicación Phoenix, la API para desarrolladores, los webhooks y los endpoints de MCP

## Flujo de trabajo local

1. Instala Node 22+, Elixir 1.19+, Erlang/OTP 28+ y PostgreSQL.
2. Copia `apps/web/.env.example` a `apps/web/.env.local`.
3. Copia `apps/site/.env.example` a `apps/site/.env.local`.
4. Genera un token de Proton SMTP Submission antes de enviar correos locales reales.
5. Ejecuta `pnpm setup` desde la raíz del repositorio.
6. Inicia Astro con `pnpm --dir apps/site dev`.
7. Inicia Phoenix con `cd apps/web && mix phx.server`.

## URLs locales

- Sitio público de Astro: `http://localhost:4321`
- Aplicación y API de Phoenix: `http://localhost:4001`

## Grupos de entorno

Las variables de entorno están organizadas por responsabilidad:

- Entorno de ejecución local de Phoenix: `apps/web/.env.local`
- Configuración pública local de Astro: `apps/site/.env.local`
- operaciones de despliegue/administración de producción: `devops/env/prod.env.local`
- operaciones de despliegue/administración de pruebas: `devops/env/test.env.local`

No uses archivos env en la raíz. Solo se versionan los archivos de ejemplo por ámbito.

## Modo de autenticación

Configura `TEXTREE_AUTH_MODE` en el entorno de ejecución de Phoenix para elegir qué
métodos de registro e inicio de sesión son visibles.

| Valor | Interfaz de registro/inicio de sesión | Habilitado tras bambalinas | ¿Requiere entrega de correo? | Uso típico |
| --- | --- | --- | --- | --- |
| `magic_link_or_ethereum` | Solo enlace mágico por correo y billetera de Ethereum. Solana, Google y correo/contraseña están ocultos. | Enlace mágico por correo, correo/contraseña y billetera de Ethereum. | Sí, configura SMTP. | Modo de lanzamiento predeterminado actual. |
| `wallet_only` | Solo botones de billetera de Ethereum y Solana. Enlace mágico por correo, Google y correo/contraseña están ocultos. | Billetera de Ethereum y Solana. | No. | Lanzamiento solo cripto o entrega de correo no verificada. |
| `wallet_first` | Botones de billetera, Google, enlace mágico por correo y correo/contraseña. | Billeteras, Google, enlace mágico por correo y correo/contraseña. | Sí, configura SMTP. | Superficie de autenticación amplia después de verificar el correo y OAuth. |
| `full` | Google, enlace mágico por correo, correo/contraseña y botones de billetera. | Google, enlace mágico por correo, correo/contraseña y billeteras. | Sí, configura SMTP. | Superficie completa de autenticación en el navegador para lanzamientos posteriores. |

Para cualquier modo que muestre enlaces mágicos por correo, configura `TEXTREE_MAILER_ADAPTER=smtp`
y las variables `TEXTREE_SMTP_*` antes del lanzamiento, y luego ejecuta
`mix textree.email.test recipient@example.com`.

## Primer flujo de trabajo alfa

Una vez que el stack esté en funcionamiento:

1. Regístrate o inicia sesión a través de TextTree en `/signup` o `/login`, o crea una
   cuenta de agente headless con `POST /api/v1/accounts` o `POST /mcp/accounts`.
2. Abre `/app`.
3. Crea o recupera un token de acceso bearer `txt_...` de TextTree con `messages:write`.
4. Añade saldo prepago de SMS con una factura de financiamiento en USDC.
5. Consulta el estado de la factura hasta que el saldo se acredite.
6. Confirma que el destinatario no esté bajo una supresión de espacio de trabajo.
7. Usa el token de acceso bearer de TextTree contra `POST /api/v1/messages`.
8. Consulta `GET /api/v1/messages/:id` o inspecciona `/app` para ver el estado del proveedor y del financiamiento.

## Onboarding programático

La API actual expone el bootstrap de cuentas y la configuración de lanzamiento para usuarios y agentes autenticados:

- `POST /api/v1/accounts` para la creación de cuentas headless con nombre de usuario/contraseña
- `POST /mcp/accounts` para el mismo bootstrap headless a través del espacio de nombres de MCP
- `GET /api/v1/onboarding` con `onboarding:read`
- `POST /api/v1/onboarding/api-key` con `onboarding:write` para emitir un token bearer `txt_...` con scopes
- `POST /api/v1/onboarding/funding-invoices` con `onboarding:write`
- `GET /api/v1/onboarding/funding-invoices/:id` con `onboarding:read`
- `POST /api/v1/onboarding/branded-request` con `onboarding:write`

El bootstrap headless devuelve códigos de respaldo de un solo uso y un token bearer `txt_...`
de TextTree con scopes de API/MCP. El mismo estado de financiamiento está disponible para los agentes a través de
las herramientas MCP `onboarding.status`, `onboarding.create_invoice` y
`onboarding.invoice_status`.

## Comandos de verificación

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

## Lo que garantiza la versión alfa actual

- espacios de nombres de rutas estables
- configuración de Ecto lista para Neon
- colas de Oban para el trabajo de mensajería y webhooks
- autenticación nativa de Phoenix y normalización de identidades locales
- aplicación de supresiones de espacio de trabajo y de campaña
- reconciliación de STOP/exclusión del proveedor en supresiones de espacio de trabajo
- autorización de gasto antes de la ejecución en el proveedor
- ingesta verificada de webhooks de mensajería y financiamiento
- auditorías de ejecución de MCP, cuotas y política de tiempos de espera

## Lo que aún no es público

La versión alfa actual todavía mantiene parte de la configuración crítica dentro de la aplicación autenticada en lugar de
endpoints de API públicos:

- gestión de supresiones de espacio de trabajo/campaña
- gestión de límites de gasto
- rotación de códigos de respaldo en el navegador después del bootstrap headless inicial