lxq/changes/n05-salary-calc/execution-contract.md

n05-salary-calc 执行合同

Intent Lock

• 变更名称：n05-salary-calc
• 要解决的问题：当前后端没有城市职工社保、公积金、大病固定费和到手工资估算能力，求职者无法基于地级行政区默认参数、个人覆盖项和累计预扣法获得可复核的结果，也无法保存独立的历史快照。
• 范围内：新增仅限登录 STUDENT 的 /salary-calculator/** 后端模块；新增 V40/V41 城市政策和历史表；实现城市参数、用户覆盖、工资计算、累计预扣、历史保存/查询/物理删除、政策版本校验、幂等并发、账号注销清理、OpenAPI 和测试。
• 范围外：前端页面、ADMIN 政策维护、企业成本、年终奖/股权/多收入来源、年度汇算、非居民税制、薪资参考、Offer 关联、个人数据导出和港澳台政策。

Approved Behavior

• 已批准需求摘要：specs/salary-calculation/spec.md 与 specs/salary-history/spec.md 中的 22 条 ### Requirement 全部批准，覆盖：
  • STUDENT-only 权限和六个接口。
  • 城市政策目录、地级行政区粒度、版本元数据和全量种子。
  • 用户覆盖优先、基数截断、个人五险一金、大病固定费。
  • 累计月份、专项附加扣除、居民个人综合所得累计预扣、到手工资和完整结果拆解。
  • 输入范围、金额精度和 9801–9805 错误语义。
  • 自动保存历史、完整可重建快照、幂等并发、个人隔离、分页、不可编辑、物理删除和长期保留。
  • 历史不进业务审计日志或数据导出，账号注销时物理清理。
  • V40/V41 迁移、全量城市覆盖、唯一键、索引和完整性约束。
• 关键场景：城市政策版本冲突不生成历史；覆盖基数超出城市范围返回 400；monthIndex 表示累计计税月份；累计税额不产生负数；相同幂等键只创建一条历史；跨用户历史统一返回 404；城市停用不影响旧历史；账号注销完成删除全部薪资历史。
• 验收检查：六个接口的 MockMvc/E2E 场景，城市种子完整性测试，金额边界测试，幂等并发测试，权限与注销测试，OpenAPI 校验，真实 MySQL/Docker 黑盒验收。
• 未映射需求：无。22 条需求均在 tasks.md 的 Requirement-to-Task Coverage 中有任务覆盖。

Design Constraints

• 架构约束：新增 com.mydreamjob.salarycalculator 模块，复用 ApiResponse、PageResponse、SecurityContext、UserRepository、DeletionGuardInterceptor 和现有注销事务；不引入外部服务。
• 接口约束：只提供以下接口，并仅在成功请求时创建历史：
  • GET /salary-calculator/cities
  • GET /salary-calculator/cities/{cityCode}
  • POST /salary-calculator/calculations
  • GET /salary-calculator/calculations
  • GET /salary-calculator/calculations/{id}
  • DELETE /salary-calculator/calculations/{id}
• 计算约束：使用 BigDecimal；城市只提供社保/公积金/大病参数；全国税率表、速算扣除数、5,000 元减除费用和税率版本在代码中维护；expectedPolicyVersion 必须匹配。
• 数据约束：只新增 salary_city_policy 和 salary_calculation_history；城市编码唯一，历史用户+幂等键唯一；输入、最终参数和结果 JSON 快照必须可独立读取；账号注销物理删除历史。
• 隐私约束：日志不得记录金额、基数、税额或快照；历史不写业务审计日志、不进入个人数据导出。

Execution Plan

• 推荐模式：sdd。任务跨越迁移、查询、计算、历史、权限/注销、测试和文档多个波次，需要显式依赖和 review receipt。
• 用户确认状态：DP-4 待 DP-3 通过后由 build-executor 重新运行 ssf execution recommend 并由用户确认。本合同不把推荐自动视为已选择。
• 执行计划命令：待 DP-4 确认后由 build-executor 执行 ssf execution plan <change-dir> --mode sdd --confirm --reason "<用户确认原因>" --wave ...。
• 计划 revision / artifact hash：由 ssf execution plan 或状态重建记录。

Execution Waves

Wave W1 - 数据基础

• Wave ID：W1
• 任务：1, 2
• 依赖 wave：无
• 策略：serial
• 目标：完成 V40 表结构、领域持久化基础、V41 城市政策种子及全量种子校验。
• 输入：V39 现状、官方行政区划清单、公开城市政策资料、实体/Repository 约定。
• 输出：两张业务表、实体、Repository、城市种子和迁移/种子测试。
• 完成标准：H2/MySQL 迁移成功；目标城市全覆盖、编码唯一、字段合法、日期不晚于采集截止日、版本号非空。
• Review gate：报告 .superpowers/sdd/reviews/W1.md；wave 完成时记录 base/head SHA；ssf execution review 必须为 pass。

Wave W2 - 城市查询与计算引擎

• Wave ID：W2
• 任务：3, 4
• 依赖 wave：W1
• 策略：serial
• 目标：实现城市列表/详情接口和精确薪资计算引擎。
• 输入：W1 实体/Repository/城市种子、公式约束、DTO 与校验规则。
• 输出：城市 Service/Controller/DTO；计算器、税率表、输入/结果 DTO；服务与控制器测试。
• 完成标准：STUDENT 可查询城市默认参数；基数截断、覆盖率、个人缴费、累计预扣、税额下限和金额精度测试通过。
• Review gate：报告 .superpowers/sdd/reviews/W2.md；wave 完成时记录 base/head SHA；ssf execution review 必须为 pass。

Wave W3 - 历史、幂等、权限与注销

• Wave ID：W3
• 任务：5, 6, 7
• 依赖 wave：W2
• 策略：serial
• 目标：实现计算并保存、历史 CRUD、政策版本校验、幂等并发、用户隔离、注销守卫和物理清理。
• 输入：W2 计算服务和城市接口；历史表/Repository；现有错误码与注销事务。
• 输出：计算/历史 Service 与 Controller、9801–9805、幂等指纹、注销清理调用及集成测试。
• 完成标准：正常计算返回历史 ID；版本冲突返回 409/9805；同键重放返回原历史；跨用户 404；删除物理生效；注销完成无历史残留。
• Review gate：报告 .superpowers/sdd/reviews/W3.md；wave 完成时记录 base/head SHA；ssf execution review 必须为 pass。

Wave W4 - 发布证明与文档

• Wave ID：W4
• 任务：8, 9
• 依赖 wave：W3
• 策略：serial
• 目标：补齐模块测试、OpenAPI、API/联调文档、README/路线图，执行全量回归和真实 MySQL/Docker 黑盒验收。
• 输入：W1–W3 全部代码和测试；现有 OpenAPI 校验脚本。
• 输出：六个接口的静态契约和文档、模块专项测试、全量构建结果、MySQL 黑盒验收记录。
• 完成标准：mvn -Dtest=Salary*Test test、mvn clean verify、python docs/verify_openapi.py 通过；真实 MySQL/Docker 迁移与六个接口验收通过。
• Review gate：报告 .superpowers/sdd/reviews/W4.md；wave 完成时记录 base/head SHA；ssf execution review 必须为 pass。

Test Obligations

• 必须先从失败测试开始的行为：城市种子完整性和范围校验；基数截断与用户覆盖；个人养老/医疗/失业/公积金/大病费用；累计月份与累计预扣；政策版本冲突；幂等重放/冲突；跨用户历史隔离；物理删除；账号注销清理。
• 必需的边界情况：基数下限、上限和区间中值；比例 0；大病固定费为 0；专项附加扣除为 0 和大于月薪；monthIndex=1 和 12；税率档边界；重复删除；城市停用后的旧历史；金额超过两位小数；size=101。
• 回归敏感区域：现有账号注销守卫和完成事务；用户角色读取；ErrorCode 新增值；SecurityConfig 路由；既有 OpenAPI 路径总数；H2 与 MySQL 对 JSON/唯一约束的行为差异。
• 测试命令：专项 mvn -Dtest=Salary*Test test；完整 mvn clean verify；契约 python docs/verify_openapi.py；发布门禁另执行真实 MySQL/Docker 黑盒验收。

Execution Mode

• 可用方式与推荐：inline、batch-inline、sdd；推荐 sdd。
• 用户确认的模式：DP-4 阶段确认，本合同不代替用户选择。
• 推荐理由 / 项目事实：9 个任务拆为 4 个有依赖的 wave，跨数据库迁移、计算、API、权限和历史生命周期，必须保留 review receipt。
• 非推荐选择的风险确认：不适用；若用户选择非推荐模式，必须由 CLI 记录 --acknowledge-recommendation。
• 执行计划命令：由 build-executor 在 DP-4 后运行。
• 允许的修订：仅可保留或升级为 sdd；新 revision 必须先刷新 recommendation，并清除旧 receipt。
• 计划 revision / artifact hash：执行计划保存后记录。

Verification Dimensions

维度	状态	发现
Completeness	Pending	等待实现与测试证据
Correctness	Pending	等待金额、迁移和接口验证
Coherence	Pending	等待实现与规格逐条对照

总体结论：Pending，等待实现和 wave review 证据。

Review Gates

• 强制审查点：每个 Execution Wave 完成后必须记录 ssf execution review 的 pass receipt；W1–W4 的报告路径分别由 wave 完成时生成。
• 阻塞类别：依赖 wave 未通过、review receipt 为 fail、缺失或过期、合同与 specs 不一致、城市种子不完整。
• 收口条件：W1–W4 均有当前 revision 的 pass receipt；专项/全量/OpenAPI/MySQL 证据存在；没有未映射需求或未解决的 P1/P2 审查问题。

Escalation Rules

• 何时回退到 specifying：目标城市定义、计算口径、权限语义、历史生命周期或错误码发生变化；新增或删除已批准需求；必须扩大范围到前端、ADMIN、奖金、年度汇算或薪资参考。
• 何时回退到 bridging：execution-contract.md 与 proposal/spec/design/tasks 不一致；执行 wave 改变依赖或完成标准；城市数据或注销集成方案改变架构约束。
• 何时不得继续实现：DP-3 未批准、没有当前 execution plan、依赖 wave 未 pass、review receipt 缺失/过期、V41 无法满足目标城市全量覆盖、发现未处理的安全/隐私回归。
• DP-4 规则：sdd 模式仅在重新运行 recommendation 并由用户显式确认后写入 execution plan；不得由 Agent 自动代替用户确认。