Superpowers 最佳实战：7 阶段工作流交付电商系统 SKU 商品库存扣减逻辑

你：我需要为电商系统实现 SKU 库存扣减功能，用户下单时
    根据选定的商品规格扣减对应 SKU 的库存。

AI：这个需求涉及几个关键决策点。先问第一个：
    库存扣减需要支持并发下单吗？也就是说，
    同一个 SKU 可能同时被多个用户购买？

你：是的，需要处理并发。

AI：并发场景下有两种常见方案：
    A. 悲观锁 - SELECT ... FOR UPDATE，简单直接但吞吐量低
    B. 乐观锁 - 版本号控制，吞吐量高但需要处理冲突重试

    根据你的场景（电商下单），我推荐方案 A（悲观锁），
    原因是：实现简单，且库存扣减的冲突概率不高，
    悲观锁的锁等待开销可接受。你觉得呢？

你：用悲观锁。

AI：下一个问题：扣减失败时（库存不足），
    需要返回什么级别的错误信息？
    A. 简单提示"库存不足"
    B. 详细信息（包含当前可用库存数量）

你：方案 B，需要告诉用户当前还有多少库存。

AI：最后一个问题：是否需要支持部分扣减？
    比如：用户买 5 件但只有 3 件库存，
    是扣 3 件还是全部失败？

你：全部失败，不允许部分扣减。

# 自动保存的设计文档路径
docs/superpowers/specs/2026-04-12-sku-inventory-deduction-design.md

AI：我正在使用 using-git-worktrees 技能创建隔离工作区。

    [检查 .worktrees/ 目录 - 已存在]
    [验证 .worktrees/ 已被 gitignore - 确认]
    [创建工作区]

$ git worktree add .worktrees/sku-deduction -b feature/sku-deduction
准备工作区检出（分离的 HEAD 4a8f2c1）
更新文件: 127, 完成。

$ cd .worktrees/sku-deduction
$ pip install -r requirements.txt
安装完成: 42 个包

$ pytest tests/ -v
================== 47 passed, 0 failed ==================

工作区已就绪: .worktrees/sku-deduction
测试基线: 47 个测试通过, 0 个失败
准备实现 SKU 库存扣减功能

# tests/test_sku_model.py
from app.models.sku import SKU

def test_sku_creation():
    sku = SKU(
        product_id=1,
        specs={"color": "black", "size": "M"},
        stock=100
    )
    assert sku.stock == 100
    assert sku.specs == {"color": "black", "size": "M"}

$ pytest tests/test_sku_model.py -v
FAILED - ModuleNotFoundError: No module named 'app.models.sku'

# app/models/sku.py
from sqlalchemy import Column, Integer, JSON, ForeignKey
from sqlalchemy.orm import relationship
from app.database import Base

class SKU(Base):
    __tablename__ = "skus"

    id = Column(Integer, primary_key=True, index=True)
    product_id = Column(Integer, ForeignKey("products.id"), nullable=False)
    specs = Column(JSON, nullable=False)
    stock = Column(Integer, nullable=False, default=0)

    product = relationship("Product", back_populates="skus")

$ pytest tests/test_sku_model.py -v
PASSED

$ git add app/models/sku.py tests/test_sku_model.py
$ git commit -m "feat: add SKU model with specs and stock"

AI：我正在使用 Subagent-Driven Development 执行计划。

[读取计划文件: docs/superpowers/plans/sku-inventory.md]
[提取全部 6 个任务的完整文本和上下文]
[创建 TodoWrite 跟踪所有任务]

---

Task 1: SKU 模型定义
[派遣实现子代理 - 提供完整任务文本 + 项目上下文]

实现子代理:
  - 使用 TDD 实现（先写测试，再写代码）
  - 5/5 测试通过
  - 自查: 未发现问题
  - 已提交 (a7981ec)

[派遣规格审查子代理]
规格审查子代理: ✅ 规格符合 - 所有需求已实现，无多余内容

[派遣代码质量审查子代理]
质量审查子代理:
  优点: 干净的模型定义，测试充分
  问题: 无
  评估: ✅ 通过

[标记 Task 1 完成]

---

Task 2: 库存扣减核心逻辑
[派遣实现子代理]

实现子代理:
  - 使用 TDD 实现
  - 2/2 测试通过
  - 自查: 发现缺少边界检查，已补充
  - 已提交 (3df7661)

[派遣规格审查子代理]
规格审查子代理:
  ❌ 发现问题:
  - 缺失: SKU 不存在时未处理（规格要求返回 404）
  - 多余: 添加了 InsufficientStockError 类，
    但规格里只要求 ValueError

[实现子代理修复]
  - 添加 SKU 不存在的处理逻辑
  - 将 InsufficientStockError 改为 ValueError 的子类

[规格审查子代理复审]
规格审查子代理: ✅ 规格符合

