"""
全局事件信号中心（基于 blinker）

使用方式：
    # 发送信号（核心业务层）
    from app.core.signals import order_created
    order_created.send(order=order_obj, tenant_id=tid)

    # 订阅信号（插件层）
    from app.core.signals import order_created
    @order_created.connect
    def my_handler(sender, order, tenant_id, **kwargs):
        ...
"""
from blinker import Namespace

_signals = Namespace()

# ── 订单类信号 ─────────────────────────────────────────────────
order_created = _signals.signal("order_created")
"""
订单创建成功后触发。
payload: order (Order), tenant_id (int)
用途: 扣减库存、同步 ERP、发送确认邮件
"""

order_paid = _signals.signal("order_paid")
"""
支付成功后触发。
payload: order (Order), payment (Payment), tenant_id (int)
用途: 发送收据、触发返佣、更新财务记录
"""

order_status_changed = _signals.signal("order_status_changed")
"""
订单状态变更时触发。
payload: order (Order), old_status (str), new_status (str), tenant_id (int)
用途: 推送物流通知、触发自动化工作流
"""

# ── 价格计算信号（插件可介入修改价格）──────────────────────────
price_calculating = _signals.signal("price_calculating")
"""
价格计算过程中触发，插件可修改折扣。
payload: context (dict 包含 items, subtotal, tenant_id)
插件通过修改 context['discount_total'] 参与计算
"""

calculate_discount = _signals.signal("calculate_discount")
"""
折扣计算阶段。
payload: context (dict)
"""

calculate_shipping = _signals.signal("calculate_shipping")
"""
运费计算阶段，物流插件在此阶段介入。
payload: context (dict 包含 items, shipping_address, tenant_id)
插件通过修改 context['shipping_total'] 写入运费
"""

# ── 商品类信号 ─────────────────────────────────────────────────
product_created = _signals.signal("product_created")
product_updated = _signals.signal("product_updated")
category_updated = _signals.signal("category_updated")
product_image_uploaded = _signals.signal("product_image_uploaded")
"""
图片上传后触发，WebP 转换插件订阅此信号。
payload: image_id (int), product_id (int), url (str), tenant_id (int)
"""

stock_low = _signals.signal("stock_low")
"""
库存告急时触发（低于阈值）。
payload: product_id (int), variant_id (int), current_qty (int), tenant_id (int)
"""

# ── SEO 类信号 ─────────────────────────────────────────────────
seo_tags_generating = _signals.signal("seo_tags_generating")
"""
生成 SEO 标签前触发，插件可修改 meta_title / meta_description。
payload: context (dict 包含 product/category obj, tenant_id)
"""

sitemap_update_requested = _signals.signal("sitemap_update_requested")
"""商品/分类发生变更，需要更新 sitemap.xml 时触发（异步任务处理）"""

# ── 支付类信号 ─────────────────────────────────────────────────
payment_gateway_callback = _signals.signal("payment_gateway_callback")
"""
支付网关回调收到时触发。
payload: gateway (str), raw_data (dict), tenant_id (int)
"""