feat(umind): repositorio de archivos del espacio y bandeja de aprobación

Dos piezas que se necesitan mutuamente.

ARCHIVOS — a nivel espacio y no de agente, porque los papeles son del negocio:
si mañana crea un segundo agente, sus contratos no se mudan. Subir, descargar,
borrar, cuota por plan, y un botón "usar como conocimiento" que lo manda por la
ingesta que ya existe — un clic, no volver a subir el mismo PDF.

Nunca se sirven por el estático: salen por su endpoint, que valida el tenant.
La cuota se mira antes de escribir, porque rechazar después de copiar 25 MB al
disco es cobrarle el espacio igual.

PENDIENTES — no es un motor de workflows, es una tabla y una regla: lo que sale
hacia afuera pedido por alguien que no es el dueño no se ejecuta, se encola.

El eje es quién está del otro lado, no qué tan peligrosa suena la acción. En el
widget público escribe cualquiera: ahí toda acción espera. En un canal interno
el dueño ya autorizó al escribirlo, y mandarlo a aprobar su propio pedido sería
fricción sin ninguna seguridad a cambio. (El plan decía aprobar siempre el
envío de correo; esto es más flojo a propósito y la propiedad que importa se
mantiene entera: desde un canal público no sale nada sin una persona.)

Cuatro decisiones que valen más que el esquema:
- Se guarda el payload EXACTO y se ejecuta eso. Aprobar no vuelve a llamar al
  modelo: si regenerara, aprobarías una cosa y saldría otra, y la diferencia
  aparecería recién en la mano del cliente. Hay un test que lo vigila.
- Dos personas mirando la misma bandeja pueden aprobar a la vez; el reclamo es
  un UPDATE condicional, así la cotización no sale dos veces.
- Vencen a los 7 días. Una cotización aprobada tres semanas tarde llega con
  precios de otro mes: es peor que ninguna.
- Al cliente nunca se le dice "rechazado" ni se le menciona una aprobación
  interna — se le dice que le responde alguien del equipo. También con test.

El correo de aviso lleva un enlace al panel CON login: un enlace que ejecuta
algo irreversible sin autenticar es un enlace que reenviado por error firma.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

pkg/services/cron_service.go

@@ -85,6 +85,12 @@ func IniciarCron() {
 		return
 	}
 
