stapel-orders 0.1.0__py3-none-any.whl

stapel_orders/CONFIG.MD

@@ -0,0 +1,27 @@
+# CONFIG.MD — stapel-orders
+
+Config registry for **stapel-orders**. One row per configuration key the
+module reads, its **source** (`env` = the process environment / the
+`STAPEL_ORDERS` settings dict), what it is for, whether it is required, and
+its default.
+
+Every key is read through `orders_settings` (`stapel_orders.conf`, namespace
+`STAPEL_ORDERS`). Resolution order per key: `settings.STAPEL_ORDERS` dict →
+a flat Django setting of the same name → environment variable → the default
+below. `CHECKOUT_REQUIRES_ACCOUNT` and `PAYMENT` are CTO-facing config axes.
+
+## stapel-orders
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| PURCHASABLE_TYPES | settings | what can be bought: {type_name: {"resolve": "<comm function>"}} merged over the empty built-ins; None removes a type. Empty is system check E001. | yes | {} |
+| CHECKOUT_REQUIRES_ACCOUNT | env | axis: a guest (anonymous account) is refused at checkout with `error.403.checkout_requires_account`. Not derived from the posture. | no | true |
+| MAX_LINE_QUANTITY | env | cap on one line's quantity; feeds the money-bound proof (E005). | no | 999 |
+| MAX_LINES_PER_CART | env | cap on distinct lines per cart; feeds the money-bound proof (E005). | no | 100 |
+| CART_TTL_DAYS | env | carts untouched this long are purged (beat entry / `manage.py purge_carts`). | no | 30 |
+| BASE_CURRENCY | env | reporting currency of `Order.total_base`. | no | USD |
+| TOTAL_BASE_CONVERTER | settings | dotted path `(amount, currency, base) -> Decimal or None` computing `total_base`; default asks `currencies.convert`, NULL when unanswered. | no | stapel_orders.money.currencies_converter |
+| PAYMENT | env | axis: `none` (orders stay unpaid, staff confirm) or `mock` (paid at once; prototype stage only, E002/W002), or a registered provider name; a dotted path only from the settings module. | no | none |
+| OWNER_CANCELLABLE_STATUSES | settings | statuses from which the buyer may cancel their own order. | no | ("new",) |
+| NOTIFY | env | best-effort buyer notifications `orders.placed` / `orders.status_changed`. | no | true |
+| ORDER_URL_TEMPLATE | env | `{order_id}` / `{number}` template for notification links; empty = no link. | no | "" |

stapel_orders/__init__.py

@@ -0,0 +1,31 @@
+"""stapel-orders — Cart, checkout and orders for the Stapel framework.
+
+Public API (lazily exported, PEP 562 — importing this package never pulls
+in Django or requires configured settings):
+
+- ``orders_settings`` — resolved app settings (``stapel_orders.conf``).
+"""
+
+__all__ = [
+    "orders_settings",
+]
+
+# name -> submodule that defines it. Resolution is deferred until first
+# attribute access so that `import stapel_orders` stays Django-free.
+_LAZY_EXPORTS = {
+    "orders_settings": ".conf",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_EXPORTS:
+        from importlib import import_module
+
+        value = getattr(import_module(_LAZY_EXPORTS[name], __name__), name)
+        globals()[name] = value  # cache for subsequent lookups
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_orders/_capabilities.py

@@ -0,0 +1,36 @@
+"""stapel-orders capabilities.json emitter — thin shim over stapel_tools.capabilities."""
+from pathlib import Path
+
+from stapel_tools.capabilities import axis_group_rules, run_capabilities_cli
+
+
+def main(argv=None):
+    from stapel_orders._codegen import _configure
+
+    _configure()
+    from stapel_orders.conf import DEFAULTS
+    from stapel_orders.urls import GATE_REGISTRY
+
+    # Two CTO-facing axes, both behavioural (no endpoint is unmounted):
+    # CHECKOUT_REQUIRES_ACCOUNT (guest checkout) and PAYMENT (none | mock |
+    # a registered provider). PURCHASABLE_TYPES is the extension seam.
+    axes = {"CHECKOUT_REQUIRES_ACCOUNT", "PAYMENT"}
+    return run_capabilities_cli(
+        argv,
+        repo=Path(__file__).resolve().parent,
+        canonical_prefix="/orders/api/v1",
+        defaults=DEFAULTS,
+        registry=GATE_REGISTRY,
+        is_axis=lambda k: k in axes,
+        axis_group=axis_group_rules(
+            exact={
+                "CHECKOUT_REQUIRES_ACCOUNT": "orders.checkout",
+                "PAYMENT": "orders.payment",
+            }
+        ),
+        prog="stapel-orders-capabilities",
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stapel_orders/_codegen.py

@@ -0,0 +1,120 @@
+"""stapel-orders contract-emission harness (contract-pipeline.md §2-3).
+
+Emits the module's own contract triad into ``docs/`` from a single-module
+``{orders + core}`` Django instance mounted at the canonical
+``orders/api/v1/`` prefix:
+
+  docs/schema.json   drf-spectacular OpenAPI, this module only, canonical prefix
+  docs/flows.json    generate_flow_docs machine artifact ([] — no @flow_step here)
+  docs/errors.json   generate_error_keys registry
+
+The *mechanism* is stapel_tools.codegen (shared, unchanged); this file is the
+thin per-module *config* that wires the module's settings + canonical mount.
+
+Usage:
+    python -m stapel_orders._codegen --out docs        # `make contract`
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+
+def _configure() -> None:
+    """Configure + boot the single-module Django instance for emission."""
+    repo_root = os.path.dirname(os.path.abspath(__file__))
+    sys.path[:] = [p for p in sys.path if os.path.abspath(p or os.getcwd()) != repo_root]
+
+    from django.conf import settings
+
+    if not settings.configured:
+        from stapel_orders._codegen_settings import settings_kwargs
+
+        settings.configure(
+            **settings_kwargs(root_urlconf="stapel_orders.codegen_urls", contract=True)
+        )
+
+    import django
+
+    django.setup()
+
+    from drf_spectacular.settings import spectacular_settings
+
+    from stapel_orders._codegen_settings import CODEGEN_SCHEMA_PATH_PREFIX
+
+    spectacular_settings.SCHEMA_PATH_PREFIX = CODEGEN_SCHEMA_PATH_PREFIX
+
+    # Stable enum component names (stapel-schema-lint SCH004).
+    from drf_spectacular.plumbing import _load_enum_name_overrides
+
+    from stapel_orders._codegen_settings import enum_name_overrides
+
+    spectacular_settings.ENUM_NAME_OVERRIDES = enum_name_overrides()
+    _load_enum_name_overrides.cache_clear()
+
+    # Register drf-spectacular's JWT cookie-auth extension explicitly (a real
+    # host triggers this as a side effect of wiring its Swagger URLs). Without
+    # it, the protected endpoints
+    # would emit without their `security: [{"JWTCookieAuth": []}]` entry — a
+    # real contract gap. Applied per stapel-calendar's precedent.
+    from stapel_core.django.openapi.swagger import _register_jwt_auth_extension
+
+    _register_jwt_auth_extension()
+
+
+def _require_python_312() -> None:
+    """Abort emission if not running the pinned 3.12 interpreter.
+
+    drf-spectacular's rendering of component descriptions (``Optional[X]`` vs
+    ``X | None``) depends on the Python minor version — contracts emitted on
+    anything other than 3.12 (the CI/monolith pin) produce false diffs.
+    """
+    if sys.version_info[:2] != (3, 12):
+        got = f"{sys.version_info.major}.{sys.version_info.minor}"
+        raise SystemExit(
+            f"stapel-orders contract emission ABORTED: running Python {got}, "
+            "but contracts must be emitted on Python 3.12 (the CI/monolith "
+            "pin). drf-spectacular renders component descriptions (Optional[X] "
+            "vs X | None) differently across Python minor versions, so emitting "
+            "on any other minor produces false diffs against the committed "
+            "docs/*.json. Re-run under a 3.12 interpreter."
+        )
+
+
+def main(argv: list[str] | None = None) -> int:
+    _require_python_312()
+
+    parser = argparse.ArgumentParser(
+        prog="stapel-orders-contract",
+        description="Emit this module's contract triad (schema.json + flows.json "
+        "+ errors.json) into --out, canonical /orders/api/v1/ prefix.",
+    )
+    parser.add_argument(
+        "--out",
+        default="docs",
+        help="Output directory for the triad (default: docs).",
+    )
+    args = parser.parse_args(argv)
+
+    _configure()
+
+    from stapel_tools.codegen import emit_errors, emit_flows, emit_schema
+
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    paths = emit_schema(out / "schema.json")
+    flows = emit_flows(out / "flows.json")
+    errors = emit_errors(out / "errors.json")
+
+    print(
+        f"stapel-orders contract: {paths} paths, {flows} flows, {errors} error keys "
+        f"→ {out}/",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stapel_orders/_codegen_settings.py

@@ -0,0 +1,104 @@
+"""Single-module Django settings shared by the test suite and contract emission.
+
+One copy, so the harness that emits ``docs/schema.json`` and the tests that
+prove it can never drift in INSTALLED_APPS or comm config. The production
+``REST_FRAMEWORK`` (exception handler, schema class) is used by both: the
+error envelope the tests assert is the one a host serves.
+"""
+from __future__ import annotations
+
+#: The resolver Function the test catalog provides (tests/catalog.py).
+TEST_RESOLVER = "orders_test.purchasables"
+
+
+def settings_kwargs(
+    *,
+    root_urlconf: str = "stapel_orders.tests.urls",
+    contract: bool = False,
+) -> dict:
+    rest_framework = {
+        "DEFAULT_RENDERER_CLASSES": ["rest_framework.renderers.JSONRenderer"],
+        "DEFAULT_SCHEMA_CLASS": "stapel_core.django.openapi.schemas.PermissionAwareAutoSchema",
+        "EXCEPTION_HANDLER": "stapel_core.django.api.errors.stapel_exception_handler",
+    }
+    if contract:
+        rest_framework.update({
+            "DEFAULT_AUTHENTICATION_CLASSES": [
+                "stapel_core.django.jwt.authentication.JWTCookieAuthentication",
+            ],
+            "DEFAULT_PERMISSION_CLASSES": [
+                "stapel_core.django.api.permissions.IsServiceRequest",
+                "stapel_core.django.api.permissions.IsSuperUser",
+            ],
+            "DEFAULT_RENDERER_CLASSES": [
+                "rest_framework.renderers.JSONRenderer",
+                "rest_framework.renderers.BrowsableAPIRenderer",
+            ],
+        })
+    return dict(
+        SECRET_KEY="test-secret-key-not-for-production",
+        INSTALLED_APPS=[
+            "django.contrib.contenttypes",
+            "django.contrib.auth",
+            "django.contrib.sessions",
+            "django.contrib.admin",
+            "django.contrib.messages",
+            "stapel_core.django.apps.CommonDjangoConfig",
+            "stapel_core.django.users",
+            "rest_framework",
+            "drf_spectacular",
+            "stapel_orders",
+        ],
+        AUTH_USER_MODEL="users.User",
+        DATABASES={"default": {"ENGINE": "django.db.backends.sqlite3", "NAME": ":memory:"}},
+        DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
+        USE_TZ=True,
+        ROOT_URLCONF=root_urlconf,
+        CACHES={"default": {"BACKEND": "django.core.cache.backends.locmem.LocMemCache"}},
+        STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
+        STAPEL_COMM={
+            "OUTBOX_ENABLED": False,
+            "ACTION_TRANSPORT": "inprocess",
+            "VALIDATE_SCHEMAS": True,
+        },
+        STAPEL_ORDERS={
+            "PURCHASABLE_TYPES": {"item": {"resolve": TEST_RESOLVER}},
+        },
+        TEMPLATES=[{
+            "BACKEND": "django.template.backends.django.DjangoTemplates",
+            "APP_DIRS": True,
+            "OPTIONS": {"context_processors": [
+                "django.template.context_processors.request",
+                "django.contrib.auth.context_processors.auth",
+                "django.contrib.messages.context_processors.messages",
+            ]},
+        }],
+        MIDDLEWARE=[
+            "django.contrib.sessions.middleware.SessionMiddleware",
+            "django.contrib.auth.middleware.AuthenticationMiddleware",
+            "django.contrib.messages.middleware.MessageMiddleware",
+        ],
+        MIGRATION_MODULES={"users": None},
+        REST_FRAMEWORK=rest_framework,
+    )
+
+
+#: Forced on drf-spectacular's singleton so a single-module instance derives
+#: the same operation ids as a multi-module aggregate.
+CODEGEN_SCHEMA_PATH_PREFIX = "/"
+
+
+def enum_name_overrides() -> dict:
+    """Stable enum component names (stapel-schema-lint SCH004).
+
+    ``OrderStatus`` is carried by ``OrderResponse.status`` and
+    ``OrderTransitionRequest.to``; naming both sets keeps the react pair's
+    generated types from being renamed by an unrelated edit. Called after
+    ``django.setup()``.
+    """
+    from stapel_orders.models import OrderStatus, PaymentStatus
+
+    return {
+        "OrderStatusEnum": OrderStatus,
+        "PaymentStatusEnum": PaymentStatus,
+    }

stapel_orders/actions.py

@@ -0,0 +1,69 @@
+"""Action subscriptions of stapel-orders.
+
+Handlers are idempotent: delivery is at-least-once.
+
+- ``user.merged`` (stapel-auth) — a guest was folded into an account on
+  sign-in: its cart lines join the survivor's cart (same pair summed and
+  capped, another currency dropped) and its orders follow it.
+- ``payment.completed`` (a payment provider; billing ask B1, or the mock) —
+  only ``reference_type == "order"`` is ours.
+- ``user.deleted`` / ``gdpr.erasure.requested`` are answered by
+  ``register_gdpr_owner`` (``apps.py``), not here.
+"""
+import json
+import logging
+from pathlib import Path
+
+from django.db import transaction
+from stapel_core.comm import on_action
+
+logger = logging.getLogger(__name__)
+
+_CONSUMES = Path(__file__).resolve().parent / "schemas" / "consumes"
+
+
+def _schema(name: str) -> dict:
+    return json.loads((_CONSUMES / f"{name}.json").read_text(encoding="utf-8"))
+
+
+@on_action("user.merged", schema=_schema("user.merged"))
+def handle_user_merged(event):
+    """Re-parent the guest's cart lines and orders to the surviving account."""
+    from .models import CheckoutAttempt, Order
+    from .services.cart import merge_carts
+
+    payload = event.payload or {}
+    from_user_id = str(payload.get("from_user_id") or "")
+    into_user_id = str(payload.get("into_user_id") or "")
+    if not from_user_id or not into_user_id:
+        logger.error("user.merged without from/into user id: %s", event.event_id)
+        return
+    if from_user_id == into_user_id:
+        return
+    with transaction.atomic():
+        cart = merge_carts(from_user_id, into_user_id)
+        orders = Order.objects.filter(user_id=from_user_id).update(user_id=into_user_id)
+        survivor_keys = set(
+            CheckoutAttempt.objects.filter(user_id=into_user_id).values_list(
+                "idempotency_key", flat=True
+            )
+        )
+        CheckoutAttempt.objects.filter(
+            user_id=from_user_id, idempotency_key__in=survivor_keys
+        ).delete()
+        CheckoutAttempt.objects.filter(user_id=from_user_id).update(user_id=into_user_id)
+    if cart["moved"] or cart["summed"] or cart["dropped"] or orders:
+        logger.info(
+            "user.merged %s -> %s: cart moved %s, summed %s, dropped %s; %s orders",
+            from_user_id, into_user_id, cart["moved"], cart["summed"], cart["dropped"], orders,
+        )
+
+
+@on_action("payment.completed", schema=_schema("payment.completed"))
+def handle_payment_completed(event):
+    """Mark an order paid, or send it to review when the amount disagrees."""
+    from .services.orders import apply_payment
+
+    outcome = apply_payment(event.payload or {})
+    if outcome not in ("ignored", "duplicate"):
+        logger.info("payment.completed %s: %s", event.event_id, outcome)