[派遣代码质量审查子代理]
质量审查子代理:
  ✅ 优点: 悲观锁使用正确，测试覆盖正常和异常路径
  ⚠️ 建议: deduct 方法缺少数量 ≤ 0 的边界检查
  评估: 修复后可通过

[实现子代理修复]
  添加数量校验: quantity <= 0 时抛出 ValueError

[代码质量审查子代理复审]
质量审查子代理: ✅ 通过

[标记 Task 3 完成]

... 后续任务类似流程 ...

# tests/test_inventory_service.py
import pytest
from app.services.inventory import InventoryService

def test_deduct_stock_success(db_session):
    """测试正常扣减"""
    sku = create_test_sku(db_session, stock=100)
    service = InventoryService(db_session)
    service.deduct(sku.id, quantity=3)

    db_session.refresh(sku)
    assert sku.stock == 97

def test_deduct_stock_insufficient(db_session):
    """测试库存不足"""
    sku = create_test_sku(db_session, stock=5)
    service = InventoryService(db_session)

    with pytest.raises(ValueError, match="库存不足"):
        service.deduct(sku.id, quantity=10)

$ pytest tests/test_inventory_service.py -v
FAILED - ModuleNotFoundError: No module named 'app.services.inventory'

# app/services/inventory.py
from sqlalchemy.orm import Session
from sqlalchemy import select
from app.models.sku import SKU

class InsufficientStockError(ValueError):
    def __init__(self, sku_id: int, requested: int, available: int):
        self.sku_id = sku_id
        self.requested = requested
        self.available = available
        super().__init__(
            f"库存不足: 需要 {requested}，当前库存 {available}"
        )

class InventoryService:
    def __init__(self, session: Session):
        self.session = session

    def deduct(self, sku_id: int, quantity: int) -> None:
        stmt = (
            select(SKU)
            .where(SKU.id == sku_id)
            .with_for_update()  # 悲观锁
        )
        sku = self.session.execute(stmt).scalar_one()

        if sku.stock < quantity:
            raise InsufficientStockError(
                sku_id, quantity, sku.stock
            )

        sku.stock -= quantity
        self.session.commit()

$ pytest tests/test_inventory_service.py -v
test_deduct_stock_success PASSED
test_deduct_stock_insufficient PASSED
================== 2 passed ==================

代码审查子代理:

✅ 优点:
  - 测试覆盖率高，正常路径和异常路径都有测试
  - 悲观锁实现正确，避免了并发超卖
  - 错误信息包含具体数值，便于前端展示

⚠️ Important 级别问题:
  1. deduct() 方法没有处理 db_session.commit() 失败的情况
     建议: 添加 try/except + rollback
  2. 批量扣减场景下，多次 WITH FOR UPDATE 可能导致
     锁等待时间过长
     建议: 按 sku_id 排序后再加锁，避免死锁

ℹ️ Minor 级别建议:
  - SKU 模型的 specs 字段可以考虑添加 JSON Schema 校验
  - InventoryService 可以添加日志记录扣减操作

评估: 修复 Important 问题后可合并

# app/services/inventory.py - 修复版
class InventoryService:
    def __init__(self, session: Session):
        self.session = session

    def deduct(self, sku_id: int, quantity: int) -> None:
        if quantity <= 0:
            raise ValueError("扣减数量必须大于 0")

        try:
            stmt = (
                select(SKU)
                .where(SKU.id == sku_id)
                .with_for_update()
            )
            sku = self.session.execute(stmt).scalar_one()

            if sku.stock < quantity:
                raise InsufficientStockError(
                    sku_id, quantity, sku.stock
                )

            sku.stock -= quantity
            self.session.commit()
        except NoResultFound:
            raise ValueError(f"SKU {sku_id} 不存在")
        except Exception:
            self.session.rollback()
            raise

    def batch_deduct(
        self, items: list[tuple[int, int]]
    ) -> None:
        """批量扣减，按 sku_id 排序避免死锁"""
        sorted_items = sorted(items, key=lambda x: x[0])
        for sku_id, quantity in sorted_items:
            self.deduct(sku_id, quantity)

AI：正在使用 finishing-a-development-branch 技能完成交付。

$ pytest tests/ -v
================== 56 passed, 0 failed ==================
（基线 47 个 + 新增 9 个测试，全部通过）

实现已完成。你希望怎么处理？

1. 合并回 main 分支
2. 推送并创建 Pull Request
3. 保留分支（稍后自己处理）
4. 丢弃这个工作

请选择:

$ git checkout main
$ git pull
$ git merge feature/sku-deduction
$ pytest tests/ -v
================== 56 passed, 0 failed ==================

# 合并后测试仍然通过，清理工作区
$ git worktree remove .worktrees/sku-deduction

systematic-debugging → test-driven-development
→ verification-before-completion

brainstorming → writing-plans → executing-plans

brainstorming → writing-plans
→ subagent-driven-development
→ requesting-code-review
→ finishing-a-development-branch