fix(template): honor restored capability contracts

Author: dlivxpr

docs/migration-traceability.toml

@@ -45,7 +45,7 @@ legacy_source = "legacy/template/{{cookiecutter.project_slug}}/backend/app/core/
 target = "app/core/logging.py"
 allowed_transformations = ["删除用户/JWT 脱敏模式", "保留凭据脱敏"]
 removed_references = ["email、JWT、Bearer、refresh token 模式"]
-approved_deviation = ["类名明确为 SecretRedactionFilter"]
+approved_deviation = ["无"]
 verification = ["test_minimal_tree_contains_only_legacy_core_service"]
 
 [[target]]

template/[% if ci_type == 'github' %].github[% endif %]/workflows/ci.yml.jinja

@@ -7,7 +7,7 @@ on:
 jobs:
   quality:
     runs-on: ubuntu-latest
-[% if database == "postgresql" or background_tasks == "taskiq" or enable_caching or rate_limiting == "redis" %]    services:
+[% if database == "postgresql" or enable_redis %]    services:
 [% if database == "postgresql" %]      postgres:
         image: postgres:17-alpine
         env:
@@ -21,7 +21,7 @@ jobs:
           --health-interval 2s
           --health-timeout 3s
           --health-retries 15
-[% endif %][% if background_tasks == "taskiq" or enable_caching or rate_limiting == "redis" %]      redis:
+[% endif %][% if enable_redis %]      redis:
         image: redis:8-alpine
         ports:
           - 6379:6379
@@ -32,8 +32,8 @@ jobs:
           --health-retries 15
 [% endif %][% endif %]    env:
 [% if database == "postgresql" %]      DATABASE_URL: postgresql+asyncpg://postgres:postgres@127.0.0.1:5432/app
-[% endif %][% if background_tasks == "taskiq" or enable_caching or rate_limiting == "redis" %]      REDIS_URL: redis://127.0.0.1:6379/0
-[% endif %][% if telemetry == "logfire" %]      LOGFIRE_SEND_TO_LOGFIRE: "false"
+[% endif %][% if enable_redis %]      REDIS_URL: redis://127.0.0.1:6379/0
+[% endif %][% if enable_logfire %]      LOGFIRE_SEND_TO_LOGFIRE: "false"
 [% endif %]    steps:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v6

template/[% if enable_docker %]deploy[% endif %]/compose.yaml.jinja

@@ -6,17 +6,17 @@ services:
     environment:
       API_KEY: "${API_KEY:-[[ deployment_api_key ]]}"
 [% if database == "postgresql" %]      DATABASE_URL: postgresql+asyncpg://postgres:postgres@postgres:5432/app
-[% endif %][% if background_tasks == "taskiq" or enable_caching or rate_limiting == "redis" %]      REDIS_URL: redis://redis:6379/0
-[% endif %][% if agent_capability == "pydantic-ai" %]      LLM_BASE_URL: "${LLM_BASE_URL:-https://api.example.com/v1}"
+[% endif %][% if enable_redis %]      REDIS_URL: redis://redis:6379/0
+[% endif %][% if ai_framework == "pydantic_ai" %]      LLM_BASE_URL: "${LLM_BASE_URL:-https://api.example.com/v1}"
       LLM_API_KEY: "${LLM_API_KEY:-model-key-CHANGEME}"
       LLM_MODEL: "${LLM_MODEL:-model-name-CHANGEME}"
-[% endif %][% if telemetry == "logfire" %]      LOGFIRE_TOKEN: "${LOGFIRE_TOKEN:-}"
+[% endif %][% if enable_logfire %]      LOGFIRE_TOKEN: "${LOGFIRE_TOKEN:-}"
 [% endif %]    ports:
       - "8000:8000"
-[% if database == "postgresql" or background_tasks == "taskiq" or enable_caching or rate_limiting == "redis" %]    depends_on:
+[% if database == "postgresql" or enable_redis or background_tasks == "taskiq" %]    depends_on:
 [% if database == "postgresql" %]      migrate:
         condition: service_completed_successfully
-[% endif %][% if background_tasks == "taskiq" or enable_caching or rate_limiting == "redis" %]      redis:
+[% endif %][% if enable_redis or background_tasks == "taskiq" %]      redis:
         condition: service_healthy
 [% endif %][% endif %]    healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health/ready')"]
@@ -31,7 +31,7 @@ services:
     command: ["uv", "run", "--no-sync", "taskiq", "worker", "app.tasks.taskiq:broker"]
     environment:
       REDIS_URL: redis://redis:6379/0
