feat: new module for daily settlement

2026-02-08 11:37:52 +08:00
parent 72597ce81f
commit c564b1af32
15 changed files with 991 additions and 0 deletions
--- a/docs/settlement/DESIGN.md
+++ b/docs/settlement/DESIGN.md
@@ -0,0 +1,441 @@
+# 日结服务设计方案
+
+## 一、概述
+
+日结服务是一个基于 Celery 的定时任务系统，用于在每天凌晨5点自动执行各商户的日结统计。服务采用独立模块设计，支持商户级别的配置，包括统计模块选择和通知渠道配置。
+
+## 二、设计原则
+
+1. **独立模块**：`settlement` 模块独立，职责清晰
+2. **配置驱动**：每个商户可独立配置统计模块和通知渠道
+3. **统一调度**：运行时间在 settings.py 中统一配置，便于管理
+4. **商户隔离**：每个商户的日结任务独立执行，互不干扰
+5. **信号通知**：通过 signal 通知日结完成，便于后续扩展
+6. **模块化统计**：统计函数集中在 `services.py`，便于后续填充具体逻辑
+7. **容错性强**：单个模块失败不影响其他模块
+8. **可扩展性**：未来可轻松添加新的统计模块和通知渠道
+
+## 三、模块结构
+
+```
+settlement/
+├── __init__.py
+├── apps.py              # 应用配置，注册信号处理器
+├── models.py            # 日结配置模型
+├── signals.py           # 日结完成信号定义
+├── handlers.py          # 信号处理器（日志输出）
+├── services.py          # 统计服务函数（空壳）
+├── tasks.py            # Celery定时任务
+└── migrations/         # 数据库迁移文件
+```
+
+## 四、模型设计
+
+### 4.1 日结配置模型
+
+```python
+class NotificationChannelEnum(models.TextChoices):
+    """通知渠道枚举"""
+    WECOM = 'wecom', '企业微信'
+    NONE = 'none', '不通知'
+
+
+class SettlementModuleEnum(models.TextChoices):
+    """日结模块枚举"""
+    PLATE_ORDER = 'plate_order', '开版订单'
+    PRINTING_ORDER = 'printing_order', '生产订单'
+
+
+class DailySettlementConfig(ModelBase):
+    """日结配置 - 每个商户一条记录（可选）"""
+    id = models.BigAutoField(primary_key=True)
+    merchant = models.OneToOneField(
+        'basic_info.Merchant',
+        on_delete=models.CASCADE,
+        related_name='settlement_config',
+        verbose_name='所属商户'
+    )
+    
+    # 统计模块配置（JSON数组，存储枚举值）
+    settlement_modules = models.JSONField(
+        default=list,
+        verbose_name='统计模块',
+        help_text='例如: ["plate_order", "printing_order"]'
+    )
+    
+    # 通知配置
+    notification_enabled = models.BooleanField(default=False, verbose_name='启用通知')
+    notification_channel = models.CharField(
+        max_length=20,
+        choices=NotificationChannelEnum.choices,
+        default=NotificationChannelEnum.NONE,
+        verbose_name='通知渠道'
+    )
+    
+    # 其他配置
+    description = models.TextField(blank=True, null=True, verbose_name='备注')
+    
+    class Meta:
+        verbose_name = '日结配置'
+        verbose_name_plural = '日结配置'
+```
+
+**说明**：
+- 新商户不创建配置，则不参与日结统计
+- 配置中不包含 `run_hour` 和 `run_minute`，统一在 settings.py 中配置
+
+## 五、信号设计
+
+### 5.1 信号定义
+
+```python
+from django.dispatch import Signal
+
+# 日结完成信号
+# 参数：
+#   merchant: Merchant 实例
+#   settlement_date: datetime.date
+#   status: 'success' / 'failed' / 'partial'
+#   modules: list[str] - 参与统计的模块列表
+#   errors: dict - 模块错误详情 {'module_name': 'error message'}
+#   task_id: str - Celery 任务ID
+daily_settlement_completed = Signal()
+```
+
+### 5.2 信号处理器
+
+```python
+def on_daily_settlement_completed(sender, **kwargs):
+    """日结完成时的处理（日志输出）"""
+    merchant = kwargs.get('merchant')
+    settlement_date = kwargs.get('settlement_date')
+    status = kwargs.get('status')
+    modules = kwargs.get('modules', [])
+    errors = kwargs.get('errors', {})
+    task_id = kwargs.get('task_id')
+    
+    # 检查配置是否启用通知
+    config = merchant.settlement_config
+    if not config or not config.notification_enabled:
+        logger.info(
+            f'[settlement.handlers] 商户 {merchant.id} 日结完成，通知未启用'
+        )
+        return
+    
+    # 根据通知渠道处理（目前只有企业微信）
+    if config.notification_channel == NotificationChannelEnum.WECOM:
+        logger.info(
+            f'[settlement.handlers] 商户 {merchant.id} 日结完成，'
+            f'状态={status}, 模块={modules}, 错误={errors}, '
+            f'通知渠道=企业微信（暂不发送具体内容）'
+        )
+        # 未来可以在这里添加具体的企业微信通知逻辑
+```
+
+## 六、统计服务函数（空壳）
+
+### 6.1 开版订单统计
+
+```python
+def calculate_plate_order_daily_summary(
+    merchant_id: int,
+    settlement_date: datetime.date
+) -> dict:
+    """
+    计算开版订单日结汇总（空壳实现）
+    
+    Args:
+        merchant_id: 商户ID
+        settlement_date: 结算日期
+    
+    Returns:
+        dict: 统计结果（空壳）
+    """
+    logger.info(
+        f'[settlement.services] 计算开版订单日结汇总: '
+        f'merchant_id={merchant_id}, date={settlement_date}'
+    )
+    
+    return {
+        'merchant_id': merchant_id,
+        'settlement_date': str(settlement_date),
+        'total_orders': 0,
+        'completed_orders': 0,
+        'in_progress_orders': 0,
+    }
+```
+
+### 6.2 生产订单统计
+
+```python
+def calculate_printing_order_daily_summary(
+    merchant_id: int,
+    settlement_date: datetime.date
+) -> dict:
+    """
+    计算生产订单日结汇总（空壳实现）
+    
+    Args:
+        merchant_id: 商户ID
+        settlement_date: 结算日期
+    
+    Returns:
+        dict: 统计结果（空壳）
+    """
+    logger.info(
+        f'[settlement.services] 计算生产订单日结汇总: '
+        f'merchant_id={merchant_id}, date={settlement_date}'
+    )
+    
+    return {
+        'merchant_id': merchant_id,
+        'settlement_date': str(settlement_date),
+        'total_orders': 0,
+        'completed_orders': 0,
+        'in_progress_orders': 0,
+    }
+```
+
+## 七、Celery 任务设计
+
+### 7.1 主调度任务
+
+```python
+@shared_task(bind=True)
+def run_daily_settlement(self):
+    """
+    执行所有商户的日结任务（固定时间触发）
+    
+    在 settings.py 中配置的固定时间触发，
+    拉取所有配置了统计模块的商户，逐个执行日结。
+    """
+    from basic_info.models import Merchant
+    
+    # 获取所有配置了统计模块的商户
+    configs = DailySettlementConfig.objects.filter(
+        settlement_modules__len__gt=0
+    ).select_related('merchant')
+    
+    logger.info(
+        f'[settlement.tasks] 开始执行日结，共 {configs.count()} 个商户需要统计'
+    )
+    
+    # 为每个商户触发日结任务
+    for config in configs:
+        settlement_date = timezone.localdate() - datetime.timedelta(days=1)
+        run_merchant_daily_settlement.delay(
+            merchant_id=config.merchant.id,
+            settlement_date=str(settlement_date)
+        )
+    
+    return {
+        'task_id': self.request.id,
+        'total_merchants': configs.count(),
+        'settlement_date': str(timezone.localdate() - datetime.timedelta(days=1)),
+    }
+```
+
+### 7.2 商户日结任务
+
+```python
+@shared_task(bind=True)
+def run_merchant_daily_settlement(
+    self,
+    merchant_id: int,
+    settlement_date: str | None = None
+):
+    """
+    执行单个商户的日结
+    
+    Args:
+        merchant_id: 商户ID
+        settlement_date: 结算日期（YYYY-MM-DD），默认为昨天
+    
+    Returns:
+        dict: 包含 task_id 和执行结果的 payload
+    """
+    from basic_info.models import Merchant
+    
+    # 解析日期
+    if settlement_date:
+        date_obj = datetime.datetime.strptime(settlement_date, '%Y-%m-%d').date()
+    else:
+        date_obj = timezone.localdate() - datetime.timedelta(days=1)
+    
+    merchant = Merchant.objects.get(id=merchant_id)
+    config = merchant.settlement_config
+    
+    modules = config.settlement_modules
+    summaries = {}
+    errors = {}
+    overall_status = 'success'
+    
+    logger.info(
+        f'[settlement.tasks] 开始执行商户 {merchant_id} 的日结，'
+        f'日期={date_obj}, 模块={modules}'
+    )
+    
+    # 执行各模块的统计
+    for module in modules:
+        try:
+            if module == SettlementModuleEnum.PLATE_ORDER:
+                summary = calculate_plate_order_daily_summary(
+                    merchant_id=merchant_id,
+                    settlement_date=date_obj
+                )
+                summaries['plate_order'] = summary
+                
+            elif module == SettlementModuleEnum.PRINTING_ORDER:
+                summary = calculate_printing_order_daily_summary(
+                    merchant_id=merchant_id,
+                    settlement_date=date_obj
+                )
+                summaries['printing_order'] = summary
+                
+        except Exception as e:
+            logger.exception(
+                f'[settlement.tasks] 商户 {merchant_id} 的 {module} 统计失败: {e}'
+            )
+            errors[module] = str(e)
+            overall_status = 'partial'
+    
+    # 如果所有模块都失败
+    if len(errors) == len(modules):
+        overall_status = 'failed'
+    
+    # 发送信号（不包含统计结果详情）
+    daily_settlement_completed.send(
+        sender=run_merchant_daily_settlement,
+        merchant=merchant,
+        settlement_date=date_obj,
+        status=overall_status,
+        modules=modules,
+        errors=errors,
+        task_id=self.request.id
+    )
+    
+    payload = {
+        'task_id': self.request.id,
+        'merchant_id': merchant_id,
+        'settlement_date': str(date_obj),
+        'status': overall_status,
+        'modules': modules,
+        'errors': errors,
+    }
+    
+    logger.info(
+        f'[settlement.tasks] 商户 {merchant_id} 日结完成: {payload}'
+    )
+    return payload
+```
+
+## 八、Celery Beat 配置
+
+在 `settings.py` 的 `CELERY_BEAT_SCHEDULE` 中添加：
+
+```python
+# 日结任务 - 每天凌晨5点执行
+'daily_settlement': {
+    'task': 'settlement.tasks.run_daily_settlement',
+    'schedule': crontab(hour=5, minute=0),
+},
+```
+
+**说明**：
+- 运行时间统一在 settings.py 中配置（`hour=5, minute=0`）
+- 不需要每小时检查，直接在固定时间触发
+
+## 九、settings.py 配置
+
+```python
+# 日结服务配置
+# ------------------------------------------------------------------------------
+# 日结运行时间（固定时间，所有商户统一）
+SETTLEMENT_RUN_HOUR = env.int('SETTLEMENT_RUN_HOUR', default=5)
+SETTLEMENT_RUN_MINUTE = env.int('SETTLEMENT_RUN_MINUTE', default=0)
+# ------------------------------------------------------------------------------
+```
+
+然后在 CELERY_BEAT_SCHEDULE 中使用：
+
+```python
+from celery.schedules import crontab
+
+'daily_settlement': {
+    'task': 'settlement.tasks.run_daily_settlement',
+    'schedule': crontab(
+        hour=settings.SETTLEMENT_RUN_HOUR,
+        minute=settings.SETTLEMENT_RUN_MINUTE
+    ),
+},
+```
+
+## 十、应用配置
+
+```python
+class SettlementConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'settlement'
+    verbose_name = '日结管理'
+
+    def ready(self):
+        """注册信号处理函数"""
+        from .signals import daily_settlement_completed
+        from . import handlers
+        
+        # 注册日结完成信号处理器
+        daily_settlement_completed.connect(
+            handlers.on_daily_settlement_completed,
+            dispatch_uid='settlement.on_daily_settlement_completed'
+        )
+        
+        logger.info(
+            f'[settlement.apps] 已注册 daily_settlement_completed 信号处理器'
+        )
+```
+
+## 十一、错误处理策略
+
+1. **模块级隔离**：每个模块的统计失败不影响其他模块
+2. **错误记录**：记录每个模块的错误信息到 `errors` 字典
+3. **状态判断**：
+   - `success`：所有模块都成功
+   - `partial`：部分模块成功
+   - `failed`：所有模块都失败
+4. **日志记录**：使用 logger 记录详细日志（开始、完成、异常）
+
+## 十二、并发控制说明
+
+**暂不考虑并发控制**，原因：
+1. 日结任务在凌晨时段触发，业务量较小
+2. 商户数量预期不多，可以逐个串行执行
+3. 未来如需提升性能，可以通过增加 Celery worker 数量来解决
+4. Celery 本身支持任务队列和并发控制，后续可以轻松扩展
+
+## 十三、实施步骤
+
+1. 创建 `settlement` 模块目录结构
+2. 实现 `models.py`（配置模型）
+3. 实现 `signals.py`（信号定义）
+4. 实现 `services.py`（空壳统计函数）
+5. 实现 `handlers.py`（信号处理器）
+6. 实现 `tasks.py`（Celery 任务）
+7. 实现 `apps.py`（注册信号处理器）
+8. 在 `settings.py` 中添加 `settlement` 到 `INSTALLED_APPS`
+9. 在 `settings.py` 中配置 Celery Beat 和日结运行时间
+10. 创建数据库迁移
+11. 编写测试用例
+12. 手动触发测试，验证结果
+
+## 十四、方案优势
+
+1. **独立模块**：`settlement` 模块独立，职责清晰
+2. **配置驱动**：每个商户可独立配置统计模块和通知渠道
+3. **统一调度**：运行时间在 settings.py 中统一配置，便于管理
+4. **商户隔离**：每个商户的日结任务独立执行，互不干扰
+5. **信号通知**：通过 signal 通知日结完成，便于后续扩展
+6. **模块化统计**：统计函数集中在 `services.py`，便于后续填充具体逻辑
+7. **容错性强**：单个模块失败不影响其他模块
+8. **可扩展性**：未来可轻松添加新的统计模块和通知渠道
+9. **简化信号**：信号参数只包含基本信息，不包含统计结果详情
+10. **日志友好**：handler 中只做日志输出，便于调试