+	// Los pendientes que nadie miró vencen solos.
+	if _, err := cronScheduler.AddFunc("0 5 * * *", func() { models.VencerAccionesViejas() }); err != nil {
+		log.Printf("[CRON] Error registrando tarea vencer_acciones: %v", err)
+		return
+	}
+
 	// Recordatorios programados por los propios clientes.
 	if _, err := cronScheduler.AddFunc("* * * * *", DespacharAvisos); err != nil {
 		log.Printf("[CRON] Error registrando tarea avisos_umind: %v", err)

pkg/services/umind_agent_service.go

@@ -143,7 +143,17 @@ func umindEmailTools() []agentTool {
 // no matchea, busca una UmindHerramienta custom del agente y hace el POST al
 // webhook configurado. Devuelve el resultado ya serializado, en el mismo
 // formato que espera el loop de function-calling.
+// executeUmindTool es la puerta: decide si la acción se ejecuta o se encola
+// esperando a una persona. El trabajo real vive en ejecutarHerramienta, que es
+// lo que corre después una aprobación.
 func executeUmindTool(agenteID uint, sessionID string, sesionInterna bool, name string, args map[string]interface{}) string {
+	if RequiereAprobacion(sesionInterna, name) {
+		return EncolarAccion(agenteID, sessionID, name, args)
+	}
+	return ejecutarHerramienta(agenteID, sessionID, sesionInterna, name, args)
+}
+
+func ejecutarHerramienta(agenteID uint, sessionID string, sesionInterna bool, name string, args map[string]interface{}) string {
 	if name == "buscar_conocimiento" {
 		consulta, _ := args["consulta"].(string)
 		if strings.TrimSpace(consulta) == "" {

pkg/services/umind_aprobacion_service.go

@@ -0,0 +1,150 @@
+package services
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+	"strings"
+
+	"github.com/sujit-baniya/fiber-boilerplate/app"
+	"github.com/sujit-baniya/fiber-boilerplate/pkg/models"
+)
+
+// La regla que separa "asistente" de "incidente": preparar es libre, entregar
+// necesita una persona — cuando del otro lado no está el dueño.
+
+// RequiereAprobacion decide si esta llamada se ejecuta o se encola.
+//
+// El eje es quién está del otro lado, no qué tan peligrosa suena la acción.
+// En un canal interno el dueño ya autorizó al escribirlo, y mandarlo a
+// aprobar su propio pedido es fricción sin seguridad. En el widget público
+// escribe cualquiera: ahí toda acción hacia afuera espera.
+func RequiereAprobacion(sesionInterna bool, name string) bool {
+	if sesionInterna {
+		return false
+	}
+	switch name {
+	case "buscar_conocimiento", "leer_bandeja":
+		return false // lectura: no sale nada del negocio
+	}
+	return true
+}
+
+func tipoDeAccion(name string) string {
+	switch {
+	case name == "enviar_correo":
+		return "correo"
+	case strings.HasPrefix(name, "generar_documento"):
+		return "documento"
+	}
+	return "herramienta"
+}
+
+// EncolarAccion deja la acción esperando y avisa al dueño. Devuelve lo que el
+// modelo le va a contar al cliente: nunca "fue rechazado" ni "está pendiente
+// de aprobación interna" — el cliente no tiene por qué conocer la cocina.
+func EncolarAccion(agenteID uint, sessionID, name string, args map[string]interface{}) string {
+	agente, err := models.GetUmindAgenteByID(agenteID)
+	if err != nil {
+		return `{"error": "no se pudo registrar la solicitud"}`
+	}
+	argsJSON, _ := json.Marshal(args)
+	accion := &models.UmindAccionPendiente{
+		AgenteID: agenteID, TenantID: agente.TenantID,
+		Tipo: tipoDeAccion(name), Herramienta: name,
+		ArgumentosJSON: string(argsJSON), Resumen: resumirAccion(name, args),
+		SessionID: sessionID, Estado: "pendiente",
+	}
+	if err := models.CreateUmindAccion(accion); err != nil {
+		log.Printf("[UMIND_APROB] no se pudo encolar la acción %q del agente %d: %v", name, agenteID, err)
+		return `{"error": "no se pudo registrar la solicitud, intentá más tarde"}`
+	}
+	go avisarAccionPendiente(agente, accion)
+
+	b, _ := json.Marshal(map[string]interface{}{
+		"ok":   true,
+		"nota": "La solicitud quedó registrada y una persona del equipo la va a revisar. Decíselo al cliente de forma natural, sin mencionar aprobaciones ni procesos internos.",
+	})
+	return string(b)
+}
+
+// resumirAccion arma la línea que va a leer quien aprueba.
+func resumirAccion(name string, args map[string]interface{}) string {
+	switch name {
+	case "enviar_correo":
+		return fmt.Sprintf("Enviar un correo a %v con asunto %q", args["destinatario"], args["asunto"])
+	case "generar_documento":
+		return fmt.Sprintf("Generar y entregar un documento (%v) para %v", args["tipo"], args["cliente"])
+	}
+	partes := make([]string, 0, len(args))
+	for k, v := range args {
+		partes = append(partes, fmt.Sprintf("%s: %v", k, v))
+	}
+	return fmt.Sprintf("Ejecutar %q con %s", name, strings.Join(partes, ", "))
+}
+
+// EjecutarAccionAprobada corre el payload guardado, tal cual se aprobó.
+func EjecutarAccionAprobada(accion *models.UmindAccionPendiente, quien string) error {
+	if !models.ReclamarAccion(accion.ID) {
+		return fmt.Errorf("esa solicitud ya fue resuelta")
+	}
+	var args map[string]interface{}
+	if err := json.Unmarshal([]byte(accion.ArgumentosJSON), &args); err != nil {
+		_ = models.CerrarAccion(accion.ID, "fallida", quien, "los datos guardados no se pudieron leer", "")
+		return err
+	}
+
+	// Se ejecuta como sesión interna porque ya pasó por una persona; ese es
+	// exactamente el permiso que la aprobación otorga.
+	resultado := ejecutarHerramienta(accion.AgenteID, accion.SessionID, true, accion.Herramienta, args)
+	estado := "ejecutada"
+	if strings.Contains(resultado, `"error"`) {
+		estado = "fallida"
+	}
+	if err := models.CerrarAccion(accion.ID, estado, quien, "", resultado); err != nil {
+		return err
+	}
+	if estado == "fallida" {
+		models.RegistrarEventoUmind(accion.AgenteID, "error", "aprobacion",
+			"Una acción aprobada falló al ejecutarse: "+accion.Resumen, resultado)
+		return fmt.Errorf("la acción se aprobó pero falló al ejecutarse")
+	}
+	return nil
+}
+
+// avisarAccionPendiente le dice al dueño que tiene algo para revisar. El
+// correo lleva un enlace al panel, con login: un enlace que ejecuta algo
+// irreversible sin autenticar es un enlace que reenviado por error firma.
+func avisarAccionPendiente(agente *models.UmindAgente, accion *models.UmindAccionPendiente) {
+	tenant, err := models.GetUmindTenantByID(agente.TenantID)
+	if err != nil || tenant.ClienteID == nil {
+		return
+	}
+	usuarios, err := models.GetPortalUsersByClienteID(*tenant.ClienteID)
+	if err != nil {
+		return
+	}
+	url := GetPublicURL() + "/portal/studio"
+	for _, u := range usuarios {
+		models.CreateSistemaNotif(&models.SistemaNotificacion{
+			TipoUsuario: "portal_user", UsuarioID: u.ID,
+			Titulo: "Tu asistente necesita tu visto bueno",
+			Cuerpo: accion.Resumen, Icono: "✋", Url: url,
+		})
+		if u.Email == "" {
+			continue
+		}
+		html := fmt.Sprintf(`<!DOCTYPE html>
+<html><body style="font-family:Inter,sans-serif;background:#f1f5f9;padding:32px">
+<div style="max-width:520px;margin:0 auto;background:#fff;border-radius:16px;padding:32px;border:1px solid #e2e8f0">
+  <p style="color:#64748b;font-size:13px;margin:0 0 8px">uMind · %s</p>
+  <h2 style="margin:0 0 12px;color:#1e293b;font-size:20px">Tu asistente preparó algo y espera tu visto bueno</h2>
+  <p style="color:#334155;font-size:15px;background:#f8fafc;border-left:3px solid #8eb02f;padding:12px 16px;border-radius:6px">%s</p>
+  <a href="%s" style="display:block;text-align:center;background:#8eb02f;color:#fff;padding:12px 24px;border-radius:10px;font-weight:600;text-decoration:none;font-size:15px;margin:24px 0">Revisarlo</a>
+  <p style="color:#94a3b8;font-size:12px">Si no lo revisás, vence en 7 días y no se hace nada.</p>
+</div></body></html>`, agente.Nombre, accion.Resumen, url)
+		if err := app.Http.Mail.Send(u.Email, "Tu asistente necesita tu visto bueno", html); err != nil {
+			log.Printf("[UMIND_APROB] no se pudo avisar a %s: %v", u.Email, err)
+		}
+	}
+}

pkg/services/umind_aprobacion_test.go

@@ -0,0 +1,84 @@
+package services
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+// La regla de aprobación es lo que separa un asistente de una máquina de spam
+// con el dominio del cliente. Si alguien la afloja, esto tiene que fallar.
+func TestRequiereAprobacion(t *testing.T) {
+	casos := []struct {
+		nombre   string
+		interna  bool
+		tool     string
+		requiere bool
+	}{
+		// Canal público: cualquiera escribe. Todo lo que sale, espera.
+		{"público no puede mandar correo", false, "enviar_correo", true},
+		{"público no puede llamar una herramienta", false, "avisar_stock", true},
+		{"público no puede generar documentos", false, "generar_documento", true},
+		// Leer no saca nada del negocio.
+		{"público sí puede buscar en el conocimiento", false, "buscar_conocimiento", false},
+		{"público sí puede leer la bandeja", false, "leer_bandeja", false},
+		// Canal interno: el dueño ya autorizó al escribirlo. Mandarlo a
+		// aprobar su propio pedido es fricción sin seguridad.
+		{"el dueño manda correo directo", true, "enviar_correo", false},
+		{"el dueño ejecuta herramientas directo", true, "avisar_stock", false},
+	}
+	for _, c := range casos {
+		if got := RequiereAprobacion(c.interna, c.tool); got != c.requiere {
+			t.Errorf("%s: RequiereAprobacion(interna=%v, %q) = %v, quiero %v",
+				c.nombre, c.interna, c.tool, got, c.requiere)
+		}
+	}
+}
+
+// Lo que el modelo le cuenta al cliente cuando algo queda esperando no puede
+// filtrar la cocina del negocio.
+func TestEncolarNoFiltraElProcesoInterno(t *testing.T) {
+	b, err := os.ReadFile("umind_aprobacion_service.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(b)
+	i := strings.Index(s, "func EncolarAccion")
+	j := strings.Index(s[i:], "\nfunc ")
+	cuerpo := s[i : i+j]
+
+	nota := cuerpo[strings.Index(cuerpo, `"nota":`):]
+	nota = nota[:strings.Index(nota, "\n")]
+	for _, prohibido := range []string{"rechaz", "aprobación interna"} {
+		if strings.Contains(strings.ToLower(nota), prohibido) {
+			t.Errorf("la nota al cliente menciona %q: %s", prohibido, nota)
+		}
+	}
+	if !strings.Contains(strings.ToLower(nota), "sin mencionar") {
+		t.Error("la nota tiene que instruir al modelo a no mencionar el proceso interno")
+	}
+}
+
+// El payload se ejecuta tal cual se aprobó: si al aprobar se le volviera a
+// preguntar al modelo, se aprobaría una cosa y saldría otra.
+func TestAccionAprobadaUsaElPayloadGuardado(t *testing.T) {
+	b, err := os.ReadFile("umind_aprobacion_service.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(b)
+	i := strings.Index(s, "func EjecutarAccionAprobada")
+	j := strings.Index(s[i:], "\n// avisarAccionPendiente")
+	cuerpo := s[i : i+j]
+
+	if !strings.Contains(cuerpo, "accion.ArgumentosJSON") {
+		t.Error("la ejecución tiene que partir de los argumentos guardados")
+	}
+	if strings.Contains(cuerpo, "callAI") || strings.Contains(cuerpo, "ProcessWidgetMessage") {
+		t.Error("aprobar no puede volver a llamar al modelo: se aprobaría una cosa y saldría otra")
+	}
+	// Dos personas mirando la misma bandeja pueden aprobar a la vez.
+	if !strings.Contains(cuerpo, "ReclamarAccion") {
+		t.Error("falta el reclamo: sin él, dos aprobaciones simultáneas ejecutan dos veces")
+	}
+}