python-platform 0.1.1__py3-none-any.whl

python_platform/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_platform/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-platform")
+    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-platform" or not document["Version"]:
+        raise CommandError("Wheel must contain the python-platform distribution")
+    return FrameworkSource(
+        document["Version"], f"{{ path = {json.dumps('vendor/' + wheel.name)} }}", wheel
+    )

python_platform/developer_kit/templates/module/cookiecutter.json

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

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

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

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

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

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

@@ -0,0 +1,10 @@
+"""缓存契约只声明一次；提交后处理负责失效。"""
+
+from datetime import timedelta
+
+from python_platform.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_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/application/events.py.jinja

@@ -0,0 +1,24 @@
+"""提交后失效缓存与通知；失败不伪装成数据库未提交，不承诺跨进程事件投递。"""
+
+from python_platform import LocalEventPhase, local_event_handler
+from python_platform.caching import DistributedCache
+from python_platform.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_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/application/integration.py.jinja

@@ -0,0 +1,46 @@
+"""可选外部线程集成示例；替换线程生产逻辑即可接入 SDK，不另建容器或任务执行器。"""
+
+import asyncio
+import logging
+from threading import Event, Thread
+
+from python_platform import (
+    HostedService,
+    HostedServiceContext,
+    HostedServiceInvocationRejectedError,
+    Options,
+    ShutdownReason,
+)
+
+from .options import {{ cookiecutter.class_prefix }}Options
+
+
+async def observe_integration() -> None:
+    logging.getLogger(__name__).info("External integration callback received")
+
+
+class OrderIntegrationService(HostedService):
+    def __init__(self, options: Options[{{ cookiecutter.class_prefix }}Options]) -> None:
+        self._options = options
+        self._stop = Event()
+        self._thread: Thread | None = None
+
+    async def start(self, context: HostedServiceContext) -> None:
+        if self._options.value.integration_enabled:
+            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_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/application/module.py.jinja

@@ -0,0 +1,29 @@
+"""模块贡献自己的服务与任务；provider 选择留给 Host。"""
+
+from python_platform import AppModule, BackgroundExecutionOptions, 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 .integration import OrderIntegrationService
+from .options import {{ cookiecutter.class_prefix }}Options
+from .tasks import APPROVE_JOB, MAINTENANCE_WORKER, ORDER_SCHEDULE
+
+
+class {{ cookiecutter.class_prefix }}ApplicationModule(AppModule):
+    dependencies = ({{ cookiecutter.class_prefix }}DomainModule, {{ cookiecutter.class_prefix }}ApplicationContractsModule)
+    scan_packages = (__package__ + ".orders", __package__ + ".events")
+    cache_definitions = (ORDER_CACHE,)
+    background_job_definitions = (APPROVE_JOB,)
+    background_job_schedules = (ORDER_SCHEDULE,)
+    background_worker_definitions = (MAINTENANCE_WORKER,)
+    hosted_services = (OrderIntegrationService,)
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.configure({{ cookiecutter.class_prefix }}Options, section=MODULE_NAME)
+        # Worker 默认禁用；开发者显式改为 true 后才运行。
+        context.configure(
+            BackgroundExecutionOptions,
+            values={"workers": {MAINTENANCE_WORKER.name: {"enabled": False}}},
+        )

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

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

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

@@ -0,0 +1,81 @@
+"""正式应用服务共用验证、授权、审计和 UoW；业务层不接触框架执行器。"""
+
+import logging
+from uuid import UUID, uuid4
+
+from python_platform import ApplicationService, CurrentUser
+from python_platform.authorization import authorize
+from python_platform.background_jobs import BackgroundJobEnqueuer
+from python_platform.caching import DistributedCache
+from python_platform.errors import BusinessError
+from python_platform.errors.base import ResourceConflictError, ResourceNotFoundError
+
+from ..application_contracts.orders import (
+    ApproveOrder,
+    CreateOrder,
+    {{ cookiecutter.class_prefix }}ApplicationService,
+    OrderView,
+)
+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 APPROVE_JOB, 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)
+    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)
+    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(APPROVE_JOB, ApprovalPayload(order_id=id))

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

