feat: batch update - gift card breakdown spec, backend APIs, miniprogram pages, ETL finance recharge, docs & migrations

apps/etl/connectors/feiqiu/tasks/dws/finance_recharge_task.py

@@ -139,6 +139,48 @@ class FinanceRechargeTask(FinanceBaseTask):
         rows = self.db.query(sql, (site_id, start_date, end_date))
         return [dict(row) for row in rows] if rows else []
     
+    # CHANGE 2026-07-17 | task 2.1: card_type_id → 细分余额字段名映射
+    GIFT_TYPE_FIELD_MAP = {
+        2794699703437125: 'gift_liquor_balance',     # 酒水卡
+        2791990152417157: 'gift_table_fee_balance',   # 台费卡
+        2793266846533445: 'gift_voucher_balance',     # 抵用券
+    }
+
+    # CHANGE 2026-07-18 | task 3.1: card_type_id → 细分充值字段名映射
+    GIFT_RECHARGE_FIELD_MAP = {
+        2794699703437125: 'gift_liquor_recharge',     # 酒水卡
+        2791990152417157: 'gift_table_fee_recharge',   # 台费卡
+        2793266846533445: 'gift_voucher_recharge',     # 抵用券
+    }
+
+    # CHANGE 2026-07-18 | task 3.1: 按 card_type_id 拆分赠送卡新增充值
+    def _extract_gift_recharge_breakdown(self, site_id: int, start_date: date, end_date: date) -> Dict[str, Decimal]:
+        """按卡类型拆分赠送卡新增充值（JOIN 充值订单与会员卡账户维度表）"""
+        cutoff = self.config.get("app.business_day_start_hour", 8)
+        biz_expr = biz_date_sql_expr("ro.pay_time", cutoff)
+        sql = f"""
+            SELECT dca.card_type_id, SUM(ro.point_amount) AS gift_recharge
+            FROM dwd.dwd_recharge_order ro
+            JOIN dwd.dim_member_card_account dca
+                ON ro.tenant_member_card_id = dca.tenant_member_id
+            WHERE ro.site_id = %s
+              AND {biz_expr} >= %s AND {biz_expr} <= %s
+              AND dca.card_type_id IN (2794699703437125, 2791990152417157, 2793266846533445)
+              AND dca.scd2_is_current = 1
+              AND COALESCE(dca.is_delete, 0) = 0
+            GROUP BY dca.card_type_id
+        """
+        rows = self.db.query(sql, (site_id, start_date, end_date))
+
+        result: Dict[str, Decimal] = {
+            field: Decimal('0') for field in self.GIFT_RECHARGE_FIELD_MAP.values()
+        }
+        for row in (rows or []):
+            field_name = self.GIFT_RECHARGE_FIELD_MAP.get(row['card_type_id'])
+            if field_name:
+                result[field_name] = self.safe_decimal(row['gift_recharge'])
+        return result
+
     def _extract_card_balances(self, site_id: int, stat_date: date) -> Dict[str, Decimal]:
         CASH_CARD_TYPE_ID = 2793249295533893
         GIFT_CARD_TYPE_IDS = [2791990152417157, 2793266846533445, 2794699703437125]
@@ -162,6 +204,10 @@ class FinanceRechargeTask(FinanceBaseTask):
         
         cash_balance = Decimal('0')
         gift_balance = Decimal('0')
+        # CHANGE 2026-07-17 | task 2.1: 按 card_type_id 拆分赠送卡余额
+        gift_breakdown: Dict[str, Decimal] = {
+            field: Decimal('0') for field in self.GIFT_TYPE_FIELD_MAP.values()
+        }
         
         for row in (rows or []):
             card_type_id = row['card_type_id']
@@ -170,11 +216,16 @@ class FinanceRechargeTask(FinanceBaseTask):
                 cash_balance += balance
             elif card_type_id in GIFT_CARD_TYPE_IDS:
                 gift_balance += balance
+                # 写入细分字段（未知 card_type_id 不会命中 GIFT_TYPE_FIELD_MAP）
+                field_name = self.GIFT_TYPE_FIELD_MAP.get(card_type_id)
+                if field_name:
+                    gift_breakdown[field_name] += balance
         
         return {
             'cash_balance': cash_balance,
             'gift_balance': gift_balance,
-            'total_balance': cash_balance + gift_balance
+            'total_balance': cash_balance + gift_balance,
+            **gift_breakdown,
         }