antissoft / lvqianmeiye_ERP

门店驾驶舱储扣分析接口实现说明.md 4.39 KB

门店驾驶舱储扣分析接口实现说明

一、实现内容

1. DTO字段扩展

在 StoreDashboardStatisticsOutput 中添加了以下储扣相关字段：

基础指标

  • DeductAmount：储扣总金额
  • DeductCount：储扣次数（按开单计数，有储扣的开单数）
  • DeductDetailCount：储扣明细次数（储扣明细记录数）
  • DeductMemberCount：储扣会员数（去重后的使用储扣的会员数）

比率指标

  • DeductPenetrationRate：储扣渗透率（有储扣的开单数/总开单数 × 100%）
  • DeductAmountRatio：储扣金额占比（储扣金额/整单业绩 × 100%）
  • AvgDeductAmount：平均储扣金额（储扣总金额/储扣次数）

分类统计

  • LifeBeautyDeductAmount：生美储扣金额
  • MedicalBeautyDeductAmount：医美储扣金额
  • TechBeautyDeductAmount：科美储扣金额
  • ProductDeductAmount：产品储扣金额

类型统计

  • StorageCardDeductAmount：储值卡类型储扣金额
  • ItemDeductAmount：品项类型储扣金额

二、统计逻辑

1. 数据源

  • 主表：lq_kd_deductinfo（开单扣减信息表）
  • 关联表：
    • lq_kd_kdjlb（开单记录表）：获取门店、开单时间、会员等信息
    • lq_xmzl（品项资料表）：获取品项分类（qt2字段）

2. 查询条件

WHERE deduct.F_IsEffective = 1
    AND billing.F_IsEffective = 1
    AND billing.djmd = '{StoreId}'
    AND COALESCE(deduct.F_BillingTime, billing.kdrq) >= '{startDate}'
    AND COALESCE(deduct.F_BillingTime, billing.kdrq) <= '{endDateTime}'

关键点：

  • 时间字段优先使用 deduct.F_BillingTime，如果为空则使用 billing.kdrq
  • 如果是当月，endDateTime 使用 DateTime.Now，与门店驾驶舱其他指标保持一致
  • 必须同时过滤 deduct.F_IsEffective = 1 和 billing.F_IsEffective = 1

3. 计算逻辑

储扣渗透率

储扣渗透率 = (有储扣的开单数 / 总开单数) × 100%

储扣金额占比

储扣金额占比 = (储扣金额 / 整单业绩) × 100%

注意：整单业绩（zdyj）需要单独查询，不能使用实付业绩（sfyj）

平均储扣金额

平均储扣金额 = 储扣总金额 / 储扣次数

三、验证数据

测试门店：绿纤南湖店（ID: 1649328471923847193）

测试月份：202601

数据库查询结果

  • 储扣总金额：24,779.73
  • 储扣次数：26（开单数）
  • 储扣明细次数：30（明细记录数）
  • 储扣会员数：19
  • 总开单数：90
  • 整单业绩：112,205.48

分类统计

  • 生美储扣：6,803.53
  • 医美储扣：509.90
  • 科美储扣：17,466.30
  • 产品储扣：0.00

类型统计

  • 储值卡类型：3,300.00
  • 品项类型：21,479.73

计算指标

  • 储扣渗透率：28.89% (26/90)
  • 储扣金额占比：22.08% (24,779.73/112,205.48)
  • 平均储扣金额：953.07 (24,779.73/26)

四、接口调用

接口地址

POST /api/Extend/LqStoreDashboard/GetStatistics

请求参数

{
  "storeId": "1649328471923847193",
  "statisticsMonth": "202601"
}

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "BillingPerformance": 22728.0,
    "ConsumePerformance": 55634.56,
    "DeductAmount": 24779.73,
    "DeductCount": 26,
    "DeductDetailCount": 30,
    "DeductPenetrationRate": 28.89,
    "DeductAmountRatio": 22.08,
    "AvgDeductAmount": 953.07,
    "DeductMemberCount": 19,
    "LifeBeautyDeductAmount": 6803.53,
    "MedicalBeautyDeductAmount": 509.90,
    "TechBeautyDeductAmount": 17466.30,
    "ProductDeductAmount": 0.00,
    "StorageCardDeductAmount": 3300.00,
    "ItemDeductAmount": 21479.73
  }
}

五、注意事项

  1. 服务重启：代码修改后需要重启后端服务才能生效
  2. 时间字段：优先使用 deduct.F_BillingTime，如果为空则使用 billing.kdrq
  3. 当月处理：如果是当月，endDateTime 应该使用 DateTime.Now，与门店驾驶舱其他指标保持一致
  4. 有效性过滤：必须同时过滤 deduct.F_IsEffective = 1 和 billing.F_IsEffective = 1
  5. 金额处理：使用 COALESCE(deduct.F_Amount, 0) 处理空值

六、测试脚本

测试脚本位置：scripts/sh/test_store_dashboard_deduct.sh

使用方法：

./scripts/sh/test_store_dashboard_deduct.sh