antissoft / lvqianmeiye_ERP

  # 仓库领用成本统计表逻辑梳理
  
  ## 📋 需求概述
  
  创建一个**仓库领用成本统计表**，按**月份**和**门店**两个维度进行统计。
  
  ---
  
  ## 🔍 数据来源分析
  
  ### 相关数据表
  
  #### 1. `lq_inventory_usage`（仓库使用记录表）
  **关键字段**：
  - `F_Id`：使用记录ID（主键）
  - `F_StoreId`：门店ID
  - `F_ProductId`：产品ID
  - `F_UsageBatchId`：使用批次ID（关联申请表）
  - `F_TotalAmount`：合计金额（单价×数量）
  - `F_UsageQuantity`：使用数量
  - `F_UnitPrice`：单价
  - `F_IsEffective`：是否有效（1-有效，0-无效）
  
  **说明**：
  - 一个申请批次可能包含多条使用记录（多个产品）
  - 每条记录都有金额（`F_TotalAmount`）
  
  #### 2. `lq_inventory_usage_application`（仓库使用申请表）
  **关键字段**：
  - `F_Id`：申请编号（主键）
  - `F_UsageBatchId`：使用批次ID（关联使用记录表）
  - `F_ApplicationStoreId`：申请门店ID
  - `F_ApprovalStatus`：审批状态（待审批/审批中/已通过/未通过/已退回）
  - `F_IsReceived`：是否已领取（1-已领取，0-未领取）
  - `F_ReceiveTime`：领取时间（**关键时间字段**）
  - `F_TotalAmount`：申请总金额（该批次所有商品的总价）
  - `F_IsEffective`：是否有效（1-有效，0-无效）
  
  **说明**：
  - 领取时间（`F_ReceiveTime`）是统计的时间依据
  - 只有已领取（`F_IsReceived = 1`）且审批通过（`F_ApprovalStatus = '已通过'`）的记录才计入统计
  
  #### 3. `lq_mdxx`（门店信息表）
  **关键字段**：
  - `F_Id`：门店ID
  - `dm`：门店名称
  
  ---
  
  ## 📊 统计逻辑设计
  
  ### 统计维度
  
  1. **月份**：YYYYMM格式（如：202601）
     - 基于 `lq_inventory_usage_application.F_ReceiveTime`（领取时间）
     - 使用 `DATE_FORMAT(a.F_ReceiveTime, '%Y%m')` 进行分组
  
  2. **门店**：门店ID（`F_StoreId`）
     - 来源：`lq_inventory_usage.F_StoreId`
     - 需要关联 `lq_mdxx` 获取门店名称
  
  ### 统计指标
  
  #### 核心指标（必选）
  
  1. **领用成本金额**（`TotalCostAmount`）
     - **计算方式**：`SUM(u.F_TotalAmount)`
     - **含义**：该月份该门店所有已领取的仓库使用记录的总金额
     - **数据来源**：`lq_inventory_usage.F_TotalAmount`
  
  2. **领用次数**（`ReceiveCount`）
     - **计算方式**：`COUNT(DISTINCT a.F_UsageBatchId)`
     - **含义**：该月份该门店已领取的申请批次数量（按批次去重）
     - **数据来源**：`lq_inventory_usage_application.F_UsageBatchId`
  
  3. **领用记录数**（`UsageRecordCount`）
     - **计算方式**：`COUNT(u.F_Id)`
     - **含义**：该月份该门店的使用记录明细数量（不按批次去重）
     - **数据来源**：`lq_inventory_usage.F_Id`
  
  #### 扩展指标（可选）
  
  4. **平均领用金额**（`AvgReceiveAmount`）
     - **计算方式**：`TotalCostAmount / ReceiveCount`
     - **含义**：每次领用的平均金额
  
  5. **平均单笔金额**（`AvgRecordAmount`）
     - **计算方式**：`TotalCostAmount / UsageRecordCount`
     - **含义**：每条使用记录的平均金额
  
  6. **领用产品种类数**（`ProductVarietyCount`）
     - **计算方式**：`COUNT(DISTINCT u.F_ProductId)`
     - **含义**：该月份该门店领用的不同产品种类数量
  
  ---
  
  ## 🔧 SQL 查询逻辑
  
  ### 基础查询结构
  
  ```sql
  SELECT 
      DATE_FORMAT(a.F_ReceiveTime, '%Y%m') as StatisticsMonth,
      u.F_StoreId as StoreId,
      store.dm as StoreName,
      -- 核心指标
      COALESCE(SUM(u.F_TotalAmount), 0) as TotalCostAmount,
      COUNT(DISTINCT a.F_UsageBatchId) as ReceiveCount,
      COUNT(u.F_Id) as UsageRecordCount,
      -- 扩展指标
      CASE 
          WHEN COUNT(DISTINCT a.F_UsageBatchId) > 0 
          THEN COALESCE(SUM(u.F_TotalAmount), 0) / COUNT(DISTINCT a.F_UsageBatchId)
          ELSE 0 
      END as AvgReceiveAmount,
      CASE 
          WHEN COUNT(u.F_Id) > 0 
          THEN COALESCE(SUM(u.F_TotalAmount), 0) / COUNT(u.F_Id)
          ELSE 0 
      END as AvgRecordAmount,
      COUNT(DISTINCT u.F_ProductId) as ProductVarietyCount
  FROM lq_inventory_usage u
  INNER JOIN lq_inventory_usage_application a ON u.F_UsageBatchId = a.F_UsageBatchId
  LEFT JOIN lq_mdxx store ON u.F_StoreId = store.F_Id
  WHERE u.F_IsEffective = 1
      AND a.F_IsEffective = 1
      AND a.F_ApprovalStatus = '已通过'
      AND a.F_IsReceived = 1
      AND a.F_ReceiveTime IS NOT NULL
      -- 时间筛选（可选）
      -- AND DATE_FORMAT(a.F_ReceiveTime, '%Y%m') = '202601'
      -- 门店筛选（可选）
      -- AND u.F_StoreId = '门店ID'
  GROUP BY 
      DATE_FORMAT(a.F_ReceiveTime, '%Y%m'),
      u.F_StoreId,
      store.dm
  ORDER BY 
      StatisticsMonth DESC,
      TotalCostAmount DESC
  ```
  
  ### 筛选条件说明
  
  1. **有效性筛选**：
     - `u.F_IsEffective = 1`：使用记录有效
     - `a.F_IsEffective = 1`：申请记录有效
  
  2. **状态筛选**：
     - `a.F_ApprovalStatus = '已通过'`：只统计审批通过的申请
     - `a.F_IsReceived = 1`：只统计已领取的记录
  
  3. **时间筛选**：
     - `a.F_ReceiveTime IS NOT NULL`：领取时间不能为空
     - 基于 `F_ReceiveTime` 进行月份分组和筛选
  
  ---
  
  ## 📈 统计场景
  
  ### 场景1：查询指定月份所有门店的统计
  
  **输入参数**：
  - `statisticsMonth`：统计月份（YYYYMM格式，如：202601）
  
  **返回数据**：
  - 该月份所有有领用记录的门店统计数据
  - 按领用成本金额降序排列
  
  ### 场景2：查询指定门店所有月份的统计
  
  **输入参数**：
  - `storeId`：门店ID
  
  **返回数据**：
  - 该门店所有月份的统计数据
  - 按月份降序排列
  
  ### 场景3：查询指定月份和门店的统计
  
  **输入参数**：
  - `statisticsMonth`：统计月份（YYYYMM格式）
  - `storeId`：门店ID
  
  **返回数据**：
  - 该月份该门店的统计数据（单条记录）
  
  ### 场景4：查询时间范围内的统计（按月汇总）
  
  **输入参数**：
  - `startMonth`：开始月份（YYYYMM格式）
  - `endMonth`：结束月份（YYYYMM格式）
  - `storeIds`：门店ID列表（可选）
  
  **返回数据**：
  - 时间范围内所有月份的统计数据
  - 可按门店筛选
  
  ---
  
  ## 🎯 接口实现
  
  ### 接口信息
  
  **接口路径**：`POST /api/Extend/LqInventoryUsage/get-store-receive-cost-statistics`
  
  **请求参数**：
  ```json
  {
    "statisticsMonth": "202601",  // 可选，YYYYMM格式（优先使用）
    "startMonth": "202601",        // 可选，开始月份（YYYYMM，与endMonth配合使用）
    "endMonth": "202612",          // 可选，结束月份（YYYYMM，与startMonth配合使用）
    "storeId": "门店ID",           // 可选，单个门店查询
    "storeIds": ["门店ID1", "门店ID2"],  // 可选，多个门店查询
    "warehouse": "仓库名称",        // 可选，筛选特定仓库
    "currentPage": 1,              // 可选，分页参数，默认1
    "pageSize": 20,                // 可选，分页参数，默认20
    "sidx": "StatisticsMonth",     // 可选，排序字段
    "sort": "desc"                 // 可选，排序方式（asc/desc）
  }
  ```
  
  **返回结构**：
  ```json
  {
    "code": 200,
    "data": {
      "list": [
        {
          "StatisticsMonth": "202601",
          "StoreId": "门店ID",
          "StoreName": "门店名称",
          "ReceiveCount": 10,
          "ProductVarietyCount": 8,
          "AvgUnitPrice": 1543.21,
          "TotalCostAmount": 12345.67,
          "WarehouseCount": 2,
          "UsageRecordCount": 25,
          "AvgReceiveAmount": 1234.57,
          "AvgRecordAmount": 493.83,
          "TotalUsageQuantity": 150,
          "MaxRecordAmount": 5000.00,
          "MinRecordAmount": 50.00
        }
      ],
      "pagination": {
        "total": 100,
        "pageIndex": 1,
        "pageSize": 20
      }
    },
    "message": "查询成功"
  }
  ```
  
  ### 返回字段说明
  
  | 字段名 | 类型 | 说明 |
  |--------|------|------|
  | **StatisticsMonth** | string | 统计月份（YYYYMM格式） |
  | **StoreId** | string | 门店ID |
  | **StoreName** | string | 门店名称 |
  | **ReceiveCount** | int | 领取数量（按批次去重，即领用次数） |
  | **ProductVarietyCount** | int | 领取品种数量（产品种类数） |
  | **AvgUnitPrice** | decimal | 平均单价（总价/领取品种数量） |
  | **TotalCostAmount** | decimal | 总价（领用成本金额） |
  | **WarehouseCount** | int | 涉及仓库数量（不同仓库的数量） |
  | **UsageRecordCount** | int | 领用记录数（明细记录数，不按批次去重） |
  | **AvgReceiveAmount** | decimal | 平均领用金额（总价/领取数量） |
  | **AvgRecordAmount** | decimal | 平均单笔金额（总价/领用记录数） |
  | **TotalUsageQuantity** | int | 领用总数量（所有产品的数量总和） |
  | **MaxRecordAmount** | decimal | 最大单笔金额 |
  | **MinRecordAmount** | decimal | 最小单笔金额 |
  
  ---
  
  ## ⚠️ 注意事项
  
  ### 1. 时间字段选择
  - ✅ **使用 `F_ReceiveTime`（领取时间）**：这是财务统计的正确时间点
  - ❌ **不使用 `F_UsageTime`（使用时间）**：使用时间可能早于领取时间，不符合财务统计逻辑
  
  ### 2. 数据完整性
  - 必须关联申请表，因为领取时间和状态在申请表中
  - 必须筛选 `F_IsReceived = 1`，只统计已领取的记录
  - 必须筛选 `F_ApprovalStatus = '已通过'`，只统计审批通过的记录
  
  ### 3. 金额计算
  - 使用 `lq_inventory_usage.F_TotalAmount`（每条使用记录的金额）
  - 不要使用 `lq_inventory_usage_application.F_TotalAmount`（申请总金额），因为可能存在数据不一致
  
  ### 4. 去重逻辑
  - **领用次数**：按批次ID去重（`COUNT(DISTINCT a.F_UsageBatchId)`）
  - **领用记录数**：不去重（`COUNT(u.F_Id)`）
  - **产品种类数**：按产品ID去重（`COUNT(DISTINCT u.F_ProductId)`）
  
  ### 5. 门店信息关联
  - 使用 `LEFT JOIN` 关联 `lq_mdxx` 表获取门店名称
  - 如果门店不存在，门店名称为空或显示"未知门店"
  
  ---
  
  ## 📝 参考实现
  
  可以参考以下现有实现：
  1. **`LqStoreManagerSalaryService.CalculateStoreManagerSalary`**（第335-347行）
     - 产品物料统计逻辑
     - 基于领取时间的月份筛选
  
  2. **`LqShareStatisticsStoreService.CalculateCost`**（第323-334行）
     - 产品成本统计逻辑
     - 基于领取时间的时间范围筛选
  
  3. **`LqInventoryUsageService.GetStoreReceiveStatisticsAsync`**（第1642行开始）
     - 门店领取统计逻辑
     - 可以参考其查询结构
  
  ---
  
  ## ✅ 实现可行性
  
  ### 数据完整性
  - ✅ 数据表结构完整
  - ✅ 关联关系清晰（通过 `F_UsageBatchId`）
  - ✅ 时间字段存在（`F_ReceiveTime`）
  - ✅ 状态字段完整（`F_IsReceived`、`F_ApprovalStatus`）
  
  ### 统计逻辑
  - ✅ 可以按月份分组（`DATE_FORMAT(a.F_ReceiveTime, '%Y%m')`）
  - ✅ 可以按门店分组（`u.F_StoreId`）
  - ✅ 可以计算金额总和（`SUM(u.F_TotalAmount)`）
  - ✅ 可以统计次数（`COUNT(DISTINCT a.F_UsageBatchId)`）
  
  ### 性能考虑
  - ✅ 建议在 `F_ReceiveTime` 和 `F_StoreId` 上建立索引
  - ✅ 建议在 `F_UsageBatchId` 上建立索引（关联查询）
  - ✅ 大数据量时建议使用分页查询
  
  ---
  
  ## 🎯 总结
  
  **仓库领用成本统计表**可以实现，核心逻辑如下：
  
  1. **数据来源**：`lq_inventory_usage` + `lq_inventory_usage_application` + `lq_mdxx`
  2. **统计维度**：月份（YYYYMM）+ 门店（StoreId）
  3. **时间依据**：`F_ReceiveTime`（领取时间）
  4. **筛选条件**：已领取 + 审批通过 + 有效记录
  5. **核心指标**：领用成本金额、领用次数、领用记录数
  
  **建议实现方案**：创建一个新的接口，支持按月份、门店、时间范围等多种查询方式，返回分页数据。