uContact Forms Template

Template para crear aplicaciones Vue.js standalone en uContact — sin SDK, sin router, sin autenticación embebida.

¿Qué es uContact Forms?

uContact Forms son aplicaciones Vue standalone que viven en uContact pero no se embeben en iframe del CRM. Se acceden directamente via URL (/forms/mi-app/) y son ideales para:

• ✅ Formularios públicos
• ✅ Wizards simples
• ✅ Apps sin autenticación compleja
• ✅ Vistas únicas con tabs

¿Cuándo usar este template?

Usa forms-template si...	Usa plugin-template si...
No necesitas SDK uCRM	Necesitas comunicación con el CRM parent
No necesitas autenticación	Necesitas evento userLogged del parent
Vista única con tabs	Múltiples vistas con navegación
Acceso directo /forms/app/	Embebido en iframe del CRM

Qué incluye

Stack Tecnológico

• Vue 3 (Composition API con <script setup>)
• Vuetify 3 (tema N2P con colores y defaults)
• Pinia (state management)
• vue-i18n (internacionalización es/en/pt)
• Axios (HTTP client)
• Vite (build tool)

Estructura del Proyecto

forms-template/
├── src/
│   ├── App.vue              # Vista única con 3 tabs
│   ├── main.js              # Entry point (Pinia, Vuetify, i18n)
│   ├── components/          # Componentes por feature (vacío)
│   ├── stores/              # Pinia stores (vacío)
│   ├── repositories/        # Backend communication (vacío)
│   ├── services/
│   │   └── apiService.js    # Axios configurado
│   ├── locales/             # Traducciones es/en/pt
│   ├── plugins/
│   │   ├── vuetify.js       # Tema N2P
│   │   └── i18n.js          # Configuración i18n
│   └── styles/
│       └── custom.scss      # Estilos globales N2P
├── docs/
│   ├── QUICK_START.md       # Guía de inicio rápido
│   ├── DESIGN_GUIDELINES.md # Lineamientos de diseño
│   ├── BACKEND_FLOWS_GUIDE.md # Guía de backend flows
│   └── backend-flows/       # Reglas para agente AI
├── vite.config.js           # Config con proxy obligatorio
├── .env.example             # Variables de entorno
└── .windsurfrules           # Reglas para Windsurf AI

Instalación

1. Copiar el template

cp -r forms-template mi-nueva-app
cd mi-nueva-app

2. Instalar dependencias

npm install

3. Configurar el proyecto

npm run setup

El wizard te pregunta dos cosas:

¿Host de uContact? (ej: miinstancia.ucontactcloud.com): miinstancia.ucontactcloud.com
¿Nombre del proyecto/módulo? (ej: encuesta-satisfaccion): encuesta-satisfaccion

Esto genera el .env automáticamente con:

• Proxy apuntando a tu instancia
• Base path de producción: /forms/encuesta-satisfaccion/

4. Correr en desarrollo

npm run dev

Abre http://localhost:5173

Desarrollo

Estructura de tabs

El App.vue incluye 3 tabs vacíos listos para personalizar:

<v-tabs v-model="tab" color="primary">
  <v-tab value="tab1">{{ t('app.tab1') }}</v-tab>
  <v-tab value="tab2">{{ t('app.tab2') }}</v-tab>
  <v-tab value="tab3">{{ t('app.tab3') }}</v-tab>
</v-tabs>

<v-window v-model="tab" class="mt-4">
  <v-window-item value="tab1">
    <!-- TODO: Contenido tab 1 -->
  </v-window-item>
  <!-- ... -->
</v-window>

Crear componentes

# Crear componente en src/components/
src/components/MiComponente.vue

Crear stores (Pinia)

# Crear store en src/stores/
src/stores/miStore.js

Ejemplo:

import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useMiStore = defineStore('miStore', () => {
  const data = ref([])
  
  async function fetchData() {
    // TODO: implementar
  }
  
  return { data, fetchData }
})

Crear repositories (backend)

# Crear repository en src/repositories/
src/repositories/miRepository.js

Ejemplo:

import apiService from '@/services/apiService'

export const fetchItems = async () => {
  return apiService.post('/getItems', {})
}

Deploy

1. Build

npm run build

2. Subir al servidor

Subir el contenido de dist/ al servidor uContact:

/etc/uContactServer/forms/build/{VITE_PROJECT_NAME}/
├── index.html
└── assets/

Verificar via SSH:

ls -lah /etc/uContactServer/forms/build/

3. Ejecutar SQL de flows + restart

Después de insertar los flows en MySQL:

sudo systemctl restart uContactServer

4. Dar permisos al usuario de webhooks (si hay escritura)

GRANT INSERT, UPDATE, DELETE ON ccrepo.* TO 'client'@'%';
FLUSH PRIVILEGES;
GRANT INSERT, UPDATE, DELETE ON ccdata.* TO 'client'@'%';
FLUSH PRIVILEGES;
GRANT INSERT, UPDATE, DELETE ON bdcustom.* TO 'client'@'%';
FLUSH PRIVILEGES;

Luego reiniciar nuevamente:

sudo systemctl restart uContactServer

Ver guía completa en docs/DEPLOY_GUIDE.md

Documentación

• Quick Start: docs/QUICK_START.md — Guía de inicio rápido
• Deploy: docs/DEPLOY_GUIDE.md — SSH, permisos MySQL, restart servidor
• Diseño: docs/DESIGN_GUIDELINES.md — Colores, botones, diálogos, tablas, CSS
• Backend: docs/BACKEND_FLOWS_GUIDE.md — Cómo crear endpoints en uContact
• Reglas AI: .windsurfrules — Reglas para Windsurf/agente AI

Diferencias con plugin-template

Característica	forms-template	plugin-template
SDK uCRM	❌ No	✅ Sí
Autenticación	❌ No (pública)	✅ Evento userLogged
Router	❌ No (tabs locales)	✅ Hash history
Navegación	Vista única	Múltiples vistas
Acceso	URL directa	Iframe en CRM
Estilos	✅ Idénticos (N2P)	✅ Idénticos (N2P)
Backend	✅ Flows uContact	✅ Flows uContact

Soporte

Para dudas sobre:

• Diseño visual: Ver docs/DESIGN_GUIDELINES.md
• Backend flows: Ver docs/BACKEND_FLOWS_GUIDE.md
• Windsurf AI: Ver .windsurfrules

---

Template creado para uContact Forms — Apps standalone sin SDK ni router