stapel_orders/admin.py

@@ -0,0 +1,87 @@
+"""Admin for stapel-orders.
+
+Money and snapshots are read-only; status moves only through the service
+(transition actions), never a raw field edit, so every move is checked by
+the FSM and announced on the bus.
+"""
+from django.contrib import admin, messages
+
+from .models import Cart, CartLine, Order, OrderLine, OrderStatus
+
+
+class OrderLineInline(admin.TabularInline):
+    model = OrderLine
+    extra = 0
+    can_delete = False
+    fields = ("purchasable_type", "purchasable_key", "title", "quantity",
+              "unit_price", "line_total", "seller_id")
+    readonly_fields = fields
+
+    def has_add_permission(self, request, obj=None):
+        return False
+
+
+def _transition_action(to_status: str):
+    def action(modeladmin, request, queryset):
+        from .services import OrdersError
+        from .services.orders import staff_transition
+
+        moved = refused = 0
+        for order in queryset:
+            try:
+                staff_transition(order.pk, to_status, reason="admin")
+                moved += 1
+            except OrdersError:
+                refused += 1
+        if moved:
+            modeladmin.message_user(request, f"{moved} order(s) moved to {to_status}.")
+        if refused:
+            modeladmin.message_user(
+                request, f"{refused} order(s) cannot move to {to_status}.", messages.WARNING
+            )
+
+    action.__name__ = f"mark_{to_status}"
+    action.short_description = f"Mark selected orders {to_status}"
+    return action
+
+
+@admin.register(Order)
+class OrderAdmin(admin.ModelAdmin):
+    list_display = ("number", "status", "payment_status", "total", "currency", "created_at")
+    list_filter = ("status", "payment_status", "currency")
+    search_fields = ("number", "user_id")
+    inlines = [OrderLineInline]
+    readonly_fields = (
+        "number", "user_id", "status", "payment_status", "currency", "subtotal",
+        "total", "total_base", "base_currency", "provider_ref", "contact_name",
+        "contact_phone", "contact_email", "address_line1", "address_line2",
+        "address_city", "address_region", "address_postal_code", "address_country",
+        "shipping_method", "comment", "created_at", "updated_at",
+    )
+    actions = [
+        _transition_action(OrderStatus.CONFIRMED),
+        _transition_action(OrderStatus.SHIPPED),
+        _transition_action(OrderStatus.COMPLETED),
+        _transition_action(OrderStatus.CANCELLED),
+    ]
+
+    def has_add_permission(self, request):
+        return False
+
+
+class CartLineInline(admin.TabularInline):
+    model = CartLine
+    extra = 0
+    fields = ("purchasable_type", "purchasable_key", "title", "quantity", "unit_price", "line_total")
+    readonly_fields = fields
+
+    def has_add_permission(self, request, obj=None):
+        return False
+
+
+@admin.register(Cart)
+class CartAdmin(admin.ModelAdmin):
+    list_display = ("user_id", "currency", "updated_at")
+    search_fields = ("user_id",)
+    readonly_fields = ("user_id", "currency", "created_at", "updated_at")
+    inlines = [CartLineInline]

