# 数据交接查询规则

## 规则

所有模块在查询"我的数据"（按用户 ID 过滤的业务数据列表）时，**必须调用 `HrmUserHandoverApi.expandUserIds()`** 扩展用户 ID 集合，确保交接人能查看已离职交接人的业务数据。

## 背景

当员工离职时，其业务数据（客户、商机、工单、采购申请等）需要交由交接人管理。系统通过 `hrm_user_handover` 映射表记录了离职用户与交接目标用户的关联，而非直接修改业务数据的所有者字段。

查询时通过 `expandUserIds` 将交接源用户 ID 纳入查询范围，使交接人能同时看到自己和离职人的数据。

## 核心 API

```java
// 接口：HrmUserHandoverApi (yudao-module-hrm-api)
public interface HrmUserHandoverApi {
    Set<Long> expandUserIds(Set<Long> userIds);
}
```

## 各模块集成方式

### 基本用法

```java
// 注入 API
@Resource
private HrmUserHandoverApi handoverApi;

// 在查询前扩展 userId
public PageResult<XxxDO> getXxxPage(XxxPageReqVO reqVO) {
    Long currentUserId = getCurrentUserId();
    Set<Long> expandedUserIds = handoverApi.expandUserIds(Set.of(currentUserId));
    // 用 expandedUserIds 做 IN 查询
    return mapper.selectPage(reqVO, new LambdaQueryWrapperX<XxxDO>()
            .in(XxxDO::getOwnerUserId, expandedUserIds)
            ...);
}
```

### Mapper 层写法

```java
// 如果 userId 是动态传入的（如管理员可查看所有人的数据），先做判断：
default PageResult<XxxDO> selectPage(XxxPageReqVO reqVO, Set<Long> userIds) {
    return selectPage(reqVO, new LambdaQueryWrapperX<XxxDO>()
            .inIfPresent(XxxDO::getOwnerUserId, CollUtil.isNotEmpty(userIds) ? userIds : null)
            ...);
}
```

## 各模块涉及的查询场景

| 模块 | 查询场景 | 涉及表 | 用户字段 |
|------|----------|--------|----------|
| CRM | 我的客户 | `crm_customer` | `ownerUserId` |
| CRM | 我的线索 | `crm_clue` | `ownerUserId` |
| CRM | 我的联系人 | `crm_contact` | `ownerUserId` |
| CRM | 我的合同 | `crm_contract` | `ownerUserId` |
| CRM | 我的商机 | `crm_business` | `ownerUserId` |
| CRM | 我的回款 | `crm_receivable` | `ownerUserId` |
| CRM | 我的回款计划 | `crm_receivable_plan` | `ownerUserId` |
| CRM | 我的报价 | `crm_sale_quotation` | `ownerUserId` |
| ERP | 我的采购申请 | `erp_purchase_request` | `requestUserId` |
| ERP | 我的销售订单 | `erp_sale_order` | `saleUserId` |
| ERP | 我的付款单 | `erp_finance_payment` | `financeUserId` |
| ERP | 我的收款单 | `erp_finance_receipt` | `financeUserId` |
| MES | 我的工单/报工/质检等 | 各 MES 表 | `userId` / `inspectorUserId` / `chargeUserId` 等 |

## expandUserIds 原理

```
hrm_user_handover 表记录:
┌────┬──────────────┬────────────┬───────────────┬─────────────────┐
│ id │ from_user_id │ to_user_id │ resignation_id│ handover_status │
├────┼──────────────┼────────────┼───────────────┼─────────────────┤
│ 1  │ 100(离职人)  │ 101(交接人)│ 1             │ 20(已完成)       │
└────┴──────────────┴────────────┴───────────────┴─────────────────┘

expandUserIds({101}) → {101, 100}
→ 交接人101查询时：WHERE owner_user_id IN (101, 100)
→ 同时看到自己的和离职人的数据
```

## 注意事项

- `expandUserIds` 只扩展**已完成的交接记录**（`handoverStatus = 20`）
- 传入空集合返回空集合
- 查询性能：映射表数据量极小（仅为已离职人员数），可放心在每次查询前调用
- 如果查询要求严格只看本人数据（如个人设置页），则不应调用 `expandUserIds`

## Maven 依赖

需要在模块的 `pom.xml` 中添加对 HRM API 的依赖：

```xml
<dependency>
    <groupId>cn.iocoder.boot</groupId>
    <artifactId>yudao-module-hrm-api</artifactId>
    <version>${revision}</version>
</dependency>
```