chore: Various improvements and CI setup

- Add Jenkinsfile for CI/CD pipeline - Fix keyboard shortcut '?' handling for help dialog - Update note form and connections components - Add work mode toggle improvements - Update navigation history and usage tracking - Improve validators - Add session summaries
2026-03-23 22:25:36 -03:00
parent e0433f8e57
commit ece8163d15
12 changed files with 976 additions and 36 deletions
--- a/resumen/2026-03-22-2000-resumen.md
+++ b/resumen/2026-03-22-2000-resumen.md
@@ -0,0 +1,431 @@
+# Recall - Resumen Técnico Detallado
+
+## Información General
+
+**Nombre:** Recall
+**Descripción:** Sistema de gestión de conocimiento personal (PKM) para captura y recuperación de notas, comandos, snippets y conocimiento técnico.
+**Fecha de creación:** 2026-03-22
+**Estado:** MVP-5 Completo
+
+## Stack Tecnológico
+
+| Componente | Tecnología | Versión |
+|------------|-------------|---------|
+| Framework | Next.js + App Router + Turbopack | 16.2.1 |
+| Base de datos | SQLite via Prisma ORM | 5.22.0 |
+| Lenguaje | TypeScript | 5.x |
+| UI | TailwindCSS + shadcn/ui | 4.x / latest |
+| Testing | Jest | 30.3.0 |
+| Notificaciones | Sonner (toasts) | latest |
+| IDE | VSCode / Cursor |
+
+## Estructura del Proyecto
+
+```
+src/
+├── app/
+│   ├── api/
+│   │   ├── notes/
+│   │   │   ├── route.ts           # GET, POST /api/notes
+│   │   │   ├── [id]/route.ts      # GET, PUT, DELETE /api/notes/:id
+│   │   │   ├── quick/route.ts     # POST /api/notes/quick
+│   │   │   ├── links/route.ts     # GET /api/notes/links
+│   │   │   ├── suggest/route.ts   # GET /api/notes/suggest
+│   │   │   ├── backlinks/route.ts # GET /api/notes/:id/backlinks
+│   │   │   └── versions/
+│   │   │       ├── route.ts       # GET, POST /api/notes/:id/versions
+│   │   │       └── [versionId]/route.ts # GET, PUT
+│   │   ├── tags/
+│   │   │   ├── route.ts           # GET /api/tags
+│   │   │   └── suggest/route.ts   # GET /api/tags/suggest
+│   │   ├── search/route.ts       # GET /api/search
+│   │   ├── usage/
+│   │   │   ├── route.ts           # GET /api/usage
+│   │   │   └── co-usage/route.ts # GET /api/usage/co-usage
+│   │   ├── metrics/route.ts      # GET /api/metrics
+│   │   ├── centrality/route.ts   # GET /api/centrality
+│   │   ├── export-import/route.ts # GET, POST
+│   │   ├── import-markdown/route.ts # POST
+│   │   └── capture/route.ts       # POST /api/capture
+│   ├── notes/[id]/page.tsx       # Detalle de nota
+│   ├── edit/[id]/page.tsx        # Edición de nota
+│   ├── new/page.tsx              # Nueva nota
+│   ├── capture/page.tsx          # Confirmación de captura
+│   ├── settings/page.tsx         # Configuración
+│   └── page.tsx                  # Dashboard (raíz)
+├── components/
+│   ├── ui/                       # Componentes shadcn/ui
+│   ├── dashboard.tsx             # Dashboard inteligente
+│   ├── note-form.tsx             # Formulario de notas
+│   ├── note-card.tsx             # Tarjeta de nota
+│   ├── note-list.tsx             # Lista de notas (grid)
+│   ├── keyboard-navigable-note-list.tsx # Lista con navegación teclado
+│   ├── note-connections.tsx      # Panel de conexiones
+│   ├── related-notes.tsx         # Notas relacionadas
+│   ├── version-history.tsx        # Historial de versiones
+│   ├── search-bar.tsx            # Búsqueda en tiempo real
+│   ├── command-palette.tsx        # Command palette (Ctrl+K)
+│   ├── keyboard-shortcuts-dialog.tsx # Diálogo de atajos
+│   ├── shortcuts-provider.tsx     # Provider de atajos
+│   ├── keyboard-hint.tsx         # Hint de atajos
+│   ├── work-mode-toggle.tsx       # Toggle modo trabajo
+│   ├── draft-recovery-banner.tsx  # Banner de recuperación
+│   ├── backup-restore-dialog.tsx  # Restore con preview
+│   ├── backup-list.tsx           # Lista de backups
+│   ├── bookmarklet-instructions.tsx # Instrucciones bookmarklet
+│   ├── recent-context-list.tsx    # Historial de navegación
+│   ├── track-navigation-history.tsx # Tracking de historial
+│   ├── preferences-panel.tsx     # Panel de preferencias
+│   ├── markdown-content.tsx       # Contenido con highlight
+│   ├── quick-add.tsx             # Captura rápida
+│   └── track-note-view.tsx       # Tracking de vistas
+├── hooks/
+│   ├── use-global-shortcuts.ts   # Atajos globales
+│   ├── use-note-list-keyboard.ts # Navegación teclado
+│   └── use-unsaved-changes.ts   # Guard de cambios sin guardar
+└── lib/
+    ├── prisma.ts                 # Cliente Prisma
+    ├── search.ts                 # Búsqueda con scoring
+    ├── query-parser.ts           # Parser de queries
+    ├── related.ts                # Notas relacionadas
+    ├── backlinks.ts               # Sistema de enlaces [[wiki]]
+    ├── tags.ts                   # Normalización y sugerencias
+    ├── usage.ts                  # Tracking de uso
+    ├── metrics.ts                # Métricas de dashboard
+    ├── centrality.ts             # Cálculo de centralidad
+    ├── type-inference.ts         # Detección automática de tipo
+    ├── link-suggestions.ts       # Sugerencias de enlaces
+    ├── features.ts               # Feature flags
+    ├── validators.ts             # Zod schemas
+    ├── errors.ts                 # Manejo de errores
+    ├── versions.ts               # Historial de versiones
+    ├── backup.ts                 # Snapshot de backup
+    ├── backup-storage.ts         # IndexedDB storage
+    ├── backup-policy.ts          # Política de retención
+    ├── backup-validator.ts       # Validación de backups
+    ├── restore.ts                # Restore de backups
+    ├── drafts.ts                 # Borradores locales
+    ├── work-mode.ts              # Modo trabajo
+    ├── navigation-history.ts     # Historial de navegación
+    ├── export-markdown.ts        # Exportación Markdown
+    ├── export-html.ts            # Exportación HTML
+    ├── import-markdown.ts        # Importador Markdown
+    ├── external-capture.ts       # Captura externa
+    ├── templates.ts              # Templates por tipo
+    ├── command-items.ts          # Items de command palette
+    └── command-groups.ts         # Grupos de comandos
+```
+
+## Modelos de Datos (Prisma)
+
+### Note
+```prisma
+model Note {
+  id             String    @id @default(cuid())
+  title          String
+  content        String
+  type           String    @default("note")
+  isFavorite     Boolean   @default(false)
+  isPinned       Boolean   @default(false)
+  createdAt      DateTime  @default(now())
+  updatedAt      DateTime  @updatedAt
+  creationSource String    @default("form")
+}
+```
+
+### NoteUsage
+```prisma
+model NoteUsage {
+  id        String   @id @default(cuid())
+  noteId    String
+  eventType String
+  query     String?
+  createdAt DateTime @default(now())
+}
+```
+
+### NoteCoUsage
+```prisma
+model NoteCoUsage {
+  id         String @id @default(cuid())
+  fromNoteId String
+  toNoteId   String
+  weight     Int    @default(1)
+}
+```
+
+### NoteVersion
+```prisma
+model NoteVersion {
+  id        String   @id @default(cuid())
+  noteId    String
+  title     String
+  content   String
+  createdAt DateTime @default(now())
+}
+```
+
+### Backlink
+```prisma
+model Backlink {
+  sourceNoteId String
+  targetNoteId String
+}
+```
+
+## APIs REST
+
+| Endpoint | Método | Descripción |
+|----------|--------|-------------|
+| `/api/notes` | GET, POST | Listar/crear notas |
+| `/api/notes/[id]` | GET, PUT, DELETE | CRUD nota |
+| `/api/notes/quick` | POST | Creación rápida |
+| `/api/notes/links` | GET | Sugerencias de enlaces |
+| `/api/notes/suggest` | GET | Sugerencias automática |
+| `/api/notes/[id]/versions` | GET, POST | Versiones |
+| `/api/notes/[id]/backlinks` | GET | Backlinks |
+| `/api/search` | GET | Búsqueda avanzada |
+| `/api/tags` | GET | Tags |
+| `/api/tags/suggest` | GET | Sugerencias de tags |
+| `/api/usage` | GET | Uso de notas |
+| `/api/usage/co-usage` | GET | Co-uso entre notas |
+| `/api/metrics` | GET | Métricas dashboard |
+| `/api/centrality` | GET | Notas centrales |
+| `/api/export-import` | GET, POST | Export/Import |
+| `/api/import-markdown` | POST | Importar Markdown |
+| `/api/capture` | POST | Captura externa |
+
+## Features Implementadas
+
+### MVP-1: Fundamentos
+- [x] CRUD completo de notas
+- [x] Sistema de tags
+- [x] Búsqueda básica
+
+### MVP-2: Captura Inteligente
+- [x] Búsqueda avanzada con scoring
+- [x] Quick Add con prefijos (cmd:, snip:, etc.)
+- [x] Backlinks con sintaxis [[wiki]]
+- [x] Formularios guiados por tipo
+- [x] Templates inteligentes por tipo
+- [x] Vista command con copiar
+- [x] Vista snippet con syntax highlight
+- [x] Checklist interactivo en procedure
+
+### MVP-3: Uso y Contexto
+- [x] Usage tracking (vistas, clics, copias)
+- [x] Dashboard inteligente
+- [x] Scoring boost basado en uso
+- [x] Sugerencias automáticas de tags
+- [x] Panel "Conectado con"
+- [x] Quick Add multilínea
+- [x] Pegado inteligente con detección de tipo
+- [x] Sugerencia automática de tipo
+- [x] Sugerencia de enlaces internos
+- [x] Registro de co-uso entre notas
+- [x] Métricas internas
+- [x] Cálculo de notas centrales
+- [x] Feature flags configurables
+
+### MVP-4: Query Parser y Navegación
+- [x] Query parser (`type:`, `tag:`, `is:favorite`, `is:pinned`)
+- [x] Búsqueda en tiempo real (300ms debounce)
+- [x] Navegación por teclado (↑↓ Enter ESC)
+- [x] Dropdown de resultados con cache
+- [x] Sidebar contextual con co-uso
+- [x] Historial de versiones
+- [x] Preload de notas en hover
+
+### MVP-5: Flujo Diario y Portabilidad
+
+**Sprint 1 - Confianza:**
+- [x] Sistema de backup automático (IndexedDB)
+- [x] Política de retención (max 10 backups, 30 días)
+- [x] Restore con preview y validación
+- [x] Backup previo automático
+- [x] Guard de cambios sin guardar
+
+**Sprint 2 - Shortcuts Globales:**
+- [x] Command Palette (Ctrl+K / Cmd+K)
+- [x] Shortcuts: g h, g n, n, /, ?
+- [x] Navegación de listas por teclado
+
+**Sprint 3 - Contexto y Continuidad:**
+- [x] Sidebar contextual persistente
+- [x] Modo trabajo con toggle
+- [x] Autosave de borradores locales
+- [x] Historial de navegación contextual
+
+**Sprint 4 - Captura Ubicua:**
+- [x] Bookmarklet para capturar desde web
+- [x] Página de confirmación
+- [x] Endpoint seguro con rate limiting
+
+**P2 - Exportación e Importación:**
+- [x] Exportación Markdown con frontmatter
+- [x] Exportación HTML legible
+- [x] Importador Markdown mejorado
+- [x] Centro de respaldo en Settings
+- [x] Panel de preferencias
+- [x] Validaciones y límites
+
+## Algoritmos de Scoring
+
+### Búsqueda
+```
+score = baseScore + favoriteBoost(+2) + pinnedBoost(+1) + usageBoost
+```
+
+### Notas Relacionadas
+```
+score = sameType(+3) + sharedTags(×3) + titleKeywords(max+3) + contentKeywords(max+2) + usageBoost
+```
+
+### Centralidad
+```
+centrality = backlinks(×3) + outboundLinks(×1) + usageViews(×0.5) + coUsageWeight(×2)
+```
+
+## Atajos de Teclado
+
+| Atajo | Acción |
+|-------|--------|
+| `Ctrl+K` / `Cmd+K` | Command Palette |
+| `g h` | Ir al Dashboard |
+| `g n` | Ir a Notas |
+| `n` | Nueva nota |
+| `/` | Enfocar búsqueda |
+| `?` | Mostrar ayuda |
+| `↑↓` | Navegar listas |
+| `Enter` | Abrir nota |
+| `E` | Editar nota |
+| `F` | Favoritar nota |
+| `P` | Fijar nota |
+
+## Tipos de Nota
+
+| Tipo | Descripción | Color |
+|------|-------------|-------|
+| `note` | Nota general | Slate |
+| `command` | Comando o snippet ejecutable | Green |
+| `snippet` | Fragmento de código | Blue |
+| `decision` | Decisión tomada | Purple |
+| `recipe` | Receta o procedimiento | Orange |
+| `procedure` | Procedimiento con checkboxes | Yellow |
+| `inventory` | Inventario o lista | Gray |
+
+## Comandos npm
+
+```bash
+npm run dev          # Desarrollo (Turbopack)
+npm run build        # Build producción
+npm run start        # Iniciar producción
+npm test             # Tests (Jest)
+npx jest --watch     # Tests en watch mode
+npx prisma db push   # Sync schema a BD
+npx prisma studio    # UI de base de datos
+npx prisma generate  # Generar tipos
+```
+
+## Tests
+
+**226 tests** organizados en:
+- `__tests__/api.*.test.ts` - Tests de integración de APIs
+- `__tests__/search.test.ts` - Búsqueda y scoring
+- `__tests__/query-parser.test.ts` - Parser de queries
+- `__tests__/related.test.ts` - Notas relacionadas
+- `__tests__/backlinks.test.ts` - Sistema de enlaces
+- `__tests__/tags.test.ts` - Tags y sugerencias
+- `__tests__/usage.test.ts` - Tracking de uso
+- `__tests__/versions.test.ts` - Historial de versiones
+- `__tests__/dashboard.test.ts` - Dashboard
+- `__tests__/command-items.test.ts` - Command palette
+- `__tests__/external-capture.test.ts` - Captura externa
+- `__tests__/navigation-history.test.ts` - Historial
+- `__tests__/link-suggestions.test.ts` - Sugerencias de enlaces
+- `__tests__/type-inference.test.ts` - Inferencia de tipo
+- `__tests__/quick-add.test.ts` - Quick Add
+
+## Feature Flags
+
+Configurables via `localStorage` o `.env`:
+
+```bash
+FLAG_CENTRALITY=true        # Habilitar centralidad
+FLAG_PASSIVE_RECOMMENDATIONS=true  # Recomendaciones pasivas
+FLAG_TYPE_SUGGESTIONS=true  # Sugerencias de tipo
+FLAG_LINK_SUGGESTIONS=true  # Sugerencias de enlaces
+```
+
+## Límites del Sistema
+
+| Recurso | Límite |
+|---------|--------|
+| Tamaño de backup | 50MB |
+| Cantidad de notas | 10,000 |
+| Longitud de título (captura) | 500 chars |
+| Longitud de URL (captura) | 2000 chars |
+| Longitud de selección (captura) | 10,000 chars |
+| Backups retenidos | 10 máximo |
+| Días de retención | 30 días |
+
+## Commits del Proyecto
+
+```
+33a4705 feat: MVP-4 P2 - Preload notes on hover
+e66a678 feat: MVP-5 P2 - Export/Import, Settings, Tests y Validaciones
+8d56f34 feat: MVP-5 Sprint 4 - External Capture via Bookmarklet
+a40ab18 feat: MVP-5 Sprint 3 - Sidebar, Work Mode, and Drafts
+cde0a14 feat: MVP-5 Sprint 2 - Command Palette and Global Shortcuts
+8c80a12 feat: MVP-5 Sprint 1 - Backup/Restore system
+6694bce mvp
+af0910f feat: initial commit
+f2e4706 Initial commit
+```
+
+## Dependencias Principales
+
+```json
+{
+  "next": "16.2.1",
+  "@prisma/client": "5.22.0",
+  "prisma": "5.22.0",
+  "sonner": "latest",
+  "zod": "latest",
+  "tailwindcss": "4.x",
+  "@radix-ui/react-*": "latest"
+}
+```
+
+## Patrones de Diseño
+
+- **Server Components** para páginas estáticas
+- **Client Components** para interactividad
+- **Hooks personalizados** para lógica reutilizable
+- **Feature Flags** para features opcionales
+- **IndexedDB** para persistencia local de backups
+- **localStorage** para preferencias y borradores
+
+## Estado de Implementación
+
+| Feature | Estado |
+|---------|--------|
+| CRUD notas | ✅ |
+| Tags | ✅ |
+| Búsqueda avanzada | ✅ |
+| Quick Add | ✅ |
+| Backlinks [[wiki]] | ✅ |
+| Usage tracking | ✅ |
+| Dashboard inteligente | ✅ |
+| Versiones de notas | ✅ |
+| Command Palette | ✅ |
+| Shortcuts globales | ✅ |
+| Modo trabajo | ✅ |
+| Backup/Restore | ✅ |
+| Bookmarklet capture | ✅ |
+| Export Markdown/HTML | ✅ |
+| Import Markdown | ✅ |
+| Settings completo | ✅ |
+| Feature flags UI | ✅ |
+| Tests | ✅ (226) |
+| Preload on hover | ✅ |