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/auth.py

@@ -2,7 +2,9 @@
 Authentication module - Responsible for Yonyou BIP system login and logout operations
 """
 
-from playwright.sync_api import Playwright, Browser, BrowserContext, Page, Frame
+import logging
+from typing import Optional
+from playwright.sync_api import Playwright, Browser, BrowserContext, Page, Frame, FrameLocator
 
 
 def login(
@@ -13,7 +15,8 @@ def login(
     headless: bool,
     ignore_https_errors: bool,
     verbose: bool = True,
-) -> tuple[Browser, BrowserContext, Page, Frame]:
+    logger: Optional[logging.Logger] = None,
+) -> tuple[Browser, BrowserContext, Page, FrameLocator]:
     """
     Login to Yonyou BIP system
 
@@ -24,7 +27,8 @@ def login(
         url: Complete login page URL (required)
         headless: Whether to use headless mode (required)
         ignore_https_errors: Whether to ignore HTTPS errors (required)
-        verbose: Whether to print detailed logs (default: True)
+        verbose: Whether to print detailed logs (default: True). Deprecated, use logger instead.
+        logger: Optional logging.Logger instance. If None and verbose=True, creates default logger.
 
     Returns:
         tuple: (browser, context, page, main_frame)
@@ -34,6 +38,13 @@ def login(
             - main_frame: Main iframe after login (forwardFrame)
     """
     import time
+    from utils.logging import get_logger
+
+    # Create default logger if needed
+    if logger is None and verbose:
+        logger = get_logger('bipauto.auth')
+    elif logger is None:
+        logger = None  # Silent mode, no logging
 
     # Validate required parameters
     if not username or not username.strip():
@@ -71,27 +82,35 @@ def login(
     confirm_btn = main_frame.get_by_role("button", name="确定")
     if confirm_btn.count() > 0:
         confirm_btn.click()
-        if verbose:
-            print("Force login detected")
+        if logger:
+            logger.info("Force login detected")
     else:
-        if verbose:
-            print("Normal login")
+        if logger:
+            logger.debug("Normal login")
 
     return browser, context, page, main_frame
 
 
-def logout(main_frame: Frame, verbose: bool = True) -> None:
+def logout(main_frame: FrameLocator, verbose: bool = True, logger: Optional[logging.Logger] = None) -> None:
     """
     Execute account logout
 
     Args:
         main_frame: Main iframe object (forwardFrame)
-        verbose: Whether to print detailed logs
+        verbose: Whether to print detailed logs. Deprecated, use logger instead.
+        logger: Optional logging.Logger instance. If None and verbose=True, creates default logger.
     """
     import time
+    from utils.logging import get_logger
 
-    if verbose:
-        print("Clicking account menu button...")
+    # Create default logger if needed
+    if logger is None and verbose:
+        logger = get_logger('bipauto.auth')
+    elif logger is None:
+        logger = None  # Silent mode, no logging
+
+    if logger:
+        logger.info("Clicking account menu button...")
 
     # Element 1: Account menu button (logo icon)
     main_frame.get_by_role("img", name="logo").click()
@@ -99,8 +118,8 @@ def logout(main_frame: Frame, verbose: bool = True) -> None:
     # Wait for menu to appear
     time.sleep(1)
 
-    if verbose:
-        print("Clicking logout button...")
+    if logger:
+        logger.info("Clicking logout button...")
 
     # Element 2: "Logout" button
     main_frame.get_by_text("退出登录").click()
@@ -108,19 +127,19 @@ def logout(main_frame: Frame, verbose: bool = True) -> None:
     # Wait for confirmation dialog to appear
     time.sleep(1)
 
-    if verbose:
-        print("Waiting for logout confirmation dialog...")
+    if logger:
+        logger.info("Waiting for logout confirmation dialog...")
 
     # Element 3: Logout confirmation dialog (check if appears)
     try:
         confirm_text = main_frame.get_by_text("退出确定要退出当前账号吗？")
-        if verbose:
-            print("Found confirmation dialog, clicking confirm button")
+        if logger:
+            logger.info("Found confirmation dialog, clicking confirm button")
 
         # Element 4: Confirm button
         main_frame.get_by_role("button", name="确定(Y)").click()
     except:
-        if verbose:
-            print("Confirmation dialog not found, may have auto-logged out")
+        if logger:
+            logger.warning("Confirmation dialog not found, may have auto-logged out")
 
     time.sleep(2)  # Wait for logout to complete