260121: Documentación Captain Claude API v3

02_COMPONENTES/internos/captain_claude_api_v3.md

@@ -0,0 +1,230 @@
+# Captain Claude API v3
+
+API para interactuar con Claude Code desde aplicaciones móviles/web.
+
+## Información General
+
+| Campo | Valor |
+|-------|-------|
+| **Servidor** | ARCHITECT (69.62.126.110) |
+| **Puerto** | 3030 |
+| **Protocolo** | HTTP + WebSocket |
+| **Dominio externo** | captain.tzzrarchitect.me |
+| **Ubicación código** | `/home/architect/captain-claude/apps/captain-mobile-v2/backend/captain_api_v3.py` |
+
+## Autenticación
+
+JWT Bearer Token. Obtener via `/auth/login`.
+
+```bash
+curl -X POST https://captain.tzzrarchitect.me/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"***"}'
+```
+
+Respuesta:
+```json
+{
+  "token": "eyJ...",
+  "username": "admin"
+}
+```
+
+## Endpoints REST
+
+### GET /health
+Estado del servicio.
+
+```json
+{"status": "ok", "version": "3.0.0"}
+```
+
+### POST /auth/login
+Autenticación.
+
+**Request:**
+```json
+{
+  "username": "string",
+  "password": "string"
+}
+```
+
+**Response:**
+```json
+{
+  "token": "string",
+  "username": "string"
+}
+```
+
+### GET /sessions
+Lista sesiones activas. Requiere Bearer token.
+
+**Response:**
+```json
+[
+  {
+    "session_id": "abc123...",
+    "name": "Mi sesión"
+  }
+]
+```
+
+### POST /sessions
+Crear nueva sesión. Requiere Bearer token.
+
+**Request:**
+```json
+{
+  "name": "Nombre de la sesión"
+}
+```
+
+**Response:**
+```json
+{
+  "session_id": "abc123...",
+  "name": "Nombre de la sesión"
+}
+```
+
+## WebSocket
+
+### Endpoint
+```
+wss://captain.tzzrarchitect.me/ws/chat
+```
+
+### Flujo de conexión
+
+1. Conectar al WebSocket
+2. Enviar autenticación:
+   ```json
+   {"type": "auth", "token": "eyJ..."}
+   ```
+3. Recibir confirmación con sesiones existentes:
+   ```json
+   {
+     "type": "init",
+     "sessions": [{"session_id": "...", "name": "..."}]
+   }
+   ```
+
+### Mensajes Cliente → Servidor
+
+#### Crear sesión
+```json
+{
+  "type": "create_session",
+  "name": "Nombre de la sesión"
+}
+```
+
+#### Conectar a sesión existente
+```json
+{
+  "type": "connect_session",
+  "session_id": "abc123..."
+}
+```
+
+#### Enviar mensaje a Claude
+```json
+{
+  "type": "message",
+  "content": "Hola Claude"
+}
+```
+
+### Mensajes Servidor → Cliente
+
+#### Sesión creada
+```json
+{
+  "type": "session_created",
+  "session_id": "abc123...",
+  "name": "Nombre"
+}
+```
+
+#### Conectado a sesión
+```json
+{
+  "type": "session_connected",
+  "session_id": "abc123...",
+  "name": "Nombre"
+}
+```
+
+#### Output de Claude (streaming)
+```json
+{
+  "type": "output",
+  "content": "Texto de respuesta..."
+}
+```
+
+#### Respuesta completada
+```json
+{
+  "type": "done",
+  "session_id": "uuid-de-claude"
+}
+```
+
+#### Error
+```json
+{
+  "type": "error",
+  "message": "Descripción del error"
+}
+```
+
+## Arquitectura
+
+```
+┌─────────────┐     HTTPS/WSS      ┌─────────────┐
+│ App Móvil   │ ◄────────────────► │ Caddy       │
+│ (Flutter)   │                    │ (reverse    │
+└─────────────┘                    │  proxy)     │
+                                   └──────┬──────┘
+                                          │ :3030
+                                   ┌──────▼──────┐
+                                   │ Captain API │
+                                   │ v3 (uvicorn)│
+                                   └──────┬──────┘
+                                          │ subprocess
+                                   ┌──────▼──────┐
+                                   │ Claude Code │
+                                   │ (claude -p) │
+                                   └─────────────┘
+```
+
+## Notas
+
+- **Sin screen**: v3 usa `claude -p` directamente como subprocess, no sesiones screen
+- **Session ID**: El `session_id` inicial es temporal. Después del primer mensaje, se actualiza con el UUID real de Claude para poder hacer `--resume`
+- **Streaming**: Las respuestas se envían en tiempo real vía WebSocket
+- **Concurrencia**: Una sesión solo procesa un mensaje a la vez
+
+## Servicio systemd
+
+```ini
+[Unit]
+Description=Captain Claude API v3
+After=network.target
+
+[Service]
+Type=simple
+User=architect
+WorkingDirectory=/home/architect/captain-claude/apps/captain-mobile-v2/backend
+ExecStart=/home/architect/captain-claude/apps/captain-mobile-v2/backend/venv/bin/uvicorn captain_api_v3:app --host 0.0.0.0 --port 3030
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+---
+*Última actualización: 2026-01-21*