5.9 KiB

Raw Blame History

n05-salary-calc 薪资计算器与历史记录

Why

路线图将“薪资计算器”列为完全缺失能力，当前后端没有城市社保、公积金政策参数，也没有统一的到手工资计算与历史快照。求职者只能手工套用税率和各地政策，容易出现基数截断、累计预扣、个人缴费比例或大病固定费口径错误，且无法保存和复核自己的估算结果。

本变更新增一个面向已登录 STUDENT 的后端闭环：按中国大陆地级行政区和省直辖县级市加载当前政策，允许用户覆盖个人缴费参数，按居民个人综合所得累计预扣法估算到手工资，并把每次成功计算保存为独立的不可变历史快照。

What Changes

新增 salarycalculator 后端模块与六个接口：
- GET /salary-calculator/cities
- GET /salary-calculator/cities/{cityCode}
- POST /salary-calculator/calculations
- GET /salary-calculator/calculations
- GET /salary-calculator/calculations/{id}
- DELETE /salary-calculator/calculations/{id}
新增 salary_city_policy 与 salary_calculation_history 两张核心表，V40 建表，V41 写入覆盖全部目标城市的政策种子，并通过 dataLevel 区分城市级参数与省级回退参数。
城市政策以六位行政区划代码为主键，覆盖大陆全部地级行政区、直辖市和省直辖县级市；同城不拆分到区县。每条记录标记 CITY 或 PROVINCE_FALLBACK，不得把省级近似值伪装成城市级官方值。
计算支持城市默认值、用户覆盖项、社保与公积金基数截断、个人养老/医疗/失业/公积金、大病固定费、专项附加扣除、累计月份和居民个人综合所得累计预扣。
历史记录保存输入、城市默认参数、用户覆盖项、最终生效参数、完整结果、城市政策版本、全国税率版本和创建时间；历史不可编辑，支持分页列表、详情和物理删除单条。
计算接口支持可选 idempotencyKey 和服务端请求指纹去重，并要求 expectedPolicyVersion 与当前城市政策版本一致。
新增 9801–9805 错误码，覆盖城市不存在、参数非法、历史不存在、幂等冲突和政策版本冲突。
薪资历史不写入业务审计日志、不进入个人数据导出；账号注销完成时物理删除该用户全部薪资历史。

Scope

In Scope

中国大陆地级行政区、直辖市和省直辖县级市的城市政策配置、启用状态、dataLevel 数据精度、政策版本与生效日期。
城市列表、城市详情和当前默认参数查询。
税前月薪、累计月份、专项附加扣除和用户覆盖项驱动的到手工资估算。
居民个人综合所得累计预扣、个人五险一金、公积金和大病固定费计算。
计算历史的快照保存、分页查询、详情、物理删除和账号注销清理。
STUDENT 角色、JWT 身份、用户数据隔离、政策版本冲突和幂等并发处理。
V40/V41 Flyway 迁移、H2 集成测试、真实 MySQL/Docker 黑盒验收、OpenAPI 和前端联调文档。

Out of Scope

前端页面、交互设计、客户端状态管理和支付/工资单集成。
企业用工成本、单位社保和单位公积金视角。
年终奖、13 薪、绩效、提成、股票、期权、副业或多单位收入。
入职、离职、请假导致的天级折算，非居民个人计税和年度汇算清缴。
个税专项附加扣除的项目级明细、家庭成员和年度限额管理。
行业薪资参考、岗位薪资排名、薪资分布和 Offer 综合比较。
ADMIN 城市政策维护界面、外部实时政策 API 和自动抓取服务。\n- 不承诺未核验城市参数达到城市级官方精确度；此类城市只能使用明确标记的省级回退参数。
个人数据导出中的薪资历史章节。
港澳台地区和其他不适用内地社保、公积金及税制的地区。

Impact

mydreamjob-server/src/main/resources/db/migration/：新增 V40、V41，不修改历史迁移。
mydreamjob-server/src/main/java/com/mydreamjob/salarycalculator/：新增实体、Repository、计算服务、Controller、DTO 和错误处理。
mydreamjob-server/src/main/java/com/mydreamjob/common/exception/ErrorCode.java：新增 9801–9805。
mydreamjob-server/src/main/java/com/mydreamjob/config/SecurityConfig.java：明确薪资接口的认证入口。
mydreamjob-server/src/main/java/com/mydreamjob/deletion/AccountDeletionCompletionWorker.java：在注销完成事务中清理该用户薪资历史。
mydreamjob-server/src/test/java/com/mydreamjob/salarycalculator/：新增单元、MockMvc、持久化、权限、幂等、迁移和端到端测试。
docs/openapi-rc.json、docs/salary-calculator-api.md、docs/frontend-integration.md、docs/backend-development-roadmap.md、README.md：同步接口、错误码、计算口径和状态。
不改变现有 Offer、个人资料、求职偏好、账号注销读接口或既有错误码语义。

Proof of Completion

已登录 STUDENT 可通过城市接口加载当前政策，通过计算接口获得包含当月与累计拆解的到手工资估算。
用户覆盖项优先于城市默认值；基数截断、比例、上限、大病固定费、专项扣除和累计税款的边界测试全部通过。
政策版本不匹配返回 409/9805 且不生成历史；相同幂等键重放不产生重复历史，同键不同规范化请求返回 409/9804。
历史只能由所属用户查询和删除；删除为物理删除，账号注销完成会清理该用户全部薪资历史。
V41 种子测试证明目标城市全覆盖、城市编码唯一、字段合法、生效日期不晚于采集截止日、版本号非空，并明确区分城市级与省级回退记录。
mvn -Dtest=SalaryCalculator*Test test、mvn clean verify、python docs/verify_openapi.py 和真实 MySQL/Docker 黑盒验收通过。

5.9 KiB Raw Blame History