# 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.