Flutter 交易所架构实战：DDD + Clean 落地指南

features/trading/
  presentation/
    pages/
    state/                # Notifier / State
  application/
    usecases/             # PlaceOrderUseCase, CancelOrderUseCase
  domain/
    entities/             # Order, Position, TradeFill
    value_objects/        # Price, Quantity, Symbol
    repositories/         # TradingRepository (abstract)
    services/             # RiskCheckService
  data/
    datasources/          # TradingApi, TradingWs
    models/               # DTO
    mappers/              # DTO <-> Entity
    repositories/         # TradingRepositoryImpl

Presentation (TradePage)
  -> PlaceOrderUseCase
      -> WalletReadRepository (Domain Interface)
      -> MarketReadRepository (Domain Interface)
      -> RiskCheckService (Domain Rule)
      -> TradingRepository (Domain Interface)

class OrderEntity {
  final String orderId;
  final OrderStatus status;
  final Price price;
  final Quantity quantity;
  final Quantity filledQuantity;

  // 状态转换：只有合法转换才能发生
  OrderEntity fill(Quantity qty) {
    assert(status == OrderStatus.open || status == OrderStatus.partiallyFilled);
    final newFilled = filledQuantity + qty;
    final newStatus = newFilled >= quantity
        ? OrderStatus.filled
        : OrderStatus.partiallyFilled;
    return copyWith(filledQuantity: newFilled, status: newStatus);
  }

  OrderEntity cancel() {
    if (status == OrderStatus.filled) {
      throw DomainException('已成交订单不能撤销');
    }
    return copyWith(status: OrderStatus.canceled);
  }

  // 只读计算属性，不存储
  Quantity get remainingQuantity => quantity - filledQuantity;
  double get fillRate => filledQuantity.value / quantity.value;
}

class Price {
  final BigDecimal value;
  final int tickSize; // 最小价格步长的小数位

  Price(this.value, {required this.tickSize}) {
    // 构造时就校验，不合法的 Price 根本不存在
    if (!_isAlignedToTick(value, tickSize)) {
      throw DomainException('价格 $value 不符合步长精度 $tickSize');
    }
  }

  bool _isAlignedToTick(BigDecimal v, int tick) {
    final scale = BigDecimal.fromInt(10).pow(tick);
    return (v * scale).remainder(BigDecimal.one) == BigDecimal.zero;
  }

  Price operator +(Price other) => Price(value + other.value, tickSize: tickSize);
}

class Quantity {
  final BigDecimal value;
  final BigDecimal minLot;  // 最小下单量
  final BigDecimal stepSize; // 数量步长

  Quantity(this.value, {required this.minLot, required this.stepSize}) {
    if (value < minLot) throw DomainException('数量低于最小下单量');
    if (!_isAlignedToStep(value, stepSize)) throw DomainException('数量不符合步长');
  }
}

class PlaceOrderUseCase {
  Future<Result<OrderEntity>> execute(PlaceOrderCommand command) async {
    // 1. 先在本地创建一个 pending 状态的订单
    final optimisticOrder = OrderEntity.pending(
      clientOrderId: command.clientOrderId,
      price: command.price,
      quantity: command.quantity,
    );

    // 2. 立刻推给 UI
    _orderStreamController.add(optimisticOrder);

    try {
      // 3. 发请求
      final confirmed = await _repo.placeOrder(command);
      // 4. 用服务端返回的真实状态替换 pending
      _orderStreamController.add(confirmed);
      return Result.success(confirmed);
    } catch (e) {
      // 5. 失败：移除 pending 订单，回滚 UI
      _orderStreamController.add(optimisticOrder.copyWith(
        status: OrderStatus.failed,
        errorMessage: e.toString(),
      ));
      return Result.failure(e);
    }
  }
}

class PlaceOrderUseCase {
  final _inFlight = <String, Future<Result<OrderEntity>>>{};

  Future<Result<OrderEntity>> execute(PlaceOrderCommand command) {
    final key = '${command.symbol}-${command.clientOrderId}';

    // 如果同一笔请求已经在飞，直接返回同一个 Future
    if (_inFlight.containsKey(key)) {
      return _inFlight[key]!;
    }

    final future = _doPlaceOrder(command).whenComplete(() {
      _inFlight.remove(key);
    });

    _inFlight[key] = future;
    return future;
  }
}

// Domain 层只有业务错误
sealed class DomainError {
  const DomainError();
}
class InsufficientBalance extends DomainError {
  final double required;
  final double available;
}
class PricePrecisionError extends DomainError {
  final String detail;
}
class OrderAlreadyCanceled extends DomainError {}

// Data 层捕获基础设施错误，映射成 Domain Error 或 AppError
class TradingRepositoryImpl implements TradingRepository {
  @override
  Future<OrderEntity> placeOrder(PlaceOrderCommand command) async {
    try {
      final response = await _api.placeOrder(command.toDto());
      return _mapper.toDomain(response);
    } on DioException catch (e) {
      // HTTP 业务错误 -> Domain Error
      if (e.response?.statusCode == 400) {
        final code = e.response?.data['code'];
        throw _mapApiErrorToDomain(code, e.response?.data);
      }
      // 网络错误 -> AppError（基础设施层的错误）
      throw NetworkError(message: e.message);
    }
  }

  DomainError _mapApiErrorToDomain(String code, Map? data) => switch (code) {
    'INSUFFICIENT_BALANCE' => InsufficientBalance(
        required: data?['required'] ?? 0,
        available: data?['available'] ?? 0,
      ),
    'PRICE_PRECISION_ERROR' => PricePrecisionError(detail: data?['message'] ?? ''),
    _ => UnknownDomainError(code: code),
  };
}