# 社保公积金方案改为「按部门绑定」 - 前端联调方案

## 变更背景

原来社保公积金方案只能一个员工一个员工地在「员工社保公积金档案」里绑定，几百号人逐个维护不现实。
现在方案本身可以挂「适用部门」，薪资核算时按员工所在部门取方案；原来的员工档案保留作个别覆盖。

## 涉及页面

- 社保公积金方案（`/hrm/salary/social-security-scheme`）：表单新增「适用部门」「默认社保基数」「默认公积金基数」，列表新增「适用部门」列
- 薪资核算（`/hrm/salary/calculation`）：无需改造，接口入参本来就有 `deptId`，行为自动生效
- 员工社保公积金档案：不改，继续作为个别覆盖入口

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /hrm/salary/social-security-scheme/create | 新增方案，可带适用部门与默认基数 |
| PUT | /hrm/salary/social-security-scheme/update | 修改方案，适用部门为整组替换（传空数组即解除全部部门） |
| GET | /hrm/salary/social-security-scheme/get | 详情，返回 `deptIds` / `deptNames` |
| GET | /hrm/salary/social-security-scheme/list | 列表，返回 `deptIds` / `deptNames` |
| GET | /hrm/salary/calculation/preview | 试算，入参 `period` + 可选 `deptId` |

**请求参数新增（create / update）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| deptIds | Long[] | 否 | 适用部门ID列表；空数组或不传 = 不限定部门（全局默认方案） |
| defaultSocialSecurityBase | Decimal | 否 | 默认社保缴费基数；留空则用员工基本工资 |
| defaultHousingFundBase | Decimal | 否 | 默认公积金缴费基数；留空或 0 则用社保基数 |

**响应字段新增（get / list）：**

| 字段 | 类型 | 说明 |
|------|------|------|
| deptIds | Long[] | 适用部门ID列表，未绑定返回 `[]` |
| deptNames | String | 适用部门名称，多个用「、」连接；未绑定返回空串。名称解析失败时回退 `ID=xxx` |
| defaultSocialSecurityBase | Decimal | 默认社保缴费基数，可为 null |
| defaultHousingFundBase | Decimal | 默认公积金缴费基数，可为 null |

**响应示例：**

```json
{
  "code": 0,
  "data": {
    "id": 3,
    "name": "2026年宁夏社保标准",
    "effectiveDate": "2026-01-01",
    "deptIds": [119, 129],
    "deptNames": "生产部、仓储部",
    "defaultSocialSecurityBase": 5023.00,
    "defaultHousingFundBase": 0.00,
    "status": 0
  }
}
```

**部门冲突报错（code 1030005027）：**

```json
{
  "code": 1030005027,
  "data": null,
  "msg": "部门【生产部】已绑定方案【2025年宁夏社保标准】，无法再绑定到方案【2026年宁夏社保标准】。请先在原方案上取消该部门，或改选其它部门"
}
```

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| 适用部门 | 方案表单（多选树） | 不选表示全局默认方案，placeholder 已写明「只对所选部门本级的员工生效」 |
| 适用部门 | 方案列表 | 直接展示后端 `deptNames`；为空时显示「全局默认」标签 |
| 默认社保基数 / 默认公积金基数 | 方案表单 | `InputNumber`，`min: 0`、`precision: 2`，允许留空 |
| 社保/公积金扣款 | 核算列表、试算弹窗 | 无需改动，后端按新优先级取数 |

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 比例来源优先级 | ① 员工社保档案指定的方案 ② 员工所在部门绑定的启用方案（生效日期 ≤ 核算期间，取最新） ③ 未绑定任何部门的启用方案中生效日期最新者（全局默认） ④ 都没有则用代码默认比例 |
| 缴费基数优先级 | 社保基数：档案 → 方案默认社保基数 → 员工基本工资；公积金基数：档案 → 方案默认公积金基数（>0 才用）→ 社保基数 |
| 部门覆盖范围 | 只覆盖所选部门**本级**的员工，不含子部门 |
| 一个部门的归属 | 一个部门同时只能绑定一个方案；保存时若该部门已被别的方案占用，返回上面那条精确报错 |
| 删除方案 | 方案删除时其部门关联一并解除，部门随之空闲 |

## 注意事项

- 方案的「适用部门」是**整组替换**语义：编辑时要把当前绑定的部门全部回显到多选框里再提交，不能只提交本次新增的部门。
- 存量方案默认没有绑定任何部门，因此都是「全局默认」候选；此时核算结果与改造前完全一致（万通 23 名员工口径已逐行核对一致），要生效必须先给方案填「默认缴费基数」并把方案绑到部门。
- 员工社保公积金档案里已指定方案的员工，永远优先走档案，方案绑定部门不会改变他们的金额。
- 比例输入框走的是「百分比显示、小数存储」：界面填 8.5 表示 8.5%，落库 0.085；显示保留 2 位百分比小数，与数据库 `decimal(5,4)` 精度一一对应。个税税率配置页的表单与列表同口径。