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.
• Repository contract — OrdersRepository with read, status, note, and create operations plus createCustomOrder, updateCustomOrderSpec, recordDeposit, and advanceFulfillmentStatus.
• 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, and the GetOrders / UpdateOrderStatus / AddOrderNote / CreateOrder / CreateCustomOrder / RecordDeposit use cases.
• Presentation — OrdersPage, OrderCard, OrderDetailPanel, OrderStatusChip, CustomOrderFormPage, CustomOrderConfirmationPage, FulfillmentStatusChip, showReferenceImageDialog.

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.

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/.