antissoft / lvqianmeiye_ERP

  # 员工工资查询接口逻辑梳理
  
  ## 📋 概述
  
  所有薪酬服务都提供了根据员工ID和月份查询工资的接口，供员工查看自己的工资条。本文档梳理了所有薪酬服务中的查询逻辑。
  
  ---
  
  ## 🔍 接口列表
  
  ### 1. 健康师工资查询
  - **服务**: `LqSalaryService`
  - **路由**: `GET /api/Extend/lqsalary/query-by-employee`
  - **方法**: `GetSalaryByEmployee`
  - **返回类型**: `HealthCoachSalaryOutput`
  - **数据表**: `lq_salary_statistics`
  
  ### 2. 店长工资查询
  - **服务**: `LqStoreManagerSalaryService`
  - **路由**: `GET /api/Extend/lqstoremanagersalary/query-by-employee`
  - **方法**: `GetSalaryByEmployee`
  - **返回类型**: `StoreManagerSalaryOutput`
  - **数据表**: `lq_store_manager_salary_statistics`
  
  ### 3. 主任工资查询
  - **服务**: `LqDirectorSalaryService`
  - **路由**: `GET /api/Extend/lqdirectorsalary/query-by-employee`
  - **方法**: `GetSalaryByEmployee`
  - **返回类型**: `DirectorSalaryOutput`
  - **数据表**: `lq_director_salary_statistics`
  
  ### 4. 店助工资查询
  - **服务**: `LqAssistantSalaryService`
  - **路由**: `GET /api/Extend/lqassistantsalary/query-by-employee`
  - **方法**: `GetSalaryByEmployee`
  - **返回类型**: `AssistantSalaryOutput`
  - **数据表**: `lq_assistant_salary_statistics`
  
  ### 5. 事业部总经理/经理工资查询
  - **服务**: `LqBusinessUnitManagerSalaryService`
  - **路由**: `GET /api/Extend/lqbusinessunitmanagersalary/query-by-employee`
  - **方法**: `GetSalaryByEmployee`
  - **返回类型**: `BusinessUnitManagerSalaryOutput`
  - **数据表**: `lq_business_unit_manager_salary_statistics`
  
  ### 6. 科技部老师工资查询
  - **服务**: `LqTechTeacherSalaryService`
  - **路由**: `GET /api/Extend/lqtechteachersalary/query-by-employee`
  - **方法**: `GetSalaryByEmployee`
  - **返回类型**: `TechTeacherSalaryOutput`
  - **数据表**: `lq_tech_teacher_salary_statistics`
  
  ### 7. 科技部总经理工资查询
  - **服务**: `LqTechGeneralManagerSalaryService`
  - **路由**: `GET /api/Extend/lqtechgeneralmanagersalary/query-by-employee`
  - **方法**: `GetSalaryByEmployee`
  - **返回类型**: `TechGeneralManagerSalaryOutput`
  - **数据表**: `lq_tech_general_manager_salary_statistics`
  
  ### 8. 大项目主管工资查询
  - **服务**: `LqMajorProjectDirectorSalaryService`
  - **路由**: `GET /api/Extend/lqmajorprojectdirectorsalary/query-by-employee`
  - **方法**: `GetSalaryByEmployee`
  - **返回类型**: `MajorProjectDirectorSalaryOutput`
  - **数据表**: `lq_major_project_director_salary_statistics`
  
  ### 9. 大项目部老师工资查询
  - **服务**: `LqMajorProjectTeacherSalaryService`
  - **路由**: `GET /api/Extend/lqmajorprojectteachersalary/query-by-employee`
  - **方法**: `GetSalaryByEmployee`
  - **返回类型**: `MajorProjectTeacherSalaryOutput`
  - **数据表**: `lq_major_project_teacher_salary_statistics`
  
  ---
  
  ## 📝 统一查询逻辑
  
  ### 输入参数
  
  所有接口都使用相同的输入参数类：`SalaryQueryByEmployeeInput`
  
  ```csharp
  public class SalaryQueryByEmployeeInput
  {
      /// <summary>
      /// 年份
      /// </summary>
      public int Year { get; set; }
  
      /// <summary>
      /// 月份
      /// </summary>
      public int Month { get; set; }
  
      /// <summary>
      /// 员工ID
      /// </summary>
      public string EmployeeId { get; set; }
  }
  ```
  
  ### 查询条件
  
  所有接口的查询条件都相同：
  
  ```csharp
  .Where(x => 
      x.StatisticsMonth == monthStr           // 统计月份匹配
      && x.EmployeeId == input.EmployeeId     // 员工ID匹配
      && x.IsLocked == 1                      // 只查询已锁定的工资
      && x.EmployeeConfirmStatus != 1         // 只查询未确认的工资
  )
  ```
  
  **关键点**：
  - ✅ **只查询已锁定的工资**：`IsLocked == 1`
  - ✅ **只查询未确认的工资**：`EmployeeConfirmStatus != 1`（已确认的工资无法查询）
  - ✅ **员工ID匹配**：`EmployeeId == input.EmployeeId`
  - ✅ **月份匹配**：`StatisticsMonth == monthStr`（格式：YYYYMM）
  
  **重要说明**：
  - 员工只能查看**已锁定但未确认**的工资记录
  - 一旦员工确认工资后（`EmployeeConfirmStatus = 1`），该工资记录将无法通过此接口查询
  - 这个设计确保员工在确认工资后，无法再次查看已确认的工资记录
  
  ### 参数验证
  
  所有接口都进行相同的参数验证：
  
  ```csharp
  // 1. 验证年份和月份
  if (input.Year <= 0 || input.Month <= 0 || input.Month > 12)
  {
      throw NCCException.Oh("年份和月份参数不正确");
  }
  
  // 2. 验证员工ID
  if (string.IsNullOrWhiteSpace(input.EmployeeId))
  {
      throw NCCException.Oh("员工ID不能为空");
  }
  
  // 3. 格式化月份
  var monthStr = $"{input.Year}{input.Month:D2}";  // 例如：202512
  ```
  
  ### 查询结果处理
  
  ```csharp
  // 查询工资记录
  var salary = await _db.Queryable<SalaryStatisticsEntity>()
      .Where(x => x.StatisticsMonth == monthStr 
          && x.EmployeeId == input.EmployeeId 
          && x.IsLocked == 1)
      .Select(x => new SalaryOutput { /* 字段映射 */ })
      .FirstAsync();
  
  // 如果未找到，抛出异常
  if (salary == null)
  {
      throw NCCException.Oh($"未找到员工{input.EmployeeId}在{input.Year}年{input.Month}月的工资记录");
  }
  
  return salary;
  ```
  
  ---
  
  ## 🔐 安全机制
  
  ### 1. 锁定机制
  - **只查询已锁定的工资**：`IsLocked == 1`
  - **目的**：确保员工只能查看已完成的工资数据，避免查看未完成计算的工资
  - **业务逻辑**：工资计算完成后，管理员需要先锁定工资，员工才能查看
  
  ### 1.1 确认状态限制
  - **只查询未确认的工资**：`EmployeeConfirmStatus != 1`
  - **目的**：员工确认工资后，该工资记录将无法再次查询
  - **业务逻辑**：
    1. 工资计算完成 → 管理员锁定（`IsLocked = 1`）
    2. 员工可以查看工资（`IsLocked = 1` 且 `EmployeeConfirmStatus != 1`）
    3. 员工确认工资（`EmployeeConfirmStatus = 1`）
    4. 确认后无法再次查询（`EmployeeConfirmStatus = 1` 的记录被排除）
  
  ### 2. 员工ID匹配
  - **精确匹配**：`EmployeeId == input.EmployeeId`
  - **目的**：确保员工只能查看自己的工资，不能查看其他员工的工资
  - **实现方式**：
    - 后端：通过SQL查询条件 `EmployeeId == input.EmployeeId` 实现精确匹配
    - 前端：从本地存储获取当前登录用户的ID，自动填充到查询参数中
  
  ### 3. 月份限制
  - **格式验证**：月份必须在 1-12 之间
  - **目的**：确保查询参数的有效性
  
  ### 4. 权限验证说明
  
  #### 当前实现
  - **后端**：接口**没有**验证当前登录用户，只通过 `EmployeeId` 参数查询
  - **前端**：从 `uni.getStorageSync('userInfo')` 获取用户ID，自动填充到查询参数
  - **安全依赖**：依赖前端确保传入的 `EmployeeId` 是当前登录用户的ID
  
  #### 潜在安全问题
  - **风险**：如果前端被篡改，可能会查询到其他员工的工资
  - **现状**：目前通过SQL查询条件 `EmployeeId == input.EmployeeId` 实现精确匹配，但**没有验证** `input.EmployeeId` 是否与当前登录用户ID一致
  
  #### 建议改进
  可以在后端增加权限验证，确保员工只能查询自己的工资：
  
  ```csharp
  // 获取当前登录用户ID
  var currentUserId = _userManager.UserId;
  
  // 验证：员工只能查询自己的工资
  if (input.EmployeeId != currentUserId && !_userManager.IsAdministrator)
  {
      throw NCCException.Oh("您只能查询自己的工资记录");
  }
  ```
  
  **注意**：管理员可能需要查询所有员工的工资，所以需要判断 `IsAdministrator`
  
  ---
  
  ## 📊 数据流程
  
  ### 查询流程
  
  ```
  1. 接收请求参数（Year, Month, EmployeeId）
     ↓
  2. 参数验证
     - 年份和月份有效性检查
     - 员工ID非空检查
     ↓
  3. 格式化月份（YYYYMM格式）
     ↓
  4. 查询数据库
     - 条件：StatisticsMonth == monthStr
     - 条件：EmployeeId == input.EmployeeId
     - 条件：IsLocked == 1（已锁定）
     - 条件：EmployeeConfirmStatus != 1（未确认）
     ↓
  5. 数据映射（Entity → Output DTO）
     ↓
  6. 结果验证
     - 如果未找到，抛出异常
     ↓
  7. 返回工资记录
  ```
  
  ### 数据表结构
  
  每个薪酬服务对应一个工资统计表：
  
  | 服务 | 数据表 | 主键字段 | 员工ID字段 | 月份字段 | 锁定字段 |
  |------|--------|---------|-----------|---------|---------|
  | 健康师 | `lq_salary_statistics` | `F_Id` | `F_EmployeeId` | `F_StatisticsMonth` | `F_IsLocked` |
  | 店长 | `lq_store_manager_salary_statistics` | `F_Id` | `F_EmployeeId` | `F_StatisticsMonth` | `F_IsLocked` |
  | 主任 | `lq_director_salary_statistics` | `F_Id` | `F_EmployeeId` | `F_StatisticsMonth` | `F_IsLocked` |
  | 店助 | `lq_assistant_salary_statistics` | `F_Id` | `F_EmployeeId` | `F_StatisticsMonth` | `F_IsLocked` |
  | 事业部总经理/经理 | `lq_business_unit_manager_salary_statistics` | `F_Id` | `F_EmployeeId` | `F_StatisticsMonth` | `F_IsLocked` |
  | 科技部老师 | `lq_tech_teacher_salary_statistics` | `F_Id` | `F_EmployeeId` | `F_StatisticsMonth` | `F_IsLocked` |
  | 科技部总经理 | `lq_tech_general_manager_salary_statistics` | `F_Id` | `F_EmployeeId` | `F_StatisticsMonth` | `F_IsLocked` |
  | 大项目主管 | `lq_major_project_director_salary_statistics` | `F_Id` | `F_EmployeeId` | `F_StatisticsMonth` | `F_IsLocked` |
  | 大项目部老师 | `lq_major_project_teacher_salary_statistics` | `F_Id` | `F_EmployeeId` | `F_StatisticsMonth` | `F_IsLocked` |
  
  ---
  
  ## 🔄 与其他功能的关系
  
  ### 1. 工资计算
  - **关系**：查询接口依赖工资计算接口生成的数据
  - **流程**：先执行计算接口（`calculate/*`），生成工资记录，然后才能查询
  
  ### 2. 工资锁定
  - **关系**：查询接口只返回已锁定的工资
  - **流程**：工资计算完成后，需要锁定（`IsLocked = 1`），员工才能查看
  
  ### 3. 员工确认
  - **关系**：查询接口返回的数据包含确认状态（`EmployeeConfirmStatus`）
  - **流程**：员工查看工资后，可以确认工资条
  
  ---
  
  ## ⚠️ 注意事项
  
  ### 1. 锁定状态
  - **必须锁定**：只有已锁定的工资才能被员工查询
  - **未锁定处理**：如果工资未锁定，查询接口会返回404错误
  
  ### 1.1 确认状态
  - **必须未确认**：只有未确认的工资才能被员工查询
  - **已确认处理**：如果工资已确认（`EmployeeConfirmStatus = 1`），查询接口会返回404错误
  - **业务含义**：员工确认工资后，该工资记录将无法再次查询，确保数据安全
  
  ### 2. 员工ID匹配
  - **精确匹配**：必须使用正确的员工ID
  - **安全考虑**：接口不验证当前登录用户，需要前端或中间件确保员工只能查询自己的工资
  
  ### 3. 月份格式
  - **格式要求**：月份必须格式化为 YYYYMM（如：202512）
  - **验证**：月份必须在 1-12 之间
  
  ### 4. 数据完整性
  - **字段映射**：每个服务的Output DTO字段可能不同
  - **空值处理**：如果未找到记录，返回404错误
  
  ---
  
  ## 📋 接口调用示例
  
  ### 健康师工资查询
  ```http
  GET /api/Extend/lqsalary/query-by-employee?Year=2025&Month=12&EmployeeId=员工ID
  ```
  
  ### 店长工资查询
  ```http
  GET /api/Extend/lqstoremanagersalary/query-by-employee?Year=2025&Month=12&EmployeeId=员工ID
  ```
  
  ### 主任工资查询
  ```http
  GET /api/Extend/lqdirectorsalary/query-by-employee?Year=2025&Month=12&EmployeeId=员工ID
  ```
  
  ### 店助工资查询
  ```http
  GET /api/Extend/lqassistantsalary/query-by-employee?Year=2025&Month=12&EmployeeId=员工ID
  ```
  
  ### 事业部总经理/经理工资查询
  ```http
  GET /api/Extend/lqbusinessunitmanagersalary/query-by-employee?Year=2025&Month=12&EmployeeId=员工ID
  ```
  
  ### 科技部老师工资查询
  ```http
  GET /api/Extend/lqtechteachersalary/query-by-employee?Year=2025&Month=12&EmployeeId=员工ID
  ```
  
  ### 科技部总经理工资查询
  ```http
  GET /api/Extend/lqtechgeneralmanagersalary/query-by-employee?Year=2025&Month=12&EmployeeId=员工ID
  ```
  
  ### 大项目主管工资查询
  ```http
  GET /api/Extend/lqmajorprojectdirectorsalary/query-by-employee?Year=2025&Month=12&EmployeeId=员工ID
  ```
  
  ### 大项目部老师工资查询
  ```http
  GET /api/Extend/lqmajorprojectteachersalary/query-by-employee?Year=2025&Month=12&EmployeeId=员工ID
  ```
  
  ---
  
  ## 🔍 代码实现对比
  
  ### 共同点
  
  所有服务的查询逻辑都相同：
  
  1. **参数验证**：年份、月份、员工ID验证
  2. **月份格式化**：`$"{input.Year}{input.Month:D2}"`
  3. **查询条件**：`StatisticsMonth == monthStr && EmployeeId == input.EmployeeId && IsLocked == 1`
  4. **异常处理**：未找到记录时抛出异常
  5. **返回类型**：返回对应的Output DTO
  
  ### 差异点
  
  1. **数据表不同**：每个服务查询不同的工资统计表
  2. **Output DTO不同**：每个服务返回的字段可能不同
  3. **字段映射不同**：根据岗位不同，返回的工资字段不同
  
  ---
  
  ## 📝 总结
  
  ### 核心逻辑
  
  1. **统一接口**：所有薪酬服务都提供 `query-by-employee` 接口
  2. **统一参数**：都使用 `SalaryQueryByEmployeeInput` 作为输入参数
  3. **统一条件**：都查询已锁定（`IsLocked == 1`）的工资记录
  4. **统一验证**：都进行相同的参数验证和异常处理
  
  ### 安全机制
  
  1. **锁定检查**：只查询已锁定的工资
  2. **员工匹配**：精确匹配员工ID
  3. **参数验证**：验证年份、月份、员工ID的有效性
  
  ### 使用场景
  
  1. **员工查看工资条**：员工通过小程序或PC端查看自己的工资
  2. **工资确认**：员工查看工资后，可以确认工资条
  3. **历史查询**：员工可以查询历史月份的工资记录
  
  ---
  
  **文档版本**: v1.0  
  **创建日期**: 2026-01-09  
  **适用范围**: 所有薪酬服务的员工工资查询接口