a05a4c2ba3
- Document project overview and architecture - Add development environment setup instructions - Specify environment configuration requirements - Document module structure and page interaction patterns - Add common commands for testing - Establish code conventions including mandatory test coverage for new components Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
91 lines
4.1 KiB
Markdown
91 lines
4.1 KiB
Markdown
# 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)
|
|
- `ERP_AUTO_CLOSE_BROWSER` - Whether to automatically close browser after operations (true/false)
|
|
|
|
## Architecture
|
|
|
|
### Module Structure
|
|
|
|
**`utils/auth.py`** - Core authentication module
|
|
- `login()` - Handles Yonyou BIP login with automatic force-login popup detection
|
|
- `logout()` - Performs logout with confirmation dialog handling
|
|
- `close_session()` - Closes browser session with respect to auto-close configuration
|
|
- Auto-loads environment variables from `.env` on module import
|
|
- Returns tuple: `(browser, context, 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.
|
|
|
|
## 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**: All configuration values should default to reading from environment variables. No hardcoded URLs, credentials, or user-specific paths 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.
|