Daniel Arroyo
7c5fba5f12
- Add MVP-4 sprints 1-4 features - Update structure with query-parser.ts, versions.ts - Add NoteVersion model and versions API - Update test count to 211
243 lines
7.3 KiB
Markdown
243 lines
7.3 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
|
||
- **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 de notas, versions, quick
|
||
│ │ ├── tags/ # Tags y sugerencias
|
||
│ │ ├── search/ # Búsqueda avanzada
|
||
│ │ ├── usage/ # Tracking de 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
|
||
└── 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") // command, snippet, decision, recipe, procedure, inventory, note
|
||
isFavorite Boolean @default(false)
|
||
isPinned Boolean @default(false)
|
||
createdAt DateTime @default(now())
|
||
updatedAt DateTime @updatedAt
|
||
creationSource String @default("form") // form, quick, import
|
||
}
|
||
```
|
||
|
||
### NoteUsage
|
||
```prisma
|
||
model NoteUsage {
|
||
id String @id @default(cuid())
|
||
noteId String
|
||
eventType String // view, search_click, related_click, link_click, copy_command, copy_snippet
|
||
query String?
|
||
createdAt DateTime @default(now())
|
||
}
|
||
```
|
||
|
||
### NoteCoUsage
|
||
```prisma
|
||
model NoteCoUsage {
|
||
id String @id @default(cuid())
|
||
fromNoteId String
|
||
toNoteId String
|
||
weight Int @default(1)
|
||
}
|
||
```
|
||
|
||
### Backlink
|
||
```prisma
|
||
model Backlink {
|
||
sourceNoteId String
|
||
targetNoteId String
|
||
}
|
||
```
|
||
|
||
### NoteVersion
|
||
```prisma
|
||
model NoteVersion {
|
||
id String @id @default(cuid())
|
||
noteId String
|
||
title String
|
||
content String
|
||
createdAt DateTime @default(now())
|
||
}
|
||
```
|
||
|
||
## 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 (Completado)
|
||
- CRUD completo de notas
|
||
- Sistema de tags
|
||
- Búsqueda básica
|
||
|
||
### MVP-2 (Completado)
|
||
- Búsqueda avanzada con scoring
|
||
- Quick Add con prefijos (cmd:, snip:, etc.)
|
||
- Backlinks con sintaxis [[wiki]]
|
||
- Formularios guiados por tipo de nota
|
||
|
||
### MVP-3 Sprint 1
|
||
- Usage tracking (vistas, clics, copias)
|
||
- Dashboard inteligente (Recientes, Más usadas, Por tipo)
|
||
- Scoring boost basado en uso
|
||
|
||
### MVP-3 Sprint 2
|
||
- Sugerencias automáticas de tags
|
||
- Panel "Conectado con" (backlinks, enlaces, relacionadas)
|
||
|
||
### MVP-3 Sprint 3
|
||
- Quick Add multilínea
|
||
- Pegado inteligente con detección de tipo
|
||
- Sugerencia automática de tipo de nota
|
||
- Sugerencia de enlaces internos
|
||
|
||
### MVP-3 Sprint 4
|
||
- Registro de co-uso entre notas
|
||
- Métricas internas (notas por tipo, más vistas, por origen)
|
||
- Cálculo de notas centrales (centrality score)
|
||
- Registro de origen de creación (form/quick/import)
|
||
- Feature flags configurables
|
||
|
||
### Mejoras UI Recientes
|
||
- Header responsive con menú hamburguesa en móvil
|
||
- Desktop: una fila con logo, nav links, QuickAdd y botón Nueva nota
|
||
- Mobile: logo + QuickAdd + hamburguesa → dropdown con nav links y botón Nueva nota
|
||
|
||
### MVP-4 Sprint 1
|
||
- 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 de 50 entradas
|
||
|
||
### MVP-4 Sprint 2
|
||
- Sidebar contextual con co-uso (notas vistas juntas)
|
||
- Cache de resultados de búsqueda
|
||
|
||
### MVP-4 Sprint 3
|
||
- Historial de versiones de notas
|
||
- API de versiones (crear, listar, restaurar)
|
||
- UI de historial en diálogo de nota
|
||
|
||
### MVP-4 Sprint 4
|
||
- Tests de historial de versiones (11 tests)
|
||
|
||
## 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, etc.)
|
||
- 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 run test # Tests
|
||
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 de integración E2E
|