Compare commits
No commits in common. "b4d2c44d10252ed908811f73cd5920d456502af9" and "70607d36f4f025016a06f5b2f35ddf327513392d" have entirely different histories.
b4d2c44d10
...
70607d36f4
|
|
@ -1,694 +0,0 @@
|
|||
# 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<T>` | ✅ Complete |
|
||||
| `KcBootstrap` | ✅ Complete |
|
||||
| `KcAppScope<T>` 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<T>` contract + `InMemoryCache<T>` | ✅ Complete |
|
||||
| `SyncQueue` contract + `InMemorySyncQueue` | ✅ Complete |
|
||||
| `ConflictResolver<T>` + 3 concrete implementations | ✅ Complete |
|
||||
| `ChangeTracker<T>` + `InMemoryChangeTracker<T>` | ✅ Complete |
|
||||
| `DataMapper<TLocal, TRemote>` contract | ✅ Complete |
|
||||
| SQLite-backed `LocalCache<T>` 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<T>` 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.*
|
||||
|
|
@ -2,12 +2,9 @@
|
|||
|
||||
## Current status
|
||||
|
||||
- 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
|
||||
- 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
|
||||
|
||||
## Slice tracker
|
||||
|
||||
|
|
@ -610,29 +607,6 @@
|
|||
- 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
|
||||
|
|
|
|||
|
|
@ -139,25 +139,26 @@ Rules:
|
|||
|
||||
### Latest known validation state on `main`
|
||||
|
||||
> **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`
|
||||
- `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`
|
||||
- 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`: `506/506 passed` ← +31 new (Stage 10D, pending merge)
|
||||
- latest reported count for `feature_wordpress`: `475/475 passed` ← +51 new (Stage 10C)
|
||||
- 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: `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)
|
||||
- total: `1015/1015 passed` (Stage 10C baseline: 957 + 58 Stage 10B + 86 Stage 10C new tests)
|
||||
- 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 |
|
||||
|
|
@ -188,125 +189,18 @@ Delivered:
|
|||
|
||||
### Next recommended branch
|
||||
|
||||
> **⚠️ 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`.
|
||||
**`feat/square-catalog-sync-service-controller`** — Stage 10E: `SquareSyncController` Riverpod provider.
|
||||
|
||||
**`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:
|
||||
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:
|
||||
|
||||
- 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 `AppServices` and `MobileAppServices` so the sync can be triggered from the UI
|
||||
- Wires into `MobileAppServices` (or `WebAppServices`) so the sync can be triggered from the UI
|
||||
|
||||
**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)
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -1373,7 +1267,7 @@ For every branch/stage:
|
|||
|
||||
Use this at the start of any new slice:
|
||||
|
||||
```plaintext
|
||||
```text
|
||||
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.
|
||||
|
|
@ -1406,50 +1300,41 @@ Working rules:
|
|||
|
||||
## Appendix A: Feature maturity matrix
|
||||
|
||||
> **Last updated:** 2026-07-25 — Comprehensive State Audit
|
||||
|
||||
| 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_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** |
|
||||
|
||||
### Key changes from previous matrix (updated 2026-07-25)
|
||||
### Key changes from previous matrix
|
||||
|
||||
- `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).
|
||||
- `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.
|
||||
|
||||
---
|
||||
|
||||
## Appendix B: Integration landscape
|
||||
|
||||
> **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) |
|
||||
| -------------------- | ------------------- | ------------- | ------------------- | ------------ |
|
||||
| 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 |
|
||||
|
|
@ -1469,28 +1354,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 |
|
||||
|
||||
### Active Square keys (Stage 10A — live on `main`)
|
||||
### Planned (Stage 8+)
|
||||
|
||||
| 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 |
|
||||
| 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 |
|
||||
|
||||
### `KC_ENV` values
|
||||
### Planned `KC_ENV` values
|
||||
|
||||
| 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) |
|
||||
| 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 |
|
||||
|
||||
---
|
||||
|
||||
## Appendix D: Stage dependency graph
|
||||
|
||||
```plaintext
|
||||
```
|
||||
Stages 1–6 (COMPLETE/IN PROGRESS) — Foundation
|
||||
│
|
||||
├── Stage 7 — Bulk actions (independent, can proceed in parallel)
|
||||
|
|
|
|||
Loading…
Reference in New Issue