```console
-$ pip install requests httpx python-jose
+$ pip install requests httpx pyjwt
$ pip freeze > requirements.txt
```
diff --git a/docs/en/contributing/development-setup.md b/docs/en/contributing/development-setup.md
index c3d74f5..17b98d3 100644
--- a/docs/en/contributing/development-setup.md
+++ b/docs/en/contributing/development-setup.md
@@ -403,7 +403,7 @@ FastAPI-fastkit/
- **`scaffolder.py`** - The generation pipeline shared by `init` and `startdemo`
- **`transducer.py`** - Template transducer
- **`core/`** - Core configuration and exceptions
- - **`fragments/`** - Jinja2 fragments rendered into generated projects (see below)
+ - **`fragments/`** - Jinja2 fragments rendered into generated projects (see above)
- **`fastapi_project_template/`** - Project templates (fastapi-default, fastapi-domain-starter, etc.)
- **`utils/`** - Shared utility functions
- **`tests/`** - Test suite
diff --git a/docs/en/reference/translation-status.md b/docs/en/reference/translation-status.md
index a4115a9..555d488 100644
--- a/docs/en/reference/translation-status.md
+++ b/docs/en/reference/translation-status.md
@@ -34,19 +34,18 @@ next section explains).
| Locale | Status | Markdown pages | Notes |
|---|---|---:|---|
| 🇬🇧 English (`en`) | ✅ Source of truth | 29 / 29 | Authoritative. |
-| 🇰🇷 Korean (`ko`) | 🟡 Partial | 26 / 29 | Phases 1-3 complete. The three tutorials added in v1.4.0 (`tutorial/auth-jwt.md`, `tutorial/sqlmodel.md`, `tutorial/llm-agent.md`) are not translated yet and fall back to English. `docs/ko/changelog.md` intentionally reuses the canonical English `CHANGELOG.md`. |
-| 🇯🇵 Japanese (`ja`) | 🟡 Partial | 26 / 29 | Phases 1-3 complete. The three tutorials added in v1.4.0 (`tutorial/auth-jwt.md`, `tutorial/sqlmodel.md`, `tutorial/llm-agent.md`) are not translated yet and fall back to English. `docs/ja/changelog.md` intentionally reuses the canonical English `CHANGELOG.md`. |
-| 🇨🇳 Chinese (`zh`) | 🟡 Partial | 26 / 29 | Phases 1-3 complete. The three tutorials added in v1.4.0 (`tutorial/auth-jwt.md`, `tutorial/sqlmodel.md`, `tutorial/llm-agent.md`) are not translated yet and fall back to English. `docs/zh/changelog.md` intentionally reuses the canonical English `CHANGELOG.md`. |
-| 🇪🇸 Spanish (`es`) | 🟡 Partial | 26 / 29 | Phases 1-3 complete. The three tutorials added in v1.4.0 (`tutorial/auth-jwt.md`, `tutorial/sqlmodel.md`, `tutorial/llm-agent.md`) are not translated yet and fall back to English. `docs/es/changelog.md` intentionally reuses the canonical English `CHANGELOG.md`. |
-| 🇫🇷 French (`fr`) | 🟡 Partial | 26 / 29 | Phases 1-3 complete. The three tutorials added in v1.4.0 (`tutorial/auth-jwt.md`, `tutorial/sqlmodel.md`, `tutorial/llm-agent.md`) are not translated yet and fall back to English. `docs/fr/changelog.md` intentionally reuses the canonical English `CHANGELOG.md`. |
-| 🇩🇪 German (`de`) | 🟡 Partial | 26 / 29 | Phases 1-3 complete. The three tutorials added in v1.4.0 (`tutorial/auth-jwt.md`, `tutorial/sqlmodel.md`, `tutorial/llm-agent.md`) are not translated yet and fall back to English. `docs/de/changelog.md` intentionally reuses the canonical English `CHANGELOG.md`. |
-
-*Snapshot verified 2026-09-04, for the v1.4.0 release. English gained three
-tutorial pages (`tutorial/auth-jwt.md`, `tutorial/sqlmodel.md`,
-`tutorial/llm-agent.md`), so every other locale dropped from ✅ Complete to
-🟡 Partial at 26 / 29. The Korean landing page, CLI reference and starter
-guide were re-synced with their English sources in the same release; the
-remaining Korean pages are present but predate the v1.4.0 English updates.* These counts are maintained by hand;
+| 🇰🇷 Korean (`ko`) | ✅ Complete | 29 / 29 | Phases 1-3 complete. Re-synced with the v1.4.1 English sources on 2026-10-11: the three v1.4.0 tutorials (`tutorial/auth-jwt.md`, `tutorial/sqlmodel.md`, `tutorial/llm-agent.md`) are translated and pages that had drifted since their original translation were brought back in line. `docs/ko/changelog.md` intentionally reuses the canonical English `CHANGELOG.md`. |
+| 🇯🇵 Japanese (`ja`) | ✅ Complete | 29 / 29 | Phases 1-3 complete. Re-synced with the v1.4.1 English sources on 2026-10-11: the three v1.4.0 tutorials (`tutorial/auth-jwt.md`, `tutorial/sqlmodel.md`, `tutorial/llm-agent.md`) are translated and pages that had drifted since their original translation were brought back in line. `docs/ja/changelog.md` intentionally reuses the canonical English `CHANGELOG.md`. |
+| 🇨🇳 Chinese (`zh`) | ✅ Complete | 29 / 29 | Phases 1-3 complete. Re-synced with the v1.4.1 English sources on 2026-10-11: the three v1.4.0 tutorials (`tutorial/auth-jwt.md`, `tutorial/sqlmodel.md`, `tutorial/llm-agent.md`) are translated and pages that had drifted since their original translation were brought back in line. `docs/zh/changelog.md` intentionally reuses the canonical English `CHANGELOG.md`. |
+| 🇪🇸 Spanish (`es`) | ✅ Complete | 29 / 29 | Phases 1-3 complete. Re-synced with the v1.4.1 English sources on 2026-10-11: the three v1.4.0 tutorials (`tutorial/auth-jwt.md`, `tutorial/sqlmodel.md`, `tutorial/llm-agent.md`) are translated and pages that had drifted since their original translation were brought back in line. `docs/es/changelog.md` intentionally reuses the canonical English `CHANGELOG.md`. |
+| 🇫🇷 French (`fr`) | ✅ Complete | 29 / 29 | Phases 1-3 complete. Re-synced with the v1.4.1 English sources on 2026-10-11: the three v1.4.0 tutorials (`tutorial/auth-jwt.md`, `tutorial/sqlmodel.md`, `tutorial/llm-agent.md`) are translated and pages that had drifted since their original translation were brought back in line. `docs/fr/changelog.md` intentionally reuses the canonical English `CHANGELOG.md`. |
+| 🇩🇪 German (`de`) | ✅ Complete | 29 / 29 | Phases 1-3 complete. Re-synced with the v1.4.1 English sources on 2026-10-11: the three v1.4.0 tutorials (`tutorial/auth-jwt.md`, `tutorial/sqlmodel.md`, `tutorial/llm-agent.md`) are translated and pages that had drifted since their original translation were brought back in line. `docs/de/changelog.md` intentionally reuses the canonical English `CHANGELOG.md`. |
+
+*Snapshot verified 2026-10-11, after the v1.4.1 release. All six translated
+locales were brought to parity with the English sources: the three tutorials
+added in v1.4.0 were translated and every page that had drifted since its
+original translation was re-synced. Translations can still lag within a
+release — if a translated page disagrees with English, trust English.* These counts are maintained by hand;
to recount the current state from the repo root, run:
```console
@@ -61,6 +60,8 @@ update it (or open a PR / issue noting the drift).
Legend:
- ✅ **Source of truth** — the locale we author against.
+- ✅ **Complete** — every English page has a translated counterpart.
+ Individual pages may still lag behind an English update within a release.
- 🟡 **Partial** — some pages translated; missing pages fall back.
- 🔴 **Skeleton** — language switcher entry exists, but no translated
pages are checked in yet. The site renders English content under the
diff --git a/docs/en/tutorial/mcp-integration.md b/docs/en/tutorial/mcp-integration.md
index 3b4b9c9..c1a0f35 100644
--- a/docs/en/tutorial/mcp-integration.md
+++ b/docs/en/tutorial/mcp-integration.md
@@ -452,6 +452,7 @@ user_db = UserDatabase()
from typing import Optional, List
from fastapi import Depends, HTTPException, status, Security
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials, APIKeyHeader
+import jwt
from src.auth.jwt_handler import decode_token, token_manager
from src.auth.models import User, UserInDB, Permission, user_db
diff --git a/docs/es/contributing/development-setup.md b/docs/es/contributing/development-setup.md
index ec8e8c6..212b44d 100644
--- a/docs/es/contributing/development-setup.md
+++ b/docs/es/contributing/development-setup.md
@@ -212,6 +212,50 @@ El Makefile del proyecto incluye comandos útiles para las tareas de desarrollo
| `make inspect-templates-verbose` | Inspecciona con salida detallada |
| `make inspect-template` | Inspecciona plantillas concretas (parámetro TEMPLATES) |
+El script subyacente acepta tres flags que conviene conocer mientras iteras:
+`--offline` (omite las consultas de actualidad en PyPI), `--no-smoke` (omite
+el arranque del proyecto generado con uvicorn — el paso más lento) y `--mypy`
+(comprueba los tipos del proyecto generado; es opcional porque es lento).
+Consulta [Aseguramiento de calidad de las plantillas](../reference/template-quality-assurance.md)
+para ver qué hace realmente cada comprobación.
+
+```console
+$ python scripts/inspect-templates.py --templates fastapi-sqlmodel --offline --no-smoke
+```
+
+### El código generado vive en fragmentos Jinja2
+
+Todo lo que `fastkit init --interactive` escribe en un proyecto — `main.py`,
+los módulos de base de datos y autenticación, los archivos de Docker, la
+configuración de pytest — se renderiza a partir de plantillas en
+`src/fastapi_fastkit/fragments/`, no se ensambla a partir de cadenas en
+Python. `main.py.j2` no fija ninguna funcionalidad en el código: itera sobre
+las listas `import_fragments`, `lifespan_fragments` y `setup_fragments` que
+proporciona `DynamicConfigGenerator` e incluye cada una, de modo que las
+funcionalidades se combinan libremente.
+
+Añadir una funcionalidad consiste, a grandes rasgos, en:
+
+1. Colocar las piezas en `main/imports/`, `main/lifespan/` y/o
+ `main/setup/` (los fragmentos de lifespan van indentados con cuatro
+ espacios; los otros dos no).
+2. Registrarlas en `DynamicConfigGenerator._main_fragments()`, protegidas
+ por la consulta de configuración correspondiente.
+3. Para un módulo independiente, añadir `
/
.py.j2` y
+ renderizarlo con `self._render(...)`.
+4. Ampliar la matriz de combinaciones en
+ `tests/test_backends/test_project_builder_config_generator.py` — esta
+ comprueba que cada archivo Python renderizado se analiza con `ast.parse`.
+
+Dos restricciones con las que es fácil tropezar: cada fragmento debe terminar
+con un salto de línea final (el entorno se construye con
+`keep_trailing_newline=True`), y `main.py.j2` debe conservar sus anclas
+`# fastkit:imports` / `# fastkit:routes` — `fastkit addroute` inserta código
+en ellas.
+
+El procedimiento de referencia vive junto a los propios fragmentos, en
+[`src/fastapi_fastkit/fragments/README.md`](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/fragments/README.md).
+
### Comandos de documentación
| Comando | Descripción |
@@ -353,13 +397,16 @@ FastAPI-fastkit/
- **`src/fastapi_fastkit/`** — código fuente del paquete principal
- **`cli.py`** — punto de entrada principal de la CLI
- **`backend/`** — lógica central del backend
- - **`inspector.py`** — inspector de plantillas
+ - **`inspection/`** — pipeline de inspección de plantillas (context, checks, consistency, freshness, smoke, lint, report)
+ - **`inspector.py`** — fachada sobre `inspection/`, mantenida por la ruta de importación histórica
- **`interactive/`** — componentes del modo interactivo (prompts, selectores, validadores)
- **`package_managers/`** — implementaciones de los gestores de paquetes (pip, uv, pdm, poetry)
- - **`project_builder/`** — utilidades de construcción de proyectos
+ - **`project_builder/`** — utilidades de construcción de proyectos, incluido el generador de configuración basado en fragmentos
+ - **`scaffolder.py`** — el pipeline de generación que comparten `init` y `startdemo`
- **`transducer.py`** — transducer de plantillas
- **`core/`** — configuración central y excepciones
- - **`fastapi_project_template/`** — plantillas de proyecto (fastapi-default, fastapi-async-crud, etc.)
+ - **`fragments/`** — fragmentos Jinja2 que se renderizan en los proyectos generados (ver más arriba)
+ - **`fastapi_project_template/`** — plantillas de proyecto (fastapi-default, fastapi-domain-starter, etc.)
- **`utils/`** — funciones de utilidad compartidas
- **`tests/`** — suite de pruebas
- **`test_backends/`** — pruebas específicas del backend
diff --git a/docs/es/contributing/template-creation-guide.md b/docs/es/contributing/template-creation-guide.md
index 57cce7c..54378de 100644
--- a/docs/es/contributing/template-creation-guide.md
+++ b/docs/es/contributing/template-creation-guide.md
@@ -97,8 +97,7 @@ fastapi-{template-name}/
│ ├── lint.sh-tpl # Linting
│ ├── run-server.sh-tpl # Ejecución del servidor
│ └── test.sh-tpl # Ejecución de pruebas
-├── pyproject.toml-tpl # ✅ Metadatos primarios (PEP 621, preferido)
-├── setup.py-tpl # 🟡 Metadatos legacy (aceptados por compatibilidad)
+├── pyproject.toml-tpl # ✅ Metadatos primarios (PEP 621, obligatorio)
├── requirements.txt-tpl # 🟡 Opcional si pyproject declara dependencias
├── setup.cfg-tpl # Configuración de herramientas de desarrollo
├── README.md-tpl # ✅ Documentación del proyecto (requerida)
@@ -110,10 +109,16 @@ fastapi-{template-name}/
- Un directorio `tests/`
- `README.md-tpl`
-- Al menos un archivo de metadatos: `pyproject.toml-tpl` (preferido, PEP 621) o `setup.py-tpl` (legacy, todavía aceptado)
-- Una declaración de `fastapi` como dependencia en al menos uno de: `pyproject.toml-tpl` `[project].dependencies`, `requirements.txt-tpl`, o `setup.py-tpl` `install_requires`
+- `pyproject.toml-tpl` (PEP 621)
+- Una declaración de `fastapi` como dependencia en `pyproject.toml-tpl` `[project].dependencies` o en `requirements.txt-tpl`
-`requirements.txt-tpl` ya no es estrictamente necesario cuando `pyproject.toml-tpl` declara `[project].dependencies`. Las plantillas modernas DEBERÍAN adoptar `pyproject.toml-tpl` como su archivo de metadatos principal.
+`requirements.txt-tpl` no es necesario cuando `pyproject.toml-tpl` declara `[project].dependencies` — pero, si una plantilla incluye ambos, deben coincidir: la inspección falla si hay divergencia de dependencias entre ellos.
+
+**Las plantillas nuevas priorizan pyproject y no deben incluir `setup.py-tpl`.** Desde v1.4.0 ninguna plantilla incluida lo trae. La inspección todavía acepta el archivo para que las plantillas externas sigan funcionando, pero es una vía heredada.
+
+**Apunta a Python 3.12 de forma coherente**: `requires-python = ">=3.12"`, black `target-version = ["py312"]`, mypy `python_version = "3.12"` y `python:3.12-slim` para cualquier imagen base de Docker. La inspección comprueba que las tres versiones fijadas coinciden.
+
+**Nunca declares `FastAPI-fastkit` como dependencia de ejecución** de un proyecto generado. La CLI es una herramienta de desarrollo; la lista de dependencias de una plantilla solo debe contener lo que importa la propia aplicación generada.
### Guía de escritura de archivos
@@ -238,52 +243,23 @@ isort==5.12.0
mypy==1.7.1
```
-#### 4. Escribir setup.py-tpl (legacy — opcional si existe pyproject)
+#### 4. Anclas de rutas
-Se conserva para plantillas legacy. Las plantillas nuevas no necesitan este archivo si traen `pyproject.toml-tpl`.
+Las plantillas que incluyen un `main.py-tpl` o un módulo agregador de la API deben marcar dónde inserta código `fastkit addroute`:
```python
-"""
-Setup del paquete
+from src.app.api import health
-Proyecto creado con FastAPI-fastkit.
-"""
-from setuptools import find_packages, setup
-
-# Lista de dependencias (anotación de tipo requerida)
-install_requires: list[str] = [
- "fastapi>=0.104.0",
- "uvicorn[standard]>=0.24.0",
- "pydantic>=2.5.0",
- "pydantic-settings>=2.1.0",
- "python-dotenv>=1.0.0",
-]
+# fastkit:imports
-setup(
- name="",
- version="1.0.0",
- description="[FastAPI-fastkit templated] ", # Marcador de identidad usado por is_fastkit_project()
- long_description=open("README.md").read(),
- long_description_content_type="text/markdown",
- author="",
- author_email="",
- packages=find_packages(),
- install_requires=install_requires,
- python_requires=">=3.8",
- classifiers=[
- "Development Status :: 4 - Beta",
- "Intended Audience :: Developers",
- "License :: OSI Approved :: MIT License",
- "Programming Language :: Python :: 3",
- "Programming Language :: Python :: 3.8",
- "Programming Language :: Python :: 3.9",
- "Programming Language :: Python :: 3.10",
- "Programming Language :: Python :: 3.11",
- "Programming Language :: Python :: 3.12",
- ],
-)
+api_router = APIRouter()
+api_router.include_router(health.router)
+
+# fastkit:routes
```
+Sin las anclas, `addroute` recurre a una inserción basada en AST que localiza por sí misma el bloque de imports y los registros de routers — así que una plantilla que no las tenga sigue funcionando, pero el resultado es menos predecible. Mantén los comentarios en su sitio al editar estos archivos.
+
#### 5. Escribir los archivos de pruebas
```python
@@ -343,8 +319,17 @@ make inspect-template TEMPLATES="fastapi-your-template"
# Validar con salida detallada
python scripts/inspect-templates.py --templates "fastapi-your-template" --verbose
+
+# Ciclo local rápido: sin red, sin arrancar el servidor
+python scripts/inspect-templates.py --templates "fastapi-your-template" \
+ --offline --no-smoke
+
+# Comprobación completa antes de abrir un PR (añade mypy sobre el proyecto generado)
+python scripts/inspect-templates.py --templates "fastapi-your-template" --mypy
```
+`--offline` omite las consultas de actualidad de dependencias en PyPI, `--no-smoke` omite el arranque del proyecto generado (el paso más lento) y `--mypy` comprueba los tipos del proyecto generado. Consulta [Aseguramiento de calidad de las plantillas](../reference/template-quality-assurance.md) para ver qué hace cada comprobación.
+
!!! note
Cuando envíes un PR, el flujo de trabajo **Template PR Inspection** se ejecutará automáticamente y validará tus cambios en la plantilla. Recibirás comentarios directamente en tu PR.
@@ -357,7 +342,7 @@ El inspector valida automáticamente lo siguiente:
- [ ] Existe el directorio `tests/`
- [ ] Existe el archivo `README.md-tpl`
-- [ ] Existe al menos uno de `pyproject.toml-tpl` (preferido) o `setup.py-tpl` (legacy)
+- [ ] Existe `pyproject.toml-tpl` (sin `setup.py-tpl` en las plantillas nuevas)
#### ✅ Validación de extensiones
@@ -369,7 +354,8 @@ El inspector valida automáticamente lo siguiente:
- [ ] `fastapi` está declarado en al menos uno de:
- [ ] `pyproject.toml-tpl` bajo `[project].dependencies` (preferido)
- [ ] `requirements.txt-tpl`
- - [ ] `setup.py-tpl` bajo `install_requires`
+- [ ] `requirements.txt-tpl` y `[project].dependencies` no se contradicen
+- [ ] `FastAPI-fastkit` **no** es una dependencia de ejecución
#### ✅ Validación de la implementación de FastAPI
@@ -382,6 +368,24 @@ El inspector valida automáticamente lo siguiente:
- [ ] La instalación de dependencias es correcta
- [ ] Todas las pruebas de pytest pasan
+#### ✅ Prueba de humo
+
+- [ ] El proyecto generado arranca con uvicorn
+- [ ] `/docs` responde
+- [ ] `/health` responde
+
+El objetivo de uvicorn se resuelve a partir de `[tool.fastapi-fastkit].app_module` en el `pyproject.toml` generado, después de `app_module` en `template-config.yml` y, por último, de las ubicaciones convencionales de `main.py`.
+
+#### ✅ Coherencia de la configuración
+
+- [ ] `requires-python`, el `target-version` de black y el `python_version` de mypy indican Python 3.12
+- [ ] No hay divergencia de dependencias entre `requirements.txt-tpl` y `[project].dependencies`
+- [ ] No hay autodependencia de `FastAPI-fastkit`
+
+#### ✅ Restos de marcadores
+
+- [ ] Ningún `` sobrevive a la generación del proyecto
+
#### ✅ Pruebas automatizadas de plantillas
FastAPI-fastkit incluye **pruebas automatizadas de plantillas** que ejecutan pruebas integrales sobre todas las plantillas:
diff --git a/docs/es/index.md b/docs/es/index.md
index 1d695c4..178fed2 100644
--- a/docs/es/index.md
+++ b/docs/es/index.md
@@ -34,6 +34,8 @@ Está inspirado en el `SpringBoot initializer` y en el CLI `django-admin` de Pyt
- **🔍 Aseguramiento de calidad automatizado de las plantillas**: pruebas automáticas semanales garantizan que todas las plantillas siguen funcionando y al día
- **🚀 Múltiples plantillas de proyecto**: elige entre varias plantillas preconfiguradas para distintos casos de uso (async CRUD, Docker, PostgreSQL, etc.)
- **📦 Soporte de varios gestores de paquetes**: elige tu gestor de paquetes Python preferido (pip, uv, pdm, poetry) para gestionar dependencias
+- **🧾 Configuraciones de proyecto reproducibles**: guarda una sesión interactiva con `--save-config` y reprodúcela más tarde con `fastkit init --config` — sin prompts, el mismo proyecto
+- **🏷️ Proyectos autodescriptivos**: cada proyecto generado registra su plantilla, preset, gestor de paquetes, entrypoint y funcionalidades seleccionadas en un bloque `[tool.fastapi-fastkit]` que `runserver` y `addroute` vuelven a leer
## Instalación
@@ -123,7 +125,7 @@ Do you want to proceed with project creation? [y/N]: y
FastAPI project will deploy at '~your-project-path~'
╭──────────────────────── Info ────────────────────────╮
-│ ℹ Injected metadata into setup.py │
+│ ℹ Injected metadata into pyproject.toml │
╰──────────────────────────────────────────────────────╯
╭──────────────────────── Info ────────────────────────╮
│ ℹ Injected metadata into config file │
@@ -174,6 +176,16 @@ Installing dependencies...
Este comando crea un nuevo espacio de trabajo para tu proyecto FastAPI e incluye también un entorno virtual de Python.
+- Opciones principales:
+ - `--project-name`, `--author`, `--author-email`, `--description`
+ - `--package-manager` [pip|uv|pdm|poetry]
+ - `--config `: crea el proyecto a partir de un archivo de configuración guardado (`.json` / `.toml`, y `.yaml` cuando PyYAML está instalado), sin prompts
+ - `--save-config `: con `--interactive`, registra las respuestas para reutilizarlas después
+ - `--dry-run`: muestra los archivos y paquetes que se crearían, sin escribir nada
+ - `--no-venv`: omite la creación del entorno virtual (implica `--no-install`)
+ - `--no-install`: omite la instalación de dependencias
+ - `--yes` / `-y`: omite la confirmación "Overwrite these files?" al desplegar in situ
+
### Crear un proyecto en modo interactivo ✨ ¡NUEVO!
Para proyectos más complejos, usa el **modo interactivo** para construir tu aplicación FastAPI paso a paso con selección inteligente de funcionalidades:
@@ -264,6 +276,30 @@ Select utilities (comma-separated numbers, e.g., 1,3,4):
Select utilities: 1
+🪵 Logging Format
+Select logging format:
+ 1. structured - JSON logs + X-Request-ID correlation middleware (stdlib only)
+ 2. None - Uvicorn's default plain-text logging
+
+Select logging format [2]: 1
+
+🧬 Database Migrations
+Select migration tool:
+ 1. Alembic - alembic.ini + async alembic/env.py + scripts/migrate.sh (recommended for SQL databases)
+ 2. None - No migration tooling
+
+Select migration tool [1]: 1
+
+🧰 Developer Tooling
+Select tooling to generate (comma-separated numbers, e.g., 1,3)
+ 1. ruff ruff + ruff-format config in pyproject.toml (replaces black/isort)
+ 2. pre-commit .pre-commit-config.yaml
+ 3. github-actions .github/workflows/test.yml (Python 3.12)
+ 4. devcontainer .devcontainer/devcontainer.json
+ 5. makefile Makefile with install/test/lint/format/run
+
+Your choice (or press Enter to skip): 1,2
+
🚀 Deployment Configuration
Select deployment option:
1. Docker - Generate Dockerfile
@@ -294,6 +330,9 @@ Enter custom package names (comma-separated, press Enter to skip):
│ Monitoring │ Prometheus │
│ Testing │ Coverage │
│ Utilities │ CORS │
+│ Logging │ structured │
+│ Migrations │ Alembic │
+│ Tooling │ ruff, pre-commit │
│ Package Manager │ uv │
└─────────────────────┴───────────────────────────────────────────────────────────────────────────┘
@@ -350,6 +389,28 @@ El modo interactivo ofrece:
- **Gestión inteligente de dependencias** con compatibilidad automática con pip
- **Validación de funcionalidades** con avisos de cableado manual para las selecciones que el preset no puede conectar automáticamente
- **Marcadores de identidad** en el `pyproject.toml` generado (marcador en `description` + tabla `[tool.fastapi-fastkit]`) para que `is_fastkit_project()` reconozca después los proyectos generados
+- **Metadatos del proyecto** registrados en `[tool.fastapi-fastkit]` — plantilla, preset, gestor de paquetes, `app_module` y las `features` seleccionadas — que `fastkit runserver` y `fastkit addroute` vuelven a leer
+- **Ejecuciones reproducibles**: `--save-config ` registra las respuestas, `--config ` las reproduce sin un solo prompt y `--dry-run` previsualiza el resultado sin escribir nada
+
+Ahora cada selección del catálogo genera código real y funcional, en lugar de
+limitarse a instalar un paquete — las tareas en segundo plano
+(Celery/Dramatiq), la caché con Redis, WebSocket, Pagination, el tracing con
+OpenTelemetry y la autenticación OAuth2 / basada en sesiones incluyen un
+módulo correspondiente y su cableado en `main.py`. Tres ejes nuevos completan
+el catálogo:
+
+- **Logging**: `structured` añade salida estructurada con `logging` + `json` de la stdlib y un middleware de request-id — sin dependencias nuevas
+- **Migraciones**: `Alembic` genera un entorno de migraciones asíncrono completo (`alembic.ini`, `alembic/env.py`, una revisión base, `scripts/migrate.sh`) para cualquier base de datos SQL seleccionada
+- **Herramientas** (selección múltiple): `ruff`, `pre-commit`, `github-actions`, `devcontainer`, `makefile` — cada una genera su propio archivo de configuración; `ruff` además fusiona un bloque `[tool.ruff]` en `pyproject.toml`
+
+Cada proyecto generado obtiene también los endpoints `/health` y `/ready`, y
+`--dry-run` lista exactamente el mismo conjunto de archivos que escribiría una
+ejecución real, incluidos estos nuevos artefactos. `classic-layered` y
+`domain-starter` conservan el `main.py` que trae la plantilla, así que la
+validación de funcionalidades avisa cuando una selección de cualquiera de
+estos ejes necesita cableado manual — consulta la
+[matriz de presets / funcionalidades](reference/preset-feature-matrix.md) para
+más detalles.
### Añadir una ruta nueva al proyecto FastAPI
@@ -445,6 +506,12 @@ FastAPI template project will deploy at '~your-project-path~'
@@ -463,18 +530,42 @@ $ fastkit list-templates
│ │ PostgreSQL │
│ fastapi-default │ Simple FastAPI Project │
│ fastapi-single-module │ FastAPI Single Module Template │
+│ fastapi-auth-jwt │ FastAPI JWT Authentication │
+│ fastapi-sqlmodel │ FastAPI SQLModel │
+│ fastapi-llm-agent │ FastAPI LLM Agent │
└────────────────────────┴───────────────────────────────────────────────────────┘
```
+Plantillas disponibles:
+
+| Plantilla | Descripción | Notas |
+|---|---|---|
+| [`fastapi-default`](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/fastapi_project_template/fastapi-default/README.md-tpl) | Proyecto FastAPI simple con una estructura clásica por capas | Buena primera opción |
+| [`fastapi-empty`](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/fastapi_project_template/fastapi-empty/README.md-tpl) | Plantilla FastAPI mínima | Base del preset `minimal` |
+| [`fastapi-single-module`](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/fastapi_project_template/fastapi-single-module/README.md-tpl) | App FastAPI de un solo archivo | Base del preset `single-module` |
+| [`fastapi-domain-starter`](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/README.md-tpl) | Starter orientado a dominios, centrado en pyproject, para APIs de tamaño medio | Base del preset `domain-starter` |
+| [`fastapi-auth-jwt`](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/fastapi_project_template/fastapi-auth-jwt/README.md-tpl) | Autenticación JWT con rotación de refresh tokens, hash argon2 y scopes | Nueva en v1.4.0 |
+| [`fastapi-sqlmodel`](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/fastapi_project_template/fastapi-sqlmodel/README.md-tpl) | SQLModel asíncrono + migraciones con Alembic + CRUD genérico con paginación | Nueva en v1.4.0 |
+| [`fastapi-llm-agent`](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/fastapi_project_template/fastapi-llm-agent/README.md-tpl) | Agente de chat Claude con streaming (SSE) y bucle de llamadas a herramientas | Nueva en v1.4.0 |
+| [`fastapi-mcp`](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/fastapi_project_template/fastapi-mcp/README.md-tpl) | App FastAPI expuesta como servidor MCP | |
+| [`fastapi-psql-orm`](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/fastapi_project_template/fastapi-psql-orm/README.md-tpl) | API de gestión de items con PostgreSQL, SQLModel, Alembic y docker-compose | Requiere Docker |
+| [`fastapi-custom-response`](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/fastapi_project_template/fastapi-custom-response/README.md-tpl) | API de gestión de items con un envoltorio de respuesta personalizado, manejo de errores y paginación | |
+| [`fastapi-async-crud`](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/fastapi_project_template/fastapi-async-crud/README.md-tpl) | API asíncrona de gestión de items | **Obsoleta** — usa `fastapi-sqlmodel` |
+| [`fastapi-dockerized`](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/fastapi_project_template/fastapi-dockerized/README.md-tpl) | API de gestión de items dockerizada | **Obsoleta** — usa `fastapi-default` con la opción Docker de `init --interactive` |
+
+Las plantillas obsoletas siguen funcionando, pero ya no son puntos de partida recomendados. Consulta [¿Qué starter elegir?](user-guide/choosing-a-starter.md) para una guía de decisión.
+
## Documentación
Para guías completas e instrucciones detalladas, explora nuestra documentación:
+- 🧭 **[¿Qué starter elegir?](user-guide/choosing-a-starter.md)** - Guía de decisión para principiantes sobre las plantillas de `startdemo` y los presets interactivos
- 📚 **[Guía de usuario](user-guide/quick-start.md)** - Guías detalladas de instalación y uso
- 🎯 **[Tutorial](tutorial/getting-started.md)** - Tutoriales paso a paso para principiantes
- 📖 **[Referencia de la CLI](user-guide/cli-reference.md)** - Referencia completa de comandos
+- 🧱 **[Matriz de presets de arquitectura](reference/preset-feature-matrix.md)** - Contrato por preset y por funcionalidad de la generación interactiva
- 🔍 **[Aseguramiento de calidad de plantillas](reference/template-quality-assurance.md)** - Pruebas automatizadas y estándares de calidad
## 🚀 Tutoriales basados en plantillas
@@ -486,16 +577,19 @@ Aprende FastAPI con casos prácticos usando nuestras plantillas ya preparadas:
- **[Construir un servidor API básico](tutorial/basic-api-server.md)** - Crea tu primer servidor FastAPI con la plantilla `fastapi-default`
- **[Construir una API CRUD asíncrona](tutorial/async-crud-api.md)** - Desarrolla una API async de alto rendimiento con la plantilla `fastapi-async-crud`
- **[Proyecto orientado a dominios (Domain Starter)](tutorial/domain-starter.md)** - Construye una API mediana con la plantilla `fastapi-domain-starter`, la opción moderna recomendada
+- **[Autenticación JWT](tutorial/auth-jwt.md)** - Añade cuentas reales con la plantilla `fastapi-auth-jwt`: refresh tokens rotatorios, hash argon2id y guards de roles y scopes
### 🗄️ Base de datos e infraestructura
- **[Integrar con una base de datos](tutorial/database-integration.md)** - Usa PostgreSQL + SQLAlchemy con la plantilla `fastapi-psql-orm`
-- **[Dockerizar y desplegar](tutorial/docker-deployment.md)** - Configura un entorno de despliegue de producción con la plantilla `fastapi-dockerized`
+- **[Persistencia asíncrona con SQLModel](tutorial/sqlmodel.md)** - SQLModel asíncrono, migraciones con Alembic, una base CRUD genérica y listas paginadas con la plantilla `fastapi-sqlmodel`
+- **[Dockerizar y desplegar](tutorial/docker-deployment.md)** - Configura un entorno de despliegue de producción con la plantilla `fastapi-dockerized` *(plantilla obsoleta — se mantiene para los usuarios existentes)*
### ⚡ Funcionalidades avanzadas
- **[Manejo personalizado de respuestas y diseño avanzado de API](tutorial/custom-response-handling.md)** - Construye APIs de nivel empresarial con la plantilla `fastapi-custom-response`
- **[Integrar con MCP](tutorial/mcp-integration.md)** - Crea un servidor API integrado con modelos de IA con la plantilla `fastapi-mcp`
+- **[Agente LLM con streaming](tutorial/llm-agent.md)** - Construye un backend de chat Claude con streaming y un bucle real de llamadas a herramientas con la plantilla `fastapi-llm-agent`
Cada tutorial ofrece:
diff --git a/docs/es/reference/preset-feature-matrix.md b/docs/es/reference/preset-feature-matrix.md
index 5769d9f..ffd02c0 100644
--- a/docs/es/reference/preset-feature-matrix.md
+++ b/docs/es/reference/preset-feature-matrix.md
@@ -29,12 +29,18 @@ Estas funcionalidades están soportadas en **todos** los presets: la instalació
| Funcionalidad | `minimal` / `single-module` | `classic-layered` / `domain-starter` |
|---|---|---|
| **Base de datos** (PostgreSQL, MySQL, SQLite, MongoDB) | Genera el módulo de configuración **y** añade llamadas stub `await init_db()` en el `main.py` regenerado. | Genera el módulo de configuración en la ruta del preset. El `main.py` que viene en la plantilla se **conserva**, así que tienes que cablear `get_db()` en los routers manualmente. |
-| **Autenticación** (JWT, FastAPI-Users, OAuth2, basada en sesiones) | Genera el módulo de configuración de auth. JWT también importa `HTTPBearer` en el `main.py` regenerado. | Genera el módulo de configuración de auth en la ruta del preset. No se añaden imports al `main.py` — cablea las dependencias manualmente. |
-| **Tareas en segundo plano** (Celery, Dramatiq) | Los paquetes se instalan; por ahora no hay regeneración automática de `main.py`. | Igual. |
-| **Caché** (Redis) | Los paquetes se instalan; por ahora no hay regeneración automática de `main.py`. | Igual. |
+| **Autenticación** (JWT, FastAPI-Users, OAuth2, basada en sesiones) | Genera el módulo de configuración de auth; JWT importa `HTTPBearer`, y OAuth2 y la basada en sesiones añaden además su configuración de middleware en `main.py`. | Genera el módulo de configuración de auth en la ruta del preset. No se añaden imports al `main.py` — cablea las dependencias manualmente. |
+| **Tareas en segundo plano** (Celery, Dramatiq) | Genera `worker.py` y `features/tasks.py`, y monta el router de tareas en el `main.py` regenerado. | Genera `worker.py` y `features/tasks.py`, pero el `main.py` que trae la plantilla se **conserva** — monta el router manualmente. |
+| **Caché** (Redis) | Genera `features/cache.py` y lo monta e inicializa en el `main.py` regenerado. | Genera `features/cache.py`; móntalo manualmente. |
+| **Utilidades: Pagination / WebSocket** | Genera `features/pagination.py` / `features/websocket.py` y monta el router en el `main.py` regenerado. | Genera el mismo módulo; móntalo manualmente. |
+| **Monitorización: OpenTelemetry** | Sin archivo independiente — la configuración de tracing se añade directamente al `main.py` regenerado. | Sin archivo independiente. El `main.py` de la plantilla se conserva, así que el tracing **no queda cableado** — añade la configuración manualmente. |
+| **Migraciones** (Alembic) | Genera `alembic.ini`, `alembic/env.py`, una revisión base y `scripts/migrate.sh` para cualquier base de datos SQL seleccionada — con independencia de la regeneración de `main.py`. | Igual — la generación de Alembic no depende de si `main.py` se conserva. |
+| **Herramientas** (ruff, pre-commit, github-actions, devcontainer, makefile) | Genera los archivos de configuración correspondientes, con independencia de la regeneración de `main.py`. | Igual. |
+| **Logging** (estructurado) | Genera `logging_config.py` y cablea el middleware de request-id en el `main.py` regenerado. | Genera `logging_config.py`; el `main.py` de la plantilla se conserva, así que cablea el middleware manualmente. |
| **CORS** (utilidad) | Se añade `CORSMiddleware` al `main.py` regenerado con `allow_origins=['*']`. | **Ya cableado** en el `main.py` que trae la plantilla (condicional a `settings.all_cors_origins`). Actívalo definiendo `BACKEND_CORS_ORIGINS` en `.env` — no requiere cambios de código. |
-| **Pruebas** (Basic / Coverage / Advanced) | Se genera `pytest.ini` en la raíz del proyecto. | Igual. |
+| **Pruebas** (Basic / Coverage / Advanced) | Se genera `pytest.ini` en la raíz del proyecto; Advanced añade además `tests/factories.py` y `tests/test_factories.py`. | Igual. |
| **Despliegue** (Docker, docker-compose) | Se escribe `Dockerfile` y/o `docker-compose.yml` en la raíz del proyecto. | Igual. |
+| **`/health` / `/ready`** | Siempre presentes en el `main.py` regenerado. | Ya presentes en el `main.py` conservado que trae la plantilla. |
## Cuándo verás un aviso de "Preset compatibility"
@@ -44,10 +50,15 @@ Para los presets que **conservan el `main.py` que trae la plantilla** (`classic-
|---|---|
| `CORS` (utilidad) | ❌ — ya cableado en el `main.py` de la plantilla. Solo rellena `BACKEND_CORS_ORIGINS` en `.env`. |
| `Rate-Limiting` (utilidad) | ✅ — la configuración del limitador `slowapi` no se añade |
-| `Prometheus` (monitorización) | ✅ — no se llama a `Instrumentator().instrument(app)` |
+| `Pagination` / `WebSocket` (utilidad) | ✅ — el router generado (`features/pagination.py` / `features/websocket.py`) no se monta |
+| `Celery` / `Dramatiq` (async_tasks) | ✅ — el router generado de `worker.py` / `features/tasks.py` no se monta |
+| `Redis` (caché) | ✅ — el `features/cache.py` generado no se monta ni se inicializa |
+| `Prometheus` / `OpenTelemetry` (monitorización) | ✅ — la configuración de instrumentación no se añade a `main.py` |
+| `structured` (logging) | ✅ — se genera `logging_config.py`, pero el middleware de request-id no se añade a `main.py` |
+| `Alembic` (migraciones), selecciones de `tooling` | ❌ — estos archivos se generan y se pueden usar sea cual sea el preset; nada depende de `main.py` |
| Cualquier selección de base de datos / auth | ⚠️ — los archivos de configuración se generan, pero tienes que añadirlos con `Depends()` en tus routers |
-Para los presets `minimal` y `single-module`, la regeneración dinámica de `main.py` se encarga automáticamente de CORS, rate limiting e instrumentación con Prometheus; no aparece ningún aviso.
+Para los presets `minimal` y `single-module`, la regeneración dinámica de `main.py` se encarga automáticamente de todos los ejes anteriores; no aparece ningún aviso.
## Combinaciones no soportadas (juego seguro)
diff --git a/docs/es/reference/template-quality-assurance.md b/docs/es/reference/template-quality-assurance.md
index ee5d493..1ed8a04 100644
--- a/docs/es/reference/template-quality-assurance.md
+++ b/docs/es/reference/template-quality-assurance.md
@@ -21,6 +21,38 @@ Cada miércoles a medianoche (UTC), nuestro flujo de trabajo de GitHub Actions i
- ✅ **Comprobación de dependencias** — confirma que FastAPI y las dependencias necesarias están bien declaradas
- ✅ **Implementación de FastAPI** — verifica que las plantillas contienen una inicialización adecuada de la app FastAPI
- ✅ **Ejecución de pruebas** — ejecuta las pruebas de la plantilla para confirmar que funcionan
+- ✅ **Prueba de humo** — arranca el proyecto generado con uvicorn y sondea su superficie HTTP
+- ✅ **Coherencia de la configuración** — versiones de Python fijadas, divergencia de dependencias, autodependencia
+- ✅ **Restos de marcadores** — ningún `