OpenSpec 管需求，Superpowers 管落地，中间还差一座桥

openspec/
  changes/
    add-payment-callback-idempotency/
      proposal.md
      design.md
      tasks.md
      specs/
        payment-callback/
          spec.md

已有能力：
- Spring Boot 订单服务接收三方支付回调
- 回调成功后更新订单状态 WAIT_PAY -> PAID
- 插入 payment_record 支付流水
- 发布 OrderPaidEvent 给后续发货链路

新增目标：
- 同一个三方支付流水重复回调只能处理一次
- 并发重复回调最多只能产生一条支付流水
- 已处理成功的重复回调仍返回 SUCCESS，避免三方持续重试
- 金额不一致、订单不存在、状态非法时进入异常分支，不触发发货

明确不做：
- 不改三方支付平台回调协议
- 不重构整套支付网关
- 不改变订单主状态机定义
- 不把历史支付流水批量迁移

# Proposal: add-payment-callback-idempotency

## Why

支付平台可能重复推送同一笔支付回调。当前系统只判断订单状态，
无法防住并发重复回调，存在重复支付流水和重复发货事件风险。

## What Changes

- 新增 payment_callback_idempotency 幂等表
- 以 channel + pay_trade_no 建立唯一约束
- 回调处理进入事务，先抢占幂等记录，再更新订单和支付流水
- 重复成功回调返回 SUCCESS，但不重复写流水、不重复发事件
- 金额不一致或订单状态非法时记录异常，不触发后续业务动作

## Non-Goals

- 不修改三方支付平台回调协议
- 不重构支付网关和支付渠道抽象
- 不改变订单主状态机定义
- 不处理历史脏数据迁移

### Requirement: Payment callback idempotency

The system SHALL process the same payment callback only once.

#### Scenario: same callback arrives concurrently

- GIVEN an order is in WAIT_PAY status
- AND two callbacks have the same channel and payTradeNo
- WHEN both callbacks are handled concurrently
- THEN only one payment record is inserted
- AND the order is changed to PAID exactly once
- AND only one OrderPaidEvent is published
- AND both callbacks return SUCCESS to the payment channel

if (order.getStatus() == OrderStatus.PAID) {
    return CallbackResult.success();
}

/opsx:explore add-payment-callback-idempotency

目标：
- 修复支付平台重复回调导致的重复流水和重复发货事件
- 必须覆盖并发重复回调
- 已成功处理的重复回调仍返回 SUCCESS
- 不改三方回调协议
- 不重构支付网关

请比较：
- 只判断订单状态
- Redis 分布式锁
- 数据库唯一幂等表
- 悲观锁订单行

输出：
- 推荐方案
- 不选其他方案的原因
- 事务边界
- 并发测试方案
- 待写入 design.md 的关键约束

## What Changes

- Add idempotency for payment callback.
- Update payment callback service.
- Add tests for duplicate callback.

## Non-Goals

- Do not change payment channel callback contract.
- Do not redesign PaymentGateway abstraction.
- Do not change order state machine definitions.
- Do not migrate historical payment records.

## Tasks

- [ ] Add payment callback idempotency table
- [ ] Add repository for idempotency record
- [ ] Update payment callback service
- [ ] Add duplicate callback tests
- [ ] Add concurrent callback tests
- [ ] Add spec compliance check before archive

Task: Add payment callback idempotency table

1. Write failing repository test for unique channel + payTradeNo
2. Add migration for payment_callback_idempotency
3. Add PaymentCallbackIdempotencyEntity
4. Add repository insert method
5. Run ./mvnw test -Dtest=PaymentCallbackIdempotencyRepositoryTest
6. Refactor naming and indexes
7. Commit idempotency table only

private final Set<String> processed = ConcurrentHashMap.newKeySet();

public CallbackResult handle(PaymentCallbackCommand command) {
    if (!processed.add(command.payTradeNo())) {
        return CallbackResult.success();
    }
    // update order and insert payment record
}

## Idempotency design

