99 lines
7.3 KiB
Markdown
99 lines
7.3 KiB
Markdown
<!--
|
||
MD011 (no-reversed-links) is disabled for this file.
|
||
|
||
This PRD uses `(descriptive text)[cite: n]` source-citation markers, which are
|
||
syntactically indistinguishable from a reversed Markdown link. They are not
|
||
links and must not be "corrected" — running `markdownlint --fix` on this file
|
||
will silently rewrite them into malformed links and destroy the citations.
|
||
-->
|
||
<!-- markdownlint-disable MD011 -->
|
||
|
||
# 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].
|
||
- **Observability & Support:** Structured logging (`KcLogger`) with five severities and a bounded in-memory evidence buffer; global uncaught-error capture (`KcErrorReporter`) across framework, platform, and zone channels; operator bug reporting (`KcBugReportService`) that attaches the recent log tail; mandatory credential redaction (`KcRedactor`) on all logged context so API tokens and secrets can never reach a log or a submitted report.
|
||
|
||
---
|
||
|
||
## 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 | ✅ Merged |
|
||
| **Stage 10C** | Square Mobile POS & In-Person Payments | ✅ Merged |
|
||
| **Stage 10E** | `SquareSyncController`, `square()`/`multi()` factories, ID fix | ✅ Merged |
|
||
| **Stage 10F** | Square Sync UI (`SquareSyncStatusPanel`, Integrations pages) | ✅ Merged |
|
||
| **Stage 16A** | **Error Logging, Crash Capture & Bug Reporting** | ✅ Merged |
|
||
| **Stage 11** | Custom Orders Workflow & Deposit Tracking | 🔄 **Next Stage** |
|
||
| **Stage 12** | Supplies Tracking & Multi-Channel Inventory Sync Engine | ⏳ Planned[cite: 3] |
|
||
| **Stage 16B** | Secure Credential Storage & Auth Guard | ⏳ Planned — Production blocker |
|
||
| **Stage 16C** | Retry/Rate Limiting & Remote Diagnostics | ⏳ Planned — Staging blocker |
|