社保管理模块，由 yudao-module-hrm 后端模块的 insurance、portal.insurance 包实现，前端实现在 @/views/hrm/insurance 和 @/views/hrm/portal/insurance 目录。

模块采用「当前配置 + 月度快照」的设计：参保方案随时可以调整，但每张月表在生成时会把方案项目复制成 JSON 快照，因此历史月份的缴费口径不会被后续改动影响。

• 参保方案：配置参保城市、户籍、缴费方式，以及社保、公积金项目。
• 员工参保资料：在员工档案中维护当前方案、社保账号、公积金账号和起缴月份。
• 月度社保：按自然月生成员工项目快照，支持添加员工、调整、停保和创建次月。

本文涉及表如下图所示：

1. 参保方案

参保方案，由 HrmInsuranceSchemeController 提供接口（/hrm/insurance/scheme）。主表保存方案范围，项目子表保存养老、医疗、失业、工伤、生育和公积金等缴费规则。

1.1 主表表结构

省略 creator/create_time/updater/update_time/deleted/tenant_id 等通用字段

CREATE TABLE `hrm_insurance_scheme` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '方案编号',

  `name` varchar(64) NOT NULL COMMENT '方案名称',
  `area_id` int DEFAULT NULL COMMENT '参保城市编号',
  `household_type` varchar(64) DEFAULT NULL COMMENT '户籍类型',
  `type` tinyint NOT NULL COMMENT '方案类型',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='HRM 社保方案';

① area_id 使用平台地区编号，保存时会归一到城市级；household_type 用于区分当地不同户籍口径。

② 枚举 type 方案类型（HrmInsuranceSchemeTypeEnum），对应字典 hrm_insurance_scheme_type：

值	枚举	说明	计算方式
1	PROPORTION	比例	公司 / 个人金额 = 缴纳基数 × 对应比例
2	AMOUNT	固定金额	直接使用项目中填写的公司 / 个人金额

③ name 方案名称由 Service 校验唯一。已被员工当前资料或任意月度记录引用的方案不能删除。

---

该表包含一个子表：

• hrm_insurance_scheme_project（社保方案项目）：在新增 / 编辑弹窗中维护，至少包含一个社保项目。

1.2 子表结构

CREATE TABLE `hrm_insurance_scheme_project` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '项目编号',

  `scheme_id` bigint NOT NULL COMMENT '方案编号',

  `type` tinyint NOT NULL COMMENT '项目类型',
  `name` varchar(64) NOT NULL COMMENT '项目名称',
  `base_amount` decimal(12,2) DEFAULT NULL COMMENT '缴纳基数',
  `corporate_rate` decimal(10,2) DEFAULT NULL COMMENT '公司比例',
  `personal_rate` decimal(10,2) DEFAULT NULL COMMENT '个人比例',
  `corporate_amount` decimal(12,2) DEFAULT NULL COMMENT '公司金额',
  `personal_amount` decimal(12,2) DEFAULT NULL COMMENT '个人金额',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='HRM 社保方案项目';

① scheme_id 关联 hrm_insurance_scheme 表的 id 字段。

② 枚举 type 项目类型（HrmInsuranceProjectTypeEnum），对应字典 hrm_insurance_project_type：1~9 属于社保（养老保险、医疗保险、失业保险、工伤保险、生育保险、补充大病医疗、补充养老、残保金、社保自定义），10~11 属于公积金（公积金、公积金自定义）。

③ 标准项目类型在同一方案内不能重复，自定义项目（9、11）可以配置多个。

方案修改与历史快照

修改方案时，系统逻辑删除旧方案及项目，再创建新版本，并把员工当前资料和员工月记录的 scheme_id 改指向新方案。

历史月记录的 projects JSON 和金额不会重算，因此历史缴费口径仍以当月快照为准。

1.3 管理后台

对应 [HRM 人力资源 -> 社保管理 -> 社保配置 -> 社保方案] 菜单，对应 yudao-ui-admin-vue3 项目的 @/views/hrm/insurance/scheme 目录。

列表

展示参保城市、公司 / 个人社保与公积金合计、当前使用人数和历史月记录数。

