mtkell
/
kell_creations
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
kell_creations/docs/development/PRD.md

5.9 KiB
Raw Blame History

Product Requirement Document (PRD): Kell Creations Operations Platform

1. Executive Summary & Vision

The Kell Creations Operations Platform is a cross-platform (Web & Android) multi-channel commerce management system. It unifies online storefront operations (WooCommerce), in-person craft market point-of-sale (Square), custom made-to-order requests, and raw supply/finished inventory management into a single operational interface[cite: 3].

2. Platform Architecture & Stack

  • Framework: Flutter (Dart 3.11+)
  • Target Platforms: Windows Desktop / Web (kell_web), Android (kell_mobile)[cite: 1, 3]
  • Monorepo Architecture: Feature-first modular packages (feature_wordpress, feature_inventory, feature_orders, feature_policy, auth, data, integrations, design_system, core)[cite: 1, 3]
  • State & Data Flow: Unidirectional flow using ChangeNotifier controllers and repository interfaces with mock (FAKE) and production implementation modes.

3. Core Functional Requirements

3.1 Multi-Channel Catalog Management

  • WooCommerce Storefront:
    • View, filter, search, and sort product drafts and published items.
    • Single-field and controlled inline edits (Name, Price, Description, Category).
    • Controlled status transitions (unpublished -> draft, pendingReview -> draft/published)[cite: 3].
    • Full Product Creation pipeline (CreateProductDialog on Web, MobileCreateProductPage on Android)[cite: 2, 3].
    • Product category CRUD and management workspace[cite: 2, 3].
    • Controlled bulk actions (Bulk move-to-draft, bulk publish, bulk submit for review)[cite: 2, 3].
  • Square Catalog Integration:
    • Map WooCommerce items to Square Catalog API objects (CatalogObject)[cite: 2, 3].
    • Support cross-channel ID mapping (ProductIdMapping) to prevent duplicate listings[cite: 3].

3.2 Mobile Point-of-Sale (POS) & Market Sales

  • Android-optimized UI using Material 3 NavigationBar and IndexedStack[cite: 2, 3].
  • In-person checkout workflow via Square API integration[cite: 2, 3].
  • Support cash recording and card processing via Square Reader SDK[cite: 3].
  • Automatic inventory deduction and digital receipt generation upon payment completion[cite: 3].

3.3 Custom Orders Workflow

  • Specification Tracking: Record custom order specs (material, color, size, dimensions, reference images)[cite: 3].
  • Financial Deposit Management: Track deposit payments, deposit dates, remaining balance due, and final settlement[cite: 3].
  • Fulfillment Pipeline: Status tracking (quoted -> depositReceived -> inProduction -> qualityCheck -> readyForPickup -> completed)[cite: 3].

3.4 Inventory & Supply Chain Operations

  • Dual-Type Tracking: Separate raw materials/supplies (inputs) from finished goods (catalog items)[cite: 3].
  • Stock Adjustments: Delta adjustments (+/-) and explicit quantity setting with reason logging[cite: 2, 3].
  • Bidirectional Stock Sync: Real-time and batch stock synchronization across WooCommerce stock levels and Square inventory counts[cite: 2, 3].
  • Reorder Logic: Automated low-stock indicators based on item reorder points[cite: 2, 3].

3.5 Infrastructure & Shared Services

  • Auth Foundation: Role-based access (admin, operator, viewer) with encrypted local token/credential storage (flutter_secure_storage)[cite: 2, 3].
  • Offline Operations: Local SQLite caching (LocalCache<T>) and offline sales queue (SyncQueue) with auto-reconciliation upon reconnection[cite: 2, 3].

4. Non-Functional Requirements & Metrics

  • Code Coverage Visibility: Maintain and expand line coverage visibility reported via Forgejo CI (flutter test --coverage)[cite: 2, 3].
  • Touch Optimization: Minimum 48×48dp touch target enforcement across all interactive controls on mobile surfaces[cite: 2, 3].
  • Tactile & Visual Feedback: Haptic feedback (mediumImpact for state changes, lightImpact for field edits) and explicit SnackBar feedback[cite: 2, 3].
  • Zero Structural Regressions: Mandatory static analysis passing (dart analyze --fatal-infos) on every commit[cite: 2, 3].

5. Milestone & Feature Release Schedule

Stage Feature Focus Status
Stages 1–3 Controlled Product Editing, UX Hardening & List Efficiency ✅ Merged[cite: 2, 3]
Stage 4 Shared Design System, Core Abstractions, CI/CD & Coverage Visibility ✅ Merged[cite: 2, 3]
Stage 5 Android Shell Bootstrap & Publishing Surface ✅ Merged[cite: 2, 3]
Stage 6 Android Touch Target Hardening & Mobile Surfaces (Orders/Inventory) ✅ Merged[cite: 2, 3]
Stage 7 Bulk Status Workflows (Move to Draft, Publish, Submit for Review) ✅ Merged[cite: 2, 3]
Stage 8 Core Integration Abstractions, Data Layer Contracts, Auth Foundation ✅ Merged[cite: 2, 3]
Stage 9 WooCommerce API Expansion (Orders, Catalog, Catalog UI) ✅ Merged[cite: 2, 3]
Stage 10A Square API Client & Authentication ✅ Merged[cite: 2, 3]
Stage 10B Square Catalog & Inventory Sync 🔄 Current Stage[cite: 2, 3]
Stage 10C Square Mobile POS & In-Person Payments ⏳ Planned[cite: 3]
Stage 11 Custom Orders Workflow & Deposit Tracking ⏳ Planned[cite: 3]
Stage 12 Supplies Tracking & Multi-Channel Inventory Sync Engine ⏳ Planned[cite: 3]