7.8 KiB

Raw Permalink Blame History

薪资计算器 API（N05）

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

发布状态（2026-10-08）：政策核验白名单默认为空；种子数据已入库不代表已获准发布。默认不提供城市参数或新计算，本人历史查询/删除仍保持原有角色及归属限制。

1. 能力边界

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

2. 查询城市列表

GET /salary-calculator/cities

仅返回启用且“城市编码 + 当前政策版本”均命中发布白名单的摘要，按省份编码和城市编码排序。默认返回 200，data=[]。以下非空响应仅为契约示例，不代表这些政策已上线。

响应示例：

{
  "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)

9. 政策核验与发布门禁

默认关闭

app.salary-publication.approved-policies 是城市编码到已核验政策版本的精确映射，默认空映射。enabled=true、dataLevel=CITY、种子数量或功能测试通过，均不等于政策已核验。V53 保留原字节，不修改种子或已有历史快照，也不新增迁移。

白名单配置

仅在完成核验和发布审批后，由部署人员通过外部 Spring 配置提供映射。例如下列内容只展示配置格式，不可直接照抄到生产：

app:
  salary-publication:
    approved-policies:
      "110000": "已核验记录对应的实际政策版本"

城市编码必须为六位数字，版本不能为空或包含首尾空白；非法配置启动失败。城市和数据库当前版本都必须精确匹配，版本变更后旧白名单不会自动批准新版本。不提供全量开放或按 CITY/PROVINCE_FALLBACK 批量开放的开关。

测试类显式配置的种子版本只用于算法、响应契约、并发与回滚验证，不可作为上线授权或政策准确性证据。生产默认配置没有任何批准项。

前端行为

城市列表默认 HTTP 200 / code=200 / data=[]；前端显示“薪资估算暂未开放”，不要自行回退到未经核验的本地参数。
未发布城市的详情和新计算返回 HTTP 404 / code=10601，使用既有固定错误文案，不泄露政策参数。
相同幂等键的历史重放也经过发布门禁；不能利用 POST 重放绕过关闭状态。
只有已发布政策才会进入原有版本冲突检查；未发布时不返回最新政策版本信息。

历史兼容

本人历史列表、详情和删除接口不受发布白名单影响，继续执行 STUDENT 角色与记录归属检查。历史快照仅表示当时的估算结果，不证明其政策准确，不能将其当成当前政策使用。

核验记录要求

每个拟开放城市必须补齐官方来源地址、发布主体、适用地区、有效期、社保和公积金基数与比例、固定费用、核验人和核验日期，并记录与数据库 policyVersion 的对应关系。省级回退数据还需核实适用性并明确展示估算限制。更正已提交政策应使用后续新增迁移，不改写 V1–V53。

当前 359 条种子的政策准确性尚未由本次测试证明，因此本轮不添加任何生产批准项；N03/N04 不受此门禁影响。合并、部署及部署后三中间件黑盒验收另行执行。

7.8 KiB Raw Permalink Blame History