lxq/changes/n05-salary-calc/design.md

n05-salary-calc 技术设计

Facts and Constraints

• 当前项目为 Spring Boot 3.5.16、Java 17、Spring Data JPA、Flyway、MySQL 8.4，测试使用 H2 MODE=MySQL。
• 现有 Flyway 迁移最高为 V39，本次只能新增 V40、V41，不得修改已发布迁移。
• JWT 认证过滤器把用户 ID 设置为 Authentication principal；现有业务模块通过 UserRepository 查询用户并检查 User.getRoles() 是否包含 STUDENT。
• 现有统一响应为 ApiResponse，分页响应为 PageResponse，分页默认值为 page=0、size=20。
• 现有账号注销守卫在 PENDING 时阻止 POST/PUT/PATCH/DELETE，在 COMPLETED 时阻止全部业务请求；注销完成事务会脱敏用户 PII 并保留业务数据。
• 路线图当前将薪资计算器列为“未开始”，仓库中没有现成城市政策数据表或薪资模块代码。
• 城市政策必须按中国大陆地级行政区、直辖市和省直辖县级市配置，不拆分到区县；目标城市全量覆盖是发布门槛。
• 用户确认不提供 ADMIN 城市政策维护接口，城市政策通过迁移发布。
• 薪资历史不进入个人数据导出，不写业务审计日志，账号注销时物理删除。

Goals and Non-Goals

Goals