- The system MUST use database unique constraint for idempotency.
- Unique key MUST be `(channel, pay_trade_no)`.
- Idempotency record and order payment update MUST be in one transaction.
- OrderPaidEvent MUST be published after transaction commit.
- In-memory idempotency cache is forbidden because service runs with multiple replicas.
- Redis lock MAY be used as optimization, but MUST NOT replace database unique constraint.

请先读取：
- openspec/changes/add-payment-callback-idempotency/proposal.md
- openspec/changes/add-payment-callback-idempotency/design.md
- openspec/changes/add-payment-callback-idempotency/specs/payment-callback/spec.md
- openspec/changes/add-payment-callback-idempotency/tasks.md

执行要求：
- 严格遵守 design.md 技术约束
- 不得修改 proposal.md 的 Non-Goals 范围
- 每个 task 拆成 TDD 步骤
- 每个 task 完成后做 spec compliance check

@Transactional
public CallbackResult handle(PaymentCallbackCommand command) {
    Order order = orderRepository.findByOrderNo(command.orderNo())
        .orElseThrow(() -> new OrderNotFoundException(command.orderNo()));

    if (order.isPaid()) {
        return CallbackResult.success();
    }

    order.markPaid(command.payTradeNo(), command.paidAt());
    paymentRecordRepository.save(PaymentRecord.from(command));
    eventPublisher.publishEvent(new OrderPaidEvent(order.getOrderNo()));
    return CallbackResult.success();
}

代码结构清晰，事务注解存在，异常处理合理。

- 是否覆盖 same callback arrives concurrently 场景？
- 是否存在数据库唯一约束？
- 支付流水是否和幂等记录在同一事务内？
- OrderPaidEvent 是否只发布一次？
- 是否违反 proposal 里的不改支付网关协议？

# spec-compliance-check

When reviewing code for an OpenSpec change:

1. Read proposal.md, design.md, tasks.md and all changed specs.
2. For every Scenario in spec.md, map it to:
   - test file
   - implementation path
   - observed behavior
3. Check every Non-Goal in proposal.md against changed files.
4. Check design.md MUST / MUST NOT rules against implementation.
5. Report any mismatch as BUG, not suggestion.

1. Superpowers code review
2. spec-compliance-check
3. ./mvnw test
4. OpenSpec verify

Archive Gate:

- proposal Non-Goals 无违反
- 所有 spec Scenario 均有测试或明确说明
- design.md MUST / MUST NOT 全部满足
- ./mvnw test 通过
- OpenSpec verify 通过
- Superpowers code review 无阻断问题

# openspec-superpowers-bridge

## Trigger

Use this skill when starting implementation for an active OpenSpec change.

## Workflow

1. Locate active change under openspec/changes/.
2. Read proposal.md, design.md, tasks.md and all specs.
3. Confirm Explore and Propose are completed.
4. Skip brainstorming unless proposal is missing business boundary.
5. Convert tasks.md into Superpowers TDD plan:
   - failing test
   - run targeted test
   - minimal implementation
   - pass test
   - refactor
   - review
6. For every completed task:
   - run targeted tests
   - run spec-compliance-check
7. Before archive:
   - run ./mvnw test
   - run OpenSpec verify
   - block archive on failures

1. /opsx:explore add-payment-callback-idempotency
   研讨技术路线，确认数据库唯一幂等表为主，Redis 锁最多作为优化。

2. /opsx:propose add-payment-callback-idempotency
   生成 proposal.md、design.md、tasks.md、specs 增量规范。

3. 人工审核四类文档
   重点看 Non-Goals、并发重复回调、金额不一致、事务边界、事件发布时机。

4. 启动 openspec-superpowers-bridge
   加载 OpenSpec 文档，把 tasks 转成 Superpowers TDD plan。

5. 逐任务 TDD
   RED -> GREEN -> REFACTOR，每个任务只改必要范围。

6. 单任务验收
   targeted mvn test + code review + spec-compliance-check。

7. 全量验收
   ./mvnw test + OpenSpec verify。

8. Archive + 分支收尾
   归档主规范，按 Superpowers finishing branch 流程合并、PR、保留或丢弃分支。

代码质量审查
  ↓
规范合规审查
  ↓
全量测试 + OpenSpec verify