@@ -0,0 +1,86 @@
+"""非持久 Worker 与持久 Job 分开；Job 重复投递由业务状态保证幂等。"""
+
+import logging
+from datetime import timedelta
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict
+
+from python_platform import (
+    BackgroundWorker,
+    BackgroundWorkerContext,
+    BackgroundWorkerDefinition,
+    Options,
+)
+from python_platform.background_jobs import (
+    BackgroundJobContext,
+    BackgroundJobDefinition,
+    BackgroundJobHandler,
+    BackgroundJobSchedule,
+)
+from python_platform.distributed_lock import DistributedLock
+from python_platform.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 | None = None
+
+
+class ApprovalJob(BackgroundJobHandler[ApprovalPayload]):
+    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 payload.order_id is None:
+            logger.info("Scheduled order count: %s", len(await self._repository.get_list()))
+            return
+        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):
+    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))
+
+
+APPROVE_JOB = BackgroundJobDefinition(
+    f"{MODULE_NAME}.approve", 1, ApprovalPayload, ApprovalJob, timedelta(seconds=30), current=True
+)
+ORDER_SCHEDULE = BackgroundJobSchedule(
+    f"{MODULE_NAME}.summary",
+    "*/5 * * * *",
+    APPROVE_JOB.name,
+    APPROVE_JOB.version,
+    ApprovalPayload().model_dump_json().encode(),
+)
+MAINTENANCE_WORKER = BackgroundWorkerDefinition(
+    f"{MODULE_NAME}.maintenance",
+    OrderMaintenanceWorker,
+    timedelta(seconds=30),
+    timedelta(seconds=10),
+)

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

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

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

@@ -0,0 +1,10 @@
+"""契约层不反向依赖应用实现或 provider。"""
+
+from python_platform 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__ + ".orders",)

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

@@ -0,0 +1,36 @@
+"""DTO 只依赖共享定义；HTTP 与进程内调用共用同一验证管线。"""
+
+from typing import Protocol
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from python_platform 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_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/__init__.py.jinja

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

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

@@ -0,0 +1,10 @@
+"""扫描仅包含实际业务声明，模块 tests 不参与服务发现。"""
+
+from python_platform 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__ + ".settings", __package__ + ".seeding")

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

@@ -0,0 +1,57 @@
+"""聚合拥有审批规则、版本及事件；持久化实现只负责映射。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from uuid import UUID
+
+from pydantic import Field
+
+from python_platform import AggregateRoot, ValueObject
+from python_platform.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_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/repository.py.jinja

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

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

@@ -0,0 +1,19 @@
+"""仅 pp db seed 显式调用；确定性业务 ID 保证重复初始化不产生新订单。"""
+
+from uuid import NAMESPACE_URL, uuid5
+
+from python_platform 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_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/settings.py.jinja

@@ -0,0 +1,16 @@
+"""设置默认值属于领域，业务通过 SettingProvider 获取冻结读取视图。"""
+
+from python_platform.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_platform/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/__init__.py.jinja

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

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

@@ -0,0 +1,24 @@
+"""修改业务名称、权限和约束的单一位置。"""
+
+from enum import Enum
+
+from python_platform import PermissionName
+from python_platform.errors import BusinessErrorDefinition
+
+MODULE_NAME = "{{ cookiecutter.module_name }}"
+ORDER_CHANGED_MESSAGE = f"{MODULE_NAME}.changed.v1"
+ORDER_SNAPSHOT_MESSAGE = f"{MODULE_NAME}.snapshot.v1"
+TITLE_MAX_LENGTH = 120
+ORDERS_READ = PermissionName(f"{MODULE_NAME}.read")
+ORDERS_WRITE = PermissionName(f"{MODULE_NAME}.write")
+ALREADY_APPROVED = BusinessErrorDefinition(
+    f"{MODULE_NAME}.already_approved", "Order is already approved"
+)
+APPROVAL_DISABLED = BusinessErrorDefinition(
+    f"{MODULE_NAME}.approval_disabled", "Order approval is disabled"
+)
+
+
+class OrderStatus(str, Enum):
+    PENDING = "pending"
+    APPROVED = "approved"

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

@@ -0,0 +1,7 @@
+"""共享层只发布业务常量与权限，不引用基础设施。"""
+
+from python_platform import AppModule
+
+
+class {{ cookiecutter.class_prefix }}DomainSharedModule(AppModule):
+    scan_packages = (__package__ + ".permissions",)

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

@@ -0,0 +1,15 @@
+"""权限名称由共享定义拥有；Provider 仅发布定义。"""
+
+from python_platform import (
+    PermissionDefinition,
+    PermissionDefinitionContext,
+    PermissionDefinitionProvider,
+)
+
+from .definitions import ORDERS_READ, ORDERS_WRITE
+
+
+class {{ cookiecutter.class_prefix }}PermissionDefinitionProvider(PermissionDefinitionProvider):
+    def define(self, context: PermissionDefinitionContext) -> None:
+        context.add(PermissionDefinition(ORDERS_READ, "Read orders"))
+        context.add(PermissionDefinition(ORDERS_WRITE, "Create and approve orders"))

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

@@ -0,0 +1 @@
+"""HTTP adapter 只依赖服务契约，不反向导入 application 或 sqlalchemy。"""