社保管理由 yudao-module-hrm 的 insurance、portal.insurance 包实现，采用“当前配置 + 月度快照”的设计。

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

本文涉及表如下图所示：

1. 参保方案

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

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 '方案类型：1 比例、2 固定金额',
  PRIMARY KEY (`id`)
) COMMENT='HRM 社保方案';

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

② type = 1 时按“缴纳基数 × 比例”计算公司和个人金额；type = 2 时直接使用项目中的固定金额。

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

hrm_insurance_scheme_project 表结构

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`)
) COMMENT='HRM 社保方案项目';

scheme_id 关联 hrm_insurance_scheme.id。标准项目类型在同一方案内不能重复，自定义项目可以配置多个；每个方案至少包含一个社保项目。

方案修改与历史快照

修改方案时，系统逻辑删除旧方案及项目，再创建新版本，并把员工当前资料和员工月记录的 scheme_id 改指向新方案。历史月记录的 projects JSON 和金额不会重算，因此历史缴费口径仍以当月快照为准。

1.2 管理后台

对应 [HRM 人力资源 -> 社保管理 -> 社保配置 -> 社保方案] 菜单。

列表

列表由 @/views/hrm/insurance/scheme/index.vue 实现，通过 HrmInsuranceSchemeController 的 GET /hrm/insurance/scheme/list 查询方案，展示参保城市、公司/个人社保与公积金、当前使用人数和历史月记录数，并提供新增、修改、删除操作。

新增 / 修改

点击“新建参保方案”或“修改”打开同目录的 InsuranceSchemeForm.vue。表单选择参保城市和户籍后，可通过 HrmInsuranceStandardController 的 GET /hrm/insurance/standard/type-list、GET /hrm/insurance/standard/project-list 加载标准方案，也可以直接添加社保、公积金和自定义项目。

比例方式填写基数及公司/个人比例，表单自动计算金额；固定金额方式直接填写公司和个人金额。修改时先调用 GET /hrm/insurance/scheme/get 回显，保存时分别调用 POST /hrm/insurance/scheme/create、PUT /hrm/insurance/scheme/update。保存成功后关闭弹窗并刷新列表。

删除

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

标准参保数据

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

2. 员工参保资料

员工参保资料由 HrmInsuranceEmployeeInfoController 提供接口，嵌入员工详情页，不设置独立列表菜单。

2.1 表结构

CREATE TABLE `hrm_insurance_employee_info` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '编号',
  `employee_id` bigint NOT 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 '社保起缴月份',
  `scheme_id` bigint DEFAULT NULL COMMENT '当前参保方案编号',
  PRIMARY KEY (`id`)
) COMMENT='HRM 员工参保资料';

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

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

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

2.2 管理后台

对应 [HRM 人力资源 -> 员工管理 -> 员工详情] 的“社保信息”区域。

查看

@/views/hrm/employee/detail/EmployeeInsuranceInfo.vue 在员工详情中调用 HrmInsuranceEmployeeInfoController 的 GET /hrm/insurance/employee-info/get，展示当前参保方案、是否首次参保、社保/公积金账号和起缴月份。没有资料时显示待完善状态，不会创建空记录。

编辑

点击“编辑”打开 EmployeeInsuranceInfoForm.vue。方案下拉复用 @/views/hrm/insurance/scheme/components/InsuranceSchemeSelect.vue；表单维护是否首次参保、两个账号和当前方案，起缴月份只读。

保存调用 PUT /hrm/insurance/employee-info/save：首次保存时新建资料，再次保存时更新同一员工记录。

批量设置方案

员工列表选择一名或多名员工后，可打开 @/views/hrm/employee/EmployeeInsuranceSchemeForm.vue 统一选择参保方案。组件逐名调用 PUT /hrm/insurance/employee-info/update-scheme，并反馈成功数和失败数。该操作只修改员工当前方案，后续新建月份会采用新方案，已经生成的月份仍以各自快照为准。

3. 月度社保

月表由 HrmInsuranceMonthRecordController 提供接口，员工月记录由 HrmInsuranceMonthEmployeeRecordController 提供接口。月表保存月份、汇总和归档状态，员工月记录保存当月项目快照。

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 '月份',
  `insured_employee_count` int DEFAULT NULL COMMENT '参保人数',
  `stopped_employee_count` int DEFAULT NULL COMMENT '停保人数',
  `status` tinyint DEFAULT NULL COMMENT '状态：0 未归档、1 已归档',
  `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`)
) COMMENT='HRM 月度社保表';

① 首次使用可选择起始年月创建首月，之后只能按自然月创建下一张月表。创建次月时自动归档当前月，没有独立归档按钮。

② 未归档月可以添加员工、调整项目和停保；已归档月只读。仅最新未归档月允许删除，且至少保留一张月表，删除后上一月恢复为未归档。

hrm_insurance_month_employee_record 表结构

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 '月份',
  `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 '公司公积金',
  `status` tinyint DEFAULT NULL COMMENT '参保状态：0 停保、1 正常',
  `projects` varchar(10000) NOT NULL COMMENT '当月参保项目快照 JSON',
  PRIMARY KEY (`id`)
) COMMENT='HRM 员工月度社保记录';

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

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