-[% if telemetry == "logfire" %]      LOGFIRE_TOKEN: "${LOGFIRE_TOKEN:-}"
+[% if enable_logfire %]      LOGFIRE_TOKEN: "${LOGFIRE_TOKEN:-}"
 [% endif %]
     depends_on:
       redis:
@@ -44,7 +44,7 @@ services:
     command: ["uv", "run", "--no-sync", "taskiq", "scheduler", "app.tasks.taskiq:scheduler"]
     environment:
       REDIS_URL: redis://redis:6379/0
-[% if telemetry == "logfire" %]      LOGFIRE_TOKEN: "${LOGFIRE_TOKEN:-}"
+[% if enable_logfire %]      LOGFIRE_TOKEN: "${LOGFIRE_TOKEN:-}"
 [% endif %]
     depends_on:
       redis:
@@ -76,7 +76,7 @@ services:
       retries: 15
     volumes:
       - postgres-data:/var/lib/postgresql/data
-[% endif %][% if background_tasks == "taskiq" or enable_caching or rate_limiting == "redis" %]
+[% endif %][% if enable_redis or background_tasks == "taskiq" %]
   redis:
     image: redis:8-alpine
     ports:
@@ -88,8 +88,8 @@ services:
       retries: 15
     volumes:
       - redis-data:/data
-[% endif %][% if database == "postgresql" or background_tasks == "taskiq" or enable_caching or rate_limiting == "redis" %]
+[% endif %][% if database == "postgresql" or enable_redis or background_tasks == "taskiq" %]
 volumes:
 [% if database == "postgresql" %]  postgres-data:
-[% endif %][% if background_tasks == "taskiq" or enable_caching or rate_limiting == "redis" %]  redis-data:
+[% endif %][% if enable_redis or background_tasks == "taskiq" %]  redis-data:
 [% endif %][% endif %]

…' %]agents[% endif %]/assistant.py.jinja …' %]agents[% endif %]/assistant.py.jinjatemplate/app/[% if agent_capability == 'pydantic-ai' %]agents[% endif %]/assistant.py.jinja renamed to template/app/[% if ai_framework == 'pydantic_ai' %]agents[% endif %]/assistant.py.jinja template/app/[% if agent_capability == 'pydantic-ai' %]agents[% endif %]/assistant.py.jinja renamed to template/app/[% if ai_framework == 'pydantic_ai' %]agents[% endif %]/assistant.py.jinja

@@ -1,13 +1,13 @@
 from __future__ import annotations
 
-[% if telemetry == "logfire" %]import logfire
+[% if enable_logfire %]import logfire
 [% endif -%]
 from taskiq import TaskiqScheduler
 from taskiq.schedule_sources import LabelScheduleSource
 from taskiq_redis import RedisAsyncResultBackend, RedisStreamBroker
 
 from app.core.config import Settings
-[% if telemetry == "logfire" %]from app.core.telemetry import configure_telemetry
+[% if enable_logfire %]from app.core.telemetry import configure_telemetry
 
 configure_telemetry()
 [% endif %]
@@ -27,7 +27,7 @@ scheduler = TaskiqScheduler(broker=broker, sources=[LabelScheduleSource(broker)]
 )
 async def example_task(value: str = "scheduled") -> dict[str, str]:
     """Return a value so callers can observe successful worker execution."""
-[% if telemetry == "logfire" %]    with logfire.span("Run Taskiq example task"):
+[% if enable_logfire %]    with logfire.span("Run Taskiq example task"):
         return {"value": value}
 [% else %]    return {"value": value}
 [% endif -%]

…ai' %]services[% endif %]/agent.py.jinja …ai' %]services[% endif %]/agent.py.jinjatemplate/app/[% if agent_capability == 'pydantic-ai' %]services[% endif %]/agent.py.jinja renamed to template/app/[% if ai_framework == 'pydantic_ai' %]services[% endif %]/agent.py.jinja template/app/[% if agent_capability == 'pydantic-ai' %]services[% endif %]/agent.py.jinja renamed to template/app/[% if ai_framework == 'pydantic_ai' %]services[% endif %]/agent.py.jinja

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-[% if orm == "sqlalchemy" %]from sqlalchemy.orm import DeclarativeBase
+[% if orm_type == "sqlalchemy" %]from sqlalchemy.orm import DeclarativeBase
 
 
 class Base(DeclarativeBase):

