python-platform 0.1.1__py3-none-any.whl

python_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/http_api/files.py.jinja

@@ -0,0 +1,74 @@
+"""原生上传与流响应；业务查询在返回响应前完成，不跨网络发送持有事务。"""
+
+import asyncio
+import hashlib
+import logging
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import File, Form, UploadFile
+from starlette.responses import Response, StreamingResponse
+
+from python_platform.authorization import authorize
+from python_platform.fastapi import ActionFilterContext, HttpRouter, service_filter
+
+from ..application_contracts.orders import CreateOrder, {{ cookiecutter.class_prefix }}ApplicationService
+from ..domain_shared.definitions import MODULE_NAME, ORDERS_READ, ORDERS_WRITE
+
+router = HttpRouter(prefix=f"/api/{MODULE_NAME}/files", permissions=(ORDERS_READ,))
+
+
+class ExportFilter:
+    async def invoke(
+        self, context: ActionFilterContext, next_action: Callable[[], Awaitable[object]]
+    ) -> object:
+        # Filter 的作用域只覆盖已绑定参数到响应准备；不假定流传输已经结束。
+        result = await next_action()
+        logging.getLogger(__name__).info("File response prepared")
+        return result
+
+
+@router.post("/upload", status_code=201)
+@authorize(ORDERS_WRITE)
+async def upload(
+    service: {{ cookiecutter.class_prefix }}ApplicationService,
+    title: Annotated[str, Form()],
+    file: Annotated[UploadFile, File()],
+) -> dict[str, object]:
+    # File/Form 使用框架读取期限额及原生 parser；UploadFile 资源由 REQUEST 关闭。
+    content = await file.read()
+    order = await service.create(CreateOrder(title=title))
+    return {
+        "order": order.model_dump(mode="json"),
+        "bytes": len(content),
+        "sha256": hashlib.sha256(content).hexdigest(),
+    }
+
+
+@router.get("/{id}/download")
+@service_filter(ExportFilter)
+async def download(id: UUID, service: {{ cookiecutter.class_prefix }}ApplicationService) -> Response:
+    order = await service.get(id)
+    return Response(
+        order.model_dump_json(),
+        media_type="application/json",
+        headers={"Content-Disposition": f'attachment; filename="{id}.json"'},
+    )
+
+
+@router.get("/export/stream")
+@service_filter(ExportFilter)
+async def export(service: {{ cookiecutter.class_prefix }}ApplicationService) -> StreamingResponse:
+    orders = await service.get_list()
+
+    async def produce() -> AsyncIterator[bytes]:
+        try:
+            for order in orders:
+                yield (order.model_dump_json() + "\n").encode()
+                await asyncio.sleep(0)
+        finally:
+            # 此示例只持有不可变 DTO，无悬挂 Session／文件；扩展外部资源时在此 shield 异步关闭。
+            logging.getLogger(__name__).info("Order export producer closed")
+
+    return StreamingResponse(produce(), media_type="application/x-ndjson")

python_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/http_api/module.py.jinja

