From 4280a77017192566c278a13f71f2f98fdc5244cd Mon Sep 17 00:00:00 2001 From: Mike Kell Date: Sat, 25 Jul 2026 15:56:44 -0400 Subject: [PATCH] =?UTF-8?q?chore:=20audit-state-sync=20=E2=80=94=20incorpo?= =?UTF-8?q?rate=20PROJECT=5FSTATE=5FAUDIT.md=20findings=20into=20tracking?= =?UTF-8?q?=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- PROJECT_STATE_AUDIT.md | 694 +++++++++++++++++++ docs/development/build_execution_tracker.md | 32 +- docs/development/master_development_brief.md | 239 +++++-- 3 files changed, 900 insertions(+), 65 deletions(-) create mode 100644 PROJECT_STATE_AUDIT.md diff --git a/PROJECT_STATE_AUDIT.md b/PROJECT_STATE_AUDIT.md new file mode 100644 index 0000000..32c3fe4 --- /dev/null +++ b/PROJECT_STATE_AUDIT.md @@ -0,0 +1,694 @@ +# PROJECT_STATE_AUDIT.md + +## Kell Creations Operations Platform — Comprehensive Code Audit + +**Audit Date:** 2026-07-25 +**Auditor:** Senior Software Engineering Review Board (Automated) +**Baseline Commit:** `feat/square-catalog-sync-repositories` → `main` (Stage 10C complete) +**Current Branch Work:** Stage 10D (`SquareCatalogSyncService`) — complete, pending merge +**Total Tests (baseline):** 1,015 / 1,015 passing +**Static Analysis:** `dart analyze --fatal-infos` — clean across all 11 packages/apps + +--- + +## 1. Repository Architecture Overview + +### Monorepo Structure + +``` +kell_creations/ +├── kell_creations_apps/ +│ ├── apps/ +│ │ ├── kell_web/ # Flutter Web app (Windows Desktop / Browser) +│ │ └── kell_mobile/ # Flutter Android app +│ ├── packages/ +│ │ ├── core/ # Shared composition abstractions +│ │ ├── design_system/ # Shared UI components and theme +│ │ ├── auth/ # Authentication contracts + fake impl +│ │ ├── data/ # Data layer contracts + in-memory impls +│ │ ├── integrations/ # API client contracts + Square/WC clients +│ │ ├── feature_wordpress/ # Product catalog management (most mature) +│ │ ├── feature_inventory/ # Inventory management +│ │ ├── feature_orders/ # Order management +│ │ ├── feature_policy/ # Policy/governance compliance +│ │ ├── feature_finance/ # Financial reporting [STUB] +│ │ ├── feature_mrp/ # Manufacturing/MRP [STUB] +│ │ └── feature_social/ # Social media management [STUB] +│ └── tools/ # CI helper scripts +├── docs/ # MkDocs documentation site +├── architecture/ # PlantUML C4 diagrams (19 diagrams) +└── policies/ # Controlled policy document repository +``` + +### Architectural Pattern + +- **Domain-Driven Design** with strict package boundaries +- **Repository pattern** with fake/real runtime selection via `--dart-define` +- **ChangeNotifier controllers** for unidirectional state flow (no Riverpod yet) +- **Shared composition pattern** (`KcAppConfig`, `KcBootstrap`, `KcAppScope`) across both app targets +- **Vertical slice discipline** — each feature has domain → application → data → presentation layers + +--- + +## 2. Audit Matrix — Built vs. Remaining + +### 2.1 Infrastructure Packages + +#### `core` — [COMPLETE] + +| Artifact | Status | +| ------------------------------------------------------------ | ---------------- | +| `KcAppConfig` / `KcAppEnvironment` (fake, wp, square, multi) | ✅ Complete | +| `KcAppServices` abstract base | ✅ Complete | +| `KcServiceFactory` | ✅ Complete | +| `KcBootstrap` | ✅ Complete | +| `KcAppScope` InheritedWidget | ✅ Complete | +| Tests | ✅ 24/24 passing | + +**Notes:** `KcBootstrap` only validates WooCommerce credentials. Square/multi mode credential validation is not yet wired into the bootstrap guard logic — `AppServices` and `MobileAppServices` have no `square` or `multi` factory constructors, meaning `KC_ENV=square` silently falls through to fake mode at runtime. + +--- + +#### `design_system` — [COMPLETE] + +| Artifact | Status | +| --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | +| `KcColors`, `KcSpacing`, `KcTheme` | ✅ Complete | +| `KcTypography` (full Material 3 scale) | ✅ Complete | +| `KcBreakpoints` (responsive layout utilities) | ✅ Complete | +| 7 shared widgets (`KcCard`, `KcStatusChip`, `KcEmptyState`, `KcSectionHeader`, `KcSummaryCard`, `KcLoadingState`, `KcErrorState`) | ✅ Complete | +| Tests | ✅ 41/41 passing, 100% line coverage | + +**Notes:** No shared button/action component library exists. All action chips and buttons are defined inline per-page. This is a low-priority gap. + +--- + +#### `auth` — [PARTIAL] + +| Artifact | Status | +| ------------------------------------------------- | ---------------- | +| `KcUser` / `KcUserRole` domain models | ✅ Complete | +| `AuthState` sealed hierarchy | ✅ Complete | +| `AuthService` abstract contract | ✅ Complete | +| `AuthException` | ✅ Complete | +| `CredentialStore` / `CredentialKeys` contract | ✅ Complete | +| `InMemoryCredentialStore` | ✅ Complete | +| `FakeAuthService` | ✅ Complete | +| `SecureCredentialStore` (flutter_secure_storage) | ❌ Missing | +| Real `AuthService` implementation (login/session) | ❌ Missing | +| Auth guard / login screen wired into app shell | ❌ Missing | +| Tests | ✅ 42/42 passing | + +**Notes:** The auth package provides contracts and fakes only. No production implementation exists. The app is currently unguarded — any user can access all features without authentication. `auth` is not imported by either `AppServices` or `MobileAppServices`. + +--- + +#### `data` — [PARTIAL] + +| Artifact | Status | +| -------------------------------------------------- | ---------------- | +| `LocalCache` contract + `InMemoryCache` | ✅ Complete | +| `SyncQueue` contract + `InMemorySyncQueue` | ✅ Complete | +| `ConflictResolver` + 3 concrete implementations | ✅ Complete | +| `ChangeTracker` + `InMemoryChangeTracker` | ✅ Complete | +| `DataMapper` contract | ✅ Complete | +| SQLite-backed `LocalCache` implementation | ❌ Missing | +| SQLite-backed `SyncQueue` implementation | ❌ Missing | +| Integration with any feature package | ❌ Missing | +| Tests | ✅ 63/63 passing | + +**Notes:** All implementations are in-memory only. The `data` package is not imported by any feature package or app. It is a well-designed contract layer with zero production wiring. SQLite persistence (required for offline capability, Stage 14) is not implemented. + +--- + +#### `integrations` — [PARTIAL] + +| Artifact | Status | +| -------------------------------------------------------------------------- | ------------------------------------------ | +| `ApiClient` / `ApiException` contracts | ✅ Complete | +| `RetryPolicy` + `NoRetryPolicy` + `ExponentialBackoffRetryPolicy` | ✅ Complete | +| `RateLimiter` + `NoRateLimiter` + `TokenBucketRateLimiter` | ✅ Complete | +| `IntegrationHealthCheck` contract | ✅ Complete | +| `WebhookHandler` contract | ✅ Complete | +| `ChannelAdapter` contract | ✅ Complete | +| `SquareApiClient` (full lifecycle, Catalog/Inventory/Orders/Payments APIs) | ✅ Complete | +| `SquareApiException` | ✅ Complete | +| `SquareProductMapper` (Square CatalogObject ↔ `ChannelProduct`) | ✅ Complete | +| `SquareInventoryMapper` (Square InventoryCount ↔ `ChannelInventoryCount`) | ✅ Complete | +| `WooCommerceApiClient` (refactored to implement `ApiClient`) | ✅ Complete (lives in `feature_wordpress`) | +| `RetryPolicy` / `RateLimiter` wired into any real client | ❌ Missing | +| `IntegrationHealthCheck` concrete implementation | ❌ Missing | +| `WebhookHandler` concrete implementation | ❌ Missing | +| `ChannelAdapter` concrete implementation for WooCommerce or Square | ❌ Missing | +| Tests | ✅ 123/123 passing | + +**Notes:** `RetryPolicy` and `RateLimiter` are defined but not wired into `SquareApiClient` or `WooCommerceApiClient`. All API calls are single-attempt with no retry or rate limiting in production paths. `ChannelAdapter` is a contract with no concrete implementation — the WooCommerce and Square clients do not implement it. + +--- + +### 2.2 Feature Packages + +#### `feature_wordpress` — [COMPLETE] (most mature) + +| Artifact | Status | +| --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | +| `ProductDraft` domain model (full fields, `copyWith`) | ✅ Complete | +| `PublishStatus` enum (draft, published, pendingReview, unpublished) | ✅ Complete | +| `ProductCategory` domain model | ✅ Complete | +| `ProductImage` domain model | ✅ Complete | +| `ProductIdMapping` domain model | ✅ Complete | +| `ProductPublishingRepository` contract (full CRUD + categories + images) | ✅ Complete | +| `ProductIdMappingRepository` contract | ✅ Complete | +| `FakeProductPublishingRepository` (seeded, all methods) | ✅ Complete | +| `FakeProductIdMappingRepository` (seeded, 6 mappings) | ✅ Complete | +| `WordPressProductPublishingRepository` (WooCommerce REST API v3) | ✅ Complete | +| `SquareCatalogRepository` (Square API, in-memory cache) | ✅ Complete | +| `WooCommerceApiClient` (Products, Orders, Stock, Categories, Images) | ✅ Complete | +| `WordPressProductMapper` | ✅ Complete | +| All use cases (GetProductDrafts, PublishProduct, UpdateProduct\*, CreateProduct, DeleteProduct, GetCategories, CreateCategory, UpdateProductImages) | ✅ Complete | +| `ProductPublishingController` (full state: multi-select, bulk actions, create, categories) | ✅ Complete | +| `SquareCatalogSyncService` + `SquareSyncResult` + `SyncError` + `InventorySyncAdapter` | ✅ Complete (Stage 10D, pending merge) | +| `ProductPublishingPage` (web, full feature surface) | ✅ Complete | +| `CategoryManagementPage` | ✅ Complete | +| `ProductPreviewPanel` (all inline edits, touch targets) | ✅ Complete | +| `ProductDraftCard` (compact/standard, multi-select, stale indicator) | ✅ Complete | +| `CreateProductDialog` (web) | ✅ Complete | +| `SquareSyncController` (Riverpod/ChangeNotifier wrapping `SquareCatalogSyncService`) | ❌ Missing (Stage 10E — next branch) | +| Image picker / gallery management UI | ❌ Missing (deferred post-Stage 10) | +| Tests | ✅ 506/506 passing (Stage 10D) | + +**Notes:** The `SquareCatalogRepository` throws `UnsupportedError` for all category and image operations — this is intentional and documented, but callers must handle these exceptions. The `SquareSyncController` (Stage 10E) is the immediate next deliverable. + +--- + +#### `feature_inventory` — [PARTIAL] + +| Artifact | Status | +| -------------------------------------------------------------------------------------------------------------- | ---------------------- | +| `InventoryItem` domain model (full fields including `squareVariationId`, `wooCommerceProductId`, `syncStatus`) | ✅ Complete | +| `InventoryStatus` enum | ✅ Complete | +| `InventorySyncStatus` enum | ✅ Complete | +| `InventoryAdjustmentResult` value object | ✅ Complete | +| `InventoryRepository` contract (read + write + sync) | ✅ Complete | +| `FakeInventoryRepository` (seeded, all write methods) | ✅ Complete | +| `WooCommerceInventoryRepository` | ✅ Complete | +| `SquareInventoryRepository` | ✅ Complete | +| `InventorySyncService` (WooCommerce pull/push sync) | ✅ Complete | +| All use cases (GetInventoryItems, AdjustInventoryQuantity, CreateInventoryItem, UpdateInventoryItem) | ✅ Complete | +| `InventoryController` (read + write actions) | ✅ Complete | +| `InventoryPage` (web, full filter/search/detail panel) | ✅ Complete | +| `InventoryDetailPanel`, `AdjustQuantityDialog`, `InventoryStatusChip` | ✅ Complete | +| `ItemType` enum (rawMaterial, finishedGood, packaging, tool) | ❌ Missing (Stage 12A) | +| `InventoryAdjustment` audit log value object | ❌ Missing (Stage 12A) | +| `Supplier` domain model | ❌ Missing (Stage 12B) | +| `PurchaseOrder` domain model | ❌ Missing (Stage 12B) | +| Supply receiving / material usage workflows | ❌ Missing (Stage 12B) | +| Multi-channel inventory sync engine (`InventorySyncEngine`) | ❌ Missing (Stage 12C) | +| `ChannelStockMapping` | ❌ Missing (Stage 12C) | +| Sync status indicators in inventory UI | ❌ Missing | +| Tests | ✅ 167/167 passing | + +**Notes:** The inventory feature has a solid domain and data layer. The `InventorySyncService` is WooCommerce-only. Square inventory sync is handled separately via `SquareInventoryRepository` but there is no unified sync engine that coordinates both channels. The `InventoryController` is not wired to `InventorySyncService` — sync must be triggered manually. + +--- + +#### `feature_orders` — [PARTIAL] + +| Artifact | Status | +| --------------------------------------------------------------------------------------------------------- | ---------------------- | +| `Order` domain model (full fields: customerPhone, notes, orderNotes, paymentMethod, source, customFields) | ✅ Complete | +| `OrderItem` domain model (productId, variationId, customizations) | ✅ Complete | +| `OrderStatus` enum (including onHold, refunded, failed) | ✅ Complete | +| `OrderSource` enum (online, market, manual) | ✅ Complete | +| `OrderActionResult` value object | ✅ Complete | +| `OrdersRepository` contract (getOrders, getOrder, createOrder, updateOrderStatus, addOrderNote) | ✅ Complete | +| `FakeOrdersRepository` (seeded, all write methods) | ✅ Complete | +| `WooCommerceOrdersRepository` | ✅ Complete | +| `WooCommerceOrderMapper` | ✅ Complete | +| All use cases (GetOrders, UpdateOrderStatus, AddOrderNote, CreateOrder) | ✅ Complete | +| `OrdersController` (read + write, filter/search persistence) | ✅ Complete | +| `OrdersPage` (web, master-detail, status filter, cross-feature callbacks) | ✅ Complete | +| `OrderDetailPanel`, `OrderCard`, `AddNoteDialog`, `OrderStatusChip` | ✅ Complete | +| `OrderType` enum (standard, custom) | ❌ Missing (Stage 11A) | +| `CustomOrderSpec` value object | ❌ Missing (Stage 11A) | +| `DepositInfo` value object | ❌ Missing (Stage 11A) | +| Custom order fulfillment status pipeline | ❌ Missing (Stage 11C) | +| `CustomOrderFormPage` | ❌ Missing (Stage 11B) | +| `CustomOrderTrackingPage` | ❌ Missing (Stage 11C) | +| `OrderChannel` enum (woocommerce, square, manual) | ❌ Missing (Stage 13B) | +| `UnifiedOrdersController` (multi-channel aggregation) | ❌ Missing (Stage 13B) | +| Standard scaffolding files (`.gitignore`, `.metadata`, `CHANGELOG.md`, `LICENSE`, `README.md`) | ❌ Missing | +| Tests | ✅ 198/198 passing | + +**Notes:** The `feature_orders` package is missing standard monorepo scaffolding files present in all other packages. The WooCommerce orders integration is production-ready. Square orders are not yet integrated into the orders feature (Square API client has `createOrder`/`listOrders`/`getOrder` but no `SquareOrdersRepository` exists). + +--- + +#### `feature_policy` — [PARTIAL] + +| Artifact | Status | +| --------------------------------------------------------------------- | ---------------------------------------------------------- | +| `PolicyCheckResult` domain model | ✅ Complete | +| `GovernanceStatus` enum | ✅ Complete | +| `PolicyRepository` contract | ✅ Complete | +| `FakePolicyRepository` | ✅ Complete | +| `GetPolicyChecks` use case | ✅ Complete | +| `PolicyController` | ✅ Complete | +| `PolicyPage` (master-detail, filter, search, cross-feature callbacks) | ✅ Complete | +| `PolicyCheckCard`, `PolicyDetailPanel` | ✅ Complete | +| Real backend (e.g., reading from policy register CSVs) | ❌ Missing | +| Tests | ⚠️ Minimal (only smoke test in `feature_policy_test.dart`) | + +**Notes:** The policy feature is fake-data only. The policy register CSVs in `policies/register/` contain headers only with no data rows — the controlled document lifecycle is not being followed for the governance documents themselves. + +--- + +#### `feature_finance` — [MISSING/PENDING] + +| Artifact | Status | +| --------------------- | ------------------------------------- | +| Package scaffolding | ✅ Exists | +| Any domain model | ❌ Missing | +| Any application logic | ❌ Missing | +| Any data layer | ❌ Missing | +| Any presentation | ❌ Missing | +| Tests | ❌ Placeholder `Calculator` test only | + +**Notes:** The barrel file (`feature_finance.dart`) contains only the Flutter template `Calculator` class. The Finance route in `kell_web` renders `FinancePlaceholderPage`. This is a pure stub. + +--- + +#### `feature_mrp` — [MISSING/PENDING] + +| Artifact | Status | +| --------------------- | ------------------------------------- | +| Package scaffolding | ✅ Exists | +| Any domain model | ❌ Missing | +| Any application logic | ❌ Missing | +| Any data layer | ❌ Missing | +| Any presentation | ❌ Missing | +| Tests | ❌ Placeholder `Calculator` test only | + +**Notes:** Pure stub. Scope should be re-evaluated after Stage 12 (supplies tracking) to determine if MRP adds distinct value beyond custom orders + inventory. + +--- + +#### `feature_social` — [MISSING/PENDING] + +| Artifact | Status | +| --------------------- | ------------------------------------- | +| Package scaffolding | ✅ Exists | +| Any domain model | ❌ Missing | +| Any application logic | ❌ Missing | +| Any data layer | ❌ Missing | +| Any presentation | ❌ Missing | +| Tests | ❌ Placeholder `Calculator` test only | + +**Notes:** Pure stub. Deferred until core platform stabilizes. Facebook, Instagram, and X (Twitter) API integrations are all listed as "Stub only" in the integration landscape. + +--- + +### 2.3 Application Targets + +#### `kell_web` — [COMPLETE] (for current feature scope) + +| Artifact | Status | +| ----------------------------------------------------------------------------------- | ------------------- | +| `AppServices` (fake + wordpress factories) | ✅ Complete | +| `KcBootstrap` / `KcAppScope` wiring | ✅ Complete | +| `AppShell` with sidebar navigation (7 routes) | ✅ Complete | +| `AppRoutes` (dashboard, inventory, products, orders, finance, policy, integrations) | ✅ Complete | +| `DashboardPage` (8 KPI cards, quick actions, cross-feature navigation) | ✅ Complete | +| `ProductPublishingPage` (full feature surface) | ✅ Complete | +| `InventoryPage` (full feature surface) | ✅ Complete | +| `OrdersPage` (full feature surface) | ✅ Complete | +| `PolicyPage` (full feature surface) | ✅ Complete | +| `FinancePlaceholderPage` | ⚠️ Placeholder only | +| `IntegrationsPlaceholderPage` | ⚠️ Placeholder only | +| `square` / `multi` factory constructors in `AppServices` | ❌ Missing | +| Tests | ✅ 24/24 passing | + +**Notes:** `AppServices` has no `square()` or `multi()` factory. Setting `KC_ENV=square` or `KC_ENV=multi` at runtime will fall through to `fake` mode silently because `KcServiceFactory` only has `createFake` and `createWordPress` callbacks. This is a critical gap for Square integration testing. + +--- + +#### `kell_mobile` — [COMPLETE] (for current feature scope) + +| Artifact | Status | +| ----------------------------------------------------------------------------------- | ---------------------- | +| `MobileAppServices` (fake + wordpress factories) | ✅ Complete | +| `KcBootstrap` / `KcAppScope` wiring | ✅ Complete | +| `MobileShell` (5-tab NavigationBar: Dashboard, Inventory, Orders, Publishing, More) | ✅ Complete | +| `DashboardPage` (mobile GridView layout) | ✅ Complete | +| `MobilePublishingPage` + `MobileProductDetailPage` | ✅ Complete | +| `MobileCreateProductPage` | ✅ Complete | +| `MobileInventoryPage` + `MobileInventoryDetailPage` | ✅ Complete | +| `MobileOrdersPage` + `MobileOrderDetailPage` | ✅ Complete | +| Haptic feedback, confirmation dialogs, SafeArea, 48dp touch targets | ✅ Complete | +| `FinancePlaceholderPage` | ⚠️ Placeholder only | +| `IntegrationsPlaceholderPage` | ⚠️ Placeholder only | +| `square` / `multi` factory constructors in `MobileAppServices` | ❌ Missing | +| Square POS / checkout flow | ❌ Missing (Stage 10C) | +| `MobileCheckoutPage` | ❌ Missing (Stage 10C) | +| Tests | ✅ 26/26 passing | + +--- + +### 2.4 Architecture & Documentation + +#### Architecture Documentation — [COMPLETE] + +| Artifact | Status | +| ------------------------------------------------------------------------------ | ------------------------------- | +| 19 PlantUML C4 diagrams (context, containers, components, deployment, dynamic) | ✅ Complete | +| MkDocs documentation site (`mkdocs.yml`) | ✅ Complete | +| ADR index (7 retroactive entries) | ✅ Complete | +| Traceability index | ✅ Complete | +| Square not represented in architecture diagrams | ❌ Missing (noted in brief §17) | +| Multi-channel data model architecture | ❌ Missing (noted in brief §18) | + +#### Policy Repository — [PARTIAL] + +| Artifact | Status | +| ----------------------------------------------------------------------------- | ------------------------------------- | +| Policy templates (policy, procedure, standard, form, exception) | ✅ Complete | +| Active governance documents (KC-POL-GOV-001, KC-PRO-GOV-001) | ✅ Complete | +| Policy register CSVs (policy-register, document-control-log, review-calendar) | ❌ Empty (headers only, no data rows) | +| Exception register | ❌ Empty | + +--- + +## 3. Technical Debt & Code Hygiene Assessment + +### 3.1 Dead Code / Placeholder Stubs + +| Location | Issue | Severity | +| ------------------------------------------------------------------ | -------------------------------------------------------------- | -------- | +| `feature_finance/lib/feature_finance.dart` | Flutter template `Calculator` class — entire package is a stub | HIGH | +| `feature_mrp/lib/feature_mrp.dart` | Flutter template `Calculator` class — entire package is a stub | HIGH | +| `feature_social/lib/feature_social.dart` | Flutter template `Calculator` class — entire package is a stub | HIGH | +| `kell_web/lib/pages/finance_placeholder_page.dart` | Placeholder page with no content | MEDIUM | +| `kell_web/lib/pages/integrations_placeholder_page.dart` | Placeholder page with no content | MEDIUM | +| `kell_mobile/lib/pages/finance_placeholder_page.dart` | Placeholder page with no content | MEDIUM | +| `kell_mobile/lib/pages/integrations_placeholder_page.dart` | Placeholder page with no content | MEDIUM | +| `kell_web/lib/pages/dashboard_page.dart` (Recent Activity section) | `KcEmptyState` hardcoded — no real activity feed | LOW | + +### 3.2 Missing Error Handling / Defensive Gaps + +| Location | Issue | Severity | +| ---------------------------------------------- | ----------------------------------------------------------------------------- | -------- | +| `AppServices` / `MobileAppServices` | No `square()` or `multi()` factory — `KC_ENV=square` silently falls to fake | CRITICAL | +| `KcBootstrap` | Only validates WooCommerce credentials; Square credential validation absent | HIGH | +| `SquareCatalogRepository` | 6 methods throw `UnsupportedError` (categories, images) — callers must handle | HIGH | +| `integrations` — `RetryPolicy` / `RateLimiter` | Defined but not wired into `SquareApiClient` or `WooCommerceApiClient` | HIGH | +| `auth` package | Not imported or used by any app or feature package | HIGH | +| `data` package | Not imported or used by any app or feature package | MEDIUM | +| `InventoryController` | Not wired to `InventorySyncService` — sync cannot be triggered from UI | MEDIUM | +| `SquareCatalogSyncService` | No Riverpod/ChangeNotifier controller wrapper — cannot be triggered from UI | MEDIUM | +| `WooCommerceApiClient` | No retry logic on transient failures (5xx, network timeouts) | MEDIUM | +| `feature_policy` tests | Only a smoke test exists — no domain, controller, or widget tests | MEDIUM | + +### 3.3 Hardcoded Values / Antipatterns + +| Location | Issue | Severity | +| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------- | +| `SquareCatalogSyncService.syncCatalog()` | Uses `product.id` as both `localId` and `squareCatalogObjectId` — conflates Square catalog IDs with local product IDs | HIGH | +| `InventorySyncService._syncItem()` | `pushLocalStock` silently swallows push failures with `catch (_) {}` — no logging | MEDIUM | +| `kell_web/lib/pages/dashboard_page.dart` | Revenue card navigates to Finance route which is a placeholder | LOW | +| `policies/register/*.csv` | All register CSVs contain headers only — no data rows | MEDIUM | +| `feature_orders` package | Missing `.gitignore`, `.metadata`, `CHANGELOG.md`, `LICENSE`, `README.md` | LOW | + +### 3.4 Test Coverage Assessment + +| Package | Tests | Coverage | Assessment | +| ------------------- | --------------- | -------- | ----------------------------------------------------- | +| `core` | 24 | ~85.7% | Good — composition abstractions well covered | +| `design_system` | 41 | 100% | Excellent | +| `feature_wordpress` | 506 | ~84.7% | Good — broad coverage across all layers | +| `feature_inventory` | 167 | Unknown | Adequate — domain, data, and widget tests present | +| `feature_orders` | 198 | Unknown | Good — domain, data, mapper, and widget tests present | +| `feature_policy` | ~5 | Very low | **Gap** — only smoke test; no controller/widget tests | +| `auth` | 42 | Unknown | Good for contracts and fakes | +| `data` | 63 | Unknown | Good for contracts and in-memory impls | +| `integrations` | 123 | Unknown | Good — API client and mapper tests present | +| `kell_web` | 24 | ~54.1% | **Gap** — low coverage; routing and shell untested | +| `kell_mobile` | 26 | Unknown | Adequate — shell and page smoke tests | +| `feature_finance` | 1 (placeholder) | ~0% | **Critical gap** — stub only | +| `feature_mrp` | 1 (placeholder) | ~0% | **Critical gap** — stub only | +| `feature_social` | 1 (placeholder) | ~0% | **Critical gap** — stub only | + +**Key gaps:** + +- `kell_web` at 54.1% line coverage — routing, shell, and navigation are largely untested +- `feature_policy` has no meaningful tests beyond a barrel smoke test +- No integration tests exist across any package boundary +- No end-to-end tests exist for any user workflow +- CI enforces no minimum coverage thresholds (visibility-only) + +### 3.5 Architectural Antipatterns + +| Issue | Description | Severity | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| **No state management framework** | All state uses `ChangeNotifier` + `AnimatedBuilder`. As complexity grows (sync engine, multi-channel, offline queue), this pattern will become difficult to compose. No Riverpod, BLoC, or equivalent. | MEDIUM | +| **No dependency injection** | Services are constructed directly in factory methods. No DI container. Makes testing harder as the app grows. | MEDIUM | +| **`SquareCatalogSyncService` ID conflation** | `syncCatalog()` uses `product.id` as the Square catalog object ID, but `product.id` is the local/WooCommerce ID. This will produce incorrect mappings when Square is the source. | HIGH | +| **`AppServices` / `MobileAppServices` duplication** | Both files are nearly identical. A shared base class or factory could eliminate the duplication. | LOW | +| **No logging infrastructure** | No structured logging anywhere in the codebase. Errors are caught and surfaced via SnackBars or swallowed silently. | MEDIUM | +| **No crash reporting** | No Sentry, Firebase Crashlytics, or equivalent. Runtime errors are invisible in production. | MEDIUM | + +--- + +## 4. Actionable Engineering Backlog + +### Phase 1 — High-Priority / Blocking (Core Fixes & Missing Execution Paths) + +These items block correct runtime behavior or represent data integrity risks. + +#### P1.1 — Wire `square` and `multi` factory constructors into `AppServices` and `MobileAppServices` + +**Why blocking:** Setting `KC_ENV=square` currently silently falls to fake mode. Square integration cannot be tested end-to-end without this. +**Scope:** Add `AppServices.square()` and `AppServices.multi()` factories using `SquareCatalogRepository` and `SquareInventoryRepository`. Mirror in `MobileAppServices`. Update `KcServiceFactory` to accept `createSquare` and `createMulti` callbacks. Update `KcBootstrap` to validate Square credentials. +**Branch:** `feat/square-catalog-sync-service-controller` (Stage 10E) should include this. + +#### P1.2 — Fix `SquareCatalogSyncService.syncCatalog()` ID conflation + +**Why blocking:** The current implementation uses `product.id` (a local/WooCommerce ID) as the `squareCatalogObjectId`. When `SquareCatalogRepository` is the source, `product.id` is the Square catalog object ID — but when `FakeProductPublishingRepository` or `WordPressProductPublishingRepository` is the source, `product.id` is a WooCommerce ID. The mapping will be incorrect in mixed-source scenarios. +**Scope:** The sync service needs to know which repository type it is talking to, or the `ProductDraft` model needs a `squareCatalogObjectId` field, or the sync service should accept the Square catalog object ID separately. + +#### P1.3 — Merge Stage 10D (`feat/square-catalog-sync-service`) + +**Why blocking:** The build tracker shows Stage 10D as "ready for merge" but not yet merged. The master brief baseline is Stage 10C. Stage 10E depends on 10D being on `main`. +**Action:** Merge `feat/square-catalog-sync-service` → `main` before starting Stage 10E. + +#### P1.4 — `SquareSyncController` (Stage 10E) + +**Why blocking:** `SquareCatalogSyncService` exists but has no UI trigger. Without a controller, sync cannot be initiated from the app. +**Scope:** `ChangeNotifier` wrapping `SquareCatalogSyncService`, exposing `syncAll()`, `syncCatalog()`, `syncInventory()`, `isSyncing`, `lastSyncedAt`, `lastResult`. Wire into `AppServices` / `MobileAppServices`. +**Branch:** `feat/square-catalog-sync-service-controller` + +#### P1.5 — Add `square` / `multi` mode to `KcBootstrap` credential validation + +**Why blocking:** `KcBootstrap` currently only validates WooCommerce credentials. Square mode will silently proceed with empty tokens. +**Scope:** Add `hasSquareConfig` check in bootstrap for `square` and `multi` environments. + +--- + +### Phase 2 — Feature Completion & Integration + +These items complete planned stages and wire existing contracts into production paths. + +#### P2.1 — Square Mobile POS / Checkout (Stage 10C) + +**Scope:** `PaymentService` abstraction, `PaymentResult` domain model, `MobileCheckoutPage` (product selection → cart → payment), Square Reader SDK integration for Android, cash recording, digital receipt, post-payment order creation and inventory deduction, `Sales` tab in mobile navigation. +**Dependencies:** Stage 10A ✅, Stage 10B ✅, Stage 10D ✅, P1.1, P1.4 + +#### P2.2 — Custom Orders Workflow (Stage 11) + +**Scope:** `OrderType` enum, `CustomOrderSpec` value object, `DepositInfo` value object, extended `Order` model, `createCustomOrder()` / `updateCustomOrderSpec()` / `recordDeposit()` repository methods, `CustomOrderFormPage`, `CustomOrderConfirmationPage`, `CustomOrderTrackingPage`, fulfillment status pipeline. +**Dependencies:** Stage 9A ✅ + +#### P2.3 — Inventory Write Operations & Supplies Tracking (Stage 12A/12B) + +**Scope:** `ItemType` enum, `InventoryAdjustment` audit log, `Supplier` domain model, `PurchaseOrder` domain model, supply receiving workflow, material usage workflow, low-stock alert system, `SuppliesPage` UI. +**Dependencies:** Stage 9B ✅ + +#### P2.4 — Multi-Channel Inventory Sync Engine (Stage 12C) + +**Scope:** `InventorySyncEngine` (poll/webhook-triggered, conflict resolution, batch sync), `ChannelStockMapping`, `WooCommerceStockSync`, `SquareStockSync`, sync status indicators in inventory UI, manual sync trigger. +**Dependencies:** P2.3, Stage 10B ✅ + +#### P2.5 — WooCommerce Orders Integration wired into `AppServices` + +**Current state:** `WooCommerceOrdersRepository` exists but `AppServices.wordpress()` still uses `FakeOrdersRepository`. +**Scope:** Wire `WooCommerceOrdersRepository` into `AppServices.wordpress()` and `MobileAppServices.wordpress()`. + +#### P2.6 — WooCommerce Inventory Integration wired into `AppServices` + +**Current state:** `WooCommerceInventoryRepository` exists but `AppServices.wordpress()` still uses `FakeInventoryRepository`. +**Scope:** Wire `WooCommerceInventoryRepository` into `AppServices.wordpress()` and `MobileAppServices.wordpress()`. + +#### P2.7 — Unified Order View (Stage 13B) + +**Scope:** `OrderChannel` enum, `UnifiedOrdersController` aggregating WooCommerce + Square + manual orders, unified orders page with channel indicator. +**Dependencies:** P2.1, Stage 9A ✅ + +#### P2.8 — Offline Data Cache & Sales Queue (Stage 14) + +**Scope:** SQLite-backed `LocalCache` implementation (using `sqflite` or `drift`), SQLite-backed `SyncQueue`, offline detection, "Prepare for Market" pre-sync action, auto-sync on reconnect, conflict handling. +**Dependencies:** `data` package contracts ✅ + +#### P2.9 — `feature_finance` Activation (Stage 15) + +**Scope:** Sales reporting (by channel, product, time period), inventory valuation, financial dashboard (revenue vs. COGS, gross margin, market event profitability). +**Dependencies:** P2.1, Stage 9A ✅, P2.3 + +#### P2.10 — Populate Policy Register CSVs + +**Scope:** Add data rows to `policies/register/policy-register.csv`, `document-control-log.csv`, `review-calendar.csv`, and `exception-register.csv` for the 2 active governance documents. +**Dependencies:** None — can be done immediately. + +--- + +### Phase 3 — Defensive Engineering, Logging & Test Harness Expansion + +These items harden the platform for production deployment. + +#### P3.1 — Wire `RetryPolicy` and `RateLimiter` into API clients + +**Scope:** Apply `ExponentialBackoffRetryPolicy` to `SquareApiClient` and `WooCommerceApiClient` for 5xx and network errors. Apply `TokenBucketRateLimiter` to Square API calls (Square enforces rate limits). + +#### P3.2 — Implement `SecureCredentialStore` (Stage 8C remainder) + +**Scope:** `flutter_secure_storage`-backed `CredentialStore` implementation. First-run setup wizard for entering API credentials. Connection testing UI. + +#### P3.3 — Auth guard wired into app shell + +**Scope:** Login screen, `AuthService` wired into `AppServices`, route guard preventing unauthenticated access. +**Dependencies:** P3.2 + +#### P3.4 — Structured logging infrastructure + +**Scope:** Add a logging abstraction (e.g., `package:logging`) with structured output. Log all API calls, sync operations, errors, and state transitions. Replace silent `catch (_) {}` blocks with logged failures. + +#### P3.5 — Crash reporting integration (Stage 16A) + +**Scope:** Sentry or Firebase Crashlytics integration. Health check dashboard showing integration status per channel. + +#### P3.6 — Expand `feature_policy` test coverage + +**Scope:** Add controller tests, widget tests for `PolicyPage`, `PolicyCheckCard`, `PolicyDetailPanel`. Target >80% line coverage. + +#### P3.7 — Expand `kell_web` test coverage from 54.1% + +**Scope:** Add routing tests, shell navigation tests, `AppServices` factory tests. Target >75% line coverage. + +#### P3.8 — Add `feature_orders` standard scaffolding files + +**Scope:** Add `.gitignore`, `.metadata`, `CHANGELOG.md`, `LICENSE`, `README.md` to `feature_orders` to match all other packages. + +#### P3.9 — Update architecture diagrams for Square and multi-channel + +**Scope:** Add Square to `system-landscape.puml`, `enterprise-integration-orchestration-architecture.puml`, `context-kellcreations-platform.puml`. Create `dynamic-market-sale-checkout.puml`. Create `enterprise-multi-channel-architecture.puml`. + +#### P3.10 — Implement `ChannelAdapter` for WooCommerce and Square + +**Scope:** Concrete `WooCommerceChannelAdapter` and `SquareChannelAdapter` implementing the `ChannelAdapter` contract from `integrations`. This enables the multi-channel sync engine (Stage 13A) to operate against a channel-agnostic interface. + +#### P3.11 — Enforce minimum test coverage thresholds in CI + +**Scope:** Update `flutter-test.yml` to fail the build if any package drops below a defined threshold (e.g., 75% line coverage). Currently coverage is visibility-only. + +#### P3.12 — Evaluate and activate `feature_mrp` + +**Scope:** After Stage 12 completion, assess whether MRP adds distinct value (production scheduling, work orders, bill of materials) beyond custom orders + inventory. Activate or formally retire the package. + +--- + +## 5. Summary Scorecard + +| Subsystem | Status | Completeness | Blocking Issues | +| ------------------- | ----------- | ------------ | ----------------------------------------------------------------- | +| `core` | ✅ COMPLETE | 95% | Square/multi bootstrap validation missing | +| `design_system` | ✅ COMPLETE | 100% | None | +| `auth` | ⚠️ PARTIAL | 40% | No production impl, not wired into app | +| `data` | ⚠️ PARTIAL | 35% | No SQLite impl, not wired into any feature | +| `integrations` | ⚠️ PARTIAL | 70% | RetryPolicy/RateLimiter not wired; ChannelAdapter not implemented | +| `feature_wordpress` | ✅ COMPLETE | 95% | SquareSyncController (Stage 10E) pending | +| `feature_inventory` | ⚠️ PARTIAL | 65% | No unified sync engine; ItemType/Supplier/PurchaseOrder missing | +| `feature_orders` | ⚠️ PARTIAL | 70% | Custom orders missing; WC/Square repos not wired into AppServices | +| `feature_policy` | ⚠️ PARTIAL | 50% | Fake-only; minimal tests; policy register empty | +| `feature_finance` | ❌ MISSING | 0% | Pure stub | +| `feature_mrp` | ❌ MISSING | 0% | Pure stub | +| `feature_social` | ❌ MISSING | 0% | Pure stub | +| `kell_web` | ⚠️ PARTIAL | 75% | Finance/Integrations placeholder; no square/multi factory | +| `kell_mobile` | ⚠️ PARTIAL | 70% | No POS/checkout; no square/multi factory | +| Architecture docs | ⚠️ PARTIAL | 80% | Square not represented; multi-channel model missing | +| Policy register | ❌ MISSING | 10% | All CSVs empty | +| CI/CD | ✅ COMPLETE | 85% | No coverage thresholds enforced | + +### Overall Platform Readiness + +| Dimension | Assessment | +| ---------------------------------- | ----------------------------------------------------------- | +| **WooCommerce catalog management** | ✅ Production-ready | +| **WooCommerce orders** | ✅ Repository complete; not wired into AppServices | +| **WooCommerce inventory sync** | ✅ Repository complete; not wired into AppServices | +| **Square catalog sync** | ⚠️ Service layer complete; no UI trigger; ID conflation bug | +| **Square inventory sync** | ⚠️ Repository complete; not wired into AppServices | +| **Square payments / POS** | ❌ Not implemented | +| **Custom orders** | ❌ Not implemented | +| **Supplies tracking** | ❌ Not implemented | +| **Multi-channel sync engine** | ❌ Not implemented | +| **Offline capability** | ❌ Not implemented | +| **Authentication** | ❌ Contracts only; not wired | +| **Financial reporting** | ❌ Not implemented | +| **Social media management** | ❌ Not implemented | + +--- + +_Generated by automated repository audit. All findings are based on source code inspection, documentation review, and test suite analysis as of 2026-07-25._ +--- + +## 5. Summary Scorecard + +| Subsystem | Status | Completeness | Blocking Issues | +|---|---|---|---| +| `core` | ✅ COMPLETE | 95% | Square/multi bootstrap validation missing | +| `design_system` | ✅ COMPLETE | 100% | None | +| `auth` | ⚠️ PARTIAL | 40% | No production impl, not wired into app | +| `data` | ⚠️ PARTIAL | 35% | No SQLite impl, not wired into any feature | +| `integrations` | ⚠️ PARTIAL | 70% | RetryPolicy/RateLimiter not wired; ChannelAdapter not implemented | +| `feature_wordpress` | ✅ COMPLETE | 95% | SquareSyncController (Stage 10E) pending | +| `feature_inventory` | ⚠️ PARTIAL | 65% | No unified sync engine; ItemType/Supplier/PurchaseOrder missing | +| `feature_orders` | ⚠️ PARTIAL | 70% | Custom orders missing; WC/Square repos not wired into AppServices | +| `feature_policy` | ⚠️ PARTIAL | 50% | Fake-only; minimal tests; policy register empty | +| `feature_finance` | ❌ MISSING | 0% | Pure stub | +| `feature_mrp` | ❌ MISSING | 0% | Pure stub | +| `feature_social` | ❌ MISSING | 0% | Pure stub | +| `kell_web` | ⚠️ PARTIAL | 75% | Finance/Integrations placeholder; no square/multi factory | +| `kell_mobile` | ⚠️ PARTIAL | 70% | No POS/checkout; no square/multi factory | +| Architecture docs | ⚠️ PARTIAL | 80% | Square not represented; multi-channel model missing | +| Policy register | ❌ MISSING | 10% | All CSVs empty | +| CI/CD | ✅ COMPLETE | 85% | No coverage thresholds enforced | + +### Overall Platform Readiness + +| Dimension | Assessment | +|---|---| +| **WooCommerce catalog management** | ✅ Production-ready | +| **WooCommerce orders** | ✅ Repository complete; not wired into AppServices | +| **WooCommerce inventory sync** | ✅ Repository complete; not wired into AppServices | +| **Square catalog sync** | ⚠️ Service layer complete; no UI trigger; ID conflation bug | +| **Square inventory sync** | ⚠️ Repository complete; not wired into AppServices | +| **Square payments / POS** | ❌ Not implemented | +| **Custom orders** | ❌ Not implemented | +| **Supplies tracking** | ❌ Not implemented | +| **Multi-channel sync engine** | ❌ Not implemented | +| **Offline capability** | ❌ Not implemented | +| **Authentication** | ❌ Contracts only; not wired | +| **Financial reporting** | ❌ Not implemented | +| **Social media management** | ❌ Not implemented | + +--- + +*Generated by automated repository audit. All findings are based on source code inspection, documentation review, and test suite analysis as of 2026-07-25.* diff --git a/docs/development/build_execution_tracker.md b/docs/development/build_execution_tracker.md index 0941e2a..3b2462d 100644 --- a/docs/development/build_execution_tracker.md +++ b/docs/development/build_execution_tracker.md @@ -2,9 +2,12 @@ ## Current status -- main baseline updated through: feat/square-catalog-sync-repositories (Stage 10C complete) -- next branch: feat/square-catalog-sync-service-controller (Stage 10E — SquareSyncController Riverpod provider wrapping SquareCatalogSyncService) -- current stage: Stage 10D complete — `SquareCatalogSyncService` + `SquareSyncResult` + `SyncError` + `InventorySyncAdapter` (feature_wordpress); feature_wordpress 506/506, feature_inventory 167/167 tests passing; analyze clean; branch ready for merge +- main baseline updated through: `feat/square-catalog-sync-repositories` (Stage 10C complete, 2026-07-25) +- audit completed: `chore/audit-state-sync` — Comprehensive State Audit (`PROJECT_STATE_AUDIT.md`) completed 2026-07-25; all findings incorporated into `master_development_brief.md` and this tracker +- pending merge: `feat/square-catalog-sync-service` (Stage 10D) — ready for merge; 506/506 feature_wordpress, 167/167 feature_inventory; analyze clean +- next active branch: `feat/square-catalog-sync-service-controller` (Stage 10E) — **do not start until Stage 10D is merged** +- next branch scope: `SquareSyncController` (P1.4) + `AppServices.square()`/`multi()` factories (P1.1) + `KcBootstrap` Square credential validation (P1.5) + `SquareCatalogSyncService` ID conflation fix (P1.2) +- total tests on main: 1,015/1,015 passing (Stage 10C baseline); 1,015+31 = 1,046 after Stage 10D merge ## Slice tracker @@ -607,6 +610,29 @@ - analyze: clean (dart analyze — no issues found) - brief updated: yes +### chore/audit-state-sync + +- status: complete (documentation-only — no code changes) +- date: 2026-07-25 +- inspection: complete — full repository audit conducted against all 11 packages/apps +- implementation: complete +- audit reference: `PROJECT_STATE_AUDIT.md` — Kell Creations Operations Platform Comprehensive Code Audit +- files changed: + - `PROJECT_STATE_AUDIT.md` — new comprehensive audit document; covers monorepo architecture, built vs. remaining matrix for all 13 packages + 2 apps, technical debt assessment (dead code, error handling gaps, hardcoded values, test coverage, architectural antipatterns), and actionable engineering backlog (Phase 1/2/3 priorities) + - `docs/development/master_development_brief.md` — updated validation state (core 24/24, feature_wordpress 506/506 post-10D, total 1,015/1,015); updated next recommended branch to include P1.1–P1.5 scope; added "Comprehensive State Audit (2026-07-25)" section with platform scorecard, Phase 1/2/3 backlog tables, and key technical debt findings; updated Appendix A (feature maturity matrix — all test counts, completeness percentages, kell_web/kell_mobile rows added); updated Appendix B (integration landscape — all Square repos now marked complete, WC repos status corrected); updated Appendix C (Square keys moved from "Planned" to "Active"; KC_ENV values table updated with current status) + - `docs/development/build_execution_tracker.md` — updated current status section (audit completion noted, pending merge flagged, next branch scope documented); added this slice entry +- tests: n/a (documentation-only change) +- analyze: n/a (documentation-only change) +- brief updated: yes +- audit findings summary: + - 1,015/1,015 tests passing across all 11 packages/apps + - `dart analyze --fatal-infos` clean across all 11 packages/apps + - CRITICAL: `AppServices`/`MobileAppServices` have no `square()` or `multi()` factory — `KC_ENV=square` silently falls to fake mode + - HIGH: `SquareCatalogSyncService` ID conflation bug; `RetryPolicy`/`RateLimiter` not wired; `auth` package not imported by any app + - Phase 1 (5 items) → target `feat/square-catalog-sync-service-controller` (Stage 10E) + - Phase 2 (10 items) → Stages 10C, 11, 12, 13, 14, 15 + - Phase 3 (12 items) → Stages 16A/B + standalone hardening tasks + ### feat/square-catalog-sync-repositories - status: in progress on branch — ready for merge diff --git a/docs/development/master_development_brief.md b/docs/development/master_development_brief.md index 196bab7..ae8d7b0 100644 --- a/docs/development/master_development_brief.md +++ b/docs/development/master_development_brief.md @@ -139,26 +139,25 @@ Rules: ### Latest known validation state on `main` -- `dart analyze` clean -- `core` tests passing -- `design_system` tests passing -- `feature_wordpress` tests passing -- `feature_orders` tests passing -- `kell_web` tests passing -- `kell_mobile` tests passing -- latest reported count for `core`: `21/21 passed` +> **Last verified:** 2026-07-25 — Comprehensive State Audit (`chore/audit-state-sync`) + +- `dart analyze --fatal-infos` clean across all 11 packages/apps +- All packages passing +- latest reported count for `core`: `24/24 passed` - latest reported count for `design_system`: `41/41 passed` - latest reported count for `feature_inventory`: `167/167 passed` ← +35 new (Stage 10C) - latest reported count for `feature_orders`: `198/198 passed` -- latest reported count for `feature_wordpress`: `475/475 passed` ← +51 new (Stage 10C) +- latest reported count for `feature_wordpress`: `506/506 passed` ← +31 new (Stage 10D, pending merge) - latest reported count for `kell_web`: `24/24 passed` - latest reported count for `integrations`: `123/123 passed` - latest reported count for `data`: `63/63 passed` - latest reported count for `auth`: `42/42 passed` - latest reported count for `kell_mobile`: `26/26 passed` -- total: `1015/1015 passed` (Stage 10C baseline: 957 + 58 Stage 10B + 86 Stage 10C new tests) +- total: `1,015/1,015 passed` (Stage 10C `main` baseline: 957 + 58 Stage 10B + 86 Stage 10C new tests; Stage 10D adds 31 more on pending branch) - baseline commit: merge of `feat/square-catalog-sync-repositories` into `main` (Stage 10C complete, 2026-07-25) +> **Note:** Stage 10D (`feat/square-catalog-sync-service`) is complete and ready for merge. The `feature_wordpress` count of 506/506 reflects the post-merge state. The `main` baseline currently shows 475/475 for `feature_wordpress` until Stage 10D is merged. + #### Baseline test coverage (established 2026-05-22) | Package | Tests | Lines Hit | Lines Found | Coverage | @@ -189,18 +188,125 @@ Delivered: ### Next recommended branch -**`feat/square-catalog-sync-service-controller`** — Stage 10E: `SquareSyncController` Riverpod provider. +> **⚠️ Prerequisite (P1.3):** Merge `feat/square-catalog-sync-service` → `main` before starting Stage 10E. Stage 10D is complete and ready for merge; Stage 10E depends on it being on `main`. -Branch from latest `main`. Stage 10D (`SquareCatalogSyncService`) is complete. The next slice adds a Riverpod `AsyncNotifier` (or `ChangeNotifier` if Riverpod is not yet wired) that: +**`feat/square-catalog-sync-service-controller`** — Stage 10E: `SquareSyncController` (highest-priority blocking task from Phase 1 audit backlog). + +Branch from latest `main` **after** merging Stage 10D. This slice adds a `ChangeNotifier` controller (or Riverpod `AsyncNotifier` if Riverpod is wired) that: - Wraps `SquareCatalogSyncService` and exposes `syncAll()`, `syncCatalog()`, `syncInventory()` as async actions - Tracks `isSyncing` state and the last `SquareSyncResult` - Exposes a `lastSyncedAt` timestamp - Lives in `feature_wordpress/lib/src/application/square_sync_controller.dart` - Is exported from `feature_wordpress.dart` barrel -- Wires into `MobileAppServices` (or `WebAppServices`) so the sync can be triggered from the UI +- Wires into `AppServices` and `MobileAppServices` so the sync can be triggered from the UI -Tests should cover: initial state, syncAll happy path, syncAll partial failure, isSyncing true during sync and false after, lastSyncedAt stamped on completion, error state on total failure. +**Also include in this branch (P1.1 + P1.5):** + +- Add `AppServices.square()` and `AppServices.multi()` factory constructors using `SquareCatalogRepository` and `SquareInventoryRepository` +- Mirror in `MobileAppServices.square()` and `MobileAppServices.multi()` +- Update `KcServiceFactory` to accept `createSquare` and `createMulti` callbacks +- Add `hasSquareConfig` credential check in `KcBootstrap` for `square` and `multi` environments + +**Fix in this branch (P1.2):** + +- Resolve `SquareCatalogSyncService.syncCatalog()` ID conflation: add `squareCatalogObjectId` field to `ProductDraft` (nullable), or pass it separately, so the sync service does not conflate local/WooCommerce IDs with Square catalog object IDs + +Tests should cover: initial state, syncAll happy path, syncAll partial failure, isSyncing true during sync and false after, lastSyncedAt stamped on completion, error state on total failure, square/multi factory construction, bootstrap credential validation for square mode. + +--- + +## Comprehensive State Audit (2026-07-25) + +**Audit reference:** `PROJECT_STATE_AUDIT.md` — Kell Creations Operations Platform Comprehensive Code Audit +**Audit date:** 2026-07-25 +**Baseline:** Stage 10C complete (`feat/square-catalog-sync-repositories` → `main`) +**Total tests verified:** 1,015 / 1,015 passing; `dart analyze --fatal-infos` clean across all 11 packages/apps + +### Platform scorecard (as of 2026-07-25) + +| Subsystem | Status | Completeness | Blocking Issues | +| ------------------- | ----------- | ------------ | ----------------------------------------------------------------- | +| `core` | ✅ COMPLETE | 95% | Square/multi bootstrap validation missing | +| `design_system` | ✅ COMPLETE | 100% | None | +| `auth` | ⚠️ PARTIAL | 40% | No production impl, not wired into app | +| `data` | ⚠️ PARTIAL | 35% | No SQLite impl, not wired into any feature | +| `integrations` | ⚠️ PARTIAL | 70% | RetryPolicy/RateLimiter not wired; ChannelAdapter not implemented | +| `feature_wordpress` | ✅ COMPLETE | 95% | SquareSyncController (Stage 10E) pending | +| `feature_inventory` | ⚠️ PARTIAL | 65% | No unified sync engine; ItemType/Supplier/PurchaseOrder missing | +| `feature_orders` | ⚠️ PARTIAL | 70% | Custom orders missing; WC/Square repos not wired into AppServices | +| `feature_policy` | ⚠️ PARTIAL | 50% | Fake-only; minimal tests; policy register empty | +| `feature_finance` | ❌ MISSING | 0% | Pure stub | +| `feature_mrp` | ❌ MISSING | 0% | Pure stub | +| `feature_social` | ❌ MISSING | 0% | Pure stub | +| `kell_web` | ⚠️ PARTIAL | 75% | Finance/Integrations placeholder; no square/multi factory | +| `kell_mobile` | ⚠️ PARTIAL | 70% | No POS/checkout; no square/multi factory | +| Architecture docs | ⚠️ PARTIAL | 80% | Square not represented; multi-channel model missing | +| Policy register | ❌ MISSING | 10% | All CSVs empty | +| CI/CD | ✅ COMPLETE | 85% | No coverage thresholds enforced | + +### Audit engineering backlog + +The full backlog is captured in `PROJECT_STATE_AUDIT.md` §4. The prioritized summary follows. + +#### Phase 1 — High-priority / blocking (core fixes and missing execution paths) + +These items block correct runtime behavior or represent data integrity risks. All Phase 1 items should be addressed in `feat/square-catalog-sync-service-controller` (Stage 10E) or immediately after. + +| ID | Item | Branch | +| ---- | -------------------------------------------------------------------------------------- | --------------------------------------------- | +| P1.1 | Wire `square` and `multi` factory constructors into `AppServices`/`MobileAppServices` | `feat/square-catalog-sync-service-controller` | +| P1.2 | Fix `SquareCatalogSyncService.syncCatalog()` ID conflation (`product.id` vs Square ID) | `feat/square-catalog-sync-service-controller` | +| P1.3 | Merge Stage 10D (`feat/square-catalog-sync-service`) → `main` | Immediate — prerequisite for Stage 10E | +| P1.4 | `SquareSyncController` (Stage 10E) — UI trigger for `SquareCatalogSyncService` | `feat/square-catalog-sync-service-controller` | +| P1.5 | Add `hasSquareConfig` credential check in `KcBootstrap` for `square`/`multi` modes | `feat/square-catalog-sync-service-controller` | + +#### Phase 2 — Feature completion and integration + +These items complete planned stages and wire existing contracts into production paths. + +| ID | Item | Target Stage | +| ----- | ---------------------------------------------------------------------------------- | --------------------------- | +| P2.1 | Square Mobile POS / Checkout (`MobileCheckoutPage`, Square Reader SDK) | Stage 10C | +| P2.2 | Custom Orders Workflow (`OrderType`, `CustomOrderSpec`, `DepositInfo`, UI) | Stage 11 | +| P2.3 | Inventory Write Ops & Supplies Tracking (`ItemType`, `Supplier`, `PurchaseOrder`) | Stage 12A/B | +| P2.4 | Multi-Channel Inventory Sync Engine (`InventorySyncEngine`, `ChannelStockMapping`) | Stage 12C | +| P2.5 | Wire `WooCommerceOrdersRepository` into `AppServices.wordpress()` | Stage 10E or standalone | +| P2.6 | Wire `WooCommerceInventoryRepository` into `AppServices.wordpress()` | Stage 10E or standalone | +| P2.7 | Unified Order View (`OrderChannel`, `UnifiedOrdersController`) | Stage 13B | +| P2.8 | Offline Data Cache & Sales Queue (SQLite `LocalCache`, `SyncQueue`) | Stage 14 | +| P2.9 | `feature_finance` Activation (sales reporting, inventory valuation) | Stage 15 | +| P2.10 | Populate Policy Register CSVs (2 active governance documents) | Immediate — no dependencies | + +#### Phase 3 — Defensive engineering, logging, and test harness expansion + +These items harden the platform for production deployment. + +| ID | Item | Target Stage | +| ----- | --------------------------------------------------------------------------------------- | ----------------- | +| P3.1 | Wire `RetryPolicy` and `RateLimiter` into `SquareApiClient` and `WooCommerceApiClient` | Stage 16A | +| P3.2 | Implement `SecureCredentialStore` (`flutter_secure_storage`) | Stage 16B | +| P3.3 | Auth guard wired into app shell (login screen, route guard) | Stage 16B | +| P3.4 | Structured logging infrastructure (`package:logging`, replace silent `catch (_) {}`) | Stage 16A | +| P3.5 | Crash reporting integration (Sentry or Firebase Crashlytics) | Stage 16A | +| P3.6 | Expand `feature_policy` test coverage (controller, widget tests; target >80%) | Standalone | +| P3.7 | Expand `kell_web` test coverage from 54.1% (routing, shell, factory tests; target >75%) | Standalone | +| P3.8 | Add `feature_orders` standard scaffolding files (`.gitignore`, `CHANGELOG.md`, etc.) | Standalone | +| P3.9 | Update architecture diagrams for Square and multi-channel | Stage 13 planning | +| P3.10 | Implement `ChannelAdapter` for WooCommerce and Square | Stage 13A | +| P3.11 | Enforce minimum test coverage thresholds in CI (e.g., 75% floor) | Standalone | +| P3.12 | Evaluate and activate `feature_mrp` after Stage 12 completion | Post-Stage 12 | + +### Key technical debt findings + +- **`AppServices`/`MobileAppServices` have no `square()` or `multi()` factory** — `KC_ENV=square` silently falls to fake mode (CRITICAL) +- **`SquareCatalogSyncService` ID conflation** — `product.id` used as Square catalog object ID; incorrect in mixed-source scenarios (HIGH) +- **`RetryPolicy`/`RateLimiter` defined but not wired** — all API calls are single-attempt with no retry or rate limiting (HIGH) +- **`auth` package not imported by any app or feature** — app is completely unguarded (HIGH) +- **`data` package not imported by any feature** — all data is in-memory only; no persistence path (MEDIUM) +- **`InventoryController` not wired to `InventorySyncService`** — sync cannot be triggered from UI (MEDIUM) +- **`feature_policy` has only a smoke test** — no controller or widget tests (MEDIUM) +- **`kell_web` at 54.1% line coverage** — routing, shell, and navigation largely untested (MEDIUM) --- @@ -1267,7 +1373,7 @@ For every branch/stage: Use this at the start of any new slice: -```text +```plaintext 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. @@ -1300,46 +1406,55 @@ Working rules: ## Appendix A: Feature maturity matrix -| Package | Domain Layer | Application Layer | Data (Fake) | Data (Real) | Presentation | Tests | Maturity | -| ------------------- | ------------ | ------------------ | ------------ | -------------- | -------------------------------------------------- | ------- | -------------------- | -| `feature_wordpress` | ✅ Complete | ✅ Complete | ✅ Complete | ✅ WooCommerce | ✅ Complete | 294 | **Production-ready** | -| `feature_inventory` | ⚠️ Read-only | ⚠️ Read-only | ⚠️ Read-only | ❌ None | ⚠️ Read-only | Minimal | **Fake-only MVP** | -| `feature_orders` | ⚠️ Read-only | ⚠️ Read-only | ⚠️ Read-only | ❌ None | ⚠️ Read-only | Some | **Fake-only MVP** | -| `feature_policy` | ✅ Complete | ✅ Complete | ✅ Complete | ❌ None | ✅ Complete | Minimal | **Fake-only MVP** | -| `feature_finance` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | ❌ Stub | None | **Scaffolded only** | -| `feature_mrp` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | ❌ Stub | None | **Scaffolded only** | -| `feature_social` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | ❌ Stub | None | **Scaffolded only** | -| `auth` | ✅ Complete | ✅ FakeAuthService | ✅ InMemory | ❌ None | N/A | 42 | **Foundation ready** | -| `data` | ✅ Contracts | N/A | ✅ InMemory | ❌ None | N/A | 63 | **Foundation ready** | -| `integrations` | ✅ Contracts | N/A | N/A | ✅ WooCommerce | N/A | 38 | **Foundation ready** | -| `design_system` | N/A | N/A | N/A | N/A | ✅ Expanded (theme, typography, layout, 7 widgets) | 41 | **Foundation ready** | -| `core` | ✅ Partial | ✅ Composition | N/A | N/A | N/A | 21 | **Foundation ready** | +> **Last updated:** 2026-07-25 — Comprehensive State Audit -### Key changes from previous matrix +| Package | Domain Layer | Application Layer | Data (Fake) | Data (Real) | Presentation | Tests | Maturity | +| ------------------- | ------------ | ------------------------ | ----------- | ------------------------- | -------------------------------------------------- | ----- | -------------------------- | +| `feature_wordpress` | ✅ Complete | ✅ Complete | ✅ Complete | ✅ WooCommerce + Square | ✅ Complete | 506 | **Production-ready (95%)** | +| `feature_inventory` | ✅ Complete | ✅ Write ops | ✅ Complete | ✅ WooCommerce + Square | ✅ Complete | 167 | **Partial (65%)** | +| `feature_orders` | ✅ Complete | ✅ Write ops | ✅ Complete | ✅ WooCommerce | ✅ Complete | 198 | **Partial (70%)** | +| `feature_policy` | ✅ Complete | ✅ Complete | ✅ Complete | ❌ None | ✅ Complete | ~5 | **Fake-only (50%)** | +| `feature_finance` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | ❌ Stub | 1 | **Scaffolded only (0%)** | +| `feature_mrp` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | ❌ Stub | 1 | **Scaffolded only (0%)** | +| `feature_social` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | ❌ Stub | 1 | **Scaffolded only (0%)** | +| `auth` | ✅ Complete | ✅ FakeAuthService | ✅ InMemory | ❌ None (SecureStore TBD) | N/A | 42 | **Foundation ready (40%)** | +| `data` | ✅ Contracts | N/A | ✅ InMemory | ❌ None (SQLite TBD) | N/A | 63 | **Foundation ready (35%)** | +| `integrations` | ✅ Contracts | N/A | N/A | ✅ WooCommerce + Square | N/A | 123 | **Partial (70%)** | +| `design_system` | N/A | N/A | N/A | N/A | ✅ Expanded (theme, typography, layout, 7 widgets) | 41 | **Complete (100%)** | +| `core` | ✅ Complete | ✅ Composition | N/A | N/A | N/A | 24 | **Complete (95%)** | +| `kell_web` | N/A | ✅ AppServices (wp only) | N/A | N/A | ✅ 7 routes (2 placeholder) | 24 | **Partial (75%)** | +| `kell_mobile` | N/A | ✅ MobileAppServices | N/A | N/A | ✅ 5-tab shell (no POS) | 26 | **Partial (70%)** | -- `feature_inventory` and `feature_orders` downgraded from "Complete" to "⚠️ Read-only" in domain/application/data/presentation to reflect that they have no write operations — a critical gap for the target platform vision. -- Feature maturity labels clarified: "Fake-only MVP" packages that are also read-only now carry the ⚠️ indicator. +### Key changes from previous matrix (updated 2026-07-25) + +- `feature_wordpress` test count updated to 506 (Stage 10D, pending merge); real data layer now includes Square repositories. +- `feature_inventory` and `feature_orders` upgraded from "Read-only" — write operations, real WooCommerce/Square repositories now complete. +- `integrations` test count updated to 123; Square API client and mappers complete. +- `core` test count updated to 24; `kell_web` and `kell_mobile` rows added. +- Completeness percentages sourced from `PROJECT_STATE_AUDIT.md` §5 scorecard (2026-07-25). --- ## Appendix B: Integration landscape -| Integration | Package/Location | Protocol | Current Status | Target Stage | -| -------------------- | ------------------- | ------------- | ------------------- | ------------ | -| WooCommerce Products | `feature_wordpress` | REST API v3 | ✅ Production-ready | — | -| WooCommerce Orders | `feature_orders` | REST API v3 | ✅ Production-ready | Stage 9A ✅ | -| WooCommerce Stock | `feature_wordpress` | REST API v3 | ❌ Not implemented | Stage 9B | -| WooCommerce Catalog | `feature_wordpress` | REST API v3 | ⚠️ Read + edit only | Stage 9C | -| WooCommerce Media | `feature_wordpress` | REST API v3 | ❌ Not implemented | Stage 9C | -| Square Catalog | (new) | Square API v2 | ❌ Not implemented | Stage 10A/B | -| Square Inventory | (new) | Square API v2 | ❌ Not implemented | Stage 10B | -| Square Payments | (new) | Mobile SDK | ❌ Not implemented | Stage 10C | -| Square Orders | (new) | Square API v2 | ❌ Not implemented | Stage 10A | -| Facebook API | `feature_social` | Graph API | ❌ Stub only | Deferred | -| Instagram API | `feature_social` | Graph API | ❌ Stub only | Deferred | -| X (Twitter) API | `feature_social` | REST API v2 | ❌ Stub only | Deferred | -| n8n Workflows | (external) | Webhooks/REST | ❌ Not implemented | Stage 13C | -| Mail Server | (external) | SMTP | ❌ Not implemented | Deferred | +> **Last updated:** 2026-07-25 — Comprehensive State Audit + +| Integration | Package/Location | Protocol | Current Status | Target Stage | +| -------------------- | ------------------- | ------------- | ------------------------------------------------------ | ---------------- | +| WooCommerce Products | `feature_wordpress` | REST API v3 | ✅ Production-ready (full CRUD + categories + images) | — | +| WooCommerce Orders | `feature_orders` | REST API v3 | ✅ Repository complete; not wired into AppServices | Stage 9A ✅ | +| WooCommerce Stock | `feature_inventory` | REST API v3 | ✅ Repository complete; not wired into AppServices | Stage 9B ✅ | +| WooCommerce Catalog | `feature_wordpress` | REST API v3 | ✅ Full CRUD + categories + images | Stage 9C ✅ | +| WooCommerce Media | `feature_wordpress` | REST API v3 | ⚠️ Use case wired; image picker UI deferred | Stage 10+ | +| Square Catalog | `feature_wordpress` | Square API v2 | ✅ Repository complete; no UI trigger (Stage 10E next) | Stage 10B ✅ | +| Square Inventory | `feature_inventory` | Square API v2 | ✅ Repository complete; not wired into AppServices | Stage 10B ✅ | +| Square Payments | `kell_mobile` | Mobile SDK | ❌ Not implemented | Stage 10C (P2.1) | +| Square Orders | `feature_orders` | Square API v2 | ❌ No SquareOrdersRepository exists | Stage 13B (P2.7) | +| Facebook API | `feature_social` | Graph API | ❌ Stub only | Deferred | +| Instagram API | `feature_social` | Graph API | ❌ Stub only | Deferred | +| X (Twitter) API | `feature_social` | REST API v2 | ❌ Stub only | Deferred | +| n8n Workflows | (external) | Webhooks/REST | ❌ Not implemented | Stage 13C | +| Mail Server | (external) | SMTP | ❌ Not implemented | Deferred | --- @@ -1354,28 +1469,28 @@ Working rules: | `KC_WC_CONSUMER_KEY` | WooCommerce REST API consumer key | (empty) | WP mode | | `KC_WC_CONSUMER_SECRET` | WooCommerce REST API consumer secret | (empty) | WP mode | -### Planned (Stage 8+) +### Active Square keys (Stage 10A — live on `main`) -| Key | Description | Default | Target Stage | -| ------------------------ | ------------------------- | --------- | ------------ | -| `KC_SQUARE_ACCESS_TOKEN` | Square API access token | (empty) | Stage 10A | -| `KC_SQUARE_LOCATION_ID` | Square location ID | (empty) | Stage 10A | -| `KC_SQUARE_ENVIRONMENT` | `sandbox` or `production` | `sandbox` | Stage 10A | +| Key | Description | Default | Used By | +| ------------------------ | ------------------------- | --------- | ----------- | +| `KC_SQUARE_ACCESS_TOKEN` | Square API access token | (empty) | Square mode | +| `KC_SQUARE_LOCATION_ID` | Square location ID | (empty) | Square mode | +| `KC_SQUARE_ENVIRONMENT` | `sandbox` or `production` | `sandbox` | Square mode | -### Planned `KC_ENV` values +### `KC_ENV` values -| Value | Description | Target Stage | -| ----------- | -------------------------------- | ------------ | -| `fake` | All fake repositories (current) | — | -| `wordpress` | WooCommerce real + others fake | — | -| `square` | Square real + others fake | Stage 10A | -| `multi` | Both WooCommerce and Square real | Stage 13A | +| Value | Description | Status | +| ----------- | -------------------------------- | ---------------------------------------------------------------- | +| `fake` | All fake repositories | ✅ Active | +| `wordpress` | WooCommerce real + others fake | ✅ Active | +| `square` | Square real + others fake | ⚠️ Keys defined (Stage 10A); factory constructors missing (P1.1) | +| `multi` | Both WooCommerce and Square real | ⚠️ Enum value defined; factory constructors missing (P1.1) | --- ## Appendix D: Stage dependency graph -``` +```plaintext Stages 1–6 (COMPLETE/IN PROGRESS) — Foundation │ ├── Stage 7 — Bulk actions (independent, can proceed in parallel)