diff --git a/.vscode/workspace_rules.md b/.vscode/workspace_rules.md new file mode 100644 index 0000000..db11b77 --- /dev/null +++ b/.vscode/workspace_rules.md @@ -0,0 +1,102 @@ +# Workspace Development Rules: Kell Creations Platform + +## 1. Core Operating Principles + +1. **Vertical Slice Discipline:** Implement features in isolated, reviewable vertical slices on feature branches. Never push unverified, broad changes directly to `main`[cite: 3]. +2. **Inspection First:** Always inspect the codebase, verify existing tests, and review existing contracts before writing or modifying code[cite: 3]. +3. **Environment Isolation:** Maintain runtime environment modes (`fake`, `wp`, `square`, `multi`) specified exclusively via `--dart-define` keys[cite: 2, 3]. Never build hardcoded settings UIs or commit API keys/tokens to source control[cite: 3]. +4. **Strict Package Boundaries:** + - Feature packages (`feature_*`) must remain decoupled[cite: 1, 3]. + - Cross-feature communication must use shared abstractions in `core`, `integrations`, or `data`[cite: 1, 3]. + - Platform-specific UI code must reside in `apps/kell_web` or `apps/kell_mobile`[cite: 1, 3]. Re-use shared presenters and controllers[cite: 2, 3]. + +--- + +## 2. Code & Design Standards + +### Flutter & Dart Execution + +- Strict typing required; avoid `dynamic` unless explicitly serializing raw JSON[cite: 2, 3]. +- Use Material Design 3 guidelines[cite: 2, 3]. On mobile (`kell_mobile`), ensure all interactive targets adhere to a minimum 48×48dp target bounding box[cite: 2, 3]. +- Wrap mobile screens in `SafeArea` to avoid system overlay clipping[cite: 2, 3]. + +### Architecture Layering (per Package) + +lib/ +├── src/ +│ ├── domain/ # Entities, Value Objects, Repository Contracts (Pure Dart) +│ ├── application/ # Use Cases, Controllers (ChangeNotifiers) +│ ├── data/ # ApiClients, Mappers, Fake & Real Repositories +│ └── presentation/ # Widgets, Pages, Dialogs, SnackBars +└── feature_name.dart # Barrel File Exports + +--- + +## 3. Standard Execution Workflow for AI Agents (Cline / VS Code) + +Whenever initiating a new task or slice, execute the following workflow steps sequentially[cite: 3]: + +1. **Step 1: Context Verification** + - Read `docs/development/master_development_brief.md` and `docs/development/build_execution_tracker.md` to identify current status[cite: 2, 3]. + +2. **Step 2: Pre-flight Validation** + - Run local test suite using the CI script: + + ```bash + bash tools/run_all_tests.sh --analyze + + ``` + + - Confirm all tests pass and static analysis is clean prior to editing[cite: 2, 3]. + +3. **Step 3: Implementation** + - Create target feature branch (e.g., `feat/square-catalog-sync`)[cite: 2]. + - Implement domain models, repository contracts, API mappers, application logic, and UI components[cite: 2, 3]. + +4. **Step 4: Testing & Hardening** + - Write unit tests for domain models and application controllers[cite: 2]. + + - Write widget tests for presentation components[cite: 2]. + - Verify static analysis passes without warnings: + + ```bash + dart analyze --fatal-infos + ``` + +5. **Step 5: Documentation & Tracking** + - Update `docs/development/build_execution_tracker.md` with: + - Files modified/added[cite: 2]. + - Test counts and pass state[cite: 2]. + - Verification/analysis result[cite: 2]. + - Update `docs/development/master_development_brief.md` next branch indicator[cite: 2, 3]. + +--- + +## 4. Prompt Template for AI Sessions + +Continue the Kell Creations Flutter operations platform workstream from current main. + +Read docs/development/master_development_brief.md first and follow it as the authoritative planning document. + +Constraints: + +- Preserve strict package boundaries. +- Fake repositories remain in feature packages. +- Real integrations are incremental alongside fake ones. +- Runtime selection stays via --dart-define, not settings UI. +- No credentials hardcoded or committed. +- Keep WooCommerce details inside the WP repository layer. +- Keep Square details inside a dedicated Square integration layer. +- Multi-channel sync contracts before implementations. +- Use small, reviewable steps only. + +Working rules: + +1. Inspect first. Do not edit immediately. +2. Summarize current relevant state from main. +3. Propose the smallest implementation plan for the requested slice. +4. Implement only that slice. +5. Add/update focused tests. +6. Run validation (run_all_tests.sh --analyze). +7. Report changed files and validation results. +8. Update master_development_brief.md and build_execution_tracker.md. diff --git a/docs/development/PRD.md b/docs/development/PRD.md new file mode 100644 index 0000000..632ee55 --- /dev/null +++ b/docs/development/PRD.md @@ -0,0 +1,82 @@ +# 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`) 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] | diff --git a/filetree.txt b/filetree.txt new file mode 100644 index 0000000..8251a62 Binary files /dev/null and b/filetree.txt differ