# 薪资计算器 API（N05）

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

## 1. 能力边界

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

## 2. 查询城市列表

`GET /salary-calculator/cities`

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

响应示例：

```json
{
  "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`

请求示例：

```json
{
  "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/9804`。
- 覆盖基数必须位于对应城市范围内；比例为 0 时允许基数为 0。

成功响应：

```json
{
  "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/9803`。

## 6. 删除历史

`DELETE /salary-calculator/calculations/{id}`

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

## 7. 错误码

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

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

## 8. 计算口径

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

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