kell_creations/kell_creations_apps/packages/feature_orders

Order management for the Kell Creations operations platform. Covers both standard catalogue orders and made-to-order custom commissions behind a single Order aggregate and one OrdersRepository contract.

Features

• Domain model — Order, OrderItem, OrderStatus, OrderSource, OrderType, PaymentMethod, PaymentResult.
• Custom orders — CustomOrderSpec (material, colour, size, dimensions, reference images, notes, estimated completion) and DepositInfo (deposit and total amounts in integer cents, deposit/settlement dates, derived balance).
• Fulfillment pipeline — FulfillmentStatus with enforced transitions: quoted → depositReceived → inProduction → qualityCheck → readyForPickup → completed, plus cancelled from any non-terminal stage and a qualityCheck → inProduction rework path. Illegal jumps are rejected by the domain, not silently applied.
• Fulfillment tracking — FulfillmentEvent records every accepted transition (stage from, stage to, timestamp, optional operator note) on an append-only Order.fulfillmentHistory.
• Material consumption — MaterialUsage itemises what a commission consumes; MaterialConsumptionPort is the outbound port the app's composition layer implements to decrement stock on completion.
• Repository contract — OrdersRepository with read, status, note, and create operations plus createCustomOrder, updateCustomOrderSpec, recordDeposit, advanceFulfillmentStatus, and recordMaterialUsage.
• Implementations — FakeOrdersRepository (seeded standard and custom orders across every pipeline stage) and WooCommerceOrdersRepository (REST API v3, custom order state round-tripped through _kc_-prefixed order meta-data).
• Application layer — OrdersController, CheckoutController, CustomOrderFormController, CustomOrderTrackingController, and the GetOrders / UpdateOrderStatus / AddOrderNote / CreateOrder / CreateCustomOrder / RecordDeposit / AdvanceFulfillment / CompleteCustomOrder use cases.
• Presentation — OrdersPage, OrderCard, OrderDetailPanel, OrderStatusChip, CustomOrderFormPage, CustomOrderConfirmationPage, CustomOrderTrackingPage, CustomOrderTrackingCard, CustomOrderTrackingDetail, FulfillmentStatusChip, FulfillmentTimeline, showReferenceImageDialog, showAdvanceStageDialog.

Getting started

Add the package as a path dependency and import the barrel:

dependencies:
  feature_orders:
    path: ../feature_orders

import 'package:feature_orders/feature_orders.dart';

Usage

final repository = FakeOrdersRepository(logger: observability.logger);

final result = await repository.createCustomOrder(
  order,
  spec: CustomOrderSpec(
    material: 'Organic cotton',
    color: 'Sage green',
    size: 'Large',
  ),
  deposit: const DepositInfo.quoted(
    totalAmountCents: 7200,
    depositAmountCents: 2400,
  ),
);

// Advance through the pipeline — illegal jumps are rejected.
await repository.recordDeposit(
  order.id,
  amountCents: 2400,
  paidAt: DateTime.now(),
);
await repository.advanceFulfillmentStatus(order.id, FulfillmentStatus.inProduction);

Custom order intake UI

CustomOrderFormPage captures an entire commission in one screen — customer contact, description, specification, reference images, pricing and deposit, and the estimated completion date. It owns a CustomOrderFormController unless one is injected, so a route or a shell can mount it with only a repository:

CustomOrderFormPage(
  repository: services.ordersRepository,
  onComplete: (order) => Navigator.of(context).pop(order),
);

Money is typed as free text and converted to integer cents by CustomOrderFormController.parseMoneyToCents before it reaches the domain, so no double arithmetic ever decides a price. On success the page swaps to CustomOrderConfirmationPage, which renders the deposit receipt.

Custom order tracking

CustomOrderTrackingPage is the workshop-side counterpart to the intake form. It lists commissions filtered by fulfillment stage (not the commercial OrderStatus, which OrdersPage already covers), and shows the full timeline of recorded stage changes for the selected commission:

CustomOrderTrackingPage(
  repository: services.ordersRepository,
  materialPort: services.materialConsumptionPort,
  onCreateCustomOrder: () => openIntakeForm(),
);

Advancing a commission opens showAdvanceStageDialog, which offers only the stages the domain permits from the current one. The repository re-validates regardless, and an illegal transition surfaces the domain's own FulfillmentTransition.rejectionReason verbatim — the UI never invents its own wording for a rule it does not own.

Inventory deduction on completion

feature_orders must not depend on feature_inventory; the two are sibling features. Instead the orders layer declares a narrow outbound port:

abstract class MaterialConsumptionPort {
  Future<MaterialDeductionResult> deductMaterials(
    String orderId,
    List<MaterialUsage> usages,
  );
}

Each app's composition layer supplies an adapter backed by its own InventoryRepository (InventoryMaterialConsumptionAdapter in kell_web and kell_mobile). CompleteCustomOrder advances the order first and deducts only after the pipeline accepted the transition, so a rejected completion can never decrement stock.

Deduction never blocks completion. A missing SKU, a rejected adjustment, or an unwired port yields a per-SKU entry in MaterialDeductionResult.failures and a warning for the operator — an operator handing over a finished piece must not be stopped by a stock discrepancy.

Observability and privacy

Repository implementations accept an optional KcLogger from core. Failed and rejected write operations are logged with the operation name, order ID, and status names only. Customer identity, addresses, money amounts, and deposit payment identifiers are never logged, and every context map is additionally passed through KcRedactor. There are no silent catch (_) {} blocks.

The WooCommerce meta-data mapping deliberately excludes the deposit transaction ID — it lives on PaymentResult alone. See the class-level documentation on WooCommerceOrderMapper for the complete key table.

Additional information

Part of the kell_creations_apps monorepo. Run the package tests with flutter test from this directory, or the whole suite with ./tools/run_all_tests.sh --analyze from kell_creations_apps/.