python-ddd-framework 0.3.1__py3-none-any.whl

python_ddd_framework/developer_kit/project_metadata.py

@@ -0,0 +1,45 @@
+"""模块生成时维护标准打包与 entry point 声明，保留其他 TOML 内容。"""
+
+import json
+import re
+import tomllib
+
+from ..cli.errors import CommandError
+from ..cli.project import MODULE_ENTRY_POINT_GROUP
+
+
+def add_module_metadata(source: str, package: str, class_prefix: str) -> str:
+    project = tomllib.loads(source)
+    backend = project.get("tool", {}).get("uv", {}).get("build-backend", {})
+    names = backend.get("module-name")
+    if backend.get("module-root") != "src" or not isinstance(names, (str, list)):
+        raise CommandError("Module generation requires explicit uv module-root=src and module-name")
+    packages = [names] if isinstance(names, str) else list(names)
+    if "modules" not in packages:
+        packages.append("modules")
+    section = re.search(r"(?ms)^\[tool\.uv\.build-backend\][ \t]*\r?\n(.*?)(?=^\[|\Z)", source)
+    if section is None:
+        raise CommandError("Cannot locate uv build-backend table")
+    body, count = re.subn(
+        r'(?m)^module-name\s*=\s*(?:"[^"\n]*"|\[[^\]\n]*\])',
+        "module-name = " + json.dumps(packages),
+        section.group(1),
+    )
+    if count != 1:
+        raise CommandError("Keep module-name on one line to allow safe package wiring")
+    updated = source[: section.start(1)] + body + source[section.end(1) :]
+    entries = project["project"].get("entry-points", {}).get(MODULE_ENTRY_POINT_GROUP, {})
+    if package in entries:
+        raise CommandError(f"Module alias already exists: {package}")
+    header = f'[project.entry-points."{MODULE_ENTRY_POINT_GROUP}"]'
+    declaration = (
+        f'{package} = "modules.{package}.sqlalchemy.module:{class_prefix}SqlAlchemyModule"\n'
+    )
+    if MODULE_ENTRY_POINT_GROUP in project["project"].get("entry-points", {}):
+        if header not in updated:
+            raise CommandError("Module entry point table must use the standard quoted group name")
+        updated = updated.replace(header, header + "\n" + declaration, 1)
+    else:
+        updated += "\n" + header + "\n" + declaration
+    tomllib.loads(updated)
+    return updated

python_ddd_framework/developer_kit/source.py

@@ -0,0 +1,53 @@
+"""生成项目固定 CLI 版本；只有显式本地 wheel 才覆盖标准索引来源。"""
+
+from __future__ import annotations
+
+import importlib.metadata as metadata
+import json
+import zipfile
+from dataclasses import dataclass
+from email.parser import Parser
+from pathlib import Path
+
+from ..cli.errors import CommandError
+
+
+@dataclass(frozen=True, slots=True)
+class FrameworkSource:
+    version: str
+    uv_source: str
+    wheel: Path | None = None
+
+
+def framework_source(wheel: Path | None) -> FrameworkSource:
+    distribution = metadata.distribution("python-ddd-framework")
+    if wheel is not None:
+        source = _wheel_source(wheel)
+        if source.version != distribution.version:
+            raise CommandError(
+                "Framework wheel version must match the CLI and its bundled templates"
+            )
+        return source
+    # 安装来源不拥有生成项目的依赖契约；Git/editable CLI 也必须显式选择本地 wheel。
+    return FrameworkSource(distribution.version, "")
+
+
+def _wheel_source(path: Path) -> FrameworkSource:
+    wheel = path.resolve()
+    if not wheel.is_file() or wheel.suffix != ".whl":
+        raise CommandError("--framework-wheel must identify an existing wheel")
+    try:
+        with zipfile.ZipFile(wheel) as archive:
+            members = [name for name in archive.namelist() if name.endswith(".dist-info/METADATA")]
+            if len(members) != 1:
+                raise CommandError(
+                    "Framework wheel must have exactly one distribution metadata file"
+                )
+            document = Parser().parsestr(archive.read(members[0]).decode("utf-8"))
+    except (OSError, ValueError, zipfile.BadZipFile):
+        raise CommandError("Cannot read framework wheel metadata") from None
+    if document["Name"] != "python-ddd-framework" or not document["Version"]:
+        raise CommandError("Wheel must contain the python-ddd-framework distribution")
+    return FrameworkSource(
+        document["Version"], f"{{ path = {json.dumps('vendor/' + wheel.name)} }}", wheel
+    )