stapel_orders/apps.py

@@ -0,0 +1,23 @@
+from django.apps import AppConfig
+
+
+class OrdersConfig(AppConfig):
+    name = "stapel_orders"
+    label = "orders"
+    verbose_name = "Cart, checkout and orders"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        from . import actions  # noqa: F401
+        from . import checks  # noqa: F401
+        from . import errors  # noqa: F401
+        from . import flows  # noqa: F401
+        from . import functions  # noqa: F401
+
+        from stapel_core.gdpr import gdpr_registry, register_gdpr_owner
+
+        from .gdpr import OWNER, SUBJECT_TYPES, OrdersGDPRProvider, erase_subject
+
+        if not any(p.section == OWNER for p in gdpr_registry.providers):
+            gdpr_registry.register(OrdersGDPRProvider())
+        register_gdpr_owner(OWNER, SUBJECT_TYPES, erase_subject)

stapel_orders/beat.py

@@ -0,0 +1,47 @@
+"""The schedule that purges abandoned carts — shipped by the library.
+
+Wire it in the settings module itself::
+
+    from stapel_orders.beat import get_orders_beat_schedule
+
+    CELERY_BEAT_SCHEDULE = {**get_orders_beat_schedule(), ...}
+
+Imports settings and nothing else, so it is safe from a settings module.
+Celery is optional: ``manage.py purge_carts`` runs the same pass from any
+scheduler.
+"""
+from __future__ import annotations
+
+PURGE_TASK_NAME = "stapel_orders.beat.purge_carts"
+PURGE_BEAT_KEY = "orders-purge-carts"
+#: Daily. CART_TTL_DAYS is measured in days, so a finer cadence buys nothing.
+PURGE_INTERVAL_SECONDS = 24 * 60 * 60
+
+
+def purge_carts() -> int:
+    """One purge pass. A plain callable for hosts without Celery."""
+    from .services.cart import purge_carts as _purge
+
+    return _purge()
+
+
+def get_orders_beat_schedule(*, seconds: int = PURGE_INTERVAL_SECONDS) -> dict:
+    """Beat entry for the cart purge. Add to ``CELERY_BEAT_SCHEDULE``."""
+    return {PURGE_BEAT_KEY: {"task": PURGE_TASK_NAME, "schedule": float(seconds)}}
+
+
+try:  # pragma: no cover - exercised by whichever profile the host installs
+    from celery import shared_task
+except ImportError:
+    pass
+else:
+    purge_carts = shared_task(name=PURGE_TASK_NAME)(purge_carts)
+
+
+__all__ = [
+    "PURGE_BEAT_KEY",
+    "PURGE_INTERVAL_SECONDS",
+    "PURGE_TASK_NAME",
+    "get_orders_beat_schedule",
+    "purge_carts",
+]