• 提供可验证的六个 /salary-calculator/** 接口，并只允许当前具有 STUDENT 角色的登录用户使用。
• 通过 cityCode 加载当前城市默认参数，执行可覆盖、可追溯的到手工资估算。
• 保存每次成功计算的可独立读取的历史快照，支持分页查询、详情和物理删除。
• 通过政策版本和幂等键分别解决“计算时政策已变化”和“请求重复提交”问题。
• 让城市政策、计算结果、权限和历史生命周期在测试中具有明确、可复现的边界。

Non-Goals

• 不设计前端页面、交互状态或客户端缓存策略。
• 不计算企业成本、年度汇算、奖金、股权、多收入来源或非居民税制。
• 不提供城市政策管理后台、自动抓取或第三方实时政策 API。
• 不把薪资历史纳入个人数据导出，也不保留用于业务审计的历史副本。
• 不支持港澳台地区或不适用内地职工社保、公积金政策的地区。

Decisions

Decision: 城市政策采用“当前有效行 + 历史快照”，不建立政策版本链

• Choice：salary_city_policy 每个六位 city_code 保留一条当前记录，保存 policy_version、policy_effective_date、参数和 enabled；历史计算把实际使用的参数复制到自身 JSON 快照。
• Rationale：每城市只有一套当前默认参数，约数百条记录足以维护；历史结果不应因为后续政策更新或停用而改变。
• Alternatives：建立 city_policy_versions 表并按生效期查询；前端携带完整默认参数。
  • 版本链会引入查询时间、发布调度和历史外键复杂度；前端传参加重客户端信任边界。
• Consequences：城市政策变更必须同步提升 policy_version；历史表不需要关联具体版本行，但必须保存完整政策快照。

Decision: 使用两张核心表，历史核心字段列式存储、快照 JSON 化

• Choice：新增 salary_city_policy 和 salary_calculation_history。历史表保存用户 ID、城市编码/名称、税前月薪、到手工资、月份、幂等键、请求指纹、创建时间等核心列，以及输入、政策、结果三组 JSON 快照。
• Rationale：核心列用于权限隔离、分页、排序和摘要展示；JSON 快照避免为每个未来字段新增大量列，同时保留历史可重建性。
• Alternatives：把所有历史和计算结果规范化为多张明细表；只存一个最终结果 JSON。
  • 多表模型增加查询和迁移成本；只存结果 JSON 无法稳定做列表排序、权限过滤或金额摘要。
• Consequences：需要定义稳定的 JSON 结构和最大长度；H2/MySQL 集成测试必须验证 JSON 字段读写和唯一约束。

Decision: 计算引擎在 Java 中使用 BigDecimal，全国税制与地方政策分层

• Choice：城市表只存地方社保、公积金和大病参数；全国统一个税税率表、速算扣除数、5,000 元基本减除费用和税率版本作为 Java 常量。计算公式按以下顺序执行：
  1. 根据城市政策截断或采用用户覆盖基数。
  2. 计算个人养老、医疗、失业、公积金和大病固定费。
  3. 按 monthIndex 推导累计收入、累计个人缴费、累计专项附加扣除和累计基本减除费用。
  4. 计算累计应纳税所得额、按全国税率表计算累计应纳税额和当月税额。
  5. 计算到手工资并按两位小数输出。
• Rationale：全国税制不应复制到每个城市；高精度十进制才能避免金额和累计税款的舍入漂移。
• Alternatives：由数据库 SQL 计算；用 double 计算。
  • SQL 会混合迁移和算法版本；double 不适用于金额和累计税额。
• Consequences：算法和税率版本进入独立单元测试；历史记录保存累计税费和 taxRulesVersion，以便变更税率时有审计轨迹。

Decision: 计算请求使用 expectedPolicyVersion 做乐观版本校验

• Choice：计算请求必须携带前端已加载的 expectedPolicyVersion。后端读取当前城市配置后先比较版本；不一致时返回 409/9805，响应只附最新 policyVersion 和 policyEffectiveDate，不生成历史。
• Rationale：城市详情和计算请求之间可能发生政策更新；静默使用新参数会让前端展示、用户覆盖和历史解释互相矛盾。
• Alternatives：后端始终使用最新配置；客户端把完整默认参数回传。
  • 静默使用最新版本会产生不可解释的历史；回传完整参数会扩大请求和信任边界。
• Consequences：政策维护流程必须保证任何参数变更都提升版本号；前端需要在版本冲突时重新加载城市详情并重新提交。

Decision: 幂等键和规范化请求指纹在同一事务中处理

• Choice：idempotencyKey 可选、最长 64 字符、空白视为未提供。请求先归一化可选字段、默认值和覆盖项，再计算业务字段指纹；同一用户同键且指纹相同返回原历史，指纹不同返回 409/9804。
• Rationale：原始 JSON 的字段顺序、空白和显式 null 不能代表业务请求是否相同；事务和数据库唯一约束必须作为并发最终防线。
• Alternatives：直接比较原始请求体；不提供幂等控制。
  • 原始请求比较误判同义请求；不提供幂等会在网络重试或双击时生成重复历史。
• Consequences：历史表需要 (student_user_id, idempotency_key) 唯一约束和请求指纹列；删除历史同时释放对应键。

Decision: 历史接口只暴露摘要和本人快照，删除采用物理删除

• Choice：列表返回摘要，详情返回完整快照；不提供更新接口。删除本人历史时物理删除记录和幂等键；账号注销完成事务调用薪资历史清理服务。访问他人历史和不存在历史统一返回 404/9803。
• Rationale：历史是用户个人试算数据，不应允许覆盖或通过 ID 枚举发现；物理删除符合用户主动清理和账号注销预期。
• Alternatives：软删除、保留历史用于审计、提供备注和编辑。
  • 软删除仍保留可关联个人数据；编辑或备注会破坏不可变快照语义；审计保留没有明确业务需求。
• Consequences：需要在注销完成事务中增加清理调用和对应集成测试；历史记录不可作为审计或财务凭证。

Decision: 城市政策通过 V41 种子交付，并采用城市级与省级回退的分层精度

• Choice：V40 建表，V41 为全部目标城市写入可计算记录，并增加 data_level 字段：
  • CITY：已核验到城市级公开参数的记录，使用城市自己的上下限和比例。
  • PROVINCE_FALLBACK：无法核验城市级参数的记录，复制所属省级公开参数，并在城市列表、城市详情、计算响应和历史快照中明确标记。
• Rationale：公开资料没有覆盖全部地级行政区的统一城市级结构化数据集；分层精度可以在保持全国目标城市都可计算的同时，避免把省级近似值伪装成城市级官方值。
• Alternatives：等待人工逐城市补齐 300+ 条政策；用省级默认值但不加标识；只发布已核验城市。
  • 逐城市核验会无限期阻塞首期；无标识回退会误导用户；只发布部分城市不满足全国可计算目标。
• Consequences：所有消费方必须展示 dataLevel；PROVINCE_FALLBACK 结果的解释必须明确说明精度较低。后续核验到城市级参数时，通过新迁移更新该城市记录、提升 policyVersion 并更新 dataLevel。

Risks and Verification

• 城市政策数据错误或缺失 → 采用采集截止日基线、目标行政区清单校验、字段范围测试和代表性城市人工抽查 → SalaryCityPolicySeedTest、迁移集成测试和 MySQL/Docker 黑盒验收。
• 累计税额或 rounding 与工资单不一致 → 使用高精度十进制、固定税率版本和明确假设 → 覆盖税率档边界、基数上下限、零缴费、monthIndex=1/12 的精确金额测试。
• 政策更新与计算竞态 → 强制 expectedPolicyVersion 校验，冲突不生成历史 → SalaryPolicyVersionIntegrationTest。
• 重复提交产生重复历史 → 规范化指纹、事务和用户+幂等键唯一约束 → SalaryIdempotencyIntegrationTest。
• 跨用户读取或删除历史 → 查询和删除同时限定当前用户，统一隐藏资源存在性 → SalaryHistoryPrivacyTest。
• 账号注销后仍保留薪资历史 → 在注销完成事务中执行物理清理 → SalaryAccountDeletionIntegrationTest。
• 历史 JSON 在 MySQL 与 H2 行为不一致 → 两套集成测试和真实 MySQL 黑盒验收 → mvn -Dtest=Salary*Test test、mvn clean verify、python docs/verify_openapi.py。