@@ -0,0 +1,58 @@
+"""自动服务暴露与手写路由共用正式认证／REQUEST 管线。"""
+
+from dishka import Scope
+
+from python_platform import AppModule, ConfigureContext
+from python_platform.fastapi import (
+    ApplicationServiceRouteOverride,
+    FastApiRealtimeModule,
+    contributes_routers,
+    exposes_application_services,
+)
+
+from ..application_contracts.module import {{ cookiecutter.class_prefix }}ApplicationContractsModule
+from ..application_contracts.orders import {{ cookiecutter.class_prefix }}ApplicationService
+from ..domain_shared.definitions import MODULE_NAME
+from .files import ExportFilter
+from .files import router as files_router
+from .realtime import router as realtime_router
+
+
+@contributes_routers(files_router, realtime_router)
+@exposes_application_services(
+    {{ cookiecutter.class_prefix }}ApplicationContractsModule,
+    overrides=(
+        ApplicationServiceRouteOverride(
+            {{ cookiecutter.class_prefix }}ApplicationService,
+            method={{ cookiecutter.class_prefix }}ApplicationService.create,
+            path=f"/api/{MODULE_NAME}",
+            status_code=201,
+        ),
+        ApplicationServiceRouteOverride(
+            {{ cookiecutter.class_prefix }}ApplicationService,
+            method={{ cookiecutter.class_prefix }}ApplicationService.get_list,
+            path=f"/api/{MODULE_NAME}",
+        ),
+        ApplicationServiceRouteOverride(
+            {{ cookiecutter.class_prefix }}ApplicationService,
+            method={{ cookiecutter.class_prefix }}ApplicationService.get,
+            path=f"/api/{MODULE_NAME}" + "/{id}",
+        ),
+        ApplicationServiceRouteOverride(
+            {{ cookiecutter.class_prefix }}ApplicationService,
+            method={{ cookiecutter.class_prefix }}ApplicationService.approve,
+            path=f"/api/{MODULE_NAME}" + "/{id}/approve",
+        ),
+        ApplicationServiceRouteOverride(
+            {{ cookiecutter.class_prefix }}ApplicationService,
+            method={{ cookiecutter.class_prefix }}ApplicationService.queue_approval,
+            path=f"/api/{MODULE_NAME}" + "/{id}/queue-approval",
+            status_code=202,
+        ),
+    ),
+)
+class {{ cookiecutter.class_prefix }}HttpApiModule(AppModule):
+    dependencies = ({{ cookiecutter.class_prefix }}ApplicationContractsModule, FastApiRealtimeModule)
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.services.add_scoped(ExportFilter, scope=Scope.REQUEST)

python_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/http_api/realtime.py.jinja

