TurboHR/20260816-账户关联部门.md

社保公积金账户关联根部门 + 员工新增自动带出账户

生成时间：2026-08-16 涉及模块：设置（账户管理）、花名册（新增员工）、组织架构（根部门关联） 核心文件：backend/src/routes/social.routes.ts、backend/src/routes/department.routes.ts、backend/src/services/contract.service.ts、frontend/src/pages/Settings.tsx、frontend/src/pages/roster/modals.tsx、frontend/src/lib/api-services.ts

---

一、需求背景

1. 社保公积金账户创建后，需要关联组织架构的根节点（公司/分公司/子公司，即 level=0 的部门）。
2. 员工新增时，选定部门后自动带出该部门所属根节点关联的社保公积金账户，可手工调整，确定后按账户当前生效的年度标准执行。

---

二、完成内容

1. 账户关联组织架构根节点

前端：设置页 → 社保公积金账户 Tab

• 新建/编辑账户弹窗新增"关联根部门"区域
• 列出所有 level=0 根部门（公司/分公司/子公司），可多选勾选
• 保存账户时同步关联到选中的根部门
• 编辑时自动加载已关联的部门并回显勾选状态

后端新增 API

方法	路径	说明
PUT	/social/accounts/:id/departments	批量设置账户关联的根部门（先清除旧关联，再批量设置新关联，仅限 level=0）
GET	/social/accounts/:id/departments	查询账户已关联的根部门列表
GET	/social/department-account/:departmentId	按部门带出适用账户 + 当前生效年度标准

部门 API

• PUT /departments/:id 的 schema 新增 socialAccountId、housingAccountId 可选字段
• 更新时写入 department.socialAccountId / department.housingAccountId

账户关联逻辑

• 账户类型为 SOCIAL 时，写入 department.socialAccountId
• 账户类型为 HOUSING 时，写入 department.housingAccountId
• 设置新关联前，先清除该账户的所有旧关联（updateMany 置 null）
• 仅允许关联 level=0 的根部门

---

2. 员工新增时自动带出账户

前端：花名册 → 新增员工

• 表单 state 新增 departmentId 字段，部门选择改为按 id 取值
• 选定部门后，自动调用 GET /social/department-account/:departmentId 查询适用账户
• 社保账户、公积金账户下拉框自动选中继承的账户
• 账户下方显示当前生效标准（基数范围、比例）
• 可手动调整账户选择（下拉切换到其他账户）
• 缴费基数默认与月工资一致，可手动修改
• 提交时将 socialAccountId / housingAccountId 写入参保记录

后端：按部门带出账户逻辑

GET /social/department-account/:departmentId 处理流程：

1. 从当前部门向上查找，直到 level=0 的根部门
2. 读取根部门的 socialAccount / housingAccount
3. 若根部门未关联账户，回退到公司默认账户（isDefault=true）
4. 查询账户当前生效的 SocialYearStandard（isCurrent=true）
5. 返回 { socialAccount, housingAccount, socialStandard, housingStandard }

后端：参保记录写入 accountId

contract.service.ts 中 createEmployee：

• EmployeeSocialInsRecord.create 写入 accountId: data.socialAccountId || null
• EmployeeHousingFundRecord.create 写入 accountId: data.housingAccountId || null

---

三、数据流

设置页：创建账户 → 勾选根部门 → 保存
    ↓
department.socialAccountId / housingAccountId
    ↓
新增员工：选择部门 → 向上找根部门 → 读取关联账户
    ↓
自动带出账户 + 当前标准 → 可手动调整
    ↓
提交 → EmployeeSocialInsRecord.accountId / EmployeeHousingFundRecord.accountId
    ↓
薪资计算：通过员工账户查年度标准 → 计算社保公积金

---

四、使用流程

1. 在 设置 → 社保公积金账户 中创建账户，勾选关联的根部门
2. 新增员工时选择部门 → 自动带出对应账户 → 确认基数 → 保存
3. 薪资计算时按员工账户的年度标准执行

---

五、兼容性

• 旧 SocialInsuranceConfig / HousingFundConfig 表保留
• 薪资计算优先用新账户年度标准，查不到回退旧表
• 未关联账户的根部门，员工新增时回退到公司默认账户
• RehireModal（重新入职）保持原有逻辑，不自动带出账户（员工已有参保记录）

---

六、部署记录

• 提交：014c94e feat: 账户关联根部门 + 员工新增自动带出账户
• 部署：2026-08-16 已部署到 https://on.hr8ai.top/
• 数据库：schema 同步完成（Department 表 socialAccountId/housingAccountId 字段已存在）