"""
Stateflow 信号定义

stateflow 模块通过信号通知外部模块状态变化，
外部模块可以监听这些信号来执行业务逻辑（通知、簿记等）。

sender 说明：
    sender 是 content_object 的类（如 PrintingJob、PlateOrder），
    监听者可以在 connect 时指定 sender 来过滤只接收特定类型的信号。

使用方式：
    # 在业务模块的 apps.py 中监听
    from django.apps import AppConfig

    class MyAppConfig(AppConfig):
        def ready(self):
            from stateflow.signals import process_completed
            from .models import PrintingJob
            from . import handlers
            
            # 只监听 PrintingJob 相关的流程完成信号
            process_completed.connect(handlers.on_process_completed, sender=PrintingJob)
            
            # 或监听所有类型（不指定 sender）
            # process_completed.connect(handlers.on_any_process_completed)
"""

from django.dispatch import Signal

# 流程完成信号
# 参数：
#   sender: content_object 的类（如 PrintingJob），用于过滤
#   process_id: 流程 ID
#   business_object_id: BusinessObject ID
#   business_object: BusinessObject 实例
#   content_object: 关联的业务对象实例（如 PrintingJob）
#   completed_by: 完成操作的用户（本次推进的操作人）
#   last_completed_state_id: 最后完成的节点 ID
#   last_completed_by: 最后步骤操作人（User 实例）
process_completed = Signal()

# 状态推进信号（每次推进都会触发）
# 参数：
#   sender: content_object 的类（如 PrintingJob），用于过滤
#   process_id: 流程 ID
#   business_object_id: BusinessObject ID
#   business_object: BusinessObject 实例
#   content_object: 关联的业务对象实例
#   state: 刚完成的 State 实例
#   state_log: StateFlowRecord 实例
#   completed_by: 完成操作的用户
#   is_process_completed: 流程是否已全部完成
#   last_completed_state_id: 最后完成的节点 ID
#   last_completed_by: 最后步骤操作人（User 实例）
state_advanced = Signal()