dataforge/kanban
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c28ae7d3c00339009a7168fdf22ebfee78256db8
kanban/app.md
T
egutierrez c28ae7d3c0 chore: auto-commit (12 archivos) 
- app.md
- backend/handlers.go
- backend/main.go
- frontend/src/App.tsx
- frontend/src/api.ts
- frontend/vite.config.ts
- backend/mcp_http.go
- backend/mcp_tokens.go
- backend/mcp_tokens_handlers.go
- backend/migrations/016_mcp_tokens.sql
- ...

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-22 14:38:17 +02:00

188 lines
9.0 KiB
Markdown
Raw Blame History

---
name: kanban
lang: go
domain: tools
version: 0.4.0
description: "Kanban board con persistencia SQLite, drag-and-drop entre columnas (dnd-kit) y tracking del tiempo que cada tarjeta pasa en cada columna. Frontend Vite + React + Mantine v9 embebido en el binario Go."
tags: [service, kanban, web, dnd-kit, mantine, sqlite, time-tracking]
uses_functions:
- random_hex_id_go_core
- parse_date_or_default_go_core
- sqlite_open_go_infra
- sqlite_apply_migrations_go_infra
- sqlite_column_exists_go_infra
- spa_handler_go_infra
- http_router_go_infra
- http_serve_go_infra
- http_middleware_chain_go_infra
- http_cors_middleware_go_infra
- http_logger_middleware_go_infra
- http_json_response_go_infra
- http_error_response_go_infra
- http_parse_body_go_infra
- http_session_cookie_middleware_go_infra
- http_session_token_extract_go_infra
- http_session_cookie_set_go_infra
- http_session_cookie_clear_go_infra
- password_hash_go_infra
- password_verify_go_infra
- session_create_go_infra
- session_cleanup_go_infra
- duration_stats_go_datascience
- format_duration_ts_core
- format_datetime_short_ts_core
- string_hash_palette_ts_core
- color_bg_ts_ui
- color_border_ts_ui
- color_swatch_ts_ui
- fetch_json_ts_infra
- claude_stream_go_core
- mcp_server_stdio_go_infra
- mcp_server_http_go_infra
- ws_upgrader_go_infra
uses_types:
- DurationStats_go_datascience
framework: "net/http + vite + react + mantine + dnd-kit"
entry_point: "backend/main.go"
dir_path: "apps/kanban"
service:
port: 8095
health_endpoint: /api/board
health_timeout_s: 3
systemd_unit: kanban.service
systemd_scope: user
restart_policy: always
runtime: systemd-user
pc_targets:
- aurgi-pc
is_local_only: false
# Validacion end-to-end (fase 4 del bucle reactivo). Ver issue 0068.
e2e_checks:
- id: build_frontend
cmd: "cd frontend && pnpm install --frozen-lockfile && pnpm build"
timeout_s: 180
expect_exit: 0
- id: build_backend
cmd: "CGO_ENABLED=1 go build -tags fts5 -o kanban ."
timeout_s: 120
expect_exit: 0
- id: migrations_apply
cmd: "rm -f /tmp/kanban_e2e.db && ./kanban --port 0 --db /tmp/kanban_e2e.db --migrate-only"
timeout_s: 15
expect_exit: 0
- id: migrations_schema
cmd: "sqlite3 /tmp/kanban_e2e.db 'SELECT version FROM schema_migrations ORDER BY version;'"
expect_stdout_contains: "1"
- id: smoke_api
cmd: "./kanban --port 8195 --db /tmp/kanban_e2e.db &"
health: "http://127.0.0.1:8195/api/board"
timeout_s: 10
- id: tests_go
cmd: "go test -tags fts5 -count=1 ./..."
timeout_s: 120
expect_exit: 0
---
## Arquitectura
Single-binary: backend Go con frontend Vite embebido. SQLite local con tres tablas (`columns`, `cards`, `card_column_history`) y endpoints REST.
```
./kanban --port 8095 --db kanban.db
```
### Schema SQLite (`migrations/001_init.sql` … `010_card_messages.sql`)
- **columns** — id, name, position, created_at
- **cards** — id, title, description, column_id (FK), position, created_at, updated_at
- **card_column_history** — id, card_id (FK), column_id, entered_at, exited_at
- Una entrada con `exited_at IS NULL` = posicion actual
- Al mover una tarjeta a otra columna: cierra la entrada activa (`exited_at = now`) e inserta una nueva
- El borrado de tarjeta hace CASCADE sobre el historial
- **card_messages** (migration 010) — id, card_id (FK CASCADE), author_id (nullable), body, created_at. Comentarios humano-a-humano por card; distintos de `card_events` (sistema) y `/api/chat` (LLM global).
### API REST
| Metodo | Path | Cuerpo |
|---|---|---|
| GET | `/api/board` | — (retorna `{columns, cards}`, cada card incluye `time_in_column_ms`) |
| POST | `/api/columns` | `{name}` |
| PATCH | `/api/columns/{id}` | `{name?, position?}` |
| DELETE | `/api/columns/{id}` | — (cascade a cards) |
| POST | `/api/columns/reorder` | `{ids: [...]}` |
| POST | `/api/cards` | `{column_id, title, description?}` |
| PATCH | `/api/cards/{id}` | `{title?, description?}` |
| DELETE | `/api/cards/{id}` | — |
| POST | `/api/cards/{id}/move` | `{column_id, ordered_ids: [...]}` |
| POST | `/api/cards/{id}/duplicate` | — (clona la card en la misma columna al final; copia titulo+" (copia)", descripcion, color, requester, assignee, tags, stickers, deadline; NO copia historial ni mensajes) |
| GET | `/api/cards/{id}/messages` | — (lista de comentarios humano-a-humano de la card) |
| POST | `/api/cards/{id}/messages` | `{body}` (crea comentario; author = usuario de la sesion) |
| DELETE | `/api/cards/{cid}/messages/{mid}` | — (solo el autor puede borrar su mensaje) |
| GET | `/api/cards/{id}/history` | — (timeline con duraciones por columna) |
| GET | `/api/flags` | — (retorna `{ <name>: bool }` con los feature flags efectivos en esta instancia) |
| POST | `/api/auth/register` | `{username, password, display_name?}` (devuelve 403 `registration_disabled` si el flag `registration-enabled` esta en `false`) |
### Feature flags
`dev/feature_flags.json` (lado del repo) define los flags por instancia. Se cargan al arrancar (override con `--flags <path>`); fichero ausente equivale a "todos los flags en `false`". El endpoint `GET /api/flags` expone el estado actual para que el frontend oculte UI condicional (ej. el toggle de "Registrate" en `LoginPage` solo aparece cuando `registration-enabled` es `true`).
| Flag | Default | Efecto cuando esta en `true` |
|---|---|---|
| `registration-enabled` | `false` | Permite crear cuentas nuevas via `POST /api/auth/register` y muestra el toggle "Registrate" en la pantalla de login. |
### Frontend
- **dnd-kit** (`@dnd-kit/core` + `@dnd-kit/sortable`) para drag-and-drop entre y dentro de columnas (multi-container).
- **Mantine v9** + `@tabler/icons-react` para UI.
- **Modales** con `@mantine/modals` (confirmacion borrado, history timeline).
- Time-in-column live: `time_in_column_ms` del backend + tick local cada segundo para que el badge se actualice sin reload.
- DnD con `closestCorners` + `DragOverlay` para feedback visual al arrastrar.
- **Auto-refresh:** el board se recarga cada 30s (`api.getBoard`) sin interaccion del usuario; equivalente a pulsar el boton de refresco. El tick de 1s del time-in-column es independiente y no toca red.
- **Modal de card en dos columnas** (`CardEditPanel`): izquierda mantiene `CardForm` (titulo, solicitante, descripcion, asignacion, tags); derecha es un `Tabs` con `Chat` (por defecto) | `Enlaces` | `Archivos` (proximamente). Tamaño del modal: 85% del viewport.
- **Chat per-card** (`CardChatPanel`): lista de comentarios humano-a-humano persistidos en `card_messages`. Enter envia, Shift+Enter salto de linea. Solo el autor puede borrar su propio mensaje.
- **Enlaces** (`CardLinksPanel`): extrae URLs (`https?://...`) de titulo, descripcion y cuerpo de cada mensaje del chat. Deduplica, muestra hostname + URL completa + badge de origen. Click abre en pestaña nueva (`target="_blank"`).
- **Duplicar card:** click derecho sobre la card abre el menu contextual (mismo que el boton `⋮`), donde aparece el item "Duplicar". Al pulsarlo invoca `POST /api/cards/{id}/duplicate`. La copia se inserta al final de la misma columna con titulo + " (copia)".
- **Sesion obligatoria para chat:** `POST/DELETE /api/cards/{id}/messages` exige sesion activa (401 si falta). `author_id` siempre poblado; no hay comentarios anonimos.
- **Archivos (proximamente):** blobs persistidos en SQLite (`card_attachments` con `BLOB`), no en filesystem.
### Build
```bash
cd frontend && pnpm install && pnpm build
cd .. && CGO_ENABLED=1 go build -tags fts5 -o kanban .
./kanban --port 8095 --db kanban.db
# Browser: http://localhost:8095
```
### Dev (frontend con HMR contra backend)
```bash
# Terminal 1
./kanban --port 8095 --db kanban.db
# Terminal 2
cd frontend && pnpm dev
# Browser: http://localhost:5180 (vite proxy /api → 8095)
```
## Notas
- Puerto por defecto 8095.
- DB por defecto `kanban.db` en cwd.
- IDs de columnas y tarjetas: 16 chars hex (8 bytes random) via `random_hex_id_go_core`.
- El historial conserva la cronologia exacta — incluso despues de cerrar y reabrir el server, los tiempos vivos siguen contando desde `entered_at`.
- El borrado de columna hace CASCADE: las tarjetas se borran y su historial tambien. Si se quiere preservar el historial al borrar, deberia archivarse en lugar de borrar.
## Capability growth log
Una linea por bump SemVer. Bump-type segun `.claude/commands/version.md`:
- `major`: breaking observable (CLI args, schema BBDD propia, formato wire).
- `minor`: feature aditiva (nuevo panel, endpoint, opcion).
- `patch`: bugfix sin cambio observable.
- v0.1.0 (2026-05-18) — baseline.
- v0.3.1 (2026-05-21) — patch: debounce board.invalidated (300ms trailing) + autoClose 4s en toasts de notification.created. Fix de blow-up de memoria en navegador por ráfagas de SSE.
- v0.4.0 (2026-05-22) — minor: endpoint MCP Streamable HTTP `/mcp` con per-user bearer tokens (tabla `mcp_tokens`, migration 016). Modal "MCP tokens" en avatar menu para generar/listar/revocar. Vite proxy enruta `/mcp` a WSL. Usa nueva funcion `mcp_server_http_go_infra`. Doc en `docs/MCP.md`.
Reference in New Issue View Git Blame Copy Permalink