# 薪资计算器 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=[]`。以下非空响应仅为契约示例，不代表这些政策已上线。

响应示例：

```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/10604`。
- 覆盖基数必须位于对应城市范围内；比例为 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/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. 计算口径

```text
社保基数 = 用户覆盖值，否则 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 配置提供映射。例如下列内容只展示配置格式，不可直接照抄到生产：

```yaml
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 不受此门禁影响。合并、部署及部署后三中间件黑盒验收另行执行。