ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

chapter5/permission-embedded-data-objects/pedo/scenarios/ecommerce.py

@@ -0,0 +1,152 @@
+"""Case study: E-commerce orders.
+
+Architectural pattern demonstrated: **compound state machine + reactions**.
+An order moves through cart -> placed -> paid -> shipped -> delivered, with
+refund inverting the state from delivered back to refunded. Each transition
+has invariants (placed orders cannot be modified; only paid orders can ship).
+The state-machine validator + reactions handle the bookkeeping; the handler
+just describes the user intent (place / pay / ship / refund).
+
+Object types: customer, product, order, order_item, audit_log
+Key invariants:
+  - order status follows: cart -> placed -> paid -> shipped -> delivered, or any -> cancelled, delivered -> refunded
+  - only the order owner can place / cancel; only admin can ship; only paid orders can ship
+  - inventory decremented on payment (via reaction)
+  - refund inverts inventory (via reaction)
+"""
+from __future__ import annotations
+
+from pedo.core.models import (
+    AccessContext, DataObject, ObjectType, Operation,
+    PermissionRule, PrivilegeType, ReactionDeclaration,
+    Relationship, RelationshipAction,
+)
+from pedo.core.store import ObjectStore
+
+
+ORDER_TRANSITIONS = {
+    None: ["cart"],
+    "cart": ["placed", "cancelled"],
+    "placed": ["paid", "cancelled"],
+    "paid": ["shipped", "refunded"],     # paid can be refunded
+    "shipped": ["delivered"],
+    "delivered": ["refunded"],            # delivered can be refunded
+    "cancelled": [],
+    "refunded": [],
+}
+
+
+def validate_order_status(proposed, existing, accessor, store):
+    new_status = proposed.content.get("status")
+    if existing is None:
+        if new_status not in ("cart", None):
+            return f"New orders must start as 'cart', got {new_status!r}"
+        return True
+    old_status = existing.content.get("status")
+    if new_status and new_status != old_status:
+        valid = ORDER_TRANSITIONS.get(old_status, [])
+        if new_status not in valid:
+            return f"Invalid order transition {old_status} -> {new_status}; valid: {valid}"
+    return True
+
+
+def validate_only_paid_can_ship(proposed, existing, accessor, store):
+    if existing is None:
+        return True
+    if proposed.content.get("status") == "shipped":
+        if existing.content.get("status") != "paid":
+            return f"Only paid orders can ship; current status is {existing.content.get('status')}"
+    return True
+
+
+def adjust_inventory_on_state_change(event, store):
+    """Reaction: decrement inventory on 'paid', increment on 'refunded'."""
+    sys_ctx = AccessContext(user_id="system", role="system", org_id=event["object_org"])
+    new_status = event["object_content"].get("status")
+    if new_status not in ("paid", "refunded"):
+        return
+    direction = -1 if new_status == "paid" else +1
+    # Find order_items for this order, adjust each product's stock
+    order_id = event["object_id"]
+    items = store.raw_query("order_item")
+    for item in items:
+        if item.content.get("order_id") != order_id:
+            continue
+        product_id = item.content.get("product_id")
+        qty = item.content.get("quantity", 0)
+        product = store.raw_read(product_id)
+        if product is None:
+            continue
+        current = product.content.get("stock", 0)
+        store.update(product_id, {"stock": current + direction * qty},
+                     sys_ctx, _reaction_depth=event["depth"])
+
+
+def register_ecommerce_types(store: ObjectStore) -> None:
+    store.register_reaction_handler("adjust_inventory_on_state_change",
+                                    adjust_inventory_on_state_change)
+
+    store.register_type(ObjectType(
+        name="customer",
+        fields={"name": "str", "email": "str"},
+        permission_rules=[
+            PermissionRule(Operation.ACCEPT, PrivilegeType.INSERT, {}),
+            PermissionRule(Operation.ACCEPT, PrivilegeType.READ, {"is_owner": True}),
+            PermissionRule(Operation.ACCEPT, PrivilegeType.READ, {"role": "admin"}),
+            PermissionRule(Operation.ACCEPT, PrivilegeType.READ, {"role": "system"}),
+        ],
+        default_policy=Operation.DENY,
+    ))
+
+    store.register_type(ObjectType(
+        name="product",
+        fields={"name": "str", "price": "int", "stock": "int"},
+        permission_rules=[
+            PermissionRule(Operation.ACCEPT, PrivilegeType.READ, {}),  # public catalog
+            PermissionRule(Operation.ACCEPT, PrivilegeType.SELECT, {}),
+            PermissionRule(Operation.ACCEPT, PrivilegeType.INSERT, {"role": "admin"}),
+            # Stock writes only via reactions (system role)
+            PermissionRule(Operation.ACCEPT, PrivilegeType.WRITE, {"role": "system"}),
+            PermissionRule(Operation.ACCEPT, PrivilegeType.WRITE, {"role": "admin"}),
+        ],
+        default_policy=Operation.DENY,
+    ))
+
+    store.register_type(ObjectType(
+        name="order",
+        fields={"status": "str", "total": "int"},
+        permission_rules=[
+            PermissionRule(Operation.ACCEPT, PrivilegeType.INSERT, {}),
+            PermissionRule(Operation.ACCEPT, PrivilegeType.READ, {"is_owner": True}),
+            PermissionRule(Operation.ACCEPT, PrivilegeType.READ, {"role": "admin"}),
+            PermissionRule(Operation.ACCEPT, PrivilegeType.READ, {"role": "system"}),
+            # Owner can update during cart/place/cancel; admin can ship; system runs reactions.
+            PermissionRule(Operation.ACCEPT, PrivilegeType.WRITE, {"is_owner": True}),
+            PermissionRule(Operation.ACCEPT, PrivilegeType.WRITE, {"role": "admin"}),
+            PermissionRule(Operation.ACCEPT, PrivilegeType.WRITE, {"role": "system"}),
+        ],
+        validators=[validate_order_status, validate_only_paid_can_ship],
+        reactions=[
+            ReactionDeclaration(event="after_update:status",
+                                 handler="adjust_inventory_on_state_change"),
+        ],
+        default_policy=Operation.DENY,
+    ))
+
+    store.register_type(ObjectType(
+        name="order_item",
+        fields={"order_id": "str", "product_id": "str", "quantity": "int", "unit_price": "int"},
+        permission_rules=[
+            PermissionRule(Operation.ACCEPT, PrivilegeType.INSERT, {}),
+            PermissionRule(Operation.ACCEPT, PrivilegeType.READ, {"is_owner": True}),
+            PermissionRule(Operation.ACCEPT, PrivilegeType.READ, {"role": "admin"}),
+            PermissionRule(Operation.ACCEPT, PrivilegeType.READ, {"role": "system"}),
+        ],
+        relationships=[
+            Relationship(name="order", target_type="order",
+                         on_delete=RelationshipAction.CASCADE),
+            Relationship(name="product", target_type="product",
+                         on_delete=RelationshipAction.RESTRICT),
+        ],
+        default_policy=Operation.DENY,
+    ))