Daniel Arroyo
ece8163d15
- 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
343 lines
11 KiB
Markdown
343 lines
11 KiB
Markdown
# Recall - Resumen del Proyecto
|
||
|
||
## Fecha
|
||
2026-03-22
|
||
|
||
## Descripción
|
||
Recall es una aplicación de gestión de conocimiento personal (PKM) para captura y recuperación de notas, comandos, snippets y conocimiento técnico.
|
||
|
||
## Stack Tecnológico
|
||
- **Framework**: Next.js 16.2.1 con App Router + Turbopack
|
||
- **Base de datos**: SQLite via Prisma ORM
|
||
- **Lenguaje**: TypeScript
|
||
- **UI**: TailwindCSS + shadcn/ui components
|
||
- **Testing**: Jest (226 tests)
|
||
- **Notificaciones**: Sonner (toasts)
|
||
|
||
## Estructura del Proyecto
|
||
|
||
```
|
||
src/
|
||
├── app/
|
||
│ ├── api/
|
||
│ │ ├── notes/ # CRUD, versions, quick, backlinks, links, suggest
|
||
│ │ ├── tags/ # Tags y sugerencias
|
||
│ │ ├── search/ # Búsqueda avanzada
|
||
│ │ ├── usage/ # Tracking de uso y co-uso
|
||
│ │ ├── metrics/ # Métricas internas
|
||
│ │ ├── centrality/ # Notas centrales
|
||
│ │ ├── export-import/ # Import/export JSON, Markdown, HTML
|
||
│ │ ├── import-markdown/ # Importador Markdown mejorado
|
||
│ │ └── capture/ # Captura externa (bookmarklet)
|
||
│ ├── notes/[id]/ # Detalle de nota
|
||
│ ├── edit/[id]/ # Edición de nota
|
||
│ ├── new/ # Nueva nota
|
||
│ ├── capture/ # Página de confirmación de captura
|
||
│ └── settings/ # Configuración
|
||
├── components/
|
||
│ ├── ui/ # shadcn/ui components
|
||
│ ├── dashboard.tsx # Dashboard inteligente
|
||
│ ├── quick-add.tsx # Captura rápida
|
||
│ ├── note-form.tsx # Formulario de nota
|
||
│ ├── note-connections.tsx # Panel de conexiones
|
||
│ ├── note-list.tsx # Lista de notas
|
||
│ ├── keyboard-navigable-note-list.tsx # Lista con navegación teclado
|
||
│ ├── keyboard-hint.tsx # Hint de atajos
|
||
│ ├── related-notes.tsx # Notas relacionadas
|
||
│ ├── version-history.tsx # Historial de versiones
|
||
│ ├── track-note-view.tsx # Tracking de vistas
|
||
│ ├── 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 shortcuts
|
||
│ ├── 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 del bookmarklet
|
||
│ ├── recent-context-list.tsx # Historial de navegación
|
||
│ ├── track-navigation-history.tsx # Tracking de historial
|
||
│ └── preferences-panel.tsx # Panel de preferencias
|
||
├── hooks/
|
||
│ ├── use-global-shortcuts.ts # Atajos globales
|
||
│ ├── use-note-list-keyboard.ts # Navegación teclado en listas
|
||
│ ├── use-unsaved-changes.ts # Guard de cambios sin guardar
|
||
│ └── ...
|
||
└── lib/
|
||
├── prisma.ts # Cliente Prisma
|
||
├── usage.ts # Tracking de uso y co-uso
|
||
├── search.ts # Búsqueda con scoring
|
||
├── query-parser.ts # Parser de queries avanzadas
|
||
├── versions.ts # Historial de versiones
|
||
├── related.ts # Notas relacionadas
|
||
├── backlinks.ts # Sistema de enlaces [[wiki]]
|
||
├── tags.ts # Normalización y sugerencias
|
||
├── 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
|
||
├── 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
|
||
```
|
||
|
||
## Modelos de Datos
|
||
|
||
### 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 Principales
|
||
|
||
| Endpoint | Método | Descripción |
|
||
|----------|--------|-------------|
|
||
| `/api/notes` | GET, POST | Listar/crear notas |
|
||
| `/api/notes/[id]` | GET, PUT, DELETE | CRUD de nota |
|
||
| `/api/notes/[id]/versions` | GET, POST | Listar/crear versiones |
|
||
| `/api/notes/[id]/versions/[vid]` | GET, PUT | Ver/restaurar versión |
|
||
| `/api/notes/quick` | POST | Creación rápida |
|
||
| `/api/notes/links` | GET | Sugerencias de enlaces |
|
||
| `/api/search` | GET | Búsqueda con scoring |
|
||
| `/api/tags` | GET | Listar/buscar tags |
|
||
| `/api/tags/suggest` | GET | Sugerencias automáticas |
|
||
| `/api/usage` | GET | Estadísticas de uso |
|
||
| `/api/usage/co-usage` | GET | Notas co-usadas |
|
||
| `/api/metrics` | GET | Métricas de dashboard |
|
||
| `/api/centrality` | GET | Notas más centrales |
|
||
| `/api/export-import` | GET, POST | Export/Import (JSON, Markdown, HTML) |
|
||
| `/api/import-markdown` | POST | Importador Markdown mejorado |
|
||
| `/api/capture` | POST | Captura externa segura |
|
||
|
||
## Features Implementadas
|
||
|
||
### MVP-1
|
||
- CRUD completo de notas
|
||
- Sistema de tags
|
||
- Búsqueda básica
|
||
|
||
### MVP-2
|
||
- Búsqueda avanzada con scoring
|
||
- Quick Add con prefijos (cmd:, snip:, etc.)
|
||
- Backlinks con sintaxis [[wiki]]
|
||
- Formularios guiados por tipo de nota
|
||
|
||
### MVP-3
|
||
- Usage tracking (vistas, clics, copias)
|
||
- Dashboard inteligente
|
||
- Scoring boost basado en uso
|
||
- Sugerencias automáticas de tags
|
||
- Panel "Conectado con"
|
||
- Quick Add multilínea
|
||
- Pegado inteligente con detección de tipo
|
||
- Sugerencia automática de tipo de nota
|
||
- Sugerencia de enlaces internos
|
||
- Registro de co-uso entre notas
|
||
- Métricas internas
|
||
- Cálculo de notas centrales
|
||
- Feature flags configurables
|
||
|
||
### MVP-4
|
||
- Query parser para búsquedas avanzadas (`type:`, `tag:`, `is:favorite`, `is:pinned`)
|
||
- Búsqueda en tiempo real con 300ms debounce
|
||
- Navegación por teclado (↑↓ Enter ESC) estilo Spotlight
|
||
- Dropdown de resultados con cache
|
||
- Sidebar contextual con co-uso
|
||
- Historial de versiones de notas
|
||
|
||
### MVP-5 (Completo)
|
||
|
||
**Sprint 1 - Confianza total:**
|
||
- Sistema de backup automático (IndexedDB)
|
||
- Política de retención (max 10 backups, 30 días)
|
||
- Restore con preview y validación
|
||
- Backup previo automático pre-destructivo
|
||
- Guard de cambios sin guardar
|
||
|
||
**Sprint 2 - Flujo diario desde teclado:**
|
||
- Command Palette global (Ctrl+K / Cmd+K)
|
||
- Modelo de acciones para palette
|
||
- Shortcuts globales (g h, g n, n, /, ?)
|
||
- Navegación de listas por teclado (↑↓ Enter E F P)
|
||
|
||
**Sprint 3 - Contexto y continuidad:**
|
||
- Sidebar contextual persistente mejorada
|
||
- Modo trabajo con toggle
|
||
- Autosave de borradores locales
|
||
- Historial de navegación contextual
|
||
|
||
**Sprint 4 - Captura ubicua:**
|
||
- Bookmarklet para capturar desde cualquier web
|
||
- Página de confirmación de captura
|
||
- Endpoint seguro /api/capture con rate limiting
|
||
|
||
**P2 - Exportación, Importación y Settings:**
|
||
- Exportación Markdown con frontmatter
|
||
- Exportación HTML legible
|
||
- Importador Markdown mejorado (frontmatter, tags, wiki links)
|
||
- Importador Obsidian-compatible
|
||
- Centro de respaldo en Settings
|
||
- Panel de preferencias (backup on/off, retención, work mode)
|
||
- Tests de command palette y captura
|
||
- Validaciones y límites (50MB backup, 10K notas, etc)
|
||
|
||
## Algoritmo de Scoring
|
||
|
||
```typescript
|
||
// Search scoring
|
||
score = baseScore + favoriteBoost(+2) + pinnedBoost(+1) + usageBoost
|
||
|
||
// Related notes scoring
|
||
score = sameType(+3) + sharedTags(×3) + titleKeywords(max+3) + contentKeywords(max+2) + usageBoost
|
||
|
||
// Centrality score
|
||
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 (en lista) |
|
||
| `F` | Favoritar nota (en lista) |
|
||
| `P` | Fijar nota (en lista) |
|
||
|
||
## Tests
|
||
|
||
**226 tests** cubriendo:
|
||
- API routes (CRUD, search, tags, versions)
|
||
- Search y scoring
|
||
- Query parser
|
||
- Notas relacionadas
|
||
- Backlinks
|
||
- Type inference
|
||
- Link suggestions
|
||
- Usage tracking
|
||
- Dashboard
|
||
- Version history
|
||
- Command items
|
||
- External capture
|
||
- Navigation history
|
||
|
||
## Comandos
|
||
|
||
```bash
|
||
npm run dev # Desarrollo
|
||
npm run build # Build producción
|
||
npm test # Tests (usar npx jest)
|
||
npx prisma db push # Sync schema
|
||
npx prisma studio # UI de BD
|
||
```
|
||
|
||
## Configuración de Feature Flags
|
||
|
||
```bash
|
||
FLAG_CENTRALITY=true
|
||
FLAG_PASSIVE_RECOMMENDATIONS=true
|
||
FLAG_TYPE_SUGGESTIONS=true
|
||
FLAG_LINK_SUGGESTIONS=true
|
||
```
|
||
|
||
## Estados 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) |
|
||
|
||
## Commits Recientes
|
||
|
||
```
|
||
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
|
||
```
|