新增

通过弹窗 InsuranceSchemeForm.vue 完成。表单上半部分是方案基础信息（方案名称、参保城市、户籍类型、方案类型），下半部分是项目子表。

选择参保城市和户籍后，可通过 HrmInsuranceStandardController 加载标准参保方案一键带出项目，也可以直接添加社保、公积金和自定义项目。比例方式填写基数及公司 / 个人比例，表单自动计算金额；固定金额方式直接填写公司和个人金额。

修改

弹窗结构与新增相同。如上文所述，保存时实际是「逻辑删除旧版本 + 创建新版本」，并把引用方迁移到新方案。

删除

后端会同时删除方案项目；只要员工当前资料或任意月度记录仍引用该方案，就会拒绝删除。

标准参保数据

标准数据来自外部公开站点，并缓存非空结果 7 天；第三方超时或解析失败时返回空列表，不阻塞手工配置。HR 仍需核验当地最新基数、比例和上下限。

2. 员工参保资料

员工参保资料，由 HrmInsuranceEmployeeInfoController 提供接口（/hrm/insurance/employee-info）。它嵌入员工详情页，不设置独立列表菜单。

2.1 表结构

CREATE TABLE `hrm_insurance_employee_info` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '编号',

  `employee_id` bigint NOT NULL COMMENT '员工编号',
  `scheme_id` bigint DEFAULT NULL COMMENT '当前参保方案编号',

  `first_social_security` bit NOT NULL DEFAULT 0 COMMENT '是否首次参保',
  `first_accumulation_fund` bit NOT NULL DEFAULT 0 COMMENT '是否首次缴纳公积金',
  `social_security_number` varchar(64) DEFAULT NULL COMMENT '社保账号',
  `accumulation_fund_number` varchar(64) DEFAULT NULL COMMENT '公积金账号',
  `social_security_start_month` datetime DEFAULT NULL COMMENT '社保起缴月份',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='HRM 员工参保资料';

① employee_id 关联 hrm_employee 表的 id 字段，业务上每名员工只有一份当前资料；scheme_id 关联当前参保方案。

② 设置参保方案要求员工状态为正式或试用，且入职状态为在职或待离职。

③ social_security_start_month 保存为当月 1 日零点。生成首个月记录时该字段若为空，系统会自动回填月表月份。

2.2 管理后台

对应 [HRM 人力资源 -> 员工管理 -> 员工档案] 的员工详情页「工资社保」页签的「社保资料」区域，对应 yudao-ui-admin-vue3 项目的 @/views/hrm/employee/detail 目录。

查看

EmployeeInsuranceInfo.vue 展示当前参保方案、是否首次参保、社保 / 公积金账号和起缴月份。没有资料时显示待完善状态，不会创建空记录。

编辑

点击【编辑】打开 EmployeeInsuranceInfoForm.vue，方案下拉复用 InsuranceSchemeSelect.vue。表单维护是否首次参保、两个账号和当前方案，起缴月份只读。保存时首次新建资料，再次保存则更新同一员工记录。

批量设置方案

在员工列表勾选员工后，可打开 EmployeeInsuranceSchemeForm.vue 统一选择参保方案，并反馈成功数和失败数。

该操作只修改员工当前方案：后续新建的月份会采用新方案，已经生成的月份仍以各自快照为准。

3. 月度社保

月表，由 HrmInsuranceMonthRecordController 提供接口（/hrm/insurance/month-record）；员工月记录，由 HrmInsuranceMonthEmployeeRecordController 提供接口（/hrm/insurance/month-employee-record）。月表保存月份、汇总和归档状态，员工月记录保存当月项目快照。

3.1 主表表结构

