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

## 一、实现内容

### 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. 查询条件
```sql
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
```

### 请求参数
```json
{
  "storeId": "1649328471923847193",
  "statisticsMonth": "202601"
}
```

### 响应示例
```json
{
  "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`

使用方法：
```bash
./scripts/sh/test_store_dashboard_deduct.sh
```