stapel_orders/checks.py

@@ -0,0 +1,101 @@
+"""Django system checks for stapel-orders.
+
+- E001  ``PURCHASABLE_TYPES`` is empty: a shop with nothing to sell.
+- E003  a ``PURCHASABLE_TYPES`` entry is not ``{"resolve": "<function>"}``.
+- W001  a registered resolver is not reachable on this transport.
+- E002 / W002  ``PAYMENT="mock"`` outside / inside the prototype posture stage.
+- E004  ``PAYMENT`` names no known provider.
+- E005  the money bounds no longer fit the columns (total could overflow).
+"""
+from django.core import checks
+from django.core.exceptions import ImproperlyConfigured
+
+
+@checks.register(checks.Tags.compatibility)
+def check_purchasable_types(app_configs, **kwargs):
+    from .conf import orders_settings
+    from .registry import get_purchasable_types
+
+    raw = orders_settings.PURCHASABLE_TYPES
+    if raw is not None and not isinstance(raw, dict):
+        return [checks.Error(
+            "STAPEL_ORDERS['PURCHASABLE_TYPES'] must be a dict of "
+            "{type_name: {'resolve': '<comm function>'} | None}.",
+            id="stapel_orders.E003",
+        )]
+    types = get_purchasable_types()
+    if not types:
+        return [checks.Error(
+            "STAPEL_ORDERS['PURCHASABLE_TYPES'] is empty: the cart cannot "
+            "accept anything.",
+            hint="Register a type, e.g. {'listing': {'resolve': "
+                 "'listings.purchasables'}} (the stapel-shop preset does this), "
+                 "or register_purchasable_type() from your AppConfig.ready().",
+            id="stapel_orders.E001",
+        )]
+    findings = []
+    from stapel_core.comm import function_unreachable_reason
+
+    for name, entry in sorted(types.items()):
+        if not isinstance(entry, dict) or not entry.get("resolve"):
+            findings.append(checks.Error(
+                f"STAPEL_ORDERS['PURCHASABLE_TYPES'][{name!r}] must be "
+                "{'resolve': '<comm function name>'}.",
+                id="stapel_orders.E003",
+            ))
+            continue
+        reason = function_unreachable_reason(str(entry["resolve"]))
+        if reason:
+            findings.append(checks.Warning(
+                f"Purchasable type {name!r}: resolver {entry['resolve']!r} is "
+                f"not reachable here ({reason}). Adds and checkouts of this "
+                "type will answer 503.",
+                id="stapel_orders.W001",
+            ))
+    return findings
+
+
+@checks.register(checks.Tags.compatibility)
+def check_payment(app_configs, **kwargs):
+    from stapel_core.django.presets import stage_finding
+
+    from .conf import orders_settings
+
+    try:
+        provider = orders_settings.PAYMENT
+    except ImproperlyConfigured as exc:
+        return [checks.Error(str(exc), id="stapel_orders.E004")]
+    if getattr(provider, "name", "") != "mock":
+        return []
+    finding = checks.Error(
+        "STAPEL_ORDERS['PAYMENT'] is 'mock': every order is marked paid "
+        "without any money moving.",
+        hint="Use PAYMENT='none' (staff confirm by hand) or a real provider; "
+             "the mock is for a prototype posture only.",
+        id="stapel_orders.E002",
+    )
+    return [stage_finding(finding, warning_id="stapel_orders.W002")]
+
+
+@checks.register(checks.Tags.compatibility)
+def check_money_bounds(app_configs, **kwargs):
+    from . import money
+    from .services.cart import limits
+
+    max_quantity, max_lines = limits()
+    if max_quantity < 1 or max_lines < 1:
+        return [checks.Error(
+            "STAPEL_ORDERS['MAX_LINE_QUANTITY'] and ['MAX_LINES_PER_CART'] "
+            "must be positive.",
+            id="stapel_orders.E005",
+        )]
+    if not money.columns_hold(max_quantity, max_lines):
+        return [checks.Error(
+            f"MAX_LINE_QUANTITY={max_quantity} x MAX_LINES_PER_CART={max_lines} "
+            f"x unit price < 10^{money.UNIT_PRICE_INTEGER_DIGITS} can exceed the "
+            f"line ({money.LINE_TOTAL_MAX_DIGITS} digits) or order "
+            f"({money.ORDER_TOTAL_MAX_DIGITS} digits) total column.",
+            hint="Lower one of the two limits; the columns are the proof's ceiling.",
+            id="stapel_orders.E005",
+        )]
+    return []

stapel_orders/codegen_urls.py

@@ -0,0 +1,6 @@
+"""Canonical-prefix URLconf for contract emission: the documented host mount."""
+from django.urls import include, path
+
+urlpatterns = [
+    path("orders/api/", include("stapel_orders.urls")),
+]