4.9 KiB

Raw Blame History

薪资计算器 API（N05）

Base URL：/api/v1 认证：Authorization: Bearer <access-token> 角色：当前登录用户必须具备 STUDENT 角色。

1. 能力边界

输入税前月薪，估算个人五险一金、大病固定费和当月个税后的到手工资。
采用居民个人综合所得累计预扣法；monthIndex 表示当前工资口径下的累计计税月份数，而不是自然月编号。
支持用户覆盖社保基数、公积金基数和个人比例。
城市政策以地级行政区、直辖市和省直辖县级市为最小单元，不拆分到区县。
dataLevel=CITY 表示城市级参数；dataLevel=PROVINCE_FALLBACK 表示由于公开城市级资料不足而使用省级回退参数，结果精度较低。
所有结果均为估算值，实际以工资单、当地政策和税务申报为准。

2. 查询城市列表

GET /salary-calculator/cities

返回全部启用城市摘要，按省份编码和城市编码排序。

响应示例：

{
  "code": 200,
  "message": "ok",
  "data": [
    {
      "cityCode": "110000",
      "provinceCode": "110000",
      "provinceName": "北京市",
      "cityName": "北京市",
      "policyVersion": "2026-09-20-v1",
      "policyEffectiveDate": "2026-07-01",
      "dataLevel": "CITY"
    }
  ]
}

3. 查询城市默认参数

GET /salary-calculator/cities/{cityCode}

返回城市级或省级回退的当前默认参数。计算请求必须原样携带响应中的 policyVersion 作为 expectedPolicyVersion。

4. 计算并保存

POST /salary-calculator/calculations

请求示例：

{
  "cityCode": "110000",
  "grossMonthlySalary": 10000.00,
  "monthIndex": 1,
  "specialAdditionalDeduction": 0.00,
  "expectedPolicyVersion": "2026-09-20-v1",
  "idempotencyKey": "optional-client-key",
  "overrides": {
    "socialSecurityBase": 10000.00,
    "housingFundBase": 10000.00,
    "pensionRate": 0.08,
    "medicalRate": 0.02,
    "unemploymentRate": 0.005,
    "housingFundRate": 0.12,
    "seriousIllnessMonthlyFee": 0.00
  }
}

cityCode、grossMonthlySalary、expectedPolicyVersion 必填。
monthIndex 默认 1，范围 1–12。
specialAdditionalDeduction 默认 0。
idempotencyKey 可选，最长 64 字符；同用户同键同规范化请求返回原历史，同键不同请求返回 409/10604。
覆盖基数必须位于对应城市范围内；比例为 0 时允许基数为 0。

成功响应：

{
  "code": 200,
  "message": "ok",
  "data": {
    "historyId": 123,
    "createdAt": "2026-09-20T16:00:00",
    "result": {
      "cityCode": "110000",
      "cityName": "北京市",
      "dataLevel": "CITY",
      "policyVersion": "2026-09-20-v1",
      "policyEffectiveDate": "2026-07-01",
      "taxRulesVersion": "CN_IIT_2019_V1",
      "estimate": true,
      "monthIndex": 1,
      "grossMonthlySalary": 10000.00,
      "socialSecurityBase": 10000.00,
      "housingFundBase": 10000.00,
      "pension": 800.00,
      "medical": 200.00,
      "unemployment": 50.00,
      "housingFund": 1200.00,
      "currentMonthTax": 82.50,
      "netSalary": 7667.50
    }
  }
}

5. 查询历史

GET /salary-calculator/calculations?page=0&size=20

仅返回当前用户的记录。
按创建时间倒序、历史 ID 倒序。
size 最大 100。

GET /salary-calculator/calculations/{id}

返回输入、政策、覆盖项和结果三组完整 JSON 快照。访问他人历史统一返回 404/10603。

6. 删除历史

DELETE /salary-calculator/calculations/{id}

物理删除本人历史；成功后再次查询返回 404/10603。删除后原幂等键可重新使用。

7. 错误码

HTTP	code	含义
400	10602	工资、比例、基数或分页参数非法
401	401	未登录或 Token 无效
403	2002	已登录但不是 `STUDENT`
404	10601	城市不存在、停用或未配置
404	10603	历史不存在或不属于当前用户
409	10604	幂等键冲突
409	10605	城市政策版本已变化

10605 响应会在 data 中返回最新 policyVersion 和 policyEffectiveDate，客户端应重新加载城市详情后再试算。

8. 计算口径

社保基数 = 用户覆盖值，否则 min(max(税前月薪, 社保下限), 社保上限)
公积金基数 = 用户覆盖值，否则 min(max(税前月薪, 公积金下限), 公积金上限)

累计收入 = 税前月薪 × monthIndex
累计基本减除费用 = 5000 × monthIndex
累计专项附加扣除 = 月度专项附加扣除 × monthIndex
累计应纳税所得额 = max(累计收入 - 累计个人社保 - 累计公积金 - 累计大病费
                         - 累计基本减除费用 - 累计专项附加扣除, 0)
当月个税 = max(累计应纳税额 - 累计已预扣税额, 0)
到手工资 = max(税前月薪 - 个人养老 - 个人医疗 - 个人失业 - 个人公积金
               - 大病固定费 - 当月个税, 0)

4.9 KiB Raw Blame History