template/app/[% if background_tasks == 'taskiq' %]tasks[% endif %]/taskiq.py.jinja

@@ -5,7 +5,7 @@ from contextlib import asynccontextmanager
 
 from sqlalchemy import text
 from sqlalchemy.exc import SQLAlchemyError
-[% if orm == "sqlalchemy" %]from sqlalchemy.ext.asyncio import (
+[% if orm_type == "sqlalchemy" %]from sqlalchemy.ext.asyncio import (
     AsyncEngine,
     AsyncSession,
     async_sessionmaker,
@@ -14,8 +14,8 @@ from sqlalchemy.exc import SQLAlchemyError
 [% else %]from sqlalchemy.ext.asyncio import AsyncEngine, async_sessionmaker, create_async_engine
 from sqlmodel.ext.asyncio.session import AsyncSession
 [% endif %]
-from app.core.exceptions import PersistenceError
-[% if telemetry == "logfire" %]from app.core.telemetry import instrument_database
+from app.core.exceptions import DatabaseError
+[% if enable_logfire %]from app.core.telemetry import instrument_database
 [% endif %]
 
 class DatabaseSessionManager:
@@ -29,7 +29,7 @@ class DatabaseSessionManager:
         if self._engine is not None:
             raise RuntimeError("Database session manager is already initialized")
         engine = create_async_engine(database_url, pool_pre_ping=True)
-[% if telemetry == "logfire" %]        instrument_database(engine)
+[% if enable_logfire %]        instrument_database(engine)
 [% endif %]
         session_factory = async_sessionmaker(
             bind=engine,
@@ -49,7 +49,7 @@ class DatabaseSessionManager:
                 await session.commit()
             except SQLAlchemyError as exc:
                 await session.rollback()
-                raise PersistenceError(resource="transaction") from exc
+                raise DatabaseError() from exc
             except BaseException:
                 await session.rollback()
                 raise

template/app/[% if database == 'postgresql' %]db[% endif %]/base.py.jinja

@@ -1,11 +1,16 @@
 """Public health probes."""
 
+[% if database == "postgresql" or enable_redis %]from datetime import UTC, datetime
+[% endif -%]
 from typing import Any
 
 from fastapi import APIRouter
+from fastapi.responses import JSONResponse
 
 from app.core.config import settings
-from app.schemas.base import HealthDetailResponse, HealthResponse
+[% if enable_redis %]from app.core.redis import redis_resources
+[% endif %][% if database == "postgresql" %]from app.db.session import database
+[% endif %]from app.schemas.base import HealthDetailResponse, HealthResponse
 from app.services.health import build_health_response
 
 router = APIRouter(tags=["health"])
@@ -31,5 +36,42 @@ async def liveness_probe() -> dict[str, Any]:
 
 
 @router.get("/health/ready", response_model=None)
-async def readiness_probe() -> dict[str, Any]:
-    return build_health_response(status="ready", checks={})
+async def readiness_probe() -> dict[str, Any] | JSONResponse:
+    checks: dict[str, dict[str, Any]] = {}
+[% if database == "postgresql" %]
+    try:
+        started_at = datetime.now(UTC)
+        await database.check_connection()
+        latency_ms = (datetime.now(UTC) - started_at).total_seconds() * 1000
+        checks["database"] = {
+            "status": "healthy",
+            "latency_ms": round(latency_ms, 2),
+            "type": "postgresql",
+        }
+    except Exception as exc:
+        checks["database"] = {
+            "status": "unhealthy",
+            "error": str(exc),
+            "type": "postgresql",
+        }
+[% endif %][% if enable_redis %]
+    try:
+        started_at = datetime.now(UTC)
+        is_healthy = await redis_resources.client.ping()
+        latency_ms = (datetime.now(UTC) - started_at).total_seconds() * 1000
+        checks["redis"] = (
+            {"status": "healthy", "latency_ms": round(latency_ms, 2)}
+            if is_healthy
+            else {"status": "unhealthy", "error": "Ping failed"}
+        )
+    except Exception as exc:
+        checks["redis"] = {"status": "unhealthy", "error": str(exc)}
+[% endif %]    all_healthy = all(check["status"] == "healthy" for check in checks.values())
+    response_data = build_health_response(
+        status="ready" if all_healthy else "not_ready",
+        checks=checks,
+    )
+    response_data.update(checks)
+    if not all_healthy:
+        return JSONResponse(status_code=503, content=response_data)
+    return response_data