python_ddd_framework/developer_kit/templates/module/cookiecutter.json

@@ -0,0 +1 @@
+{"module_name": "orders", "class_prefix": "Orders"}

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/README.md

@@ -0,0 +1,70 @@
+# {{ cookiecutter.module_name }} module
+
+This module was generated by `pddd add module`. It contains an order-management example to demonstrate the framework's boundaries. The module name does not establish business requirements: replace the example with the application's confirmed domain and keep this document current.
+
+[Application setup](../../../README.md) · [Architecture](../../../docs/architecture.md) · [Development guide](../../../docs/development.md) · [Working rules](../../../AGENTS.md)
+
+## Ownership and entry points
+
+| Concern | Source |
+| --- | --- |
+| Shared names, errors, permissions, and message types | [Shared definitions](domain_shared/definitions.py) and [permission definitions](domain_shared/permissions.py) |
+| Aggregate rules and events | [Order aggregate](domain/orders.py) |
+| Repository contract and runtime setting | [Repository](domain/repository.py) and [settings](domain/settings.py) |
+| DTOs and public service contract | [Application contracts](application_contracts/orders.py) |
+| Use cases and policies | [Application service](application/orders.py) |
+| Events, jobs, workers, and hosted integration example | [Event handlers](application/events.py), [tasks](application/tasks.py), and [integration](application/integration.py) |
+| ORM, repositories, and migration registration | [Models](sqlalchemy/models/orders.py), [repository implementation](sqlalchemy/repositories/orders.py), and [persistence module](sqlalchemy/module.py) |
+| HTTP exposure, file transfer, and WebSocket | [HTTP module](http_api/module.py), [files](http_api/files.py), and [real-time endpoint](http_api/realtime.py) |
+
+The Host selects this module's application, SQLAlchemy, and HTTP modules. Other modules consume its public contract with an explicit dependency; they do not import its concrete repository or query its tables. Source declarations own the actual Module graph, table names, permission names, and routes.
+
+## Current example behavior
+
+- An order has a validated title and moves from pending to approved. Repeated direct approval is rejected. Shared constraints and errors are declared in `domain_shared/definitions.py`.
+- The public `{{ cookiecutter.class_prefix }}ApplicationService` contract supports create, get, list, approve, and queued approval. Approval accepts an expected version; repository and database checks protect competing writes.
+- Read and write permissions are defined by the module. Approval also reads the module's runtime setting; queued approval additionally uses its startup Options. Keep these choices separate when changing policy.
+- Writes stage aggregate events through the repository. AFTER_COMMIT handlers invalidate the typed cache and send a notification to the initiating user when that identity is available. A notification failure does not undo the database commit.
+- `ApprovalJob` carries an `order_id` and safely ignores orders that are missing or already approved. Both periodic example workers are code-disabled by default. The hosted integration example is opt-in and is not registered initially.
+- The authenticated WebSocket at `/ws/{{ cookiecutter.module_name }}` sends a snapshot and accepts `{}` to refresh. Online notifications have no cross-process backplane or offline replay. File upload/download/stream examples share the public service boundary.
+
+Use the generated application's `/docs` for the current HTTP paths and payloads. Change business rules only from confirmed requirements; update their aggregate, service policy, persistence, and verification owners together.
+
+## Database and configuration
+
+After initializing the framework providers as described in the application README, run these commands from the application root:
+
+```sh
+uv run pddd db revision --module {{ cookiecutter.module_name }}
+```
+
+Review the generated revision before applying it, then run:
+
+```sh
+uv run pddd db upgrade --module {{ cookiecutter.module_name }}
+uv run pddd db status --module {{ cookiecutter.module_name }}
+uv run pddd db seed --module {{ cookiecutter.module_name }}
+```
+
+The module owns its models and migration package. Keep applied revisions immutable and upgrade external prerequisites explicitly. Seeding this module does not seed identity or migrate the schema on its behalf.
+
+Startup options are declared in [application/options.py](application/options.py) and bound to the `{{ cookiecutter.module_name }}` YAML section. For example:
+
+```yaml
+{{ cookiecutter.module_name }}:
+  allow_background_approval: false
+```
+
+Runtime setting definitions remain in `domain/settings.py`; query the current version token before a conditional update or reset. Do not copy permission, setting, queue, or database identities into a second registry.
+
+## Verification and maintenance
+
+Run the existing domain test from the application root:
+
+```sh
+uv run pytest src/modules/{{ cookiecutter.module_name }}/tests
+```
+
+This test covers the sample aggregate's approval behavior. It does not prove HTTP authorization, database concurrency, jobs, Redis, WebSocket delivery, or deployment behavior. Add focused coverage as the application implements those requirements; root Host tests cover the generic Host boundary.
+
+When changing this module, update the sections affected by its responsibilities, public contract, business invariants, persistence, background work, or validation scope. Add a more specific `AGENTS.md` only if the module needs distinct working rules; shared development instructions belong at the application root.

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

