docs(widgets): Add comprehensive request examples and improve API documentation

- Create WIDGET_REQUEST_EXAMPLES.md with detailed request/response examples for all widget endpoints
- Add JSON request body examples for chart, table, and KPI widgets
- Include cURL examples for testing widget endpoints
- Document common parameters and their usage across widget types
- Add Body() examples to chart_widget_router.py endpoints for better API documentation
- Create add_request_examples.py script for automated documentation generation
- Improve developer experience with clear endpoint usage patterns and parameter descriptions

WIDGET_REQUEST_EXAMPLES.md

@@ -0,0 +1,298 @@
+# Widget Request Body Examples
+
+This document provides request body examples for all widget endpoints.
+
+## Chart Widgets
+
+### 1. Revenue Trend (12 Months)
+**Endpoint:** `POST /api/v1/charts/revenue-trend`
+
+```json
+{
+  "widget_id": "wid_revenue_trend_12m_001",
+  "chart_type": "line",
+  "months": 12,
+  "period_window": "last_12_months"
+}
+```
+
+### 2. Gross Margin Trend (12 Months)
+**Endpoint:** `POST /api/v1/charts/gross-margin-trend`
+
+```json
+{
+  "widget_id": "wid_gross_margin_trend_12m_001",
+  "chart_type": "line",
+  "months": 12,
+  "period_window": "last_12_months"
+}
+```
+
+### 3. Channel Mix
+**Endpoint:** `POST /api/v1/charts/channel-mix`
+
+```json
+{
+  "widget_id": "wid_channel_mix_001",
+  "chart_type": "donut",
+  "period_window": "last_12_months"
+}
+```
+
+### 4. Top 5 SKUs
+**Endpoint:** `POST /api/v1/charts/top-skus`
+
+```json
+{
+  "widget_id": "wid_top_5_skus_001",
+  "chart_type": "bar",
+  "limit": 5,
+  "period_window": "last_12_months"
+}
+```
+
+### 5. Inventory Status
+**Endpoint:** `POST /api/v1/charts/inventory-status`
+
+```json
+{
+  "widget_id": "wid_inventory_status_001",
+  "chart_type": "donut"
+}
+```
+
+### 6. Top Selling Products (30 Days)
+**Endpoint:** `POST /api/v1/charts/top-selling-products`
+
+```json
+{
+  "widget_id": "wid_top_selling_products_30d_001",
+  "chart_type": "bar",
+  "window_days": 30,
+  "limit": 10
+}
+```
+
+### 7. Staff Performance
+**Endpoint:** `POST /api/v1/charts/staff-performance`
+
+```json
+{
+  "widget_id": "wid_staff_performance_001",
+  "chart_type": "bar",
+  "window_days": 30,
+  "limit": 10
+}
+```
+
+### 8. My Sales Trend (30 Days)
+**Endpoint:** `POST /api/v1/charts/my-sales-trend`
+
+```json
+{
+  "widget_id": "wid_personal_sales_trend_30d_001",
+  "chart_type": "line",
+  "window_days": 30
+}
+```
+
+### 9. Top Products Sold by Me
+**Endpoint:** `POST /api/v1/charts/my-top-products`
+
+```json
+{
+  "widget_id": "wid_top_products_sold_by_me_001",
+  "chart_type": "bar",
+  "window_days": 30,
+  "limit": 5
+}
+```
+
+### Universal Chart Endpoint
+**Endpoint:** `POST /api/v1/charts/widget`
+
+Can use any of the above widget_ids. Example:
+
+```json
+{
+  "widget_id": "wid_revenue_trend_12m_001",
+  "chart_type": "line",
+  "months": 12,
+  "period_window": "last_12_months"
+}
+```
+
+## Table Widgets
+
+### Universal Table Endpoint
+**Endpoint:** `POST /api/v1/tables/widget`
+
+### 1. Recent Orders
+```json
+{
+  "widget_id": "wid_recent_orders_001",
+  "limit": 10,
+  "offset": 0
+}
+```
+
+### 2. Pending Orders
+```json
+{
+  "widget_id": "wid_pending_orders_001",
+  "limit": 10,
+  "offset": 0
+}
+```
+
+### 3. Low Stock Items
+```json
+{
+  "widget_id": "wid_low_stock_items_001",
+  "limit": 10,
+  "offset": 0
+}
+```
+
+### 4. Top Customers (30 Days)
+```json
+{
+  "widget_id": "wid_top_customers_30d_001",
+  "window_days": 30,
+  "limit": 10,
+  "offset": 0
+}
+```
+
+### 5. Refunded/Cancelled Orders
+```json
+{
+  "widget_id": "wid_top_refunded_orders_001",
+  "limit": 10,
+  "offset": 0
+}
+```
+
+### 6. Expiring Stock (Next 30 Days)
+```json
+{
+  "widget_id": "wid_expiring_stock_001",
+  "expiry_within_days": 30,
+  "limit": 10,
+  "offset": 0
+}
+```
+
+### 7. Products Needing Reorder
+```json
+{
+  "widget_id": "wid_product_reorder_list_001",
+  "limit": 10,
+  "offset": 0
+}
+```
+
+## KPI Widgets
+
+### Get All KPIs
+**Endpoint:** `POST /api/v1/kpi/stats`
+
+```json
+{
+  "period_window": "mtd"
+}
+```
+
+Options for `period_window`:
+- `"mtd"` - Month to Date
+- `"qtd"` - Quarter to Date
+- `"ytd"` - Year to Date
+
+### Get Individual KPI
+**Endpoint:** `POST /api/v1/kpi/stats/individual/{kpi_id}`
+
+```json
+{
+  "period_window": "mtd"
+}
+```
+
+Available KPI IDs:
+- `total_revenue` (widget: wid_total_revenue_001)
+- `gross_margin_pct` (widget: wid_gross_margin_pct_001)
+- `orders_count` (widget: wid_orders_count_001)
+- `aov` (widget: wid_aov_001)
+- `repeat_rate` (widget: wid_repeat_rate_001)
+- `refund_rate` (widget: wid_refund_rate_001)
+
+## Common Parameters
+
+### Chart Widget Parameters
+- `widget_id` (required): Unique widget identifier
+- `chart_type` (optional): "line", "bar", "donut", "pie", "area"
+- `period_window` (optional): "last_30_days", "last_12_months", "mtd", "qtd", "ytd"
+- `months` (optional): Number of months for trend charts (default: 12)
+- `window_days` (optional): Number of days for window-based charts (default: 30)
+- `limit` (optional): Limit for top N results (default: 5)
+- `branch_id` (optional): Filter by specific branch
+
+### Table Widget Parameters
+- `widget_id` (required): Unique widget identifier
+- `limit` (optional): Number of records to return (default: 10)
+- `offset` (optional): Pagination offset (default: 0)
+- `sort` (optional): Sort field
+- `order` (optional): "asc" or "desc"
+- `window_days` (optional): Number of days for time-based filters
+- `expiry_within_days` (optional): Days until expiry for stock widgets
+- `branch_id` (optional): Filter by specific branch
+
+### KPI Parameters
+- `period_window` (required): "mtd", "qtd", or "ytd"
+
+## cURL Examples
+
+### Chart Widget
+```bash
+curl -X 'POST' \
+  'http://localhost:9100/api/v1/charts/revenue-trend?use_cache=true' \
+  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "widget_id": "wid_revenue_trend_12m_001",
+    "chart_type": "line",
+    "months": 12,
+    "period_window": "last_12_months"
+  }'
+```
+
+### Table Widget
+```bash
+curl -X 'POST' \
+  'http://localhost:9100/api/v1/tables/widget?use_cache=true' \
+  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "widget_id": "wid_recent_orders_001",
+    "limit": 10,
+    "offset": 0
+  }'
+```
+
+### KPI Widget
+```bash
+curl -X 'POST' \
+  'http://localhost:9100/api/v1/kpi/stats' \
+  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "period_window": "mtd"
+  }'
+```
+
+## Notes
+
+1. All endpoints require a valid JWT token in the Authorization header
+2. The `widget_id` must match the endpoint being called
+3. Widget access is controlled by the `widget_access` array in the user's role document
+4. Use `use_cache=true` query parameter to enable caching (recommended)
+5. Branch filtering is optional - omit `branch_id` to get data for all branches

