Archive: System v4 - Estado al 2024-12-24

2025-12-24 17:28:34 +00:00
parent a92d41c846
commit 1b392803fd
81 changed files with 24560 additions and 0 deletions
--- a/v4-archive/hst/docs/spec/HST_ROADMAP_v1.md
+++ b/v4-archive/hst/docs/spec/HST_ROADMAP_v1.md
@@ -0,0 +1,394 @@
+# HST - Roadmap de Implementación
+**Versión:** 1.0  
+**Fecha:** 2025-12-07  
+**Estado:** Borrador para maduración
+
+---
+
+# Visión General
+
+El sistema HST (Hash Semantic Tagging) evolucionará en 4 fases, desde especificación formal hasta una aplicación cliente universal de drag & drop.
+
+```
+Fase 0          Fase 1              Fase 2                 Fase 3
+SPEC        →   Servidor        →   Descentralización  →   App Cliente
+(Documentos)    (KVM1 Hostinger)    (Filecoin/IPFS)        (Drag & Drop)
+```
+
+---
+
+# Fase 0: Especificación Formal
+
+## Objetivo
+Documento definitivo que describe el sistema completo antes de cualquier implementación.
+
+## Entregables
+
+| Documento | Descripción | Estado |
+|-----------|-------------|--------|
+| `SPEC.md` | Especificación técnica completa del sistema HST | Pendiente |
+| `SCHEMA.md` | Modelo de datos para NocoDB/PostgreSQL | Pendiente |
+| `TAGS_v1.csv` | Listado consolidado de etiquetas (~850) | En progreso |
+| `HIERARCHY.md` | Árbol jerárquico de categorías | Pendiente |
+| `RELATIONS.md` | Grafo de relaciones entre etiquetas | Pendiente |
+| `API.md` | Especificación de endpoints REST | Pendiente |
+| `STYLES.md` | Tabla de estilos (4096 skins) | Pendiente |
+
+## Contenido de SPEC.md
+
+1. Filosofía del sistema
+2. Imagen primigenia (reglas)
+3. Hash maestro (H_maestro)
+4. Extensiones (EXT, HSU, SP, SPU, PRJ)
+5. Sistema de estilos (hash visible)
+6. Cadena de metadatos (jerarquía)
+7. Propiedad y acceso (H_propiedad, H_acceso)
+8. Bibliotecas (sistema, empresa, usuario)
+9. Pipeline de importación
+10. Integración con ecosistema (SFE, IA, n8n)
+
+## Criterios de salida
+- [ ] Todos los documentos revisados y aprobados
+- [ ] Sin ambigüedades técnicas
+- [ ] Listado de etiquetas limpio y categorizado
+
+---
+
+# Fase 1: Servidor Centralizado
+
+## Objetivo
+Primera implementación funcional en servidor KVM1 de Hostinger.
+
+## Infraestructura
+
+```
+KVM1 Hostinger
+├── Docker
+│   ├── NocoDB (metadatos)
+│   ├── PostgreSQL (base de datos)
+│   └── API HST (FastAPI/Node)
+├── /hst/
+│   ├── primigenias/{H_maestro}.png
+│   └── skins/{hash_visible}.png
+└── Nginx (proxy + SSL)
+```
+
+## Componentes
+
+| Componente | Tecnología | Función |
+|------------|------------|---------|
+| Base de datos | PostgreSQL | Almacén principal |
+| Interfaz datos | NocoDB | Gestión visual de etiquetas |
+| API REST | FastAPI | Consulta/servicio de etiquetas |
+| Almacenamiento | Sistema de archivos | Imágenes primigenias y skins |
+| Proxy | Nginx | SSL + routing |
+| Orquestación | n8n (Alfred) | Pipelines de importación |
+
+## Funcionalidades
+
+### 1. Gestión de etiquetas
+- CRUD completo vía NocoDB
+- Validación de imagen primigenia (sin metadatos)
+- Cálculo automático de H_maestro
+- Generación de skins
+
+### 2. API REST
+```
+GET  /api/v1/tags                    # Listar etiquetas
+GET  /api/v1/tags/{h_maestro}        # Obtener etiqueta
+GET  /api/v1/tags/{h_maestro}/image  # Obtener imagen
+GET  /api/v1/tags/{h_maestro}/skins  # Listar skins
+POST /api/v1/tags                    # Crear etiqueta
+GET  /api/v1/search?q=...            # Buscar por nombre/código
+GET  /api/v1/hierarchy/{ref}         # Obtener árbol jerárquico
+```
+
+### 3. Pipeline de importación
+1. Leer desde Airtable (fuente actual)
+2. Descargar imagen
+3. Limpiar metadatos
+4. Calcular SHA-256 → H_maestro
+5. Generar estructura de metadatos
+6. Subir primigenia
+7. Generar skins (según tabla de estilos)
+8. Registrar en NocoDB
+
+### 4. Subdominio
+- `hst.tzzr.pro` o `tags.tzzr.pro`
+
+## Criterios de salida
+- [ ] API funcional con todos los endpoints
+- [ ] ~850 etiquetas migradas desde Airtable
+- [ ] Pipeline de importación automatizado
+- [ ] Documentación de API generada
+
+---
+
+# Fase 2: Descentralización
+
+## Objetivo
+Servicio multi-usuario escalable con almacenamiento descentralizado.
+
+## Arquitectura
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    CAPA DE USUARIOS                      │
+│  App Web  │  App Desktop  │  App Móvil  │  Extensión    │
+└─────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────┐
+│                      API GATEWAY                         │
+│         Auth + Rate Limiting + Routing                   │
+└─────────────────────────────────────────────────────────┘
+                            │
+              ┌─────────────┼─────────────┐
+              ▼             ▼             ▼
+┌─────────────────┐ ┌─────────────┐ ┌─────────────────┐
+│  NocoDB/PostgreSQL │ │   Redis     │ │  Filecoin/IPFS  │
+│  (Índice/Metadatos)│ │   (Cache)   │ │  (Imágenes)     │
+└─────────────────┘ └─────────────┘ └─────────────────┘
+```
+
+## Componentes nuevos
+
+| Componente | Función |
+|------------|---------|
+| Filecoin/IPFS | Almacenamiento descentralizado de imágenes |
+| CID (Content ID) | Referencia inmutable a cada imagen |
+| Sistema de bibliotecas | Pública, privada, por usuario |
+| Autenticación | JWT + H_propiedad |
+| Permisos | Control por H_acceso |
+| Rate limiting | Protección de API pública |
+
+## Tipos de biblioteca
+
+| Tipo | Propiedad | Acceso | Descripción |
+|------|-----------|--------|-------------|
+| Sistema | HST | Público | Etiquetas base universales |
+| Empresa | Organización | Miembros | Etiquetas corporativas |
+| Usuario | Individual | Personal | Etiquetas propias |
+| Compartida | Múltiple | Definido | Colaboración entre usuarios |
+
+## Modelo de datos extendido
+
+```
+Etiqueta {
+  h_maestro: string (PK)
+  codigo_corto: string
+  nombres: { es, en, zh... }
+  extension: EXT | HSU | SP | SPU | PRJ
+  
+  # Almacenamiento
+  cid_primigenia: string      # IPFS/Filecoin
+  cid_skins: [string]         # Array de CIDs
+  
+  # Metadatos
+  cadena_metadatos: [string]  # Jerarquía de hashes
+  h_propiedad: string         # Biblioteca propietaria
+  h_acceso: string            # Nivel de acceso
+  
+  # Auditoría
+  created_at: timestamp
+  created_by: string
+  version: int
+}
+```
+
+## Flujo de resolución
+
+```
+1. Cliente solicita etiqueta por H_maestro
+2. API busca en caché Redis
+3. Si no existe → busca en NocoDB (índice)
+4. Obtiene CID de Filecoin/IPFS
+5. Resuelve imagen desde red descentralizada
+6. Cachea resultado
+7. Retorna al cliente
+```
+
+## Criterios de salida
+- [ ] Imágenes almacenadas en Filecoin/IPFS
+- [ ] Sistema de bibliotecas funcionando
+- [ ] Autenticación y permisos implementados
+- [ ] API pública documentada y protegida
+- [ ] Al menos 3 bibliotecas de prueba (sistema, empresa, usuario)
+
+---
+
+# Fase 3: Aplicación Cliente
+
+## Objetivo
+Aplicación universal de drag & drop para usar etiquetas HST en cualquier software.
+
+## Plataformas
+
+| Plataforma | Tecnología | Prioridad |
+|------------|------------|-----------|
+| Desktop (Windows/Mac/Linux) | Tauri o Electron | Alta |
+| Web | React/Vue | Alta |
+| Móvil (iOS/Android) | React Native o Flutter | Media |
+| Extensión Chrome/Firefox | WebExtension | Media |
+| Plugin Office | Office Add-in | Baja |
+| Plugin Figma | Figma API | Baja |
+
+## Funcionalidades core
+
+### 1. Navegador de etiquetas
+- Vista en árbol (jerarquía)
+- Vista en grid (visual)
+- Búsqueda por nombre/código/hash
+- Filtros por extensión/biblioteca
+
+### 2. Drag & Drop
+- Arrastrar etiqueta a cualquier aplicación
+- Formatos de salida:
+  - Imagen PNG
+  - Código corto (texto)
+  - Hash (texto)
+  - Markdown `![nombre](url)`
+  - HTML `<img src="url">`
+
+### 3. Gestión de bibliotecas
+- Ver bibliotecas disponibles
+- Suscribirse a bibliotecas públicas
+- Crear biblioteca personal
+- Sincronización offline
+
+### 4. Creación de etiquetas (usuarios)
+- Subir imagen primigenia
+- Asignar código y nombres
+- Seleccionar extensión (HSU, SPU, PRJ)
+- Proponer para validación (opcional)
+
+## Flujo de usuario
+
+```
+1. Usuario abre app HST
+2. Navega/busca etiqueta deseada
+3. Arrastra etiqueta
+4. Suelta en aplicación destino (Word, Figma, etc.)
+5. La etiqueta se inserta como imagen/texto según contexto
+```
+
+## Integración con sistema operativo
+
+| OS | Método |
+|----|--------|
+| Windows | Clipboard API + Shell Extension |
+| macOS | NSPasteboard + Finder Extension |
+| Linux | X11/Wayland Clipboard |
+
+## Modelo de monetización (futuro)
+
+| Tier | Precio | Incluye |
+|------|--------|---------|
+| Free | 0€ | Biblioteca pública, 10 etiquetas propias |
+| Pro | 5€/mes | Bibliotecas ilimitadas, skins premium |
+| Enterprise | Personalizado | Bibliotecas privadas, soporte, SLA |
+
+## Criterios de salida
+- [ ] App desktop funcional (1 plataforma mínimo)
+- [ ] Drag & drop funcionando en apps comunes
+- [ ] Sincronización con servidor HST
+- [ ] Documentación de usuario
+
+---
+
+# Dependencias entre fases
+
+```
+Fase 0 ──────► Fase 1 ──────► Fase 2 ──────► Fase 3
+   │              │              │              │
+   │              │              │              │
+   ▼              ▼              ▼              ▼
+SPEC.md      Servidor       Filecoin        App
+SCHEMA.md    NocoDB         Auth            Desktop
+TAGS.csv     API REST       Bibliotecas     Drag&Drop
+             Pipeline       Permisos        Móvil
+```
+
+---
+
+# H_propiedad y H_acceso (PENDIENTE DEFINIR)
+
+## H_propiedad - Definición parcial
+
+Identifica el propietario/origen de la etiqueta.
+
+| Grupo | H_propiedad |
+|-------|-------------|
+| `hst` | Hash de la etiqueta "hst" (sistema) |
+| `spe` | Hash de la etiqueta "especificación" (sistema) |
+| `hsu` | Hash del usuario creador |
+| `msu` | Hash del usuario creador |
+
+## H_acceso - Por definir
+
+Llave de acceso para descarga de imagen. Relacionado con:
+- Sistema de monetización futuro
+- Compartición de bibliotecas entre usuarios
+- Colaboración en proyectos (msu)
+
+**Notas:**
+- Se exploró embeber en metadatos PNG pero no está validado
+- Inicialmente innecesario: la cadena estará en NocoDB
+- Los grupos hsu/msu permiten compartición (por definir mecanismo)
+- Diferenciación de grupos define reglas de acceso diferentes
+
+**TODO para próximas revisiones:**
+- [ ] Definir mecanismo de compartición de bibliotecas usuario
+- [ ] Definir modelo de monetización y su relación con H_acceso
+- [ ] Validar si metadatos embebidos en PNG son viables
+- [ ] Definir permisos de colaboración en proyectos (msu)
+
+---
+
+# Preguntas abiertas (a resolver)
+
+## Fase 0
+- [x] ¿Formato definitivo de código corto? → Variable según grupo
+- [ ] ¿Cuántos estilos iniciales implementar?
+- [x] ¿Estructura exacta de cadena_metadatos? → Definida parcialmente
+
+## Fase 1
+- [ ] ¿Dominio/subdominio para el servicio?
+- [ ] ¿Migración completa desde Airtable o parcial?
+- [ ] ¿Autenticación desde Fase 1 o solo Fase 2?
+
+## Fase 2
+- [ ] ¿Filecoin vs IPFS vs ambos?
+- [ ] ¿Modelo de costos de almacenamiento descentralizado?
+- [ ] ¿Política de bibliotecas públicas (quién puede publicar)?
+
+## Fase 3
+- [ ] ¿Prioridad de plataformas?
+- [ ] ¿Modelo freemium desde el inicio?
+- [ ] ¿Integración con marketplaces de plugins?
+
+---
+
+# Timeline estimado
+
+| Fase | Duración estimada | Dependencias |
+|------|-------------------|--------------|
+| Fase 0 | 1-2 semanas | Ninguna |
+| Fase 1 | 2-4 semanas | Fase 0 completa |
+| Fase 2 | 4-8 semanas | Fase 1 estable |
+| Fase 3 | 8-12 semanas | Fase 2 funcional |
+
+**Total estimado:** 4-6 meses para MVP completo
+
+---
+
+# Notas
+
+- Este roadmap es un documento vivo que evolucionará
+- Cada fase tiene criterios de salida claros
+- Las fases pueden solaparse parcialmente
+- Priorizar funcionalidad sobre perfección en cada fase
+
+---
+
+**Próximo paso:** Consolidar SPEC.md (Fase 0)