@@ -0,0 +1 @@
+"""{{ cookiecutter.class_prefix }} 业务模块；各层通过正式 Module 组合。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/__init__.py.jinja

@@ -0,0 +1 @@
+"""应用编排、提交后处理及后台业务，不依赖具体数据库或 Host。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/cache.py.jinja

@@ -0,0 +1,10 @@
+"""缓存契约只声明一次；提交后处理负责失效。"""
+
+from datetime import timedelta
+
+from python_ddd_framework.caching import CacheDefinition
+
+from ..application_contracts.orders import OrderView
+from ..domain_shared.definitions import MODULE_NAME
+
+ORDER_CACHE = CacheDefinition(f"{MODULE_NAME}.view", OrderView, ttl=timedelta(minutes=1))

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/events.py.jinja

@@ -0,0 +1,24 @@
+"""提交后失效缓存与通知；失败不伪装成数据库未提交，不承诺跨进程事件投递。"""
+
+from python_ddd_framework import LocalEventPhase, local_event_handler
+from python_ddd_framework.caching import DistributedCache
+from python_ddd_framework.realtime import RealtimePublisher
+
+from ..domain.orders import OrderChanged
+from ..domain_shared.definitions import ORDER_CHANGED_MESSAGE
+from .cache import ORDER_CACHE
+
+
+@local_event_handler(phase=LocalEventPhase.AFTER_COMMIT)
+class OrderChangedHandler:
+    def __init__(self, cache: DistributedCache, realtime: RealtimePublisher) -> None:
+        self._cache, self._realtime = cache, realtime
+
+    async def handle(self, event: OrderChanged) -> None:
+        await self._cache.remove(ORDER_CACHE, str(event.order_id))
+        if event.user_id is not None:
+            await self._realtime.send_to_user(
+                event.user_id,
+                message_type=ORDER_CHANGED_MESSAGE,
+                payload={"id": str(event.order_id), "status": event.status.value},
+            )

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/integration.py.jinja