app/routers/chart_widget_router.py

@@ -2,7 +2,7 @@
 Chart Widget Router for dashboard chart widget endpoints.
 Implements all 9 chart widgets with role-based access control.
 """
-from fastapi import APIRouter, Depends, Query, HTTPException
+from fastapi import APIRouter, Depends, Query, Body, HTTPException
 from typing import Optional
 
 from insightfy_utils.logging import get_logger
@@ -100,7 +100,15 @@ async def require_view_personal_charts_permission(current_user: dict = Depends(g
     description="Get monthly revenue trend chart. Requires widget access."
 )
 async def get_revenue_trend_chart(
-    request: ChartWidgetRequest,
+    request: ChartWidgetRequest = Body(
+        ...,
+        example={
+            "widget_id": "wid_revenue_trend_12m_001",
+            "chart_type": "line",
+            "months": 12,
+            "period_window": "last_12_months"
+        }
+    ),
     use_cache: bool = Query(True, description="Use cached data if available"),
     current_user: dict = Depends(get_current_user)
 ):
@@ -146,7 +154,15 @@ async def get_revenue_trend_chart(
     description="Get monthly gross margin trend chart. Requires widget access."
 )
 async def get_gross_margin_trend_chart(
-    request: ChartWidgetRequest,
+    request: ChartWidgetRequest = Body(
+        ...,
+        example={
+            "widget_id": "wid_gross_margin_trend_12m_001",
+            "chart_type": "line",
+            "months": 12,
+            "period_window": "last_12_months"
+        }
+    ),
     use_cache: bool = Query(True, description="Use cached data if available"),
     current_user: dict = Depends(get_current_user)
 ):

scripts/add_request_examples.py

@@ -0,0 +1,57 @@
+"""
+Script to add request body examples to chart widget endpoints.
+"""
+
+# Mapping of endpoint paths to their widget IDs and example bodies
+ENDPOINT_EXAMPLES = {
+    "/gross-margin-trend": {
+        "widget_id": "wid_gross_margin_trend_12m_001",
+        "chart_type": "line",
+        "months": 12,
+        "period_window": "last_12_months"
+    },
+    "/channel-mix": {
+        "widget_id": "wid_channel_mix_001",
+        "chart_type": "donut",
+        "period_window": "last_12_months"
+    },
+    "/top-skus": {
+        "widget_id": "wid_top_5_skus_001",
+        "chart_type": "bar",
+        "limit": 5,
+        "period_window": "last_12_months"
+    },
+    "/inventory-status": {
+        "widget_id": "wid_inventory_status_001",
+        "chart_type": "donut"
+    },
+    "/top-selling-products": {
+        "widget_id": "wid_top_selling_products_30d_001",
+        "chart_type": "bar",
+        "window_days": 30,
+        "limit": 10
+    },
+    "/staff-performance": {
+        "widget_id": "wid_staff_performance_001",
+        "chart_type": "bar",
+        "window_days": 30,
+        "limit": 10
+    },
+    "/my-sales-trend": {
+        "widget_id": "wid_personal_sales_trend_30d_001",
+        "chart_type": "line",
+        "window_days": 30
+    },
+    "/my-top-products": {
+        "widget_id": "wid_top_products_sold_by_me_001",
+        "chart_type": "bar",
+        "window_days": 30,
+        "limit": 5
+    }
+}
+
+print("Chart Widget Request Body Examples:")
+print("=" * 80)
+for endpoint, example in ENDPOINT_EXAMPLES.items():
+    print(f"\n{endpoint}:")
+    print(f"  {example}")