CREATE TABLE `hrm_insurance_month_record` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '月表编号',

  `title` varchar(128) DEFAULT NULL COMMENT '标题',
  `year` int NOT NULL COMMENT '年份',
  `month` int NOT NULL COMMENT '月份',
  `status` tinyint DEFAULT NULL COMMENT '状态',

  `insured_employee_count` int DEFAULT NULL COMMENT '参保人数',
  `stopped_employee_count` int DEFAULT NULL COMMENT '停保人数',
  `personal_insurance_amount` decimal(12,2) DEFAULT NULL COMMENT '个人社保',
  `personal_provident_fund_amount` decimal(12,2) DEFAULT NULL COMMENT '个人公积金',
  `corporate_insurance_amount` decimal(12,2) DEFAULT NULL COMMENT '公司社保',
  `corporate_provident_fund_amount` decimal(12,2) DEFAULT NULL COMMENT '公司公积金',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='HRM 月度社保表';

① 枚举 status 月表状态（HrmInsuranceMonthStatusEnum，字典 hrm_insurance_month_status：0 = 未归档，1 = 已归档）。详见 §3.3 状态流转。

② 人数与四类金额均由 updateMonthRecordSummary 按员工月记录自动汇总，不需要前端传入；汇总时只累计正常参保的记录。

---

该表包含一个子表：

• hrm_insurance_month_employee_record（员工月度社保记录）：在月表详情页维护，保存该员工当月的项目快照与金额。

3.2 子表结构

CREATE TABLE `hrm_insurance_month_employee_record` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '员工月记录编号',

  `month_record_id` bigint NOT NULL COMMENT '月表编号',
  `employee_id` bigint NOT NULL COMMENT '员工编号',
  `scheme_id` bigint DEFAULT NULL COMMENT '方案编号',

  `year` int NOT NULL COMMENT '年份',
  `month` int NOT NULL COMMENT '月份',
  `status` tinyint DEFAULT NULL COMMENT '参保状态',

  `personal_insurance_amount` decimal(12,2) DEFAULT NULL COMMENT '个人社保',
  `personal_provident_fund_amount` decimal(12,2) DEFAULT NULL COMMENT '个人公积金',
  `corporate_insurance_amount` decimal(12,2) DEFAULT NULL COMMENT '公司社保',
  `corporate_provident_fund_amount` decimal(12,2) DEFAULT NULL COMMENT '公司公积金',
  `projects` varchar(10000) NOT NULL COMMENT '当月参保项目快照 JSON',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='HRM 员工月度社保记录';

① month_record_id 关联月表，employee_id 关联员工，scheme_id 关联生成快照时采用的方案。冗余的 year / month 便于员工历史和薪资按月查询。

② 枚举 status 参保状态（HrmInsuranceEmployeeStatusEnum），对应字典 hrm_insurance_emp_status：0 停保、1 正常。停保记录继续保留，但不计入参保人数和四类金额；未归档月可把同月停保员工重新添加为正常。

③ projects 保存项目类型、名称、基数、公司 / 个人比例和金额。月表生成后，修改当前方案不会重算该 JSON。

projects JSON 字段结构

[
  {
    "schemeProjectId": 31,
    "type": 1,
    "name": "养老保险",
    "baseAmount": 8000.00,
    "corporateRate": 16.00,
    "personalRate": 8.00,
    "corporateAmount": 1280.00,
    "personalAmount": 640.00
  },
  {
    "schemeProjectId": 36,
    "type": 10,
    "name": "公积金",
    "baseAmount": 8000.00,
    "corporateRate": 12.00,
    "personalRate": 12.00,
    "corporateAmount": 960.00,
    "personalAmount": 960.00
  }
]

① type 项目类型（HrmInsuranceProjectTypeEnum）：1 养老保险、2 医疗保险、3 失业保险、4 工伤保险、5 生育保险、6 补充大病医疗、7 补充养老、8 残保金、9 社保自定义、10 公积金、11 公积金自定义。10、11 归入公积金金额，其余归入社保金额，分别汇总到记录上的四个金额字段。

② schemeProjectId 指向生成快照时的 hrm_insurance_scheme_project，只用于追溯来源；按金额配置的项目 corporateRate、personalRate 为空。

③ 这份快照没有独立编号和生命周期，由 HrmInsuranceMonthEmployeeRecordDO 的内嵌对象承载，随员工月度记录整体保存。调整基数或比例时重写整个数组。

3.3 状态流转