@@ -0,0 +1,41 @@
+"""可选外部线程集成示例；替换线程生产逻辑即可接入 SDK，不另建容器或任务执行器。"""
+
+import asyncio
+import logging
+from threading import Event, Thread
+
+from python_ddd_framework import (
+    HostedService,
+    HostedServiceContext,
+    HostedServiceInvocationRejectedError,
+    ShutdownReason,
+)
+
+
+async def observe_integration() -> None:
+    logging.getLogger(__name__).info("External integration callback received")
+
+
+class OrderIntegrationService(HostedService):
+    def __init__(self) -> None:
+        self._stop = Event()
+        self._thread: Thread | None = None
+
+    async def start(self, context: HostedServiceContext) -> None:
+        await context.call(observe_integration)
+        self._thread = Thread(target=self._receive, args=(context,), name=__name__)
+        self._thread.start()
+
+    def _receive(self, context: HostedServiceContext) -> None:
+        # submit_call 只能来自外部线程；Future.result 等待同一正式 invocation 完成。
+        try:
+            context.submit_call(observe_integration).result()
+        except HostedServiceInvocationRejectedError:
+            return  # Application 关闭已撤销调用许可。
+        self._stop.wait()
+
+    async def stop(self, reason: ShutdownReason) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            await asyncio.to_thread(self._thread.join)
+            self._thread = None

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/module.py.jinja

@@ -0,0 +1,20 @@
+"""模块贡献自己的服务与任务；provider 选择留给 Host。"""
+
+from python_ddd_framework import AppModule, ConfigureContext
+
+from ..application_contracts.module import {{ cookiecutter.class_prefix }}ApplicationContractsModule
+from ..domain.module import {{ cookiecutter.class_prefix }}DomainModule
+from ..domain_shared.definitions import MODULE_NAME
+from .cache import ORDER_CACHE
+from .options import {{ cookiecutter.class_prefix }}Options
+from .tasks import OrderMaintenanceWorker, OrderStatisticsWorker
+
+
+class {{ cookiecutter.class_prefix }}ApplicationModule(AppModule):
+    dependencies = ({{ cookiecutter.class_prefix }}DomainModule, {{ cookiecutter.class_prefix }}ApplicationContractsModule)
+    scan_packages = (__package__,)
+    cache_definitions = (ORDER_CACHE,)
+    background_workers = (OrderStatisticsWorker, OrderMaintenanceWorker)
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.configure({{ cookiecutter.class_prefix }}Options, section=MODULE_NAME)

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/options.py.jinja

@@ -0,0 +1,7 @@
+"""typed 业务配置；从本模块 YAML 节读取，非法值在 build 失败。"""
+
+from python_ddd_framework import BaseOptions
+
+
+class {{ cookiecutter.class_prefix }}Options(BaseOptions):
+    allow_background_approval: bool = True

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/orders.py.jinja

