Egutierrez
1f93e9d502
Cada projects/<name>/ es ahora su propio repo Gitea con branch master, versionando solo sus docs de nivel-project. apps/*/ y analysis/*/ siguen como sub-repos hijos independientes (excluidos por el .gitignore del project). /full-git-push|pull los manejan via discover_git_repos. Cierra el gap de docs de nivel-project sin versionar. Aplicado a web_scraping, fn_monitoring, message_bus.
106 lines
4.7 KiB
Markdown
106 lines
4.7 KiB
Markdown
## Projects: apps, analysis y vaults bajo un tema comun
|
|
|
|
Un project agrupa apps, analyses y vaults relacionados. Vive en `projects/{nombre}/` con esta estructura:
|
|
|
|
```
|
|
projects/{nombre}/
|
|
project.md # Frontmatter obligatorio (name, description, tags)
|
|
apps/ # Apps del proyecto (cada una con app.md)
|
|
{app_name}/
|
|
app.md
|
|
...
|
|
analysis/ # Analyses del proyecto (cada uno con analysis.md)
|
|
{analysis_name}/
|
|
analysis.md
|
|
.venv/
|
|
notebooks/
|
|
run-jupyter-lab.sh
|
|
...
|
|
vaults/ # Datos del proyecto
|
|
vault.yaml # Manifest de vaults (nombre, descripcion, path, tags)
|
|
{vault_name} -> /abs/path # Symlinks a directorios reales de datos
|
|
```
|
|
|
|
### Reglas
|
|
|
|
- `project.md` sigue el template de `docs/templates/project.md` — campos: `name`, `description`, `tags`, `repo_url`
|
|
- `analysis.md` sigue el template de `docs/templates/analysis.md` — `dir_path` debe apuntar a `projects/{nombre}/analysis/{tema}/`
|
|
- `vault.yaml` lista los vaults con nombre, descripcion, path absoluto y tags
|
|
- Los vaults reales viven fuera del repo (ej: `~/vaults/{nombre}/`) con symlinks en el proyecto
|
|
- `fn index` escanea `projects/*/` y setea `project_id` automaticamente en apps, analyses y vaults
|
|
|
|
### Cada project es su propio repo Gitea (sub-repo)
|
|
|
|
Desde 2026-06-05 cada `projects/<nombre>/` es un **repo Gitea independiente** `dataforge/<nombre>` (branch `master`), igual que las apps y los analyses. El repo del project versiona **solo las docs de nivel-project** (`project.md`, `CONVENTIONS.md` y demás `.md`/`.claude/` propios del project). El contenido de los hijos NO se versiona aquí: cada `apps/<app>/` y cada `analysis/<a>/` es su propio sub-repo Gitea y queda excluido por el `.gitignore` del project:
|
|
|
|
```gitignore
|
|
apps/*/
|
|
analysis/*/
|
|
vaults/*
|
|
!vaults/.gitkeep
|
|
```
|
|
|
|
- **Crear el repo del project**: `ensure_repo_synced_bash_infra projects/<nombre> dataforge <nombre> master "init: project <nombre>"` (necesita `GITEA_URL` + `GITEA_TOKEN`; el token está en `pass gitea/dataforge-git-token`). Crear el `.gitignore` de arriba ANTES, para no trackear el contenido de los sub-repos hijos.
|
|
- **Push/pull**: `/full-git-push` y `/full-git-pull` ya lo manejan automáticamente — `discover_git_repos_bash_infra` descubre cualquier `.git` bajo `fn_registry`, incluidos los projects.
|
|
- **`repo_url`** en `project.md` apunta al repo del project; los `repo_url` de cada app viven en su `app.md`. Así el project "referencia" sus sub-repos sin git submodules (KISS).
|
|
- El repo padre `fn_registry` sigue ignorando `projects/*/` entero (regla `apps_subrepo.md`): nunca trackea contenido de projects.
|
|
- Estado actual: `dataforge/web_scraping`, `dataforge/fn_monitoring`, `dataforge/message_bus`.
|
|
- Apps y analyses sueltos (sin proyecto) siguen en `apps/` y `analysis/` en la raiz
|
|
|
|
### Raiz vs proyecto
|
|
|
|
| Ubicacion | Para que |
|
|
|-----------|---------|
|
|
| `apps/` | Apps independientes que no pertenecen a ningun proyecto |
|
|
| `analysis/` | Analyses independientes |
|
|
| `projects/{nombre}/apps/` | Apps de un proyecto — `project_id` se setea automaticamente |
|
|
| `projects/{nombre}/analysis/` | Analyses de un proyecto — `project_id` se setea automaticamente |
|
|
|
|
### Crear un proyecto nuevo
|
|
|
|
```bash
|
|
# 1. Crear estructura
|
|
mkdir -p projects/{nombre}/{apps,analysis,vaults}
|
|
|
|
# 2. Crear project.md con frontmatter
|
|
fn add -k project # genera template
|
|
|
|
# 3. Crear vault (datos fuera del repo, symlink dentro)
|
|
mkdir -p ~/vaults/{vault_name}/{raw,processed,exports}
|
|
ln -s ~/vaults/{vault_name} projects/{nombre}/vaults/{vault_name}
|
|
# Crear vault.yaml con la entrada
|
|
|
|
# 4. Crear analysis dentro del proyecto (un solo comando; ya indexa)
|
|
fn run init_jupyter_analysis --project {nombre} {nombre_analysis} --desc "..." [paquetes...]
|
|
|
|
# 5. Verificar
|
|
fn show {nombre} # verifica el project y sus componentes
|
|
|
|
# NUNCA: crear el analisis en analysis/ y luego mv al proyecto.
|
|
# Al mover se rompe el .venv (paths hardcodeados en activate).
|
|
# Si ya te paso: cd projects/{nombre}/analysis/{tema} && rm -rf .venv && uv sync
|
|
```
|
|
|
|
### Consultas utiles
|
|
|
|
```sql
|
|
-- Listar proyectos
|
|
SELECT id, description FROM projects;
|
|
|
|
-- Analysis de un proyecto
|
|
SELECT id, name, dir_path FROM analysis WHERE project_id = 'app_turismo';
|
|
|
|
-- Vaults de un proyecto
|
|
SELECT id, name, path, symlink FROM vaults WHERE project_id = 'app_turismo';
|
|
|
|
-- Apps de un proyecto
|
|
SELECT id, name, dir_path FROM apps WHERE project_id = 'app_turismo';
|
|
|
|
-- Todo lo que pertenece a un proyecto
|
|
SELECT 'analysis' as tipo, id, name FROM analysis WHERE project_id = ?
|
|
UNION ALL
|
|
SELECT 'vault', id, name FROM vaults WHERE project_id = ?
|
|
UNION ALL
|
|
SELECT 'app', id, name FROM apps WHERE project_id = ?;
|
|
```
|