From a05a4c2ba34c2450df45dfbd226d0cb5b6b46b91 Mon Sep 17 00:00:00 2001
From: Misaka_Company <pengqiangqiang0@gmail.com>
Date: Fri, 27 Mar 2026 11:15:40 +0800
Subject: [PATCH] Add CLAUDE.md with project documentation and test coverage
 requirement

- 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>
---
 CLAUDE.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..c01f8ee
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,90 @@
+# 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.