From 544decf4ac8969787574c5dabe009f5f04eb32d6 Mon Sep 17 00:00:00 2001 From: Daniel Arroyo Date: Sun, 22 Mar 2026 17:51:05 -0300 Subject: [PATCH] docs: add new project summary 2026-03-22 --- resumen/2026-03-22-1750-resumen.md | 222 +++++++++++++++++++++++++++++ 1 file changed, 222 insertions(+) create mode 100644 resumen/2026-03-22-1750-resumen.md diff --git a/resumen/2026-03-22-1750-resumen.md b/resumen/2026-03-22-1750-resumen.md new file mode 100644 index 0000000..9247a37 --- /dev/null +++ b/resumen/2026-03-22-1750-resumen.md @@ -0,0 +1,222 @@ +# 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 +- **Base de datos**: SQLite via Prisma ORM +- **Lenguaje**: TypeScript +- **UI**: TailwindCSS + shadcn/ui components +- **Testing**: Jest + +## Estructura del Proyecto + +``` +src/ +├── app/ # Next.js App Router +│ ├── api/ # API routes +│ │ ├── notes/ # CRUD, versions, quick +│ │ ├── 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 +│ ├── notes/[id]/ # Detalle de nota +│ ├── edit/[id]/ # Edición de nota +│ └── new/ # Nueva nota +├── components/ # Componentes React +│ ├── 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 +│ ├── 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 +└── lib/ # Utilidades + ├── 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 +``` + +## 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 | + +## 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 +- Tests de historial de versiones + +## 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) +``` + +## Tests + +**211 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 + +## 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 +``` + +## Roadmap +- [ ] Panel de métricas visible en UI +- [ ] Configuración de feature flags en Settings +- [ ] Visualización del grafo de conocimiento +- [ ] Exportación mejorada (Markdown, HTML) +- [ ] Tests E2E