@@ -0,0 +1,83 @@
+"""正式应用服务共用验证、授权、审计和 UoW；业务层不接触框架执行器。"""
+
+import logging
+from uuid import UUID, uuid4
+
+from python_ddd_framework import ApplicationService, CurrentUser
+from python_ddd_framework.authorization import authorize
+from python_ddd_framework.background_jobs import BackgroundJobEnqueuer
+from python_ddd_framework.caching import DistributedCache
+from python_ddd_framework.errors import BusinessError
+from python_ddd_framework.errors.base import ResourceConflictError, ResourceNotFoundError
+from python_ddd_framework.fastapi import http
+
+from ..application_contracts.orders import (
+{%- for contract in ["ApproveOrder", "CreateOrder", "OrderView", cookiecutter.class_prefix ~ "ApplicationService"] | sort %}
+    {{ contract }},
+{%- endfor %}
+)
+from ..domain.orders import Order, OrderTitle
+from ..domain.repository import OrderRepository
+from ..domain.settings import APPROVAL_ENABLED
+from ..domain_shared.definitions import APPROVAL_DISABLED, ORDERS_READ, ORDERS_WRITE
+from .cache import ORDER_CACHE
+from .tasks import ApprovalJob, ApprovalPayload
+
+logger = logging.getLogger(__name__)
+
+
+class _{{ cookiecutter.class_prefix }}ApplicationService(ApplicationService, {{ cookiecutter.class_prefix }}ApplicationService):
+    def __init__(
+        self,
+        repository: OrderRepository,
+        cache: DistributedCache,
+        jobs: BackgroundJobEnqueuer,
+        user: CurrentUser,
+    ) -> None:
+        self._repository, self._cache, self._jobs, self._user = repository, cache, jobs, user
+
+    @authorize(ORDERS_WRITE)
+    @http.post(status_code=201)
+    async def create(self, command: CreateOrder) -> OrderView:
+        order = Order.create(uuid4(), OrderTitle(value=command.title))
+        await self._repository.save(order)
+        logger.info("Order created")
+        return OrderView.model_validate(order)
+
+    @authorize(ORDERS_READ)
+    async def get(self, id: UUID) -> OrderView:
+        cached = await self._cache.get(ORDER_CACHE, str(id))
+        if cached is not None:
+            return cached
+        order = await self._repository.get(id)
+        if order is None:
+            raise ResourceNotFoundError("Order not found")
+        view = OrderView.model_validate(order)
+        await self._cache.set(ORDER_CACHE, str(id), view)
+        return view
+
+    @authorize(ORDERS_READ)
+    async def get_list(self) -> tuple[OrderView, ...]:
+        return tuple(OrderView.model_validate(order) for order in await self._repository.get_list())
+
+    @authorize(ORDERS_WRITE)
+    async def approve(self, id: UUID, command: ApproveOrder) -> OrderView:
+        if not await self.setting_provider.get(APPROVAL_ENABLED):
+            raise BusinessError(APPROVAL_DISABLED)
+        order = await self._repository.get(id)
+        if order is None:
+            raise ResourceNotFoundError("Order not found")
+        if order.version != command.expected_version:
+            raise ResourceConflictError("Order version changed")
+        order.approve(user_id=self._user.user_id)
+        await self._repository.save(order)
+        logger.info("Order approved")
+        return OrderView.model_validate(order)
+
+    @authorize(ORDERS_WRITE)
+    @http.post(status_code=202)
+    async def queue_approval(self, id: UUID) -> str:
+        if await self._repository.get(id) is None:
+            raise ResourceNotFoundError("Order not found")
+        # 入队参与本方法原生事务；失败时订单业务与队列写入一起回滚。
+        return await self._jobs.enqueue(ApprovalJob, ApprovalPayload(order_id=id))

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/tasks.py.jinja