月度社保表生命周期由 HrmInsuranceMonthRecordServiceImpl 控制。状态枚举 HrmInsuranceMonthStatusEnum：

状态值	枚举	说明	可执行操作
0	UNARCHIVED	未归档	添加员工、调整、停保、创建次月、删除
1	ARCHIVED	已归档	—

状态流转说明

创建首月 ──→ 未归档(0) ──创建次月──→ 已归档(1)（终态，只读）
                                    │
                                    └──→ 新的未归档(0) 月份

• 创建首月（createFirstMonthRecord）：选择起始年月后创建第一张月表，并按员工参保资料生成员工月记录。全局只允许创建一次。
• 维护员工月记录（createMonthEmployeeRecordList / updateMonthEmployeeRecord / stopMonthEmployeeRecordList）：仅未归档月可添加员工、调整项目金额和停保。每次变更后由 updateMonthRecordSummary 重新汇总月表人数与金额。
• 创建次月（createNextMonthRecord）：当前月归档并变为只读，同时复制正常参保员工生成下一月记录。
• 删除（deleteMonthRecord）：仅最新且未归档的月表可删除，删除后上一月恢复为当前月。已归档月表不可删除，避免破坏历史缴费口径。

3.4 管理后台

对应 [HRM 人力资源 -> 社保管理 -> 社保表] 菜单，对应 yudao-ui-admin-vue3 项目的 @/views/hrm/insurance/month-record 目录。

月份列表

按年份查询月表，展示参保 / 停保人数和公司 / 个人合计。点击月份进入详情页。

创建首月

系统尚无月表时，点击【创建首月】打开 InsuranceFirstMonthForm.vue 选择起始年月（createFirstMonthRecord）。系统为符合条件且已设置参保方案的员工生成首月快照，并在必要时回填员工的起缴月份。

创建次月

已有月表后，点击【创建次月】并确认（createNextMonthRecord）。系统把当前月归档，按自然月创建下一月，并根据员工当前方案生成新快照，完成后进入新月份详情。没有独立的归档按钮，归档由创建次月触发。

员工明细

月表详情页可按姓名、方案、参保城市和参保状态筛选员工。点击员工姓名打开 InsuranceMonthEmployeeDetail.vue，查看当月项目、公司 / 个人金额和汇总。

添加员工

未归档月点击【添加员工】打开 InsuranceAddEmployeeForm.vue。表单先排除当月已参保员工，再批量生成快照；同月已停保的员工重新添加后恢复正常参保。

调整与停保

单人调整使用 InsuranceEmployeeRecordForm.vue，可切换参保方案并修改项目基数、比例或金额；勾选员工后可通过 InsuranceBatchEmployeeRecordForm.vue 批量修改方案，或直接执行【停止参保】。每次变更都会重新汇总月表的人数和四类金额。

删除当前月

只有最新且未归档的月份可以删除（deleteMonthRecord），且系统至少保留一张月表。删除成功后，上一月恢复为未归档，可继续调整。

与薪资的衔接

薪资按年月读取状态为正常的员工月记录，把个人 / 企业社保和公积金同步为工资项。

调整未归档社保月后，需要在薪资侧重新核算；已生成的月工资快照不会自动变化，详见 《【薪资】月度工资、工资条》。

4. 我的社保

员工端「我的社保」，由 HrmPortalInsuranceController 提供只读接口（/hrm/portal/insurance/record），根据当前 system_users.id 反查 hrm_employee.user_id，只允许访问本人记录。

4.1 员工端

对应 [HRM 人力资源 -> HRM 员工端 -> 我的社保] 菜单，对应 yudao-ui-admin-vue3 项目的 @/views/hrm/portal/insurance 目录。

按年查询

页面默认查询最近有数据的年份，展示各月方案、参保状态和公司 / 个人金额。年份选择范围从本人的首个参保年份开始。

查看详情

点击【查看详情】打开 InsuranceRecordDetail.vue，读取当月 projects 快照，展示每个社保、公积金项目的基数、比例和金额。后端会校验该月记录属于当前账号绑定的员工，页面不提供修改操作。