③ 汇总只累计正常参保记录。停保记录继续保留，但不计入参保人数和四类金额；未归档月可把同月停保员工重新添加为正常。

3.2 管理后台

对应 [HRM 人力资源 -> 社保管理 -> 社保表] 菜单。

月份列表

列表由 @/views/hrm/insurance/month-record/index.vue 实现，通过 HrmInsuranceMonthRecordController 的 GET /hrm/insurance/month-record/list 按年份查询月表，展示参保/停保人数和公司/个人合计。点击月份进入 @/views/hrm/insurance/month-record/detail/index.vue。

创建首月

系统尚无月表时，点击“创建首月”打开 InsuranceFirstMonthForm.vue 选择起始年月，调用 POST /hrm/insurance/month-record/create-first。系统为符合条件且已设置参保方案的员工生成首月快照，并在必要时回填员工的起缴月份。

创建次月

已有月表后，点击“创建次月”并确认，调用 POST /hrm/insurance/month-record/create-next。系统把当前月归档，按自然月创建下一月，并根据员工当前方案生成新快照；完成后进入新月份详情。已归档月份只允许查询。

员工明细

详情页 @/views/hrm/insurance/month-record/detail/index.vue 调用 HrmInsuranceMonthEmployeeRecordController 的 GET /hrm/insurance/month-employee-record/page，可按姓名、方案、参保城市和参保状态筛选。点击员工姓名打开 InsuranceMonthEmployeeDetail.vue，通过 GET /hrm/insurance/month-employee-record/get 查看当月项目、公司/个人金额和汇总。

添加员工

未归档月点击“添加员工”打开 InsuranceAddEmployeeForm.vue。表单先调用 GET /hrm/insurance/month-employee-record/uninsured-employee-list 排除当月已参保员工，再调用 POST /hrm/insurance/month-employee-record/create-list 批量生成快照；同月已停保的员工重新添加后恢复正常参保。

调整 / 停保

单人调整使用 InsuranceEmployeeRecordForm.vue，可切换参保方案并修改项目基数、比例或金额，保存调用 PUT /hrm/insurance/month-employee-record/update。勾选员工后，批量调整通过 InsuranceBatchEmployeeRecordForm.vue 修改方案；点击“停止参保”则由详情页确认后直接调用 PUT /hrm/insurance/month-employee-record/stop-list。每次变更都会重新汇总月表人数和四类金额。

删除当前月

最新且未归档的月份可在确认后调用 DELETE /hrm/insurance/month-record/delete。系统至少保留一张月表；删除成功后，上一月恢复为未归档，可继续调整。

与薪资的衔接

薪资按年月读取状态为正常的员工月记录，把个人/企业社保和公积金同步为工资项。调整未归档社保月后，需要在薪资侧重新核算；已生成的月工资快照不会自动变化。

4. 员工端

员工端由 HrmPortalInsuranceController 提供只读接口，根据当前 system_users.id 反查 hrm_employee.user_id，只允许访问本人记录。

4.1 员工端页面

对应 [HRM 人力资源 -> HRM 员工端 -> 我的社保] 菜单。

按年查询

页面由 @/views/hrm/portal/insurance/record/index.vue 实现，默认查询最近有数据的年份，调用 GET /hrm/portal/insurance/record/list 展示各月方案、参保状态和公司/个人金额。年份选择范围从本人的首个参保年份开始。

查看详情

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