@@ -0,0 +1,84 @@
+"""非持久 Worker 与持久 Job 分开；Job 重复投递由业务状态保证幂等。"""
+
+import logging
+from datetime import timedelta
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict
+from python_ddd_framework import (
+    BackgroundWorker,
+    BackgroundWorkerContext,
+    Options,
+)
+from python_ddd_framework.background_jobs import (
+    BackgroundJobContext,
+    BackgroundJobHandler,
+)
+from python_ddd_framework.distributed_lock import DistributedLock
+from python_ddd_framework.settings import SettingProvider
+
+from ..domain.repository import OrderRepository
+from ..domain.settings import APPROVAL_ENABLED
+from ..domain_shared.definitions import MODULE_NAME, OrderStatus
+from .options import {{ cookiecutter.class_prefix }}Options
+
+logger = logging.getLogger(__name__)
+
+
+class ApprovalPayload(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    order_id: UUID
+
+
+class ApprovalJob(BackgroundJobHandler[ApprovalPayload]):
+    name = f"{MODULE_NAME}.approve"
+    version = 1
+    current = True
+    timeout = timedelta(seconds=30)
+
+    def __init__(
+        self,
+        repository: OrderRepository,
+        settings: SettingProvider,
+        options: Options[{{ cookiecutter.class_prefix }}Options],
+    ) -> None:
+        self._repository, self._settings, self._options = repository, settings, options
+
+    async def execute(self, payload: ApprovalPayload, context: BackgroundJobContext) -> None:
+        if self._options.value.allow_background_approval and await self._settings.get(
+            APPROVAL_ENABLED
+        ):
+            order = await self._repository.get(payload.order_id)
+            if order is not None and order.status is OrderStatus.PENDING:
+                order.approve()
+                await self._repository.save(order)
+
+
+class OrderMaintenanceWorker(BackgroundWorker):
+    name = f"{MODULE_NAME}.maintenance"
+    enabled = False
+    interval = timedelta(seconds=30)
+    iteration_timeout = timedelta(seconds=10)
+
+    def __init__(self, repository: OrderRepository, lock: DistributedLock) -> None:
+        self._repository, self._lock = repository, lock
+
+    async def run_iteration(self, context: BackgroundWorkerContext) -> None:
+        # 租约失效由框架请求取消并等待本轮清理；业务不吞 CancelledError。
+        async with self._lock.acquire(f"{MODULE_NAME}:maintenance") as acquired:
+            if acquired:
+                orders = await self._repository.get_list()
+                logger.info("Order maintenance completed: %s", len(orders))
+
+
+class OrderStatisticsWorker(BackgroundWorker):
+    name = f"{MODULE_NAME}.statistics"
+    enabled = False
+    interval = timedelta(minutes=5)
+    iteration_timeout = timedelta(seconds=10)
+
+    def __init__(self, repository: OrderRepository) -> None:
+        self._repository = repository
+
+    async def run_iteration(self, context: BackgroundWorkerContext) -> None:
+        logger.info("Order count: %s", len(await self._repository.get_list()))

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/__init__.py.jinja

@@ -0,0 +1 @@
+"""供调用者使用的 DTO 和服务契约。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/module.py.jinja

@@ -0,0 +1,10 @@
+"""契约层不反向依赖应用实现或 provider。"""
+
+from python_ddd_framework import AppModule
+
+from ..domain_shared.module import {{ cookiecutter.class_prefix }}DomainSharedModule
+
+
+class {{ cookiecutter.class_prefix }}ApplicationContractsModule(AppModule):
+    dependencies = ({{ cookiecutter.class_prefix }}DomainSharedModule,)
+    scan_packages = (__package__,)

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/orders.py.jinja

@@ -0,0 +1,35 @@
+"""DTO 只依赖共享定义；HTTP 与进程内调用共用同一验证管线。"""
+
+from typing import Protocol
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+from python_ddd_framework import ApplicationServiceContract
+
+from ..domain_shared.definitions import TITLE_MAX_LENGTH, OrderStatus
+
+
+class CreateOrder(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    title: str = Field(min_length=1, max_length=TITLE_MAX_LENGTH)
+
+
+class ApproveOrder(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    expected_version: int = Field(ge=1)
+
+
+class OrderView(BaseModel):
+    model_config = ConfigDict(frozen=True, from_attributes=True)
+    id: UUID
+    title: str
+    status: OrderStatus
+    version: int
+
+
+class {{ cookiecutter.class_prefix }}ApplicationService(ApplicationServiceContract, Protocol):
+    async def create(self, command: CreateOrder) -> OrderView: ...
+    async def get(self, id: UUID) -> OrderView: ...
+    async def get_list(self) -> tuple[OrderView, ...]: ...
+    async def approve(self, id: UUID, command: ApproveOrder) -> OrderView: ...
+    async def queue_approval(self, id: UUID) -> str: ...

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/__init__.py.jinja

@@ -0,0 +1 @@
+"""聚合、仓储契约、设置定义与幂等 Seed。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/module.py.jinja

@@ -0,0 +1,10 @@
+"""扫描仅包含实际业务声明，模块 tests 不参与服务发现。"""
+
+from python_ddd_framework import AppModule
+
+from ..domain_shared.module import {{ cookiecutter.class_prefix }}DomainSharedModule
+
+
+class {{ cookiecutter.class_prefix }}DomainModule(AppModule):
+    dependencies = ({{ cookiecutter.class_prefix }}DomainSharedModule,)
+    scan_packages = (__package__,)

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/orders.py.jinja

@@ -0,0 +1,56 @@
+"""聚合拥有审批规则、版本及事件；持久化实现只负责映射。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from uuid import UUID
+
+from pydantic import Field
+from python_ddd_framework import AggregateRoot, ValueObject
+from python_ddd_framework.errors import BusinessError
+
+from ..domain_shared.definitions import ALREADY_APPROVED, TITLE_MAX_LENGTH, OrderStatus
+
+
+class OrderTitle(ValueObject):
+    value: str = Field(min_length=1, max_length=TITLE_MAX_LENGTH)
+
+
+@dataclass(frozen=True)
+class OrderChanged:
+    order_id: UUID
+    status: OrderStatus
+    user_id: UUID | None = None
+
+
+class Order(AggregateRoot[UUID]):
+    def __init__(
+        self,
+        id: UUID,
+        title: OrderTitle,
+        *,
+        status: OrderStatus = OrderStatus.PENDING,
+        version: int = 0,
+    ) -> None:
+        super().__init__(id, version=version)
+        self._title, self._status = title, status
+
+    @property
+    def title(self) -> str:
+        return self._title.value
+
+    @property
+    def status(self) -> OrderStatus:
+        return self._status
+
+    @classmethod
+    def create(cls, id: UUID, title: OrderTitle) -> Order:
+        order = cls(id, title)
+        order.raise_local_event(OrderChanged(id, order.status))
+        return order
+
+    def approve(self, *, user_id: UUID | None = None) -> None:
+        if self.status is OrderStatus.APPROVED:
+            raise BusinessError(ALREADY_APPROVED)
+        self._status = OrderStatus.APPROVED
+        self.raise_local_event(OrderChanged(self.id, self.status, user_id))

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/repository.py.jinja

@@ -0,0 +1,14 @@
+"""领域需要的业务仓储边界；不暴露 Session 或容器。"""
+
+from typing import Protocol
+from uuid import UUID
+
+from python_ddd_framework import RepositoryContract
+
+from .orders import Order
+
+
+class OrderRepository(RepositoryContract, Protocol):
+    async def get(self, id: UUID) -> Order | None: ...
+    async def get_list(self) -> tuple[Order, ...]: ...
+    async def save(self, order: Order) -> None: ...

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/seeding.py.jinja

@@ -0,0 +1,19 @@
+"""仅 pddd db seed 显式调用；确定性业务 ID 保证重复初始化不产生新订单。"""
+
+from uuid import NAMESPACE_URL, uuid5
+
+from python_ddd_framework import DataSeedContributor
+
+from ..domain_shared.definitions import MODULE_NAME
+from .orders import Order, OrderTitle
+from .repository import OrderRepository
+
+
+class {{ cookiecutter.class_prefix }}SeedContributor(DataSeedContributor):
+    def __init__(self, repository: OrderRepository) -> None:
+        self._repository = repository
+
+    async def seed(self) -> None:
+        id = uuid5(NAMESPACE_URL, f"{MODULE_NAME}:sample-order")
+        if await self._repository.get(id) is None:
+            await self._repository.save(Order.create(id, OrderTitle(value="Sample order")))

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/settings.py.jinja

@@ -0,0 +1,16 @@
+"""设置默认值属于领域，业务通过 SettingProvider 获取冻结读取视图。"""
+
+from python_ddd_framework.settings import (
+    SettingDefinition,
+    SettingDefinitionContext,
+    SettingDefinitionProvider,
+)
+
+from ..domain_shared.definitions import MODULE_NAME
+
+APPROVAL_ENABLED = SettingDefinition(f"{MODULE_NAME}.approval_enabled", bool, default=True)
+
+
+class {{ cookiecutter.class_prefix }}SettingDefinitionProvider(SettingDefinitionProvider):
+    def define(self, context: SettingDefinitionContext) -> None:
+        context.add(APPROVAL_ENABLED)

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/__init__.py.jinja

@@ -0,0 +1 @@
+"""业务共享定义，不依赖应用编排或 provider。"""