@@ -0,0 +1,37 @@
+"""单进程在线通知；连接认证由框架管理，业务授权仍经过服务契约。"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel, ConfigDict
+from starlette.websockets import WebSocketDisconnect
+
+from python_platform import FrameworkError
+from python_platform.fastapi import WebSocketConnection, websocket_connection
+
+from ..application_contracts.orders import {{ cookiecutter.class_prefix }}ApplicationService
+from ..domain_shared.definitions import MODULE_NAME, ORDER_SNAPSHOT_MESSAGE
+
+router = APIRouter()
+
+
+class RefreshOrders(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+@router.websocket(f"/ws/{MODULE_NAME}")
+async def orders_socket(
+    connection: Annotated[WebSocketConnection, Depends(websocket_connection)],
+) -> None:
+    try:
+        while True:
+            orders = await connection.invoke({{ cookiecutter.class_prefix }}ApplicationService.get_list)
+            await connection.send(
+                ORDER_SNAPSHOT_MESSAGE,
+                {"orders": [item.model_dump(mode="json") for item in orders]},
+            )
+            await connection.receive(RefreshOrders)
+    except WebSocketDisconnect:
+        return
+    except FrameworkError as error:
+        await connection.send_problem(error)

python_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/__init__.py.jinja

@@ -0,0 +1 @@
+"""数据库实现由 consuming Host 选择。"""

python_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/migrations/__init__.py.jinja

@@ -0,0 +1 @@
+"""初始无业务 revision；执行 pp db revision --module {{ cookiecutter.module_name }} 后人工审查。"""

python_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/models.py.jinja

@@ -0,0 +1,26 @@
+"""修改模型后显式生成并审查迁移，不在 Host 启动时建表。"""
+
+from uuid import UUID
+
+from sqlalchemy import Integer, String, Uuid
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from python_platform.sqlalchemy import AuditedEntityMixin
+
+from ..domain_shared.definitions import MODULE_NAME, TITLE_MAX_LENGTH, OrderStatus
+
+
+class {{ cookiecutter.class_prefix }}Base(DeclarativeBase):
+    """本模块模型的原生 MetaData owner。"""
+
+
+class OrderRow(AuditedEntityMixin, {{ cookiecutter.class_prefix }}Base):
+    __tablename__ = MODULE_NAME
+    id: Mapped[UUID] = mapped_column(Uuid, primary_key=True)
+    title: Mapped[str] = mapped_column(String(TITLE_MAX_LENGTH), nullable=False)
+    status: Mapped[str] = mapped_column(
+        String(max(len(item.value) for item in OrderStatus)), nullable=False
+    )
+    version: Mapped[int] = mapped_column(Integer, nullable=False)
+    # SQLAlchemy 以行版本检查并发；聚合暂存版本与数据库提交版本保持一致。
+    __mapper_args__ = {"version_id_col": version, "version_id_generator": False}

python_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/module.py.jinja

@@ -0,0 +1,32 @@
+"""provider 依赖领域契约；Host 显式选择此实现。"""
+
+from dishka import Provider, Scope
+
+from python_platform import AppModule, ConfigureContext
+from python_platform.sqlalchemy import (
+    SqlAlchemyModelRegistration,
+    SqlAlchemyPersistenceModule,
+    contributes_sqlalchemy_models,
+)
+
+from ..domain.module import {{ cookiecutter.class_prefix }}DomainModule
+from ..domain.repository import OrderRepository
+from ..domain_shared.definitions import MODULE_NAME
+from .models import {{ cookiecutter.class_prefix }}Base
+from .repository import SqlAlchemyOrderRepository
+
+
+@contributes_sqlalchemy_models(
+    SqlAlchemyModelRegistration(
+        metadata={{ cookiecutter.class_prefix }}Base.metadata,
+        migrations_package=__package__ + ".migrations",
+        branch_label=MODULE_NAME,
+    )
+)
+class {{ cookiecutter.class_prefix }}SqlAlchemyModule(AppModule):
+    dependencies = ({{ cookiecutter.class_prefix }}DomainModule, SqlAlchemyPersistenceModule)
+
+    def configure(self, context: ConfigureContext) -> None:
+        provider = Provider()
+        provider.provide(SqlAlchemyOrderRepository, provides=OrderRepository, scope=Scope.REQUEST)
+        context.services.contribute(provider, reason="Module repository implementation")

python_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/repository.py.jinja

@@ -0,0 +1,49 @@
+"""仓储参与当前 UoW，成功暂存后由 operation 收集聚合事件。"""
+
+from uuid import UUID
+
+from sqlalchemy import select
+
+from python_platform import OptimisticConcurrencyError
+from python_platform.sqlalchemy import SqlAlchemySessionProvider
+
+from ..domain.orders import Order, OrderTitle
+from ..domain_shared.definitions import OrderStatus
+from .models import OrderRow
+
+
+class SqlAlchemyOrderRepository:
+    def __init__(self, provider: SqlAlchemySessionProvider) -> None:
+        self._provider = provider
+
+    async def get(self, id: UUID) -> Order | None:
+        async with self._provider.operation("get"):
+            row = await (await self._provider.get_session()).get(OrderRow, id)
+            return None if row is None else _order(row)
+
+    async def get_list(self) -> tuple[Order, ...]:
+        async with self._provider.operation("get_list"):
+            rows = await (await self._provider.get_session()).scalars(
+                select(OrderRow).order_by(OrderRow.created_at, OrderRow.id)
+            )
+            return tuple(_order(row) for row in rows)
+
+    async def save(self, order: Order) -> None:
+        async with self._provider.operation("save", aggregate=order):
+            session = await self._provider.get_session()
+            row = await session.get(OrderRow, order.id)
+            if row is None:
+                if order.version:
+                    raise OptimisticConcurrencyError
+                row = OrderRow(id=order.id)
+                session.add(row)
+            elif row.version != order.version:
+                raise OptimisticConcurrencyError
+            order.stage_next_version(order.version)
+            row.title, row.status, row.version = order.title, order.status.value, order.version
+
+
+def _order(row: OrderRow) -> Order:
+    return Order(
+        row.id, OrderTitle(value=row.title), status=OrderStatus(row.status), version=row.version
+    )

python_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/tests/test_domain.py.jinja

@@ -0,0 +1,18 @@
+"""模块内领域验收，不随生产 wheel 打包或参与服务扫描。"""
+
+from uuid import uuid4
+
+import pytest
+from modules.{{ cookiecutter.module_name }}.domain.orders import Order, OrderTitle
+from modules.{{ cookiecutter.module_name }}.domain_shared.definitions import OrderStatus
+
+from python_platform.errors import BusinessError
+
+
+def test_order_approval_rejects_repeat():
+    order = Order.create(uuid4(), OrderTitle(value="Example order"))
+    order.approve()
+    assert order.status is OrderStatus.APPROVED
+    assert len(order.release_local_events()) == 2
+    with pytest.raises(BusinessError):
+        order.approve()

python_platform/developer_kit/templates/project/cookiecutter.json

@@ -0,0 +1,6 @@
+{
+  "project_name": "application", "package_name": "application", "class_prefix": "Application",
+  "framework_version": "", "framework_source": "", "python_version": "", "build_version": "",
+  "database_password": "", "admin_password": "", "jwt_key": "",
+  "host_environment_variable": ""
+}

python_platform/developer_kit/templates/project/{{cookiecutter.project_name}}/.dockerignore

@@ -0,0 +1,8 @@
+.venv
+.git
+.env
+.env.*
+tests
+__pycache__
+.pytest_cache
+dist

python_platform/developer_kit/templates/project/{{cookiecutter.project_name}}/.env.jinja

@@ -0,0 +1,13 @@
+# 仅开发使用；由 pp new 随机生成。生产通过环境或挂载配置提供独立凭据。
+POSTGRES_IMAGE=postgres:18-bookworm
+REDIS_IMAGE=redis:7-bookworm
+POSTGRES_DB={{ cookiecutter.package_name }}
+POSTGRES_USER={{ cookiecutter.package_name }}
+POSTGRES_PASSWORD={{ cookiecutter.database_password }}
+POSTGRES_PORT=5432
+REDIS_PORT=6379
+PP_CONNECTION_STRINGS__DEFAULT=postgresql+asyncpg://{{ cookiecutter.package_name }}:{{ cookiecutter.database_password }}@127.0.0.1:5432/{{ cookiecutter.package_name }}
+PP_REDIS__URL=redis://127.0.0.1:6379/0
+PP_IDENTITY__KEYS__development={{ cookiecutter.jwt_key }}
+PP_IDENTITY__SEED_ADMIN_USERNAME=admin
+PP_IDENTITY__SEED_ADMIN_PASSWORD={{ cookiecutter.admin_password }}

python_platform/developer_kit/templates/project/{{cookiecutter.project_name}}/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.env
+.env.production
+dist/

python_platform/developer_kit/templates/project/{{cookiecutter.project_name}}/.python-version

@@ -0,0 +1 @@
+{{ cookiecutter.python_version }}

python_platform/developer_kit/templates/project/{{cookiecutter.project_name}}/Dockerfile

@@ -0,0 +1,22 @@
+# syntax=docker/dockerfile:1
+FROM debian:bookworm-slim AS build
+COPY --from=ghcr.io/astral-sh/uv:{{ cookiecutter.build_version }} /uv /usr/local/bin/uv
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates build-essential
+ENV UV_PYTHON_INSTALL_DIR=/opt/python UV_LINK_MODE=copy UV_COMPILE_BYTECODE=1
+WORKDIR /app
+COPY . .
+# Python 版本只从项目 .python-version 读取；PyPI 或 vendor wheel 均由 uv.lock 固定。
+RUN uv python install && uv sync --locked --no-default-groups --no-editable
+
+FROM debian:bookworm-slim AS runtime
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates libstdc++6 && useradd --create-home app
+COPY --from=build /opt/python /opt/python
+COPY --from=build /app/.venv /app/.venv
+COPY --from=build /app/pyproject.toml /app/app.yaml /app/
+WORKDIR /app
+ENV PATH="/app/.venv/bin:$PATH" {{ cookiecutter.host_environment_variable }}=production PYTHONUNBUFFERED=1
+RUN mkdir /app/.python-platform && chown app:app /app/.python-platform
+USER app
+EXPOSE 8000
+# 独立 access handler 会绕过安全 formatter；请求诊断由框架审计和追踪负责。
+CMD ["python", "-m", "host.main"]

python_platform/developer_kit/templates/project/{{cookiecutter.project_name}}/README.md

@@ -0,0 +1,86 @@
+# {{ cookiecutter.project_name }}
+
+纯 Host 骨架。`src/host` 负责 provider、配置及启动；`pp add module` 在 `src/modules` 生成六层业务。
+模块内 tests 不进入生产 wheel 或服务扫描，Host 集成验收放在根级 tests/host。
+
+## 开发次序
+
+```powershell
+uv run pp dev-init
+uv run pp add module orders
+uv run pp db upgrade --module identity
+uv run pp db upgrade --module settings
+uv run pp db upgrade --module auditing
+uv run pp db upgrade --module background_jobs
+uv run pp db revision --module orders
+# 人工审查 revision，尤其表/列改名、数据回填和外部依赖。
+uv run pp db upgrade --module orders
+uv run pp db status --module orders
+uv run pp db seed --module identity
+uv run pp db seed --module orders
+uv run pytest
+uv run pp dev
+```
+
+`dev-init` 只启动或复用开发 PostgreSQL／Redis，保留数据；不迁移、不 Seed。四个 db 命令必须指定
+`--module`，别名来自标准 entry point，目标来自真实 Module 声明。数据库命令不启动 Worker／HostedService，
+每个 Seed Contributor 独立事务。Host 启动同样不迁移、不 Seed。新增第二个模块时重复 add／revision／upgrade／seed。
+无关模块未升级不会阻塞当前模块；缺少前置迁移需先显式升级其 owner。自动生成只比较目标当前模型的表及字段，
+整表删除由开发者人工编写、审查其归属与数据影响。
+
+## 业务位置与调用
+
+- domain_shared：枚举、错误和权限名称；domain：聚合审批、事件、仓储契约、设置和幂等 Seed。
+- application_contracts：DTO 与服务契约；application：应用服务、提交后缓存失效／通知、Job／Cron／Worker 和线程集成。
+- sqlalchemy：模型、原生版本检查、仓储与迁移；http_api：自动服务暴露、上传／下载／流、Filter 和 WebSocket。
+- 打开 `/docs`，用 `.env` 中随机生成的管理员凭据调用 `/api/auth/login`，在 Authorize 填写 access token。
+  `/api/orders` 创建／查询；`/{id}/approve` 审批，非法 DTO 在业务前失败，旧版本返回 409。
+- `/api/orders/{id}/queue-approval` 在业务事务内入队；Job 对已审批状态保持幂等。Cron 每五分钟输出订单数量。
+  `/api/orders/files/upload` 使用 File／Form 及读取期限额；download、export/stream 在响应前完成短 UoW，
+  网络发送期间只持有不可变 DTO，断开后关闭 producer。
+- 使用 Bearer 认证连接 `/ws/orders`，先收到快照，发送 `{}` 刷新；同一 Host 审批后收到 changed 消息。
+  不承诺跨进程在线通知或跨进程本地事件。`/api/settings/orders.approval_enabled` 支持修改与 reset，刷新使用框架通知。
+- 审计、关联日志、tracing 使用框架默认管线；tracing 导出默认关闭，按环境配置启用已有 exporter。
+
+## 后台与配置
+
+模板 Worker 默认禁用。在模块 application/module.py 将 MAINTENANCE_WORKER 的 enabled 改为 true 后才执行。
+Worker 用 DistributedLock 取得业务锁，未取得时跳过；租约失效会取消本轮并等待清理，业务不得吞取消。
+BackgroundExecutionOptions.workers/jobs 按定义名称覆盖 mode：host、shared、exclusive；同逻辑 Job 所有版本共用位置。
+`/api/background/tasks` 由 background.view/manage 授权，POST start／stop 返回 202，继续查询状态；代码禁用不能从 HTTP 启用。
+停止 Job 保留排队数据。正式 Host 按目录／环境保持单实例，reload 等待旧进程实际退出，残留后台进程阻止新 Host。
+
+模块 Options 放在 app.yaml 对应模块名下，例如：
+
+```yaml
+orders:
+  allow_background_approval: false
+  integration_enabled: true
+```
+
+线程集成示例 start 先演示受控调用，再由外部线程 submit_call 使用同一 DI／调用管线；stop 等待线程退出。
+外部 SDK 的运行故障与恢复由 HostedService 自己管理。配置使用 app.yaml 与 app.<environment>.yaml；
+凭据放环境或 .env，不提交开发／生产密钥。
+
+## 打包与部署
+
+```powershell
+uv build --no-sources
+# APP_IMAGE 固定为验收过的同一镜像 digest，.env.production 使用独立凭据。
+docker build -t <application-image> .
+$env:MODULE = "orders"
+docker compose -f compose.production.yaml run --rm migrate
+docker compose -f compose.production.yaml up -d web
+```
+
+生产迁移按依赖顺序逐模块执行；Seed 独立使用 pp db seed --module <alias> --environment production。
+镜像入口 python -m host.main；健康端点 /health/live 与 /health/ready；SIGTERM 等待后台、HostedService、业务与 REQUEST 清理。
+版本、框架来源、构建工具版本和顶层包由标准项目 metadata 拥有。
+
+## 框架升级
+
+项目使用生成时 CLI 对应的框架精确版本，日常命令使用 `uv run pp`。
+升级前阅读目标框架版本 README，将运行依赖和 developer-kit 同时更新到目标版本，保留 extras。
+本地 wheel／旧 Git 项目首次转到 PyPI 时，仅移除 tool.uv.sources 的 python-platform 条目。
+执行 `uv lock --upgrade-package python-platform`、`uv sync --locked` 和项目原有验证。
+升级不重生成业务、Host 或模板；按框架升级说明手动迁移。全局 CLI 更新也不改变本项目版本。

python_platform/developer_kit/templates/project/{{cookiecutter.project_name}}/app.yaml.jinja

@@ -0,0 +1,16 @@
+identity:
+  issuer: "{{ cookiecutter.project_name }}"
+  audience: "{{ cookiecutter.project_name }}"
+  active_kid: development
+redis:
+  key_prefix: "{{ cookiecutter.project_name }}"
+logging:
+  application: "{{ cookiecutter.project_name }}"
+  environment: development
+  format: text
+  level: INFO
+tracing:
+  service_name: "{{ cookiecutter.project_name }}"
+  export_enabled: false
+pgqueuer_background_jobs:
+  connection_name: default

python_platform/developer_kit/templates/project/{{cookiecutter.project_name}}/compose.dev.yaml.jinja

@@ -0,0 +1,24 @@
+services:
+  postgres:
+    image: ${POSTGRES_IMAGE:?Set POSTGRES_IMAGE in .env}
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB}
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+    ports: ["127.0.0.1:${POSTGRES_PORT}:5432"]
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
+      interval: 2s
+      timeout: 2s
+      retries: 20
+    volumes: ["postgres-data:/var/lib/postgresql"]
+  redis:
+    image: ${REDIS_IMAGE:?Set REDIS_IMAGE in .env}
+    ports: ["127.0.0.1:${REDIS_PORT}:6379"]
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 2s
+      timeout: 2s
+      retries: 20
+volumes:
+  postgres-data:

python_platform/developer_kit/templates/project/{{cookiecutter.project_name}}/compose.production.yaml.jinja

@@ -0,0 +1,13 @@
+# APP_IMAGE 使用验收通过的同一 digest；显式选择模块迁移，成功后启动 Host。
+services:
+  migrate:
+    image: ${APP_IMAGE:?Provide the verified application image digest}
+    env_file: .env.production
+    command: ["pp", "db", "--environment", "production", "upgrade", "--module", "${MODULE:?Select the migration module alias}"]
+    profiles: ["operations"]
+  web:
+    image: ${APP_IMAGE:?Provide the verified application image digest}
+    env_file: .env.production
+    ports: ["${WEB_PORT:-8000}:8000"]
+    stop_grace_period: 45s
+    restart: unless-stopped

python_platform/developer_kit/templates/project/{{cookiecutter.project_name}}/pyproject.toml.jinja

@@ -0,0 +1,28 @@
+[project]
+name = "{{ cookiecutter.project_name }}"
+version = "0.1.0"
+requires-python = "=={{ cookiecutter.python_version }}"
+dependencies = ["python-platform[fastapi,identity,logging,postgresql,redis,tracing,background-jobs]=={{ cookiecutter.framework_version }}"]
+
+[project.entry-points."python_platform.hosts"]
+application = "host.main:create_application"
+web = "host.main:create_web"
+[dependency-groups]
+dev = ["python-platform[developer-kit]=={{ cookiecutter.framework_version }}", "pytest", "anyio", "testcontainers[postgres,redis]"]
+
+{% if cookiecutter.framework_source %}[tool.uv.sources]
+python-platform = {{ cookiecutter.framework_source }}
+{% endif %}
+[build-system]
+requires = ["uv_build=={{ cookiecutter.build_version }}"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "host"
+module-root = "src"
+wheel-exclude = ["**/tests/**"]
+
+[tool.pytest.ini_options]
+anyio_mode = "auto"
+testpaths = ["tests", "src/modules"]
+addopts = "--import-mode=importlib"

python_platform/developer_kit/templates/project/{{cookiecutter.project_name}}/src/host/__init__.py.jinja

@@ -0,0 +1 @@
+"""应用 composition root；业务代码由 pp add module 生成。"""

python_platform/developer_kit/templates/project/{{cookiecutter.project_name}}/src/host/main.py.jinja

@@ -0,0 +1,52 @@
+"""标准入口一次 build/start/stop；生产和开发使用同一 factory。"""
+
+import os
+from importlib.metadata import version
+from pathlib import Path
+
+from fastapi import FastAPI
+from starlette.middleware import Middleware
+from starlette.middleware.gzip import GZipMiddleware
+
+from python_platform import Application, ApplicationBuilder
+from python_platform.cli import ENVIRONMENT_VARIABLE
+from python_platform.fastapi import FastApiAdapter
+
+from .module import {{ cookiecutter.class_prefix }}HostModule
+
+
+def create_application(
+    *, environment: str | None = None, cli_args: tuple[str, ...] = ()
+) -> Application:
+    environment = environment or os.environ.get(ENVIRONMENT_VARIABLE, "development")
+    return ApplicationBuilder(
+        {{ cookiecutter.class_prefix }}HostModule,
+        environment=environment,
+        base_path=Path.cwd(),
+        env_prefix="PP_",
+        cli_args=cli_args,
+        dotenv_path=Path.cwd() / ".env" if environment == "development" else None,
+        explicit_overrides={
+            "logging": {
+                "environment": environment,
+                "format": "text" if environment == "development" else "json",
+            }
+        },
+    ).build()
+
+
+def create_web() -> FastAPI:
+    application = create_application()
+    # 全局 middleware 使用原生 Starlette 实现，在 adapter.install 前完成配置。
+    adapter = FastApiAdapter(application, middleware=(Middleware(GZipMiddleware),))
+    web = FastAPI(
+        title="{{ cookiecutter.project_name }}", version=version("{{ cookiecutter.project_name }}"), lifespan=adapter.lifespan
+    )
+    adapter.install(web)
+    return web
+
+
+if __name__ == "__main__":
+    from python_platform.fastapi.server import _run_host
+
+    _run_host("host.main:create_web", host="0.0.0.0", port=8000)

python_platform/developer_kit/templates/project/{{cookiecutter.project_name}}/src/host/module.py.jinja

@@ -0,0 +1,38 @@
+"""Host 只选择 provider 与组合 Module，不拥有业务规则。"""
+
+from dishka.integrations.fastapi import FastapiProvider
+
+from python_platform import AppModule, ConfigureContext
+from python_platform.auditing.sqlalchemy import SqlAlchemyAuditingModule
+from python_platform.background_jobs.pgqueuer import PgQueuerBackgroundJobsModule
+from python_platform.fastapi.background import BackgroundManagementHttpApiModule
+from python_platform.fastapi.settings import SettingsManagementHttpApiModule
+from python_platform.identity.http_api import IdentityHttpApiModule
+from python_platform.identity.sqlalchemy import SqlAlchemyIdentityModule
+from python_platform.observability.logging import StructuredLoggingModule
+from python_platform.observability.tracing import TracingModule
+from python_platform.redis import RedisDistributedLockModule, RedisModule
+from python_platform.redis.notifications import RedisNotificationsModule
+from python_platform.settings.notifications import SettingsNotificationsModule
+from python_platform.settings.sqlalchemy import SqlAlchemyRuntimeSettingsModule
+
+
+class {{ cookiecutter.class_prefix }}HostModule(AppModule):
+    dependencies = (
+        SqlAlchemyIdentityModule,
+        IdentityHttpApiModule,
+        SqlAlchemyAuditingModule,
+        SqlAlchemyRuntimeSettingsModule,
+        SettingsManagementHttpApiModule,
+        RedisModule,
+        RedisDistributedLockModule,
+        RedisNotificationsModule,
+        SettingsNotificationsModule,
+        PgQueuerBackgroundJobsModule,
+        BackgroundManagementHttpApiModule,
+        StructuredLoggingModule,
+        TracingModule,
+    )
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.services.contribute(FastapiProvider(), reason="Native HTTP request context")

python_platform/developer_kit/templates/project/{{cookiecutter.project_name}}/tests/conftest.py.jinja

@@ -0,0 +1,8 @@
+"""Host 验收使用 asyncio；业务模块测试位于模块内部。"""
+
+import pytest
+
+
+@pytest.fixture
+def anyio_backend():
+    return "asyncio"