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

apps/backend/app/schemas/xcx_performance.py

@@ -0,0 +1,122 @@
+"""
+小程序绩效相关 Pydantic 模型。
+
+覆盖：绩效概览（PERF-1）、绩效明细（PERF-2）响应结构。
+"""
+
+from __future__ import annotations
+
+from app.schemas.base import CamelModel
+
+
+# ---------------------------------------------------------------------------
+# 绩效通用模型
+# ---------------------------------------------------------------------------
+
+
+class DateGroupRecord(CamelModel):
+    """按日期分组的单条服务记录。"""
+
+    customer_name: str
+    avatar_char: str | None = None   # PERF-1 返回，PERF-2 不返回
+    avatar_color: str | None = None  # PERF-1 返回，PERF-2 不返回
+    time_range: str
+    hours: str
+    course_type: str
+    course_type_class: str  # 'basic' | 'vip' | 'tip'
+    location: str
+    income: str
+
+
+class DateGroup(CamelModel):
+    """按日期分组的服务记录组。"""
+
+    date: str
+    total_hours: str
+    total_income: str
+    records: list[DateGroupRecord]
+
+
+# ---------------------------------------------------------------------------
+# PERF-1 绩效概览
+# ---------------------------------------------------------------------------
+
+
+class TierInfo(CamelModel):
+    """档位信息（含基础/激励费率）。"""
+
+    basic_rate: float
+    incentive_rate: float
+
+
+class IncomeItem(CamelModel):
+    """收入明细项。"""
+
+    icon: str
+    label: str
+    desc: str
+    value: str
+
+
+class CustomerSummary(CamelModel):
+    """客户摘要（新客/常客基类）。"""
+
+    name: str
+    avatar_char: str
+    avatar_color: str
+
+
+class NewCustomer(CustomerSummary):
+    """新客户。"""
+
+    last_service: str
+    count: int
+
+
+class RegularCustomer(CustomerSummary):
+    """常客。"""
+
+    hours: float
+    income: str
+    count: int
+
+
+class PerformanceOverviewResponse(CamelModel):
+    """PERF-1 响应。"""
+
+    coach_name: str
+    coach_role: str
+    store_name: str
+    monthly_income: str
+    last_month_income: str
+    current_tier: TierInfo
+    next_tier: TierInfo
+    upgrade_hours_needed: float
+    upgrade_bonus: float
+    income_items: list[IncomeItem]
+    monthly_total: str
+    this_month_records: list[DateGroup]
+    new_customers: list[NewCustomer]
+    regular_customers: list[RegularCustomer]
+
+
+# ---------------------------------------------------------------------------
+# PERF-2 绩效明细
+# ---------------------------------------------------------------------------
+
+
+class RecordsSummary(CamelModel):
+    """月度汇总。"""
+
+    total_count: int
+    total_hours: float
+    total_hours_raw: float
+    total_income: float
+
+
+class PerformanceRecordsResponse(CamelModel):
+    """PERF-2 响应。"""
+
+    summary: RecordsSummary
+    date_groups: list[DateGroup]
+    has_more: bool