diagram-db 0.2.0__tar.gz

diagram_db-0.2.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+Formato basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/).
+El proyecto usa [versionado semántico](https://semver.org/lang/es/).
+
+## [0.2.0] — 2026-10-29
+
+Primera versión distribuible como paquete de Python.
+
+### Añadido
+
+- Paquete instalable con `pip install diagram-db` y el comando `diagram-db`.
+- Landing pública en <https://jeironpro.github.io/diagram-db/> con un
+  playground que ejecuta el analizador real en el navegador.
+- `import graphviz` deja de ser obligatorio: sin el paquete se pueden exportar
+  `--format dot` y `--format json`, y solo el render de imagen falla con un
+  mensaje claro.
+- Publicación automática en PyPI al empujar un tag `v*`, con verificación
+  posterior de la versión publicada.
+
+## [0.1.0] — 2026-10-21
+
+### Añadido
+
+- Lectura de specs markdown con entidades, campos y modificadores `PK`, `UK`,
+  `FK -> tabla.columna`, `not null` y `null`.
+- Cardinalidades inferidas del FK y sección opcional `## Relaciones` con
+  atajos `1:1`, `1:N` y `N:M`.
+- Validación con diagnósticos `E0xx` y avisos `W0xx`, código de salida por
+  severidad.
+- Render SVG y PNG con Graphviz: tablas con insignias, pata de cuervo y
+  etiquetas con el campo y la cardinalidad.
+- Export `--format dot` y `--format json`, `--rankdir`, `--check` y
+  `--allow-no-pk`.

diagram_db-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jeironpro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

diagram_db-0.2.0/MANIFEST.in

@@ -0,0 +1,10 @@
+# Archivos que entran al sdist; el wheel solo lleva el paquete y sus metadatos.
+include LICENSE
+include CHANGELOG.md
+recursive-include examples *.md
+
+# Fuera del sdist: tests, landing y configuración de CI
+prune tests
+prune landing
+prune docs
+prune .github

diagram_db-0.2.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: diagram-db
+Version: 0.2.0
+Summary: Genera diagramas entidad-relación con pata de cuervo a partir de un spec.md
+Author: jeironpro
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jeironpro/diagram-db
+Project-URL: Documentation, https://jeironpro.github.io/diagram-db/
+Project-URL: Repository, https://github.com/jeironpro/diagram-db
+Project-URL: Issues, https://github.com/jeironpro/diagram-db/issues
+Project-URL: Changelog, https://github.com/jeironpro/diagram-db/blob/main/CHANGELOG.md
+Keywords: diagram,entity-relationship,erd,graphviz,markdown,schema,sql
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: graphviz<1.0,>=0.21
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Dynamic: license-file
+
+# diagram-db
+
+Genera diagramas entidad-relación a partir de un `spec.md` en markdown.
+
+Las entidades, sus campos y las claves PK/FK se declaran en el spec; la
+herramienta valida el modelo (referencias, tipos, claves) y produce un diagrama
+con pata de cuervo en SVG o PNG usando Graphviz. Sin base de datos, sin ORM y
+sin servicios externos.
+
+- Landing y [playground](https://jeironpro.github.io/diagram-db/) que ejecuta el
+  analizador real en el navegador.
+- Paquete en [PyPI](https://pypi.org/project/diagram-db/).
+
+## Requisitos
+
+- Python 3.10 o superior.
+- Graphviz con el binario `dot` (`dnf install graphviz` / `apt install graphviz`).
+
+## Instalación
+
+```bash
+pip install diagram-db
+```
+
+Para trabajar sobre el código, con el entorno virtual del repo:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+.venv/bin/pip install -e .
+```
+
+En los dos casos queda disponible el comando `diagram-db` y también
+`python -m diagram_db`. Si falta el paquete `graphviz`, los formatos `dot` y
+`json` siguen funcionando; solo la generación de imágenes falla con un mensaje
+claro.
+
+## Uso
+
+```bash
+diagram-db examples/tienda.spec.md -o salida/
+# escribe salida/tienda.svg
+```
+
+| Opción | Efecto |
+|---|---|
+| `-o, --output` | Directorio de salida, o archivo `.svg`/`.png` si se pide un solo formato |
+| `--format` | `svg` (por defecto), `png`, `dot` o `json`; se combinan con comas |
+| `--rankdir` | `TB` (por defecto), `LR`, `BT` o `RL` |
+| `--check` | Solo valida el spec, sin escribir archivos |
+| `--allow-no-pk` | Una entidad sin PK pasa de error a aviso |
+| `--quiet` | Oculta avisos y mensajes de éxito |
+
+Códigos de salida: `0` correcto, `1` errores en el spec, `2` error de uso.
+
+## Formato del spec
+
+```markdown
+# Esquema: Tienda
+
+## Entidades
+
+### users
+- id: int PK
+- email: varchar(255) UK, not null
+- manager_id: int FK -> users.id, null
+
+### products
+- id: int PK
+- sku: varchar(40) UK, not null
+- price: decimal(10,2), not null
+
+### orders
+- id: int PK
+- user_id: int FK -> users.id, not null
+- total: decimal(10,2), not null
+
+### order_items
+- order_id: int PK, FK -> orders.id
+- product_id: int PK, FK -> products.id
+- qty: int, not null
+```
+
+Reglas:
+
+- `## Entidades` es obligatoria; lo que haya antes se ignora y el `# Título` se
+  usa como título del diagrama.
+- Cada entidad es un `### nombre`. Los nombres con punto (por ejemplo
+  `sales.order`) se encierran en comillas invertidas dentro del encabezado.
+- Cada campo es `- nombre: tipo` seguido de modificadores opcionales, en
+  cualquier orden y separados por comas o espacios.
+- Las comas dentro de paréntesis no separan modificadores: `decimal(10,2)` se
+  conserva como un solo tipo.
+- Los bloques de código y los comentarios `<!-- ... -->` se ignoran.
+- Un campo es anulable por defecto; una PK siempre es obligatoria.
+
+### Modificadores
+
+| Modificador | Alias | Efecto |
+|---|---|---|
+| `PK` | `pk` | Clave primaria; varias líneas forman una PK compuesta |
+| `UK` | `uk`, `unique` | Clave única |
+| `FK -> tabla.columna` | `fk` | Clave foránea; la columna es opcional si la PK destino es simple |
+| `not null` | `nn` | Campo obligatorio |
+| `null` | `nullable` | Fuerza la nulabilidad |
+
+### Cardinalidades
+
+Se infieren del propio FK: si el campo es anulable el padre es opcional, y si
+es `UK` la relación es 1:1. Una entidad cuya PK se compone solo de FK se dibuja
+como tabla puente y sus aristas se etiquetan `N:M`.
+
+Para sobrescribir una arista concreta, usa la sección opcional `## Relaciones`:
+
+```markdown
+## Relaciones
+
+- users.manager_id: 0..1:N "reporta a"
+- orders.user_id: 1:N "realiza"
+```
+
+- `1:1`, `1:N` y `N:M` son atajos; la forma explícita es `<padre>:<hijo>`, con
+  `1` o `0..1` en el padre y `1`, `0..1`, `N`, `0..N` o `1..N` en el hijo.
+- El texto entre comillas reemplaza el nombre del campo en la etiqueta; la
+  cardinalidad se sigue mostrando (`reporta a  0..1:N`).
+
+## Cómo leer el diagrama
+
+- Cabecera con el nombre de la entidad y un filete terracota debajo; el
+  filete se vuelve rojizo si la entidad no declara PK.
+- Insignias por columna: `PK`, `FK`, `UK`, combinables.
+- `?` al final del tipo indica que el campo es anulable.
+- Cada arista va del padre al hijo con el nombre del campo y su cardinalidad
+  al lado del punto medio, sin tapar la línea; las puntas terminan en el borde
+  de la tabla.
+- Marcadores: `teetee` (doble barra) = exactamente uno, `odottee` (círculo y
+  barra) = cero o uno, `crow` = cero o muchos, `crowtee` = uno o muchos.
+
+## Diagnósticos
+
+Cada problema se informa como `archivo:línea: CÓDIGO mensaje` por stderr. Los
+errores impiden generar el diagrama; los avisos no.
+
+| Código | Tipo | Cuándo aparece |
+|---|---|---|
+| E000 | error | Falta `## Entidades` |
+| E001 | error | Entidad duplicada |
+| E002 | error | Campo duplicado en la misma entidad |
+| E003 | error | Entidad sin campos |
+| E004 | error | FK a una entidad inexistente |
+| E005 | error | FK a una columna inexistente |
+| E006 | error | FK sin columna y la PK destino no es simple |
+| E007 | error | Entidad sin PK |
+| E008 | error | Línea no reconocida dentro de `## Entidades` |
+| E009 | error | Nombre de entidad no válido |
+| E010 | error | Nombre de campo no válido |
+| E011 | error | Línea de campo sin `:` |
+| E012 | error | Campo sin tipo |
+| E013 | error | Modificador no reconocido |
+| E020 | error | Línea de `## Relaciones` mal formada |
+| E021 | error | La relación apunta a una entidad o campo inexistente |
+| E022 | error | La relación apunta a un campo que no es FK |
+| E023 | error | Cardinalidad no válida |
+| E024 | error | Relación duplicada para el mismo FK |
+| W001 | aviso | FK a una columna que no es PK ni UK |
+| W002 | aviso | Tipo del FK distinto del tipo destino |
+| W003 | aviso | Campo `PK` declarado como `null` (gana `PK`) |
+| W004 | aviso | Entidad sin PK con `--allow-no-pk` |
+
+## Landing y playground
+
+La web vive en [`landing/`](landing/index.html) y se publica en GitHub Pages. Es
+HTML, CSS y JavaScript sin compilación; el playground descarga Pyodide solo
+cuando se pide el primer análisis y ejecuta el mismo paquete que instala `pip`,
+servido desde `landing/vendor/diagram_db`.
+
+La publicación es un paso manual de una sola vez: activar Pages en
+**Settings → Pages → Source: GitHub Actions** y definir la variable de
+repositorio `PAGES_ENABLED=true`. Hasta entonces el workflow queda omitido, así
+que `main` no falla mientras no esté activado.
+
+Esa copia es la fuente única del playground y CI falla si diverge. Tras tocar
+`src/diagram_db`, sincronízala:
+
+```bash
+cp src/diagram_db/*.py landing/vendor/diagram_db/
+```
+
+Para verla en local basta servir la carpeta:
+
+```bash
+python3 -m http.server 8765 --directory landing
+```
+
+## Desarrollo
+
+```bash
+.venv/bin/pip install -r test-requirements.txt
+ruff check .
+ruff format --check .
+pre-commit run --all-files
+.venv/bin/python -m pytest
+```
+
+Las dependencias se gestionan con `pip-tools` a partir de `pyproject.toml`:
+
+```bash
+pip-compile pyproject.toml -o requirements.txt
+pip-compile --extra dev pyproject.toml -o test-requirements.txt
+```
+
+CI (`.github/workflows/ci.yml`) corre Ruff, comprueba que la copia del playground
+no diverja, pasa pytest en Python 3.10–3.13, construye el sdist y el wheel,
+valida los metadatos con `twine check --strict` y prueba el wheel instalado en un
+entorno limpio.
+
+El release sale por tag `v*`: `.github/workflows/release.yml` corre los tests,
+crea el GitHub Release con los artefactos, publica en PyPI con trusted
+publishing (OIDC, sin tokens) y verifica que la versión instalada genera un
+diagrama.
+
+La landing se publica con `.github/workflows/pages.yml`, que queda omitido hasta
+que Pages esté activado en el repositorio y la variable `PAGES_ENABLED` valga
+`true`.
+
+## Publicación
+
+La versión vive en `diagram_db.__version__` y `pyproject.toml` la lee de ahí, así
+que un release es un tag:
+
+```bash
+git tag v0.2.0 && git push origin v0.2.0
+```
+
+El workflow de release corre los tests, crea el GitHub Release con los
+artefactos, publica en PyPI con trusted publishing (OIDC, sin tokens) y verifica
+que `pip install diagram-db==<versión>` genera un diagrama. El publisher se
+configura una sola vez en <https://pypi.org/manage/account/publishing/> con el
+repositorio `jeironpro/diagram-db`, el workflow `release.yml` y el entorno
+`pypi`.
+
+## Licencia
+
+Este proyecto está bajo la licencia **MIT**. Consulta el archivo
+[LICENSE](LICENSE) para más detalles.

diagram_db-0.2.0/README.md

@@ -0,0 +1,245 @@
+# diagram-db
+
+Genera diagramas entidad-relación a partir de un `spec.md` en markdown.
+
+Las entidades, sus campos y las claves PK/FK se declaran en el spec; la
+herramienta valida el modelo (referencias, tipos, claves) y produce un diagrama
+con pata de cuervo en SVG o PNG usando Graphviz. Sin base de datos, sin ORM y
+sin servicios externos.
+
+- Landing y [playground](https://jeironpro.github.io/diagram-db/) que ejecuta el
+  analizador real en el navegador.
+- Paquete en [PyPI](https://pypi.org/project/diagram-db/).
+
+## Requisitos
+
+- Python 3.10 o superior.
+- Graphviz con el binario `dot` (`dnf install graphviz` / `apt install graphviz`).
+
+## Instalación
+
+```bash
+pip install diagram-db
+```
+
+Para trabajar sobre el código, con el entorno virtual del repo:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+.venv/bin/pip install -e .
+```
+
+En los dos casos queda disponible el comando `diagram-db` y también
+`python -m diagram_db`. Si falta el paquete `graphviz`, los formatos `dot` y
+`json` siguen funcionando; solo la generación de imágenes falla con un mensaje
+claro.
+
+## Uso
+
+```bash
+diagram-db examples/tienda.spec.md -o salida/
+# escribe salida/tienda.svg
+```
+
+| Opción | Efecto |
+|---|---|
+| `-o, --output` | Directorio de salida, o archivo `.svg`/`.png` si se pide un solo formato |
+| `--format` | `svg` (por defecto), `png`, `dot` o `json`; se combinan con comas |
+| `--rankdir` | `TB` (por defecto), `LR`, `BT` o `RL` |
+| `--check` | Solo valida el spec, sin escribir archivos |
+| `--allow-no-pk` | Una entidad sin PK pasa de error a aviso |
+| `--quiet` | Oculta avisos y mensajes de éxito |
+
+Códigos de salida: `0` correcto, `1` errores en el spec, `2` error de uso.
+
+## Formato del spec
+
+```markdown
+# Esquema: Tienda
+
+## Entidades
+
+### users
+- id: int PK
+- email: varchar(255) UK, not null
+- manager_id: int FK -> users.id, null
+
+### products
+- id: int PK
+- sku: varchar(40) UK, not null
+- price: decimal(10,2), not null
+
+### orders
+- id: int PK
+- user_id: int FK -> users.id, not null
+- total: decimal(10,2), not null
+
+### order_items
+- order_id: int PK, FK -> orders.id
+- product_id: int PK, FK -> products.id
+- qty: int, not null
+```
+
+Reglas:
+
+- `## Entidades` es obligatoria; lo que haya antes se ignora y el `# Título` se
+  usa como título del diagrama.
+- Cada entidad es un `### nombre`. Los nombres con punto (por ejemplo
+  `sales.order`) se encierran en comillas invertidas dentro del encabezado.
+- Cada campo es `- nombre: tipo` seguido de modificadores opcionales, en
+  cualquier orden y separados por comas o espacios.
+- Las comas dentro de paréntesis no separan modificadores: `decimal(10,2)` se
+  conserva como un solo tipo.
+- Los bloques de código y los comentarios `<!-- ... -->` se ignoran.
+- Un campo es anulable por defecto; una PK siempre es obligatoria.
+
+### Modificadores
+
+| Modificador | Alias | Efecto |
+|---|---|---|
+| `PK` | `pk` | Clave primaria; varias líneas forman una PK compuesta |
+| `UK` | `uk`, `unique` | Clave única |
+| `FK -> tabla.columna` | `fk` | Clave foránea; la columna es opcional si la PK destino es simple |
+| `not null` | `nn` | Campo obligatorio |
+| `null` | `nullable` | Fuerza la nulabilidad |
+
+### Cardinalidades
+
+Se infieren del propio FK: si el campo es anulable el padre es opcional, y si
+es `UK` la relación es 1:1. Una entidad cuya PK se compone solo de FK se dibuja
+como tabla puente y sus aristas se etiquetan `N:M`.
+
+Para sobrescribir una arista concreta, usa la sección opcional `## Relaciones`:
+
+```markdown
+## Relaciones
+
+- users.manager_id: 0..1:N "reporta a"
+- orders.user_id: 1:N "realiza"
+```
+
+- `1:1`, `1:N` y `N:M` son atajos; la forma explícita es `<padre>:<hijo>`, con
+  `1` o `0..1` en el padre y `1`, `0..1`, `N`, `0..N` o `1..N` en el hijo.
+- El texto entre comillas reemplaza el nombre del campo en la etiqueta; la
+  cardinalidad se sigue mostrando (`reporta a  0..1:N`).
+
+## Cómo leer el diagrama
+
+- Cabecera con el nombre de la entidad y un filete terracota debajo; el
+  filete se vuelve rojizo si la entidad no declara PK.
+- Insignias por columna: `PK`, `FK`, `UK`, combinables.
+- `?` al final del tipo indica que el campo es anulable.
+- Cada arista va del padre al hijo con el nombre del campo y su cardinalidad
+  al lado del punto medio, sin tapar la línea; las puntas terminan en el borde
+  de la tabla.
+- Marcadores: `teetee` (doble barra) = exactamente uno, `odottee` (círculo y
+  barra) = cero o uno, `crow` = cero o muchos, `crowtee` = uno o muchos.
+
+## Diagnósticos
+
+Cada problema se informa como `archivo:línea: CÓDIGO mensaje` por stderr. Los
+errores impiden generar el diagrama; los avisos no.
+
+| Código | Tipo | Cuándo aparece |
+|---|---|---|
+| E000 | error | Falta `## Entidades` |
+| E001 | error | Entidad duplicada |
+| E002 | error | Campo duplicado en la misma entidad |
+| E003 | error | Entidad sin campos |
+| E004 | error | FK a una entidad inexistente |
+| E005 | error | FK a una columna inexistente |
+| E006 | error | FK sin columna y la PK destino no es simple |
+| E007 | error | Entidad sin PK |
+| E008 | error | Línea no reconocida dentro de `## Entidades` |
+| E009 | error | Nombre de entidad no válido |
+| E010 | error | Nombre de campo no válido |
+| E011 | error | Línea de campo sin `:` |
+| E012 | error | Campo sin tipo |
+| E013 | error | Modificador no reconocido |
+| E020 | error | Línea de `## Relaciones` mal formada |
+| E021 | error | La relación apunta a una entidad o campo inexistente |
+| E022 | error | La relación apunta a un campo que no es FK |
+| E023 | error | Cardinalidad no válida |
+| E024 | error | Relación duplicada para el mismo FK |
+| W001 | aviso | FK a una columna que no es PK ni UK |
+| W002 | aviso | Tipo del FK distinto del tipo destino |
+| W003 | aviso | Campo `PK` declarado como `null` (gana `PK`) |
+| W004 | aviso | Entidad sin PK con `--allow-no-pk` |
+
+## Landing y playground
+
+La web vive en [`landing/`](landing/index.html) y se publica en GitHub Pages. Es
+HTML, CSS y JavaScript sin compilación; el playground descarga Pyodide solo
+cuando se pide el primer análisis y ejecuta el mismo paquete que instala `pip`,
+servido desde `landing/vendor/diagram_db`.
+
+La publicación es un paso manual de una sola vez: activar Pages en
+**Settings → Pages → Source: GitHub Actions** y definir la variable de
+repositorio `PAGES_ENABLED=true`. Hasta entonces el workflow queda omitido, así
+que `main` no falla mientras no esté activado.
+
+Esa copia es la fuente única del playground y CI falla si diverge. Tras tocar
+`src/diagram_db`, sincronízala:
+
+```bash
+cp src/diagram_db/*.py landing/vendor/diagram_db/
+```
+
+Para verla en local basta servir la carpeta:
+
+```bash
+python3 -m http.server 8765 --directory landing
+```
+
+## Desarrollo
+
+```bash
+.venv/bin/pip install -r test-requirements.txt
+ruff check .
+ruff format --check .
+pre-commit run --all-files
+.venv/bin/python -m pytest
+```
+
+Las dependencias se gestionan con `pip-tools` a partir de `pyproject.toml`:
+
+```bash
+pip-compile pyproject.toml -o requirements.txt
+pip-compile --extra dev pyproject.toml -o test-requirements.txt
+```
+
+CI (`.github/workflows/ci.yml`) corre Ruff, comprueba que la copia del playground
+no diverja, pasa pytest en Python 3.10–3.13, construye el sdist y el wheel,
+valida los metadatos con `twine check --strict` y prueba el wheel instalado en un
+entorno limpio.
+
+El release sale por tag `v*`: `.github/workflows/release.yml` corre los tests,
+crea el GitHub Release con los artefactos, publica en PyPI con trusted
+publishing (OIDC, sin tokens) y verifica que la versión instalada genera un
+diagrama.
+
+La landing se publica con `.github/workflows/pages.yml`, que queda omitido hasta
+que Pages esté activado en el repositorio y la variable `PAGES_ENABLED` valga
+`true`.
+
+## Publicación
+
+La versión vive en `diagram_db.__version__` y `pyproject.toml` la lee de ahí, así
+que un release es un tag:
+
+```bash
+git tag v0.2.0 && git push origin v0.2.0
+```
+
+El workflow de release corre los tests, crea el GitHub Release con los
+artefactos, publica en PyPI con trusted publishing (OIDC, sin tokens) y verifica
+que `pip install diagram-db==<versión>` genera un diagrama. El publisher se
+configura una sola vez en <https://pypi.org/manage/account/publishing/> con el
+repositorio `jeironpro/diagram-db`, el workflow `release.yml` y el entorno
+`pypi`.
+
+## Licencia
+
+Este proyecto está bajo la licencia **MIT**. Consulta el archivo
+[LICENSE](LICENSE) para más detalles.

diagram_db-0.2.0/examples/biblioteca.spec.md

@@ -0,0 +1,36 @@
+# Esquema: Biblioteca
+
+Catálogo mínimo: quién escribe, qué se presta y quién lo recibe.
+
+## Entidades
+
+### autores
+- id: int PK
+- nombre: varchar(120), not null
+- pais: varchar(60)
+
+### libros
+- id: int PK
+- autor_id: int FK -> autores.id, not null
+- titulo: varchar(200), not null
+- isbn: varchar(20) UK, not null
+- anio: int, not null
+
+### socios
+- id: int PK
+- nombre: varchar(120), not null
+- correo: varchar(150) UK, not null
+- alta: date, not null
+
+### prestamos
+- id: int PK
+- libro_id: int FK -> libros.id, not null
+- socio_id: int FK -> socios.id, not null
+- retirado: date, not null
+- devuelto: date
+
+## Relaciones
+
+- libros.autor_id: 1:N "escribe"
+- prestamos.libro_id: 1:N "presta"
+- prestamos.socio_id: 1:N "recibe"

diagram_db-0.2.0/examples/prestamos_taveras.spec.md

@@ -0,0 +1,71 @@
+# Esquema: Préstamos Taveras
+
+Sistema de préstamos semanales. Lo que está fuera de `## Entidades` no se
+interpreta: sirve para documentar decisiones del modelo.
+
+Convenciones:
+
+- `uuid` es un hash SHA-256 en hexadecimal (64 caracteres) y actúa como clave
+  pública de cada tabla; `id` es la clave primaria interna.
+- `pagos.empleado_id` referencia a un usuario con rol EMPLEADO. El diagrama no
+  puede expresar ese filtro: la columna guarda el id, no el rol.
+
+## Entidades
+
+### usuarios
+- id: int PK
+- uuid: char(64) UK, not null
+- rol: enum(ADMIN, CLIENTE, EMPLEADO), not null
+- nombre: varchar(100), not null
+- apellidos: varchar(100), not null
+- cedula: varchar(20) UK, not null
+- correo: varchar(150) UK, not null
+- contrasena: varchar(255), not null
+- telefono: varchar(20)
+- direccion: varchar(200)
+
+### prestamos
+- id: int PK
+- uuid: char(64) UK, not null
+- usuario_id: int FK -> usuarios.id, not null
+- monto: decimal(12,2), not null
+- monto_cuota: decimal(12,2), not null
+- monto_mora: decimal(12,2), not null
+- cantidad_semanas: int, not null
+- dia_pago: enum(LUNES, MARTES, MIERCOLES, JUEVES, VIERNES, SABADO, DOMINGO), not null
+
+### semanas_prestamo
+- id: int PK
+- uuid: char(64) UK, not null
+- prestamo_id: int FK -> prestamos.id, not null
+- numero_semana: int, not null
+- monto: decimal(12,2), not null
+- estado: enum(PAGADA, PENDIENTE, CANCELADA), not null
+- fecha: date, not null
+
+### pagos
+- id: int PK
+- uuid: char(64) UK, not null
+- semanas_prestamo_id: int FK -> semanas_prestamo.id, not null
+- monto: decimal(12,2), not null
+- fecha: date, not null
+- tipo: enum(CUOTA, MORA, AMBOS), not null
+- metodo_pago: enum(EFECTIVO, TRANSFERENCIA), not null
+- empleado_id: int FK -> usuarios.id, not null
+
+### moras
+- id: int PK
+- uuid: char(64) UK, not null
+- semanas_prestamo_id: int FK -> semanas_prestamo.id, not null
+- monto: decimal(12,2), not null
+- fecha: date, not null
+- estado: enum(PAGADA, PENDIENTE, CANCELADA), not null
+- metodo_pago: enum(EFECTIVO, TRANSFERENCIA)
+
+## Relaciones
+
+- prestamos.usuario_id: 1:N "solicita"
+- semanas_prestamo.prestamo_id: 1:N "tiene"
+- pagos.semanas_prestamo_id: 1:N "cubre"
+- moras.semanas_prestamo_id: 1:N "genera"
+- pagos.empleado_id: 1:N "registra"