# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

BIPAuto is a Python automation framework for interacting with Yonyou BIP (用友BIP) enterprise resource planning systems. The project uses Playwright for browser automation to perform login, logout, and other operations on the web-based ERP system.

## Development Environment

**Virtual Environment**: All Python scripts must be executed within the local `.venv` virtual environment.

```bash
# Create virtual environment (if not exists)
python -m venv .venv

# Activate (Windows Git Bash)
source .venv/Scripts/activate

# Install/update dependencies
pip install -r requirements.txt
```

## Environment Configuration

The project relies heavily on environment variables loaded from `.env` file in the project root. Never commit `.env` to version control - use `.env.example` as a template.

**Critical Environment Variables:**
- `PLAYWRIGHT_BROWSERS_PATH` - Path to Playwright browser installation (custom path, not default)
- `ERP_URL` - Base URL for the ERP system
- `ERP_USERNAME` - Login username
- `ERP_PASSWORD` - Login password
- `ERP_HEADLESS` - Whether to run browser in headless mode (true/false)
- `ERP_IGNORE_HTTPS_ERRORS` - Whether to ignore HTTPS certificate errors (true/false)

Note: Test scripts are responsible for loading environment variables and passing configuration to utility functions.

## Architecture

### Module Structure

**`utils/auth.py`** - Core authentication module (pure functions)
- `login(url, username, password, page)` - Handles Yonyou BIP login with automatic force-login popup detection. Requires all parameters explicitly.
- `logout(page)` - Performs logout with confirmation dialog handling
- Callers are responsible for browser lifecycle management (context.close(), browser.close())
- Returns tuple: `(page, main_frame)` where `main_frame` is the forwardFrame iframe

**`tests/`** - Test suite
- All test files must add `PROJECT_ROOT` to `sys.path` to import `utils` modules
- Tests follow pattern: load dotenv, set browser path environment variable, run Playwright operations
- All output and log messages use English only (Chinese text reserved for page element selectors)

### Page Interaction Pattern

Yonyou BIP uses a nested iframe structure:
1. Main page contains `#forwardFrame` iframe
2. All form elements (username, password, buttons) are located within this iframe
3. Use `page.locator("#forwardFrame").content_frame` to access the iframe
4. Element selectors use role-based locators with Chinese names matching the UI:
   - `get_by_role("textbox", name="用户名")` for username field
   - `get_by_role("button", name="登录")` for login button

### Force Login Handling

The system automatically detects and handles a force-login confirmation dialog that appears after clicking the login button. The code checks for a "确定" (Confirm) button and clicks it if present.

### URL Construction Pattern

Callers must construct the complete login URL before passing to `login()`:

```python
url = f"{os.getenv('ERP_URL').rstrip('/')}/yonbip/resources/uap/rbac/login/main/index.html"
```

## Common Commands

```bash
# Run authentication configuration test
python tests/test_auth_config.py

# Run login/logout test
python tests/test_login.py

# Run any test with virtual environment
source .venv/Scripts/activate && python tests/<test_file>.py
```

## Code Conventions

1. **English Only**: All user-facing output, docstrings, comments, and log messages must be in English. Chinese text is only used for Playwright element selectors matching the actual UI.

2. **Environment-First**: Test scripts load environment variables and explicitly pass configuration to utility functions. No hardcoded values in code.

3. **Error Handling**: Functions that depend on environment variables should raise clear `ValueError` exceptions when required variables are missing.

4. **Path Handling**: Use `pathlib.Path` for all file system operations. Project root is determined as `Path(__file__).resolve().parent.parent` from within `utils/` modules.

5. **Test Coverage**: **ALL new components MUST include corresponding unit tests.** When creating new functionality in `utils/` or any other module, you must simultaneously create a test file in `tests/` directory that validates the component's behavior. Tests should verify both success and failure scenarios.