@optima-chat/bi-cli 0.3.4 → 0.3.6

package/src/commands/analytics.ts

@@ -72,19 +72,38 @@ interface FunnelResponse {
 }
 
 export function createAnalyticsCommand(): Command {
-  const analytics = new Command('analytics').description('Advanced analytics');
+  const analytics = new Command('analytics').description(
+    `Advanced analytics.
+
+Period comparison, growth analysis, customer cohorts, order funnels.`
+  );
 
   // analytics compare
   analytics
     .command('compare')
-    .description('Compare current period with previous period')
-    .option('--days <number>', 'Number of days', '30')
-    .option(
-      '--compare-to <type>',
-      'Compare to: previous_period or previous_year',
-      'previous_period'
+    .description(
+      `Period comparison analysis.
+
+Compare current period with previous period or year-over-year.
+
+Returns JSON:
+{
+  "current": { "revenue": 10000, "orders": 100, "avg_order_value": 100, "customers": 80 },
+  "previous": { "revenue": 8000, "orders": 90, ... },
+  "changes": {
+    "revenue": { "absolute": 2000, "percentage": 25.0 },
+    ...
+  }
+}
+
+Examples:
+  bi-cli analytics compare                              # Last 30 days vs previous 30
+  bi-cli analytics compare --days 7                     # This week vs last week
+  bi-cli analytics compare --compare-to previous_year   # Year-over-year`
     )
-    .option('--pretty', 'Output in pretty table format')
+    .option('--days <number>', 'Number of days to compare (default: 30)', '30')
+    .option('--compare-to <type>', 'Compare to: previous_period | previous_year', 'previous_period')
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {
@@ -167,10 +186,32 @@ export function createAnalyticsCommand(): Command {
   // analytics growth
   analytics
     .command('growth')
-    .description('Get growth trends over time')
-    .option('--period <type>', 'Period type: daily, weekly, monthly', 'daily')
-    .option('--limit <number>', 'Number of periods', '30')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Growth trend analysis.
+
+View revenue and order growth rates by day/week/month.
+
+Returns JSON:
+{
+  "trends": [
+    {
+      "period": "2024-01-01",
+      "revenue": 5000,
+      "orders": 50,
+      "customers": 40,
+      "revenue_growth": 15.5    // Growth rate vs previous period (%), null for first
+    }
+  ]
+}
+
+Examples:
+  bi-cli analytics growth                         # Daily, last 30 periods
+  bi-cli analytics growth --period weekly         # Weekly
+  bi-cli analytics growth --period monthly --limit 12  # Monthly, last 12 months`
+    )
+    .option('--period <type>', 'Period type: daily | weekly | monthly', 'daily')
+    .option('--limit <number>', 'Number of periods (default: 30)', '30')
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {
@@ -221,8 +262,27 @@ export function createAnalyticsCommand(): Command {
   // analytics cohort
   analytics
     .command('cohort')
-    .description('Customer cohort analysis')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Customer cohort analysis.
+
+Group customers by first purchase month and analyze lifetime value (LTV).
+
+Returns JSON:
+{
+  "cohorts": [
+    {
+      "month": "2024-01",
+      "customers": 100,           // New customers in this month
+      "avg_lifetime_value": 500,  // Average customer lifetime value
+      "avg_orders": 2.5,          // Average orders per customer
+      "total_revenue": 50000      // Total revenue from this cohort
+    }
+  ]
+}
+
+Use case: Evaluate customer acquisition quality, optimize marketing strategy.`
+    )
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {
@@ -270,9 +330,30 @@ export function createAnalyticsCommand(): Command {
   // analytics funnel
   analytics
     .command('funnel')
-    .description('Order status funnel analysis')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Order status funnel analysis.
+
+Analyze conversion rates and drop-offs from order creation to delivery.
+
+Returns JSON:
+{
+  "total_orders": 1000,
+  "conversion_rate": 85.5,      // Final completion rate (%)
+  "funnel": [
+    { "stage": "pending", "count": 1000, "amount": 100000, "percentage": 100 },
+    { "stage": "paid", "count": 950, "amount": 95000, "percentage": 95 },
+    { "stage": "shipped", "count": 900, "amount": 90000, "percentage": 90 },
+    { "stage": "delivered", "count": 855, "amount": 85500, "percentage": 85.5 }
+  ],
+  "dropoffs": [
+    { "status": "cancelled", "count": 50, "amount": 5000, "percentage": 5 }
+  ]
+}
+
+Use case: Identify order drop-off points, optimize fulfillment process.`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {

package/src/commands/auth.ts

@@ -38,13 +38,25 @@ interface UserInfo {
 }
 
 export function createAuthCommand(): Command {
-  const auth = new Command('auth').description('Authentication commands');
+  const auth = new Command('auth').description(
+    `Authentication commands.
+
+You must login before using other commands. Tokens are saved to ~/.optima/token.json.`
+  );
 
   // auth login
   auth
     .command('login')
-    .description('Login with OAuth 2.0 Device Flow')
-    .option('--env <environment>', 'Environment (production|stage|development)', 'production')
+    .description(
+      `Login using OAuth 2.0 Device Flow.
+
+Opens browser automatically for authorization. Token is saved after successful auth.
+
+Examples:
+  bi-cli auth login                    # Login to production (default)
+  bi-cli auth login --env stage        # Login to staging environment`
+    )
+    .option('--env <environment>', 'Environment: production | stage | development', 'production')
     .action(async (options) => {
       const env = options.env as Environment;
 
@@ -206,7 +218,7 @@ export function createAuthCommand(): Command {
   // auth logout
   auth
     .command('logout')
-    .description('Logout and delete ~/.optima/token.json')
+    .description('Logout and delete local token file (~/.optima/token.json)')
     .action(() => {
       clearAuth();
       success('Logged out successfully');
@@ -216,7 +228,7 @@ export function createAuthCommand(): Command {
   // auth whoami
   auth
     .command('whoami')
-    .description('Show current user information')
+    .description('Show current user info (email, role, merchant ID)')
     .action(async () => {
       const cfg = getConfig();
 
@@ -260,7 +272,7 @@ export function createAuthCommand(): Command {
   // auth status
   auth
     .command('status')
-    .description('Show authentication status')
+    .description('Show authentication status (environment, login state, config path)')
     .action(() => {
       const cfg = getConfig();
 

package/src/commands/product.ts

@@ -88,15 +88,36 @@ interface PerformanceResponse {
 }
 
 export function createProductCommand(): Command {
-  const product = new Command('product').description('Product analytics');
+  const product = new Command('product').description(
+    `Product analytics.
+
+Analyze product performance, price distribution, ABC classification.`
+  );
 
   // product best-sellers
   product
     .command('best-sellers')
-    .description('Get best selling products')
-    .option('--limit <number>', 'Number of products to return', '10')
-    .option('--sort <field>', 'Sort by: revenue, quantity, orders', 'revenue')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Get best selling products ranking.
+
+Returns products sorted by revenue/quantity/orders with rank, revenue, units sold, revenue share.
+
+Returns JSON:
+{
+  "products": [
+    { "rank": 1, "title": "Product Name", "revenue": 1000, "units_sold": 50, "orders": 30, "revenue_share": 15.5 }
+  ],
+  "total_revenue": number
+}
+
+Examples:
+  bi-cli product best-sellers                      # Top 10 by revenue
+  bi-cli product best-sellers --limit 5            # Top 5
+  bi-cli product best-sellers --sort quantity      # Sort by quantity`
+    )
+    .option('--limit <number>', 'Number of products to return (default: 10)', '10')
+    .option('--sort <field>', 'Sort by: revenue | quantity | orders', 'revenue')
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {
@@ -147,8 +168,23 @@ export function createProductCommand(): Command {
   // product abc-analysis
   product
     .command('abc-analysis')
-    .description('ABC inventory analysis')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `ABC inventory analysis (Pareto analysis).
+
+Classifies products by revenue contribution:
+  - A: High-value products contributing 70% of revenue (typically ~20% of products)
+  - B: Medium-value products contributing 20% of revenue
+  - C: Low-value products contributing 10% of revenue
+
+Use case: Identify core products, optimize inventory and purchasing strategy.
+
+Returns JSON:
+{
+  "summary": { "A": {...}, "B": {...}, "C": {...} },
+  "products": [ { "title": "Product Name", "category": "A", "revenue": number, ... } ]
+}`
+    )
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {
@@ -205,8 +241,20 @@ export function createProductCommand(): Command {
   // product price-analysis
   product
     .command('price-analysis')
-    .description('Price point analysis')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Price range analysis.
+
+Analyze product count, revenue, and sales by price ranges.
+
+Returns JSON:
+{
+  "price_ranges": [
+    { "range": "¥0-50", "products": 10, "revenue": 5000, "units": 200, "revenue_share": 15.5 }
+  ],
+  "totals": { "revenue": number, "units": number }
+}`
+    )
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {
@@ -256,10 +304,36 @@ export function createProductCommand(): Command {
   // product performance
   product
     .command('performance')
-    .description('Get product performance metrics')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--limit <number>', 'Number of products', '20')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Product performance metrics.
+
+Get sales, inventory, and margin metrics for each product.
+
+Returns JSON:
+{
+  "products": [
+    {
+      "title": "Product Name",
+      "price": 99.00,           // Selling price
+      "inventory": 50,          // Current stock
+      "sales": { "units": 100, "revenue": 9900, "orders": 80 },
+      "metrics": {
+        "margin_percent": 30.5, // Profit margin (%)
+        "days_of_stock": 15,    // Estimated days of stock
+        "velocity": 6.7         // Daily sales rate
+      }
+    }
+  ]
+}
+
+Examples:
+  bi-cli product performance                  # Last 30 days, top 20 products
+  bi-cli product performance --days 7         # Last 7 days
+  bi-cli product performance --limit 50       # Top 50 products`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--limit <number>', 'Number of products (default: 20)', '20')
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {

package/src/commands/sales.ts

@@ -33,14 +33,38 @@ interface SalesResponse {
 }
 
 export function createSalesCommand(): Command {
-  const sales = new Command('sales').description('Sales analytics');
+  const sales = new Command('sales').description(
+    `Sales analytics.
+
+Get sales summary and daily breakdown data.`
+  );
 
   // sales get
   sales
     .command('get')
-    .description('Get sales data')
-    .option('--days <number>', 'Number of days to fetch', '7')
-    .option('--pretty', 'Output in pretty table format (default: JSON)')
+    .description(
+      `Get sales summary and daily breakdown.
+
+Returns JSON:
+{
+  "summary": {
+    "total_revenue": number,      // Total revenue (CNY)
+    "total_orders": number,       // Total order count
+    "avg_order_value": number,    // Average order value (CNY)
+    "unique_customers": number    // Unique customer count
+  },
+  "daily": [                      // Daily breakdown array
+    { "date": "YYYY-MM-DD", "total_revenue": number, "order_count": number, ... }
+  ]
+}
+
+Examples:
+  bi-cli sales get                     # Get last 7 days
+  bi-cli sales get --days 30           # Get last 30 days
+  bi-cli sales get --days 7 --pretty   # Output as table`
+    )
+    .option('--days <number>', 'Number of days from today (range: 1-365)', '7')
+    .option('--pretty', 'Output as table (default: JSON)')
     .action(async (options) => {
       const cfg = getConfig();
 

package/src/commands/traffic.ts

@@ -69,15 +69,44 @@ function formatDuration(seconds: number): string {
 }
 
 export function createTrafficCommand(): Command {
-  const traffic = new Command('traffic').description('Traffic analytics');
+  const traffic = new Command('traffic').description(
+    `Traffic analytics.
+
+Analyze website visits, traffic sources, conversion funnels, search keywords.`
+  );
 
   // traffic overview
   traffic
     .command('overview')
-    .description('Get traffic overview')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--product <id>', 'Filter by product ID')
-    .option('--pretty', 'Output in pretty format (default: JSON)')
+    .description(
+      `Traffic overview.
+
+Get page views, unique visitors, sessions, and comparison with previous period.
+
+Returns JSON:
+{
+  "period": { "start": "2024-01-01", "end": "2024-01-30", "days": 30 },
+  "summary": {
+    "page_views": 10000,
+    "unique_visitors": 3000,
+    "sessions": 5000,
+    "avg_session_duration": 180,  // seconds
+    "bounce_rate": 0.35           // 35%
+  },
+  "comparison": {
+    "page_views_change": 0.15,    // +15%
+    "unique_visitors_change": 0.10
+  }
+}
+
+Examples:
+  bi-cli traffic overview                     # Last 30 days, all pages
+  bi-cli traffic overview --days 7            # Last 7 days
+  bi-cli traffic overview --product <uuid>    # Filter by product`
+    )
+    .option('--days <number>', 'Number of days (range: 1-365, default: 30)', '30')
+    .option('--product <id>', 'Filter by product ID (UUID format)')
+    .option('--pretty', 'Output as table (default: JSON)')
     .action(async (options) => {
       const cfg = getConfig();
 
@@ -129,10 +158,29 @@ export function createTrafficCommand(): Command {
   // traffic sources
   traffic
     .command('sources')
-    .description('Get traffic sources')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--limit <number>', 'Limit results', '10')
-    .option('--pretty', 'Output in pretty format (default: JSON)')
+    .description(
+      `Traffic source analysis.
+
+Analyze visitor sources (Google, WeChat, direct, etc.).
+
+Returns JSON:
+{
+  "sources": [
+    {
+      "source": "google",
+      "medium": "organic",
+      "visitors": 1000,
+      "page_views": 3000,
+      "percentage": 0.35  // 35%
+    }
+  ]
+}
+
+Use case: Evaluate channel effectiveness, optimize marketing spend.`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--limit <number>', 'Number of results (default: 10)', '10')
+    .option('--pretty', 'Output as table (default: JSON)')
     .action(async (options) => {
       const cfg = getConfig();
 
@@ -179,10 +227,28 @@ export function createTrafficCommand(): Command {
   // traffic funnel
   traffic
     .command('funnel')
-    .description('Get conversion funnel')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--product <id>', 'Filter by product ID')
-    .option('--pretty', 'Output in pretty format (default: JSON)')
+    .description(
+      `Conversion funnel analysis.
+
+Analyze user journey from visit to purchase:
+  Visit → View Product → Add to Cart → Checkout → Purchase
+
+Returns JSON:
+{
+  "funnel": [
+    { "step": "page_view", "count": 10000, "rate": 1.0, "conversion": 1.0 },
+    { "step": "product_view", "count": 5000, "rate": 0.5, "conversion": 0.5 },
+    { "step": "add_to_cart", "count": 1000, "rate": 0.1, "conversion": 0.2 },
+    { "step": "checkout", "count": 500, "rate": 0.05, "conversion": 0.5 },
+    { "step": "purchase", "count": 300, "rate": 0.03, "conversion": 0.6 }
+  ]
+}
+
+Note: rate = ratio from start, conversion = conversion from previous step.`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--product <id>', 'Filter by product ID (UUID format)')
+    .option('--pretty', 'Output as table (default: JSON)')
     .action(async (options) => {
       const cfg = getConfig();
 
@@ -227,11 +293,27 @@ export function createTrafficCommand(): Command {
   // traffic search
   traffic
     .command('search')
-    .description('Get search analytics')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--limit <number>', 'Limit results', '20')
-    .option('--zero-results', 'Show only zero results queries')
-    .option('--pretty', 'Output in pretty format (default: JSON)')
+    .description(
+      `Site search analytics.
+
+Analyze search keywords, result counts, and click-through rates.
+
+Returns JSON:
+{
+  "searches": [
+    { "query": "dress", "count": 500, "avg_results": 25, "click_rate": 0.65 }
+  ],
+  "zero_results": [
+    { "query": "nonexistent product", "count": 10 }
+  ]
+}
+
+Use case: Optimize product titles, add missing products, improve search.`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--limit <number>', 'Number of results (default: 20)', '20')
+    .option('--zero-results', 'Show only zero-result queries')
+    .option('--pretty', 'Output as table (default: JSON)')
     .action(async (options) => {
       const cfg = getConfig();
 
@@ -288,10 +370,28 @@ export function createTrafficCommand(): Command {
   // traffic pages
   traffic
     .command('pages')
-    .description('Get top pages')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--limit <number>', 'Limit results', '20')
-    .option('--pretty', 'Output in pretty format (default: JSON)')
+    .description(
+      `Top pages analysis.
+
+View most popular pages sorted by page views.
+
+Returns JSON:
+{
+  "pages": [
+    {
+      "path": "/products/xxx",
+      "page_views": 5000,
+      "unique_visitors": 2000,
+      "sessions": 3000
+    }
+  ]
+}
+
+Use case: Understand browsing patterns, optimize popular page experience.`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--limit <number>', 'Number of results (default: 20)', '20')
+    .option('--pretty', 'Output as table (default: JSON)')
     .action(async (options) => {
       const cfg = getConfig();