added master development brief
Publish Docs / publish-docs (push) Successful in 1m3s
Details
Publish Docs / publish-docs (push) Successful in 1m3s
Details
This commit is contained in:
parent
ae9c1dd90c
commit
de44b02d76
|
|
@ -0,0 +1,453 @@
|
|||
# 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.
|
||||
|
||||
### Current narrow edit capabilities on `main`
|
||||
|
||||
- update product status through controlled workflow
|
||||
- update product price only
|
||||
- update product name only
|
||||
|
||||
### Latest known validation state on `main`
|
||||
|
||||
- `flutter analyze` clean
|
||||
- `feature_wordpress` tests passing
|
||||
- `kell_web` dashboard tests passing
|
||||
- latest reported count for `feature_wordpress`: `195/195 passed`
|
||||
- latest reported count for `kell_web` dashboard tests: `10/10 passed`
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
##### Goal
|
||||
|
||||
Allow updating product description only.
|
||||
|
||||
##### Requirements
|
||||
|
||||
- Inspect the existing price-only and name-only edit implementations first.
|
||||
- Mirror the narrow pattern for description update.
|
||||
- Add one repository method or equivalent narrow path only if needed.
|
||||
- Fake and WP repositories evolve in parallel.
|
||||
- Use existing controller result/feedback patterns.
|
||||
- Keep WooCommerce payload logic in WP repo only.
|
||||
- Do not expose any other editable fields.
|
||||
- Keep description editing plain and controlled.
|
||||
- Do not add a rich text editor.
|
||||
|
||||
##### Expected artifacts
|
||||
|
||||
- repository contract update
|
||||
- fake repo implementation
|
||||
- WP repo implementation
|
||||
- use case
|
||||
- controller action/result handling
|
||||
- preview panel inline description edit UI
|
||||
- targeted repo/controller/widget tests
|
||||
|
||||
##### Definition of done
|
||||
|
||||
- product description updates end-to-end in FAKE and WP modes
|
||||
- no generic update API introduced
|
||||
- tests/analyze clean
|
||||
|
||||
#### Stage 1B — Category-only product edit
|
||||
|
||||
##### Goal
|
||||
|
||||
Allow updating product category only.
|
||||
|
||||
##### Requirements
|
||||
|
||||
- Use existing category representation only.
|
||||
- Do not create full taxonomy management.
|
||||
- Keep write mapping narrow inside WP repository.
|
||||
- Use a simple constrained UI.
|
||||
- Reuse the established narrow single-field edit pattern.
|
||||
|
||||
##### Definition of done
|
||||
|
||||
- category can be updated through a controlled workflow
|
||||
- no taxonomy subsystem added
|
||||
- tests/analyze clean
|
||||
|
||||
---
|
||||
|
||||
### 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
|
||||
|
||||
##### Goal
|
||||
|
||||
Make list/detail behavior predictable after edits and status changes.
|
||||
|
||||
##### Requirements
|
||||
|
||||
- preserve selection after update where sensible
|
||||
- maintain search/filter/sort persistence after writes
|
||||
- handle item repositioning under active sort cleanly
|
||||
- ensure latest values refresh correctly
|
||||
- verify last-modified updates behave consistently
|
||||
|
||||
##### Definition of done
|
||||
|
||||
- post-action behavior feels stable and predictable
|
||||
- focused tests cover persistence and repositioning
|
||||
|
||||
#### Stage 2B — Publishing workflow UX hardening
|
||||
|
||||
##### Goal
|
||||
|
||||
Tighten the publishing workflow without broadening scope.
|
||||
|
||||
##### Requirements
|
||||
|
||||
- refine success/failure wording if needed
|
||||
- improve inline validation messaging for single-field edits
|
||||
- ensure disabled/loading states are consistent
|
||||
- ensure page-level load errors remain separate from row-level action errors
|
||||
|
||||
##### Definition of done
|
||||
|
||||
- status/edit actions feel reliable and operator-friendly
|
||||
- no architecture broadening
|
||||
|
||||
---
|
||||
|
||||
### 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)
|
||||
|
||||
##### Goal
|
||||
|
||||
Prepare for future bulk actions without implementing bulk writes yet.
|
||||
|
||||
##### Requirements
|
||||
|
||||
- add selection model for multiple items
|
||||
- show selected-count UI
|
||||
- allow clear selection
|
||||
- preserve current single-item preview behavior where appropriate
|
||||
- do not add bulk publish/edit/delete actions yet
|
||||
|
||||
##### Definition of done
|
||||
|
||||
- multi-select state exists and is tested
|
||||
- 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.
|
||||
```
|
||||
Loading…
Reference in New Issue