refactor(logging): Add optional logging support throughout codebase

Add centralized logging utility and optional logger parameters to all
core functions for better observability and debugging capabilities.

New modules:
- utils/logging.py: Centralized logger configuration with console
  and optional file handlers

Enhanced features:
- Added optional logger parameter to all extractor_core functions
- Added logger support to extractor, excel_converter, and auth modules
- Functions remain silent when logger=None (backward compatible)
- Improved environment variable validation in test files

Documentation:
- Added discrete_material_plan_extractor_core.md with complete API
  reference and usage patterns

Benefits:
- Consistent logging format across all components
- Optional debug output for troubleshooting
- No breaking changes - fully backward compatible
- Better error messages and validation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

utils/logging.py

@@ -0,0 +1,81 @@
+"""
+Centralized logging utility module for BIPAuto project.
+
+Provides a standardized logger configuration for consistent logging across
+all BIPAuto components. Supports console output with optional file logging.
+
+Basic usage examples:
+
+    # Basic usage - console logging at INFO level
+    from utils.logging import get_logger
+    logger = get_logger('bipauto.auth')
+    logger.info('Login successful')
+
+    # With debug level for detailed output
+    logger = get_logger('bipauto.extractor', level=logging.DEBUG)
+    logger.debug('Processing batch 1 of 5...')
+
+    # With file output for persistent logs
+    logger = get_logger('bipauto.app', level=logging.INFO, log_file='app.log')
+    logger.info('Application started')
+
+Logger naming convention:
+    Use hierarchical names with 'bipauto.' prefix:
+    - 'bipauto.auth' - Authentication module
+    - 'bipauto.extractor' - Material plan extractor
+    - 'bipauto.converter' - Excel converter
+    - 'bipauto.utils' - Utility functions
+"""
+
+import logging
+from typing import Optional
+
+
+def get_logger(
+    name: str,
+    level: int = logging.INFO,
+    log_file: Optional[str] = None
+) -> logging.Logger:
+    """
+    Create and configure a logger with console and optional file handlers.
+
+    Args:
+        name: Logger name (use hierarchical naming, e.g., 'bipauto.auth')
+        level: Logging level (default: logging.INFO)
+        log_file: Optional path to log file. If None, only console output.
+
+    Returns:
+        Configured logging.Logger instance
+
+    Example:
+        >>> logger = get_logger('bipauto.auth')
+        >>> logger.info('User logged in')
+        [INFO] bipauto.auth: User logged in
+    """
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+
+    # Avoid adding duplicate handlers if logger already configured
+    if logger.handlers:
+        return logger
+
+    # Create formatter
+    formatter = logging.Formatter("[%(levelname)s] %(name)s: %(message)s")
+
+    # Console handler (always added)
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(level)
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+
+    # File handler (optional)
+    if log_file:
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setLevel(level)
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+
+    # Prevent log propagation to root logger (avoids duplicate output)
+    logger.propagate = False
+
+    return logger