new-saga-step

生成 Saga 步骤代码。参数：$ARGUMENTS，格式 {module}/{Method}/step-{N}。

公共步骤模板见 skills-spec/01_skill_authoring_guide.md §A-§E。

第 0 步：🚫 模块 + 启用状态检查

1. 读 BUILD_STATUS.md §0 —— 命中 🚫 模块立即拒绝
2. 读 INDEX.md §0 AIWeave 采纳进度 —— 如 docs-spec/21_distributed_transaction 未启用 → 拒绝，提示"本工程未启用 21，请先启用"

第 1 步：读设计文档

按顺序读：

1. docs/service/transaction_design.md —— §2 事务边界清单 + §3 补偿逻辑设计 + §4 幂等性设计 + §6 失败路径全景图
2. docs/service/{module}_service.md —— §4.N 单个方法的完整规格 + §4.N.3 处理步骤伪码 + §4.N.8 事务与一致性
3. docs/architecture/concurrency_safety.md §2 —— 涉及的共享状态（如 Redis Key 锁）
4. docs/architecture/ai_dev_guide.md §8.2 —— 事务与一致性约束总清单

第 2 步：校验前置

• 目标方法必须在 transaction_design.md §2 标 "Saga N 步"；如未登记 → 拒绝，要求先补 §2
• 目标 step-N 必须在 §3 补偿逻辑设计表中有"正向 + 补偿"对照行；如缺 → 拒绝，要求先补 §3
• 幂等 Key 必须在 §4 已定义；如缺 → 拒绝，要求先补 §4

第 3 步：生成代码

按 service 方法伪码生成 step-N 代码。必须包含以下结构：

// {Module}{Method}Step{N} 是 Saga 第 N 步的正向操作
func (s *{Module}Service) {Method}Step{N}(ctx context.Context, req *{Method}Step{N}Req) error {
    // [IDEMPOTENT-CHECK: key={ns}:idemp:{action}:{key-field}]
    if exists, err := s.checkIdempotent(ctx, req); err != nil {
        return err
    } else if exists {
        return nil // 幂等，跳过
    }

    // [INVARIANT-CHECK: I-N]  // 如本步关联领域不变量
    if violates := s.checkInvariant(req); violates != nil {
        return violates
    }

    // [SAGA-STEP-N] 正向操作
    if err := s.do{Step-N-Action}(ctx, req); err != nil {
        return err
    }

    // [METRIC-EMIT: {action}_step_{N}_total{result="ok"}]
    return nil
}

// {Module}{Method}Compensate{N} 是 Saga 第 N 步的补偿操作
// 必须可重复执行而不产生副作用（详见 transaction_design.md §3.2）
func (s *{Module}Service) {Method}Compensate{N}(ctx context.Context, req *{Method}Step{N}Req) error {
    // 补偿幂等去重
    lockKey := "{ns}:compensation_lock:{key-field}"
    if locked, err := s.acquireLock(ctx, lockKey); err != nil || !locked {
        return err
    }
    defer s.releaseLock(ctx, lockKey)

    // [COMPENSATE-N] 补偿操作
    return s.undo{Step-N-Action}(ctx, req)
}