antissoft / lvqianmeiye_ERP

  # 店助工资计算规则梳理
  
  ## 📋 概述
  
  店助工资由以下几个部分组成：
  1. **底薪**：根据门店分类（A、B、C类）按规则计算
  2. **提成**：根据门店业绩与门店生命线的比例计算
  3. **阶段奖励**：根据进店消耗人数是否达到阶段目标
  4. **固定奖励**：手机管理费
  
  ---
  
  # 第一部分：计算规则
  
  ## 💰 工资组成规则
  
  ### 1. 底薪规则
  
  **计算规则**：根据门店分类（A、B、C类）确定底薪金额
  
  | 门店分类 | 底薪金额 |
  |---------|---------|
  | A类门店 | 3000元 |
  | B类门店 | 3100元 |
  | C类门店 | 3200元 |
  
  **重要说明**：
  - 门店分类必须设置，系统不允许设置为NULL
  - 如果门店分类未设置，应在计算工资前进行校验并提示错误
  
  ---
  
  ### 2. 提成规则
  

  **计算公式**：分段阶梯提成模式，根据门店业绩与门店生命线的比例分段计算提成

  #### 提成前提条件

  - **必须达到70%**：门店业绩必须达到门店生命线的70%，否则无提成
  
  #### 提成比例规则（分段计算）
  
  | 业绩区间 | 提成比例 | 计算说明 |
  |---------|---------|---------|
  | 门店业绩 < 门店生命线 × 70% | 0% | 无提成 |
  | 门店生命线 × 70% ≤ 门店业绩 < 门店生命线 × 100% | 0.4% | 整个业绩按0.4%计算 |
  | 门店业绩 ≥ 门店生命线 × 100% | 0.4% + 0.6% | 0-100%部分（整个生命线）按0.4%，100%以上部分按0.6% |

  
  #### 提成计算示例
  

  **示例1：业绩在70%-100%之间**
  

  假设：
  - 门店生命线 = 100,000元
  - 门店业绩 = 85,000元
  
  计算过程：

  1. 判断比例：85,000 / 100,000 = 85%（≥ 70%，满足前提条件）

  2. 判断区间：70% ≤ 85% < 100%

  3. 计算：整个业绩按0.4%计算
     - 提成金额：85,000元 × 0.4% = 340元
  4. 总提成金额：340元
  
  **示例2：业绩超过100%**
  
  假设：
  - 门店生命线 = 150,000元
  - 门店业绩 = 189,034.40元
  
  计算过程：
  1. 判断比例：189,034.40 / 150,000 = 126.02%（≥ 70%，满足前提条件）
  2. 判断区间：≥ 100%
  3. 分段计算：
     - 0-100%部分（整个生命线）：150,000元 × 0.4% = 600元
     - 100%以上部分：(189,034.40 - 150,000)元 × 0.6% = 39,034.40元 × 0.6% = 234.21元
  4. 总提成金额：600元 + 234.21元 = 834.21元
  
  **计算公式**：
  ```
  如果 业绩 < 70%：提成 = 0
  如果 70% ≤ 业绩 < 100%：提成 = 业绩 × 0.4%
  如果 业绩 ≥ 100%：提成 = 生命线 × 0.4% + (业绩 - 生命线) × 0.6%
  ```

  
  **重要说明**：
  - 门店生命线必须在 `lq_md_target` 表中进行设置，如果未设置，系统应报错提示

  - 提成采用分段阶梯计算方式，不同区间按不同比例分别计算后累加
  - 前提条件：必须达到70%才有提成资格

  
  ---
  
  ### 3. 阶段奖励规则
  
  **考核指标**：进店消耗人数（有消费金额的，按门店按月去重客户数）
  
  #### 奖励规则
  
  | 阶段 | 目标人数 | 奖励金额 | 说明 |
  |-----|---------|---------|------|
  | 第一阶段 | 达到目标（如：100人） | 200元/月 | 只要达到第一阶段目标即可获得 |
  | 第二阶段 | 达到目标（如：140人） | 再奖励200元/月 | 在达到第一阶段的基础上，再达到第二阶段目标 |
  | 两个阶段都达到 | - | 总计400元/月 | 第一阶段200元 + 第二阶段200元 |
  
  **奖励说明**：
  - 两个阶段的奖励是累加的，不是互斥的
  - 如果只达到第二阶段但未达到第一阶段，只获得第二阶段奖励（200元）
  - 如果两个阶段都达到，获得总计400元奖励
  
  **统计规则**：
  - 按门店统计（`md` 字段）
  - 只统计有消费金额的记录（消耗金额 > 0）
  - 同一个会员按月去重（`COUNT(DISTINCT hy)`），其中 `hy` 为会员ID
  - 只统计当月有效消耗记录（`F_IsEffective = 1`）
  
  **重要说明**：
  - 阶段目标必须在 `lq_md_target` 表中进行设置，如果未设置，系统应报错提示
  - 不同门店的阶段目标可能不同（如：川师第一阶段100人，第二阶段140人）
  
  ---
  
  ### 4. 固定奖励规则
  
  **手机管理费**：150元/月
  
  **说明**：
  - 固定金额，无需计算
  - 每月固定发放
  
  ---
  
  ## 📊 完整计算公式
  
  ```
  店助月工资 = 底薪 + 提成 + 阶段奖励 + 固定奖励
  
  其中：
  - 底薪 = 根据门店分类确定（A类3000元，B类3100元，C类3200元）
  - 提成 = 门店业绩 × 提成比例（根据业绩与生命线比例确定）
  - 阶段奖励 = 根据进店消耗人数是否达到阶段目标（0/200/400元）
  - 固定奖励 = 150元（手机管理费）
  ```
  
  ---
  
  ## ⚠️ 注意事项
  
  1. **门店业绩计算**：
     - 门店业绩 = 开单业绩 - 退卡业绩
     - 只统计当月有效记录（`F_IsEffective = 1`）
  
  2. **进店消耗人数统计**：
     - 必须使用 `COUNT(DISTINCT hy)` 去重（同一个会员按月去重）
     - 只统计有消费金额的记录（消耗金额 > 0）
     - 按门店统计（`md` 字段）
     - 只统计当月有效消耗记录（`F_IsEffective = 1`）
     - 通过关联 `lq_xh_jksyj` 表判断是否有消费金额
  
  3. **阶段目标配置**：
     - 不同门店的阶段目标可能不同（如：川师第一阶段100人，第二阶段140人）
     - 必须从 `lq_md_target` 表获取对应门店的目标值
     - **重要**：如果 `lq_md_target` 表中未设置阶段目标，系统应报错提示
  
  4. **提成比例判断**：
     - 严格按照门店业绩与门店生命线的比例判断
     - 注意边界值：70% 和 100%
     - 提成按门店业绩的百分比计算
  
  5. **数据一致性**：
     - 门店业绩的计算逻辑必须与门店总业绩统计保持一致
     - 进店消耗人数的统计逻辑必须与其他统计接口保持一致
  
  6. **数据校验要求**：
     - 门店分类（`F_StoreCategory`）必须设置，不允许为NULL，未设置应报错
     - 门店生命线（`F_StoreLifeline`）必须设置，未设置应报错
     - 阶段目标（`F_AssistantHeadcountTargetStage1`、`F_AssistantHeadcountTargetStage2`）必须设置，未设置应报错
  
  ---
  
  # 第二部分：数据来源说明
  
  ## 🔍 核心数据表
  
  ### 1. `lq_mdxx` - 门店信息表
  
  **用途**：获取门店分类，用于确定店助底薪
  
  **关键字段**：
  - `F_Id`：门店ID（主键）
  - `F_StoreCategory`：门店分类
    - `1` = A类门店
    - `2` = B类门店
    - `3` = C类门店
  
  **查询条件**：门店ID（`F_Id`）
  
  **查询示例**：
  ```sql
  SELECT F_StoreCategory FROM lq_mdxx WHERE F_Id = @StoreId
  ```
  
  **代码实现**：
  - 实体类：`LqMdxxEntity.StoreCategory`（对应数据库字段 `F_StoreCategory`）
  - 枚举类：`StoreCategoryEnum`（定义A、B、C类门店）
  - 在工资计算时，已从门店信息中获取 `StoreCategory` 字段（见 `LqSalaryService.cs` 第345行）
  
  ---
  
  ### 2. `lq_md_target` - 门店目标表
  
  **用途**：获取门店生命线和阶段目标
  
  **关键字段**：
  - `F_StoreId`：门店ID
  - `F_Month`：月份（YYYYMM格式）
  - `F_StoreLifeline`：门店生命线（必须设置，未设置则报错）
  - `F_AssistantHeadcountTargetStage1`：店助第一阶段目标人数（必须设置，未设置则报错）
  - `F_AssistantHeadcountTargetStage2`：店助第二阶段目标人数（必须设置，未设置则报错）
  
  **查询条件**：门店ID（`F_StoreId`）+ 月份（`F_Month`，YYYYMM格式）
  
  **查询示例**：
  ```sql
  SELECT 
      F_StoreLifeline,
      F_AssistantHeadcountTargetStage1,
      F_AssistantHeadcountTargetStage2
  FROM lq_md_target
  WHERE F_StoreId = @StoreId AND F_Month = @Month
  ```
  
  **重要说明**：所有目标字段都必须设置，如果未设置，系统应报错提示
  
  ---
  
  ### 3. `lq_kd_kdjlb` - 开单记录表
  
  **用途**：计算门店开单业绩
  
  **关键字段**：
  - `sfyj`：实付业绩（用于计算门店开单业绩总和）
  - `Kdrq`：开单日期（用于按月过滤）
  - `F_IsEffective`：是否有效（只统计有效记录）
  
  **查询逻辑**：
  - 按门店、月份汇总 `sfyj` 字段
  - 只统计有效记录（`F_IsEffective = 1`）
  
  ---
  
  ### 4. `lq_hytk_hytk` - 退卡记录表
  
  **用途**：计算门店退卡业绩
  
  **关键字段**：
  - `F_ActualRefundAmount`：实际退卡金额（用于计算门店退卡业绩总和）
  - `tksj`：退卡时间（用于按月过滤）
  - `md`：门店ID
  - `F_IsEffective`：是否有效（只统计有效记录）
  
  **查询逻辑**：
  - 按门店、月份汇总 `F_ActualRefundAmount` 字段
  - 只统计有效记录（`F_IsEffective = 1`）
  
  ---
  
  ### 5. `lq_xh_hyhk` - 耗卡记录表
  
  **用途**：统计进店消耗人数
  
  **关键字段**：
  - `F_Id`：耗卡记录ID（主键）
  - `hy`：会员ID（用于去重统计）
  - `md`：门店ID（按门店统计）
  - `hksj`：耗卡时间（用于按月过滤）
  - `F_IsEffective`：是否有效（只统计有效记录）
  
  **查询逻辑**：
  - 按门店、月份统计去重会员数
  - 只统计有效记录（`F_IsEffective = 1`）
  - 只统计有消费金额的记录（通过关联 `lq_xh_jksyj` 表判断）
  
  ---
  
  ### 6. `lq_xh_jksyj` - 耗卡健康师业绩表
  
  **用途**：判断是否有消费金额
  
  **关键字段**：
  - `glkdbh`：关联耗卡记录ID（关联 `lq_xh_hyhk.F_Id`）
  - `jksyj`：健康师业绩（消耗金额）
  - `F_IsEffective`：是否有效（只统计有效记录）
  
  **查询逻辑**：
  - 用于判断耗卡记录是否有消费金额（`jksyj > 0`）
  - 只统计有效记录（`F_IsEffective = 1`）
  
  ---
  
  ## 📝 数据查询逻辑
  
  ### 1. 门店业绩计算
  
  **计算公式**：门店业绩 = 开单业绩 - 退卡业绩
  
  **查询逻辑**：
  ```sql
  -- 1. 计算门店开单业绩
  SELECT COALESCE(SUM(sfyj), 0) as BillingPerformance
  FROM lq_kd_kdjlb
  WHERE Djmd = @StoreId
    AND DATE_FORMAT(Kdrq, '%Y%m') = @Month
    AND F_IsEffective = 1
  
  -- 2. 计算门店退卡业绩
  SELECT COALESCE(SUM(F_ActualRefundAmount), 0) as RefundPerformance
  FROM lq_hytk_hytk
  WHERE md = @StoreId
    AND DATE_FORMAT(tksj, '%Y%m') = @Month
    AND F_IsEffective = 1
  
  -- 3. 计算门店实际业绩
  门店业绩 = 开单业绩 - 退卡业绩
  ```
  
  ---
  
  ### 2. 进店消耗人数统计
  
  **统计规则**：有消费金额的，按门店按月去重客户数
  
  **查询逻辑**：
  ```sql
  -- 统计门店当月进店消耗人数（有消费金额的，按门店按月去重客户数）
  SELECT COUNT(DISTINCT hy) as HeadCount
  FROM lq_xh_hyhk hk
  WHERE hk.md = @StoreId
    AND DATE_FORMAT(hk.hksj, '%Y%m') = @Month
    AND hk.F_IsEffective = 1
    AND EXISTS (
      -- 确保有消费金额（通过关联消耗业绩表判断）
      SELECT 1 
      FROM lq_xh_jksyj jksyj 
      WHERE jksyj.glkdbh = hk.F_Id 
        AND jksyj.F_IsEffective = 1 
        AND jksyj.jksyj > 0
    )
  ```
  
  **说明**：
  - `md`：门店ID，按门店统计
  - `hy`：会员ID，用于去重统计（同一个会员按月去重）
  - `hksj`：耗卡时间，用于按月过滤
  - `F_IsEffective = 1`：只统计有效记录
  - **重要**：只统计有消费金额的记录（消耗金额 > 0），通过关联 `lq_xh_jksyj` 表判断是否有消费金额
  
  ---
  
  ### 3. 门店分类获取
  
  **查询逻辑**：
  ```sql
  -- 获取门店分类
  SELECT F_StoreCategory FROM lq_mdxx WHERE F_Id = @StoreId
  
  -- 根据门店分类确定底薪
  -- F_StoreCategory = 1 → 底薪 = 3000元
  -- F_StoreCategory = 2 → 底薪 = 3100元
  -- F_StoreCategory = 3 → 底薪 = 3200元
  ```
  
  **代码实现**：
  ```csharp
  // 从门店信息中获取
  var store = await _db.Queryable<LqMdxxEntity>()
      .Where(x => x.Id == storeId)
      .FirstAsync();
  
  int? storeCategory = store.StoreCategory; // 1=A类, 2=B类, 3=C类
  
  // 根据门店分类确定店助底薪
  decimal baseSalary = storeCategory switch
  {
      1 => 3000m, // A类门店
      2 => 3100m, // B类门店
      3 => 3200m, // C类门店
      _ => throw new Exception($"门店分类未设置或无效：门店ID={storeId}")
  };
  ```
  
  ---
  
  ## 🔗 相关代码位置
  
  - **门店信息查询**：`LqMdxxService.cs`
  - **门店分类枚举**：`StoreCategoryEnum.cs`（`netcore/src/Modularity/Extend/NCC.Extend.Entitys/Enum/`）
  - **门店实体类**：`LqMdxxEntity.cs`（`F_StoreCategory` 字段）
  - **工资计算服务**：`LqSalaryService.cs`（第345行获取 `StoreCategory`）
  - **门店目标查询**：`LqMdTargetService.cs`
  - **门店业绩统计**：`LqStatisticsService.cs` / `LqDailyReportService.cs`
  - **进店消耗人数统计**：`LqStatisticsService.cs` / `LqDailyReportService.cs`
  
  ---
  
  ## 📅 更新记录
  
  - 2025-01-XX：初始版本，梳理店助工资计算规则
  - 2025-01-XX：更新底薪规则，明确按A、B、C类门店分类确定底薪（A类3000元，B类3100元，C类3200元）
  - 2025-01-XX：明确A、B、C类门店来源：`lq_mdxx` 表的 `F_StoreCategory` 字段（枚举值：1=A类，2=B类，3=C类）
  - 2025-01-XX：明确数据校验要求：门店分类必须设置，`lq_md_target` 表的目标字段必须设置，未设置应报错
  - 2025-01-XX：明确进店消耗人数统计规则：有消费金额的，按门店按月去重，同一个会员按月去重
  - 2025-01-XX：明确提成计算：按门店业绩的百分比计算
  - 2025-01-XX：重新组织文档结构，分为规则部分和数据来源说明部分