114 lines
5.8 KiB
Markdown
114 lines
5.8 KiB
Markdown
# Kifi V2 Phase 1 - Inventory Management Complete Implementation Plan
|
|
|
|
This document outlines the complete architecture and task breakdown required to finish Phase 1 (Inventory Management), incorporating all feedback including full UOM CRUD, GST taxation logic, and Bill of Materials (BOM).
|
|
|
|
## User Review Required
|
|
|
|
> [!IMPORTANT]
|
|
> **Stock Movements vs. Direct Edits**
|
|
> Moving forward, users will *not* directly edit the `quantity` of a product in the "Edit Product" screen. All stock adjustments will go through the new **Inventory Movements** mechanism (Add, Reduce, Adjust) to ensure a historically accurate Stock Ledger.
|
|
>
|
|
> **Bill of Materials (BOM) Consumption:**
|
|
> When a BOM/Bundle product is sold or assembled, the system must automatically deduct the stock of its underlying raw materials. We will implement "Assembly Movements" to handle this cleanly.
|
|
|
|
---
|
|
|
|
## 1. Product Detail & Ledger (Presentation Layer)
|
|
A read-only rich product view that replaces the immediate navigation to the Edit screen.
|
|
|
|
#### [NEW] `lib/features/inventory/presentation/product_detail_screen.dart`
|
|
- **Purpose:** Display a rich overview of the product.
|
|
- **Sections:**
|
|
- Header: Image carousel, Name, SKU, Status.
|
|
- Stock Summary: Available stock vs. Reserved stock.
|
|
- Pricing & Taxes: Purchase vs Selling price, GST configuration.
|
|
- Action Bar: "Adjust Stock", "Edit Product", "Share".
|
|
|
|
#### [NEW] `lib/features/inventory/presentation/stock_ledger_tab.dart`
|
|
- **Purpose:** A chronological list of all movements in and out of the warehouse for a given product.
|
|
- **Data:** Display Date, Reference (e.g. "Opening", "Adjustment"), In/Out arrows, and Running Balance.
|
|
|
|
---
|
|
|
|
## 2. Inventory Movements (Domain & API Layer)
|
|
The core backend and frontend logic for tracking stock changes robustly.
|
|
|
|
#### [NEW] `lib/features/inventory/domain/stock_movement.dart`
|
|
- **Purpose:** Data model representing an atomic inventory transaction.
|
|
- **Fields:** `id`, `productId`, `type` (OPENING, ADDITION, REDUCTION, ADJUSTMENT, DAMAGE, ASSEMBLY), `quantity`, `balanceAfter`, `date`, `notes`.
|
|
|
|
#### [MODIFY] `lib/features/inventory/providers/products_provider.dart`
|
|
- **Changes:** Add methods for `adjustStock(productId, type, quantity, notes)` and `fetchStockLedger(productId)`.
|
|
|
|
#### [NEW] `kifi-api/src/main/java/com/kifi/api/entity/inventory/StockMovement.java` (Backend)
|
|
- **Purpose:** The PostgreSQL entity for tracking historical stock changes.
|
|
|
|
---
|
|
|
|
## 3. Bill of Materials (BOM) / Bundle of Materials
|
|
Allowing products to be composed of other raw materials or sub-products.
|
|
|
|
#### [NEW] `kifi-api/src/main/java/com/kifi/api/entity/inventory/ProductBomItem.java`
|
|
- **Purpose:** Backend entity mapping a parent product to its component products with required quantities.
|
|
- **Fields:** `id`, `parentProductId`, `componentProductId`, `quantityRequired`.
|
|
|
|
#### [NEW] `lib/features/inventory/domain/bom_item.dart`
|
|
- **Purpose:** Frontend model for BOM components.
|
|
|
|
#### [NEW] `lib/features/inventory/presentation/bom/manage_bom_screen.dart`
|
|
- **Purpose:** UI for a user to select a product and add component products to it to define its recipe/bundle.
|
|
- **Functionality:** Search products, specify quantities, and save the BOM structure.
|
|
|
|
---
|
|
|
|
## 4. Business Profile & GST Configuration
|
|
The context wrapper for the Business Mode, heavily incorporating Indian GST logic.
|
|
|
|
#### [NEW] `lib/features/business/presentation/settings/business_profile_screen.dart`
|
|
- **Purpose:** UI to capture Business Registration, Industry Type, Tax Numbers (GSTIN), and Business Logo.
|
|
- **GST Logic Implementation:**
|
|
- Store the business's Home State.
|
|
- When calculating taxes on transactions/invoices, compare the customer's state with the business's state.
|
|
- **Intra-state:** Split total GST equally into SGST (9%) and CGST (9%).
|
|
- **Inter-state:** Apply full tax to IGST (18%).
|
|
|
|
#### [NEW] `lib/features/business/domain/tax_calculator.dart`
|
|
- **Purpose:** A utility to handle the SGST/CGST vs IGST split logic cleanly based on state codes.
|
|
|
|
#### [MODIFY] `lib/features/business/providers/business_provider.dart`
|
|
- **Changes:** Cache the active `BusinessProfile` object to make the Home State instantly available for tax calculations.
|
|
|
|
---
|
|
|
|
## 5. Units of Measure (UOM) Management (Full CRUD)
|
|
Master data UI for inventory sizing, completely managed by the user.
|
|
|
|
#### [NEW] `lib/features/inventory/presentation/uom/uom_list_screen.dart`
|
|
- **Purpose:** View all existing UOMs.
|
|
|
|
#### [NEW] `lib/features/inventory/presentation/uom/add_edit_uom_screen.dart`
|
|
- **Purpose:** Full CRUD capabilities. Users can create custom units (e.g., "Box", "Kg", "Dozen"), update their names, or delete them (if not linked to existing products).
|
|
|
|
#### [NEW] `lib/features/inventory/providers/uom_provider.dart`
|
|
- **Purpose:** Manage the state of UOMs (create, update, delete, fetch).
|
|
|
|
---
|
|
|
|
## 6. Inventory Dashboard & Alerts
|
|
Bringing the data to life on the Business Hub.
|
|
|
|
#### [MODIFY] `lib/features/business/presentation/hub/business_hub_screen.dart`
|
|
- **Changes:** Replace static placeholders with real widgets powered by providers:
|
|
- **Total Value Card:** Aggregated `quantity * purchasePrice`.
|
|
- **Low Stock Widget:** List of products where `currentStock <= minStock`.
|
|
|
|
---
|
|
|
|
## Verification Plan
|
|
|
|
### Manual Verification
|
|
1. **Product Detail & Movements:** Create a product, perform an "Add Stock" adjustment of 10, then a "Reduce Stock" of 2. Verify the stock ledger shows accurate running balances (10, then 8).
|
|
2. **UOM CRUD:** Create a new custom UOM ("Pallet"), verify it appears in the dropdown when creating a product, then edit its name.
|
|
3. **BOM Logic:** Create raw materials A and B. Create Final Product C with a BOM of 1xA + 2xB. Assemble 1 unit of Product C and verify A's stock reduces by 1 and B's stock reduces by 2.
|
|
4. **GST Logic:** Set Business State to "Maharashtra". Create a mock sale to "Maharashtra" and verify SGST/CGST split. Create a mock sale to "Delhi" and verify IGST mapping.
|