382 lines
12 KiB
Markdown
382 lines
12 KiB
Markdown
# Kell Creations Operations Platform — Master Development Brief
|
|
|
|
## Recommended repo location
|
|
|
|
Place this document in the repository at:
|
|
|
|
`docs/development/master_development_brief.md`
|
|
|
|
Why this location:
|
|
|
|
- keeps it versioned with the code
|
|
- makes it easy for Cline to read and update
|
|
- separates implementation planning from feature code
|
|
- works for both web and Android roadmap tracking
|
|
|
|
If `docs/development/` does not exist yet, create it.
|
|
|
|
---
|
|
|
|
## Purpose
|
|
|
|
This document is the master implementation brief for continuing development of the Kell Creations Flutter operations platform across **web** and **Android**. It is intended for use by Cline in Windows 11 VS Code.
|
|
|
|
This brief should be treated as the working source of truth for planned development after the current completed slices already landed on `main`.
|
|
|
|
---
|
|
|
|
## Working model
|
|
|
|
Development must proceed in **small, reviewable vertical slices**.
|
|
|
|
Rules:
|
|
|
|
- Branch from current `main` for each stage or sub-slice.
|
|
- Implement on a feature branch.
|
|
- Validate locally.
|
|
- Open a PR into `main`.
|
|
- Merge only after tests/analyze are clean.
|
|
- Do not stack broad unfinished work directly on `main`.
|
|
- After each merged slice, update this brief so it remains aligned to `main`.
|
|
|
|
---
|
|
|
|
## Current confirmed baseline on `main`
|
|
|
|
### Platform structure
|
|
|
|
- `apps/kell_web` exists.
|
|
- Shared packages include:
|
|
- `core`
|
|
- `design_system`
|
|
- `feature_inventory`
|
|
- `feature_wordpress`
|
|
- `feature_orders`
|
|
- `feature_policy`
|
|
- App shell, routing, dashboard, reusable shell widgets, `AppServices`, and `AppScope` are implemented.
|
|
- Dashboard uses app-composed repository data.
|
|
- Vertical slices exist for Inventory, Products/Publishing, Orders, and Policy/Governance.
|
|
- Cross-feature navigation handoffs and shared filtering/search/selection persistence are implemented.
|
|
- Runtime bootstrap uses:
|
|
- `KC_ENV`
|
|
- `KC_WC_SITE_URL`
|
|
- `KC_WC_CONSUMER_KEY`
|
|
- `KC_WC_CONSUMER_SECRET`
|
|
- App supports `FAKE` and `WP` modes with visible shell badge.
|
|
|
|
### Product publishing workflow already landed on `main`
|
|
|
|
- Controlled WooCommerce publish action landed.
|
|
- `ProductDraft.copyWith` landed.
|
|
- `unpublished -> draft` UI exposure landed.
|
|
- `pendingReview -> draft` UI exposure landed.
|
|
- `unpublished` semantics clarified as a read-only abstraction.
|
|
- Status action success/failure feedback landed.
|
|
- Publishing page polish landed.
|
|
- Richer read-side detail preview landed.
|
|
- Price-only product edit landed.
|
|
- Search/filter/sort refinement landed.
|
|
- Name-only product edit landed.
|
|
- ✅ Description-only product edit landed (Stage 1A complete — merged `feat/description-only-edit` → `main` at `cebac4c`, 2026-04-11).
|
|
- ✅ Category-only product edit landed (Stage 1B complete — merged `feat/category-only-edit` → `main` at `8e7e4cb`, 2026-04-11). Stage 1 complete.
|
|
- ✅ Post-write consistency hardening landed (Stage 2A complete — merged `feat/post-write-consistency` → `main` at `7acff83`, 2026-04-11).
|
|
- ✅ Publishing workflow UX hardening landed (Stage 2B complete — merged `feat/publishing-ux-hardening` → `main` at `b81016d`, 2026-04-11). Stage 2 complete.
|
|
- ✅ Multi-select groundwork landed (Stage 3A complete — merged `feat/multi-select-groundwork` → `main`, 2026-05-22).
|
|
|
|
### Current narrow edit capabilities on `main`
|
|
|
|
- update product status through controlled workflow
|
|
- update product price only
|
|
- update product name only
|
|
- update product description only
|
|
- update product category only
|
|
|
|
### Latest known validation state on `main`
|
|
|
|
- `dart analyze` clean
|
|
- `feature_wordpress` tests passing
|
|
- `kell_web` dashboard tests passing
|
|
- latest reported count for `feature_wordpress`: `262/262 passed`
|
|
- latest reported count for `kell_web` dashboard tests: `5/5 passed`
|
|
- baseline commit: merge of `feat/multi-select-groundwork` (2026-05-22)
|
|
|
|
### Next recommended branch
|
|
|
|
**`feat/list-efficiency-improvements`** — Stage 3B: List efficiency improvements.
|
|
Branch from latest `main`. Stage 3A (multi-select groundwork) is complete.
|
|
|
|
---
|
|
|
|
## Non-negotiable architectural constraints
|
|
|
|
These must be preserved in all future work:
|
|
|
|
- Preserve **strict package boundaries**.
|
|
- Fake repositories remain in feature packages.
|
|
- Real integrations are incremental alongside fake ones.
|
|
- Runtime selection stays via `--dart-define`, not a settings UI.
|
|
- No credentials hardcoded or committed.
|
|
- Do **not** broaden into generic product editing prematurely.
|
|
- Keep WooCommerce details inside the WP repository layer.
|
|
- Keep diffs small and reviewable.
|
|
- Prefer inspection-first development.
|
|
- Android support should reuse shared feature/domain/application layers rather than fork logic.
|
|
|
|
---
|
|
|
|
## Development stages
|
|
|
|
### Stage 1 — Web application completion: controlled product editing
|
|
|
|
#### Objective
|
|
|
|
Extend the publishing workflow with additional **single-field** edit capabilities using the same narrow pattern already established by price-only and name-only update.
|
|
|
|
#### Branching model
|
|
|
|
Use one branch per edit slice:
|
|
|
|
- `feat/description-only-edit`
|
|
- `feat/category-only-edit`
|
|
|
|
#### ~~Stage 1A — Description-only product edit~~ ✅ COMPLETE
|
|
|
|
> Merged `feat/description-only-edit` → `main` at `cebac4c` (2026-04-11).
|
|
> All artifacts delivered: repository contract, fake/WP repo implementations, use case, controller action/result handling, preview panel inline description edit UI, and targeted tests (212 total `feature_wordpress` tests passing).
|
|
|
|
#### ~~Stage 1B — Category-only product edit~~ ✅ COMPLETE
|
|
|
|
> Merged `feat/category-only-edit` → `main` at `8e7e4cb` (2026-04-11).
|
|
> All artifacts delivered: repository contract, fake/WP repo implementations, use case, controller action/result handling, preview panel inline category edit UI, snack bar feedback, and targeted tests (223 total `feature_wordpress` tests passing). Stage 1 complete.
|
|
|
|
---
|
|
|
|
### Stage 2 — Web application operational hardening
|
|
|
|
#### Objective
|
|
|
|
Improve operator consistency, predictability, and usability after writes.
|
|
|
|
#### Branches
|
|
|
|
- `feat/post-write-consistency`
|
|
- `feat/publishing-ux-hardening`
|
|
|
|
#### ~~Stage 2A — Post-write consistency hardening~~ ✅ COMPLETE
|
|
|
|
> Merged `feat/post-write-consistency` → `main` at `7acff83` (2026-04-11).
|
|
> Added `_refreshSelection()` to `ProductPublishingController` to preserve/refresh selection after all write-triggered reloads. 11 new post-write consistency tests added (234 total `feature_wordpress` tests passing).
|
|
|
|
#### ~~Stage 2B — Publishing workflow UX hardening~~ ✅ COMPLETE
|
|
|
|
> Merged `feat/publishing-ux-hardening` → `main` at `b81016d` (2026-04-11).
|
|
> Added inline validation error messages for all four single-field edits (name, price, description, category), disabled text fields and save buttons during `isUpdating`, and appended error detail to failure snack bars. 13 new tests added (247 total `feature_wordpress` tests passing). Stage 2 complete.
|
|
|
|
---
|
|
|
|
### Stage 3 — Web application operator efficiency
|
|
|
|
#### Objective
|
|
|
|
Increase throughput for product triage and management using existing data.
|
|
|
|
#### Branches
|
|
|
|
- `feat/multi-select-groundwork`
|
|
- `feat/list-efficiency-improvements`
|
|
|
|
#### ~~Stage 3A — Multi-select groundwork (read/state only first)~~ ✅ COMPLETE
|
|
|
|
> Merged `feat/multi-select-groundwork` → `main` (2026-05-22).
|
|
> Added multi-selection state to `ProductPublishingController` (`toggleMultiSelect`, `clearMultiSelection`, `selectAllVisible`, `isMultiSelected`, `multiSelectedIds`, `multiSelectedCount`). Updated `ProductDraftCard` with optional leading checkbox for multi-select mode. Added `_MultiSelectBar` to `ProductPublishingPage` with selected-count display, Select All, and Clear actions. Single-item preview selection preserved independently. 15 new multi-select tests added (262 total `feature_wordpress` tests passing). No bulk writes introduced.
|
|
|
|
#### Stage 3B — List efficiency improvements
|
|
|
|
##### Goal
|
|
|
|
Further improve operator productivity.
|
|
|
|
##### Candidate scope
|
|
|
|
- denser list/card presentation if justified
|
|
- quick visual indicators for stale products
|
|
- lightweight secondary metadata visibility
|
|
- improved keyboard/focus handling on web if easy to support
|
|
|
|
##### Definition of done
|
|
|
|
- measurable usability improvement using existing data only
|
|
|
|
---
|
|
|
|
### Stage 4 — Android application foundation
|
|
|
|
#### Objective
|
|
|
|
Bring the current operations platform capabilities to Android using shared packages first and platform-specific UI only where required.
|
|
|
|
#### Key principle
|
|
|
|
Business logic, domain logic, repositories, and feature application logic should remain shared. Android should primarily add a dedicated app shell and mobile-optimized presentation.
|
|
|
|
#### Branches
|
|
|
|
- `feat/android-app-shell`
|
|
- `feat/android-publishing-surface`
|
|
|
|
#### Stage 4A — Android app shell and bootstrap
|
|
|
|
##### Goal
|
|
|
|
Create the Android app entry and shell for the existing platform.
|
|
|
|
##### Requirements
|
|
|
|
- add or adapt app target for Android
|
|
- reuse shared packages and feature modules
|
|
- preserve runtime environment selection model
|
|
- ensure FAKE mode works cleanly on Android first
|
|
- mobile shell/navigation should stay simple and consistent with shared app structure
|
|
|
|
##### Definition of done
|
|
|
|
- app runs on Android emulator/device in FAKE mode
|
|
- shell, navigation, and core screens render
|
|
- analyze/tests remain clean
|
|
|
|
#### Stage 4B — Android publishing surface
|
|
|
|
##### Goal
|
|
|
|
Adapt the publishing workflow for mobile form factor.
|
|
|
|
##### Requirements
|
|
|
|
- reuse shared controller/use case/repository layers
|
|
- optimize preview/edit interactions for smaller screens
|
|
- keep feature parity for current publishing workflow where feasible
|
|
- do not fork business rules for Android
|
|
|
|
##### Definition of done
|
|
|
|
- Android supports browsing, filtering, status changes, and existing narrow edits
|
|
- mobile presentation is usable and tested where practical
|
|
|
|
---
|
|
|
|
### Stage 5 — Android operational maturity
|
|
|
|
#### Objective
|
|
|
|
Harden Android UX after the core feature surface works.
|
|
|
|
#### Branches
|
|
|
|
- `feat/android-feedback-polish`
|
|
- `feat/android-mobile-ux-hardening`
|
|
|
|
#### Stage 5A — Android feedback and action polish
|
|
|
|
##### Goal
|
|
|
|
Ensure action feedback patterns translate cleanly to Android.
|
|
|
|
##### Requirements
|
|
|
|
- reuse shared action result model where possible
|
|
- adapt SnackBar/feedback timing and presentation appropriately
|
|
- validate status/edit workflows on mobile
|
|
|
|
#### Stage 5B — Android mobile workflow hardening
|
|
|
|
##### Goal
|
|
|
|
Improve ergonomics on smaller screens.
|
|
|
|
##### Requirements
|
|
|
|
- verify scrolling/selection/edit flows
|
|
- ensure touch targets and inline edit behavior are mobile-friendly
|
|
- refine layout without changing shared domain/application contracts
|
|
|
|
---
|
|
|
|
### Stage 6 — Controlled bulk actions (only after groundwork)
|
|
|
|
#### Objective
|
|
|
|
Add carefully scoped bulk operations once single-item workflows are stable across web and Android.
|
|
|
|
#### Branches
|
|
|
|
- `feat/bulk-status-actions`
|
|
- `feat/bulk-operator-workflows`
|
|
|
|
#### Entry criteria
|
|
|
|
Do not begin until:
|
|
|
|
- single-item edit/status flows are stable
|
|
- multi-select groundwork is complete
|
|
- post-write consistency is hardened
|
|
- Android core publishing surface exists
|
|
|
|
#### Candidate first bulk action
|
|
|
|
- bulk move to draft
|
|
|
|
#### Explicitly defer
|
|
|
|
- bulk generic edit
|
|
- bulk category management
|
|
- destructive bulk deletion unless separately justified
|
|
|
|
---
|
|
|
|
## Required development workflow for every slice
|
|
|
|
For every branch/stage:
|
|
|
|
1. Start from latest `main`.
|
|
2. Inspect first.
|
|
3. Write a brief inspection report.
|
|
4. Propose the smallest implementation plan.
|
|
5. Implement only the current slice.
|
|
6. Run targeted tests.
|
|
7. Run `flutter analyze` or `dart analyze` as appropriate.
|
|
8. Summarize changed files and validation results.
|
|
9. Open PR into `main`.
|
|
10. Merge only after clean review and validation.
|
|
|
|
---
|
|
|
|
## Standard Cline operating prompt
|
|
|
|
Use this at the start of any new slice:
|
|
|
|
```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.
|
|
|
|
Constraints:
|
|
- Preserve strict package boundaries.
|
|
- Fake repositories remain in feature packages.
|
|
- Real integrations are incremental alongside fake ones.
|
|
- Runtime selection stays via --dart-define, not settings UI.
|
|
- No credentials hardcoded or committed.
|
|
- Do not broaden into generic product editing prematurely.
|
|
- Keep WooCommerce details inside the WP repository layer.
|
|
- Use small, reviewable steps only.
|
|
- Work is being driven through Cline in Windows 11 VS Code.
|
|
|
|
Working rules:
|
|
1. Inspect first. Do not edit immediately.
|
|
2. Summarize current relevant state from main.
|
|
3. Propose the smallest implementation plan for the requested slice.
|
|
4. Implement only that slice.
|
|
5. Add/update focused tests.
|
|
6. Run validation.
|
|
7. Report changed files and validation results.
|
|
```
|