Commit db54e696 authored by fangxinjiang's avatar fangxinjiang

V24梳理记录-fxj -合并代码前只保留本地

parent 7f3589aa
# EKP 模块 — 提前缴费 / 见费出单相关逻辑梳理
> 对应需求:[HRO-EKP提前缴费商险数据兼容需求.md](./HRO-EKP提前缴费商险数据兼容需求.md)
> HRO 侧既有逻辑见:[HRO-见费出单既有逻辑梳理.md](./HRO-见费出单既有逻辑梳理.md)
> **状态:待梳理**(本文仅建立章节结构,后续按模块补充 EKP 既有实现)
---
## 梳理范围
以下五块为 EKP 侧与 HRO 提前缴费(见费出单)联动的主要触点,与需求文档第三节、第四节对应:
| 序号 | 模块 | 需求关联 | 状态 |
| --- | --- | --- | --- |
| 1 | 收款结算单 | 3.2 收款结算;结算金额为 0 同步 HRO 待投保 | 待梳理 |
| 2 | 商险支出 | 3.1 商险支出(历史+新数据共用) | 待梳理 |
| 3 | 退单 | 收款结算单退回 | 待梳理 |
| 4 | 撤销匹配 | 4. 撤销匹配逻辑;HRO `callBackInsuranceBuyHandleStatus` | 待梳理 |
| 5 | 垫付 | 触发 HRO 待缴费→待投保(与「已收」同等) | 待梳理 |
---
## 1. 收款结算单
> **待梳理**
### 需求要点(来自需求文档)
- 拉取 **未结算** 的提前缴费数据进行结算(需梳理 EKP 既有拉取逻辑)
- **非 BPO**:正常收款结算
- **BPO**:成本归集模式
- **特殊规则**:结算金额为 **0** 时,结算完成后 **直接同步 HRO 为待投保**
### 待确认项
- [ ] 提前缴费/见费出单明细的拉取条件与 SQL/接口
- [ ] BPO / 非 BPO 分支实现位置
- [ ] 结算金额为 0 时回调 HRO 的入口与时序
- [ ] 与 HRO 预估/实缴/差额明细的匹配规则
### 已知 HRO 侧对接
- 结算状态回写:`DoJointInsuranceTask.updateInsurancesSettleStatus`
- 手动拉取:`TInsuranceDetailServiceImpl.pullPaymentStatus``EkpSettleService.getSettleStatusFromEkpAssoByIds`
---
## 2. 商险支出
> **待梳理**
### 需求要点
- **历史数据 + 新数据** 均适用
- 允许对 **未支出** 的提前缴费实缴数据进行正常商险支出
### 待确认项
- [ ] 实缴明细可选条件(提前缴费标识判断)
- [ ] 支出单审核与 HRO 支出状态同步
- [ ] 已支出时 HRO/EKP 退单阻断逻辑
### 已知 HRO 侧对接
- 退保前校验:`ekpSettleService.getSettleStatusFromEkpInsuranceDetail``payStatus` 已结算/结算中则禁止退回
---
## 3. 退单
> **待梳理**
### 需求要点(来自需求文档 4.1 / 4.2)
**存在提前缴费预估数据:**
- 检查 HRO 投保状态,仅 **待投保** 允许退回/撤销
- 其他状态提示联系投保专员
**不存在预估数据:**
- 检查实缴/差额是否 **已支出**,已支出则禁止
**非提前缴费:** 检查实缴是否已支出
### 待确认项
- [ ] 退单触发 HRO 状态回退的接口(见费出单:待投保 → 待缴费)
- [ ] 退单与结算单、商险明细的联动删除/红冲规则
### 已知 HRO 侧对接
- `callBackInsuranceBuyHandleStatus` / `callBackInsuranceBuyHandleStatusSub`
---
## 4. 撤销匹配
> **待梳理**
### 需求要点
- 与退单类似的匹配校验(是否存在预估、投保状态、是否已支出)
- 见费出单待投保时撤销 → HRO 回退 **待缴费**
### 待确认项
- [ ] 撤销匹配与退单的业务差异
- [ ] 回调 HRO 的参数(`EkpStatusParamVo.detailIds``settleNo` 等)
### 已知 HRO 侧对接
- 同 §3:`callBackInsuranceBuyHandleStatusSub`
---
## 5. 垫付
> **待梳理**
### 需求要点
- 垫付与「已收」对 HRO 等价:待缴费 → **待投保**
- 手动拉取与 EKP 回调均识别 `paymentStatus=垫付`
### 待确认项
- [ ] 垫付在 EKP 商险明细上的状态字段
- [ ] 垫付与正常收款的结算单差异
- [ ] 垫付后撤销/退单是否走同一套匹配逻辑
### 已知 HRO 侧对接
- `pullPaymentStatus``"已收".equals(vo.getPaymentStatus()) || "垫付".equals(vo.getPaymentStatus())`
- `DoJointInsuranceTask.updateInsurancesSettleStatus``paymentStatsus=0` 时同步待投保
---
## 附录:EKP 商险明细关键字段(HRO 推送侧)
| 字段 | 含义 | 见费出单典型值 |
| --- | --- | --- |
| fd_jfcd | 是否见费出单 | 是 |
| fd_3b13b2ecc164aa | 是否全部结算 | 是 |
| fd_3af9d11088facc | 实际结算月份 | 空 |
| fd_3af9d1441ef7b6 | 有无预估 | 有 |
| fd_3adfe6e30f2a3c | 应收 | 预估/差额场景见 HRO 文档 |
| fd_3adfe6e3911ffe | 应支 | 实缴场景见 HRO 文档 |
---
## 修订记录
| 日期 | 说明 |
| --- | --- |
| 2026-06-05 | 初稿:建立 EKP 五模块章节结构,标注待梳理 |
# HRO 与 EKP 系统 — 提前缴费商险数据兼容需求
> 需求原型梳理文档
> 涉及系统:HRO 系统、EKP 系统
> 业务场景:商业保险「提前缴费」数据的新旧兼容与收付结算
---
## 一、HRO 系统 — 提前缴费通用规则
### 1.1 标识规则
- 「提前缴费」数据需做明确标识,便于后续流程与 EKP 侧联动处理。
- **新增字段**:标识该条提前缴费数据为 **历史数据** 还是 **新数据**
- **历史数据**:走既有逻辑(兼容原提前缴费流程,含预估/差额等处理方式,见第二节兼容逻辑表中「是」的分支)。
- **新数据**:走新逻辑(本需求定义的规则,见 1.2、1.3 及第二节兼容逻辑表中「否」的分支)。
| 字段标识值 | 含义 | 处理路径 |
| --- | --- | --- |
| 历史数据 | 上线前已存在的提前缴费数据,或按旧规则产生的数据 | 既有逻辑 |
| 新数据 | 本需求上线后新产生的提前缴费数据 | 新逻辑 |
### 1.2 状态流转(**新数据**)
> 以下状态流转仅适用于标识为 **新数据** 的提前缴费记录;**历史数据** 仍按既有逻辑处理。
- 提前缴费订单在 **待缴费** 状态下,**跳过「派单」环节**,直接进入 **待投保(投保专员处)** 处理。
### 1.3 投保后数据处理规则(**新数据**)
> 以下规则仅适用于标识为 **新数据** 的提前缴费记录;**历史数据** 仍按既有逻辑处理。
| 规则项 | 说明 |
| --- | --- |
| 预估数据 | **不生成** 预估数据 |
| 导入实缴数据后 — BPO 项目 | 实际应收 = **0**;实际应付 = **实缴金额** |
| 导入实缴数据后 — 非 BPO 项目 | 实际应收 = **实缴金额**;实际应付 = **实缴金额** |
| 差额数据 | **不生成** 差额数据 |
---
## 二、HRO 与 EKP 系统 — 新旧数据兼容逻辑表
> 根据「是否历史提前缴费」「投保状态」「是否存在预估数据」及「下一步操作」,决定具体处理逻辑。
| 是否历史提前缴费 | 投保状态 | 是否有预估数据 | 下一步操作 | 处理逻辑 / 思路 |
| --- | --- | --- | --- | --- |
| 是 | 待缴费 | 是 | 收付 | 正常匹配预估数据进行收付 |
| 是 | 待缴费 | 是 | 撤销 | 未匹配/未结算时可撤销 |
| 是/否 | 待投保 | 是 | 导出 | — |
| 是 | 待投保 | 是 | 退保 | 生成负数预估数据 |
| 否 | 待投保 | 否 | 退保 | 不生成负数预估数据 |
| 是 | 投保中 | 是 | 投保成功 | — |
| 是 | 投保中 | 是 | 退保 | 生成负数预估数据 |
| 否 | 投保中 | 否 | 退保 | 不生成负数预估数据 |
| 是 | 已投保,无实缴 | 是 | 导入实缴 | 生成实缴数据,再生成差额数据(BPO:应收=0,应付=实缴;非 BPO:应收=应付=实缴) |
| 否 | 已投保,无实缴 | 否 | 导入实缴 | 不生成差额数据;推送实缴至 EKP(BPO:应收=0,应付=实缴;非 BPO:应收=应付=实缴) |
| 是 | 已投保,无实缴 | 是 | 退保 | 生成负数预估数据 |
| 否 | 已投保,无实缴 | 否 | 退保 | 不生成负数预估数据 |
| 是 | 已导入实缴 | 是 | 商险支出 | 未支出时可商险支出;展示成本扣减明细 |
| 否 | 已导入实缴 | 否 | 商险支出 | 查找结算账期,找不到则取当前账期;未支出时可离险支出;展示成本扣减明细 |
| 是 | 已导入实缴 | 是 | 退保 | 检查结算状态:未结算则删除实缴数据;已结算则生成负数差额数据 |
| 否 | 已导入实缴 | 否 | 退保 | 检查结算状态:未结算则删除实缴数据 |
---
## 三、EKP 系统规则
### 3.1 商险支出(**历史数据 + 新数据**)
> 以下规则对 **历史数据** 与 **新数据** 均适用,不区分新旧。
- 允许对 **未支出** 的提前缴费实缴数据进行正常商险支出。
### 3.2 收款结算
- 收款结算时,需正确拉取 **未结算** 的提前缴费数据进行结算(需要梳理 EKP 的既有拉取提前缴费的逻辑):
- **非 BPO 项目**:正常收款结算
- **BPO 项目**:成本归集模式
**特殊规则(结算金额为 0):**
- EKP 收款结算单 **结算金额为 0** 时(典型场景:BPO 项目应收为 0),结算完成后 **直接同步 HRO 侧数据状态为「待投保」**,无需再走派单等环节。
- 与 1.2 新数据状态流转衔接:新数据待缴费跳过派单;BPO 等结算金额为 0 的场景,由 EKP 结算触发同步至待投保。
---
## 四、收款结算单退回 / 撤销匹配逻辑
### 4.1 判断是否存在提前缴费预估数据
**若存在预估数据:**
- 检查 HRO 投保状态
-**待投保** 状态允许退回/撤销
- 其他状态提示用户联系投保专员处理
**若不存在预估数据:**
- 检查是否存在提前缴费实缴数据或差额数据
- 若实缴/差额数据 **已支出**,则 **禁止** 退回/撤销
### 4.2 非提前缴费数据
- 检查实缴数据是否已支出
- 若已支出,则 **禁止** 退回/撤销
---
## 五、实现要点摘要
1. **新旧数据分流**:通过新增字段区分历史/新数据,历史走既有逻辑,新数据走新逻辑。
2. **状态机驱动**:按「是否历史提前缴费 × 投保状态 × 是否有预估数据 × 操作类型」分支处理。
3. **数据生成差异**
- 新提前缴费:不生成预估、不生成差额
- 历史提前缴费:保留预估/差额兼容逻辑,退保时按需生成负数预估或负数差额
4. **BPO / 非 BPO 区分**:实缴数据的应收、应付赋值规则不同,EKP 侧结算模式也不同。
5. **结算金额为 0 的特殊同步**:EKP 收款结算单结算金额为 0 时,结算后直接同步 HRO 数据为 **待投保**
6. **退回/撤销约束**:已支出或投保状态不满足条件时,阻断退回/撤销并给出明确提示。
---
## 附录:关键术语
| 术语 | 说明 |
| --- | --- |
| 提前缴费 | 商险业务中在常规流程前预先缴费的数据类型 |
| 历史数据 / 新数据 | 通过新增字段标识;历史数据走既有逻辑,新数据走本需求新逻辑 |
| 预估数据 | 投保前/投保过程中产生的预估收付数据 |
| 实缴数据 | 实际缴纳/import 后的真实收付数据 |
| 差额数据 | 预估与实缴之间的差异数据 |
| 商险支出 | 员工商险费用支出处理 |
| HRO | 人力资源外包业务模块 |
| MVP | HRO 模块的别称,与 HRO 同义 |
| 收款结算 | EKP 侧对客户/项目的收款结算流程 |
| BPO 项目 | 业务流程外包类项目,应收为 0,走成本归集 |
| 非 BPO 项目 | 常规项目,应收应付均为实缴金额 |
This diff is collapsed.
This diff is collapsed.
# 项目配置删除功能接口文档
## 1. 接口概述
本文档描述了项目配置删除功能的相关接口,包括删除预检和实际删除两个主要接口。该功能用于安全地删除项目配置及其关联数据,并在删除前进行必要的检查和待办事项清理。
## 2. 接口详情
### 2.1 删除预检接口
#### 接口信息
- **接口名称**: 删除预检
- **接口路径**: `/tautomainrel/deletePrecheck/{id}`
- **请求方法**: GET
- **功能描述**: 在删除项目配置前,统计该项目下存在的商险续签待办和合同续签待办数量,供前端展示确认
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | String | 是 | 项目配置ID,通过URL路径传递 |
#### 响应参数
```json
{
"code": 0,
"msg": "success",
"data": {
"insuranceCount": 5,
"contractCount": 3,
"deptNo": "DEPT001",
"departName": "测试项目"
}
}
```
| 字段名 | 类型 | 说明 |
|--------|------|------|
| insuranceCount | int | 商险续签待办条数 |
| contractCount | int | 合同续签待办条数 |
| deptNo | String | 项目编码 |
| departName | String | 项目名称 |
#### 业务逻辑
1. 验证项目配置是否存在
2. 查询项目基本信息(项目编码、项目名称)
3. 统计商险续签待办数量(状态为"待确认"、"待派单"的记录)
4. 统计合同续签待办数量(状态为"待确认"、"待发起"的记录)
---
### 2.2 删除项目配置接口
#### 接口信息
- **接口名称**: 通过id删除项目配置表主表
- **接口路径**: `/tautomainrel/{id}`
- **请求方法**: DELETE
- **功能描述**: 删除指定的项目配置及其所有关联的子规则配置,并清除相关的续签待办事项
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | String | 是 | 项目配置ID,通过URL路径传递 |
#### 响应参数
```json
{
"code": 0,
"msg": "success",
"data": true
}
```
| 字段名 | 类型 | 说明 |
|--------|------|------|
| data | Boolean | 删除是否成功 |
#### 业务逻辑
##### 1. 前置校验
- 验证项目配置ID是否为空
- 验证项目配置是否存在
##### 2. 清除商险续签待办
- 调用商险服务清除该项目的商险续签待办事项
- 清除范围:状态为"待确认"(0)、"待派单"(1)的待办
##### 3. 清除合同续签待办
- 删除合同预生成记录(t_employee_contract_pre_new表)
- 条件:项目编码匹配 + 自动化标识为"0" + 流程状态为"待确认"(0)或"待发起"(1)
- 删除合同提醒记录(t_emp_contract_alert表)
- 条件:项目编码匹配 + 自动化标识为"0" + 流程状态为"待确认"(0)或"待发起"(1)
##### 4. 级联删除配置数据
按以下顺序删除关联配置:
**a. 商险规则配置**
- 删除商险标准信息明细(t_auto_standard_info)
- 删除商险购买标准(t_auto_insur_standard)
- 删除商险规则配置(t_auto_insur_rule_info)
**b. 合同规则配置**
- 删除合同签订方案配置(t_auto_contract_scheme)
- 删除合同规则配置(t_auto_contract_rule_info)
**c. 社保公积金规则配置**
- 删除社保规则明细(t_auto_social_rule_rel)
- 删除公积金规则明细(t_auto_fund_rule_rel)
- 删除社保规则配置(t_auto_social_rule_info)
- 删除公积金规则配置(t_auto_fund_rule_info)
**d. 档案规则配置**
- 删除档案管理规则配置(t_auto_emp_rule_info)
**e. 岗位字典配置**
- 删除项目岗位字典项(sys_auto_dict_item)
**f. 主表配置**
- 删除项目配置主表记录(t_auto_main_rel)
##### 5. 事务处理
- 整个删除过程在事务中执行,确保数据一致性
- 任何步骤失败都会回滚所有操作
## 3. 数据表说明
### 3.1 主要涉及的数据表
| 表名 | 说明 |
|------|------|
| t_auto_main_rel | 项目配置主表 |
| t_auto_emp_rule_info | 档案管理规则配置表 |
| t_auto_insur_rule_info | 商险规则配置表 |
| t_auto_insur_standard | 商险购买标准表 |
| t_auto_standard_info | 商险标准信息明细表 |
| t_auto_contract_rule_info | 员工合同签订规则配置表 |
| t_auto_contract_scheme | 员工合同签订规则方案表 |
| t_auto_social_rule_info | 社保规则配置表 |
| t_auto_social_rule_rel | 社保规则配置明细表 |
| t_auto_fund_rule_info | 公积金规则配置表 |
| t_auto_fund_rule_rel | 公积金规则配置明细表 |
| sys_auto_dict_item | 岗位字典项表 |
| t_emp_contract_alert | 合同提醒表 |
| t_employee_contract_pre_new | 合同预生成表 |
### 3.2 关键状态码说明
#### 商险续保状态
- `0`: 待确认
- `1`: 待派单
#### 合同续签状态
- `0`: 待确认
- `1`: 待发起
#### 自动化标识
- `0`: 自动化流程
- `1`: 非自动化流程
## 4. 使用示例
### 4.1 删除预检示例
```javascript
// 前端调用示例
axios.get('/tautomainrel/deletePrecheck/123456789', {
headers: {
'Authorization': 'Bearer YOUR_TOKEN'
}
})
.then(response => {
const { insuranceCount, contractCount, departName } = response.data.data;
if (insuranceCount > 0 || contractCount > 0) {
// 显示确认对话框
confirm(`项目"${departName}"存在未处理的待办事项:\n` +
`商险续签待办:${insuranceCount}条\n` +
`合同续签待办:${contractCount}条\n\n` +
`删除后将自动清除这些待办,是否继续?`);
} else {
// 直接删除
deleteProjectConfig('123456789');
}
});
```
### 4.2 删除项目配置示例
```javascript
// 前端调用示例
function deleteProjectConfig(id) {
axios.delete(`/tautomainrel/${id}`, {
headers: {
'Authorization': 'Bearer YOUR_TOKEN'
}
})
.then(response => {
if (response.data.code === 0) {
message.success('项目配置删除成功');
// 刷新列表
refreshList();
} else {
message.error('删除失败:' + response.data.msg);
}
})
.catch(error => {
message.error('网络异常,请稍后重试');
});
}
```
## 5. 注意事项
### 5.1 安全性考虑
1. **权限控制**: 删除操作需要`demo_tautomainrel_del`权限
2. **二次确认**: 建议前端在删除前调用预检接口,并向用户展示待办统计信息进行二次确认
3. **事务保护**: 删除操作在数据库事务中执行,保证数据一致性
### 5.2 业务影响
1. **不可逆操作**: 删除操作会永久删除项目配置及所有关联数据,无法恢复
2. **待办清除**: 会自动清除该项目下的商险和合同续签待办事项
3. **关联影响**: 删除后,该项目下员工的自动化配置将失效
### 5.3 性能考虑
1. **大数据量**: 如果项目下存在大量待办记录,删除操作可能耗时较长
2. **异步处理**: 商险待办清除通过Dapr调用,可能存在网络延迟
### 5.4 错误处理
常见错误情况:
- 项目配置不存在:返回"项目配置不存在"
- 清除商险待办失败:返回"清除商险续签待办失败:[具体原因]"
- 参数为空:返回"参数不能为空"
## 6. 版本历史
| 版本 | 日期 | 修改内容 | 修改人 |
|------|------|----------|--------|
| V1.0 | 2026-06-09 | 初始版本,包含删除预检和删除接口文档 | - |
## 7. 联系方式
如有问题,请联系开发团队。
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment