docs: add CLAUDE.md with project architecture guidance
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Misaka_Company
129
CLAUDE.md
Normal file
129
CLAUDE.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Development Commands
|
||||
|
||||
### Running the Application
|
||||
```bash
|
||||
npm run dev # Start development server with hot reload
|
||||
npm run build # Full build with type checking
|
||||
npm run build:win # Build Windows executable
|
||||
npm run build:mac # Build macOS DMG
|
||||
npm run build:linux # Build Linux AppImage
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
```bash
|
||||
npm run lint # ESLint check
|
||||
npm run format # Prettier format
|
||||
npm run typecheck # TypeScript check (both main and renderer)
|
||||
npm run typecheck:node # TypeScript check for main process only
|
||||
npm run typecheck:web # TypeScript check for renderer only
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
npm run test # Run unit tests (Vitest)
|
||||
npm run test:coverage # Run tests with coverage report
|
||||
npm run test:e2e # Run E2E tests (Playwright)
|
||||
npm run test:e2e:ui # Run E2E tests with UI
|
||||
npm run test:e2e:report # Show E2E test report
|
||||
```
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
ERPAuto is an **Electron desktop application** for automating ERP system data processing. The application follows the classic Electron architecture with three distinct processes:
|
||||
|
||||
### Process Structure
|
||||
|
||||
1. **Main Process** (`src/main/`)
|
||||
- Node.js environment managing application lifecycle
|
||||
- Entry point: `src/main/index.ts`
|
||||
- Registers all IPC handlers via `registerIpcHandlers()`
|
||||
- Loads environment variables from `.env` at startup
|
||||
|
||||
2. **Preload Script** (`src/preload/`)
|
||||
- Security bridge between main and renderer processes
|
||||
- Exposes type-safe APIs via `contextBridge` as `window.electron` and `window.api`
|
||||
- Central API surface organized by domain (auth, extractor, cleaner, database, etc.)
|
||||
|
||||
3. **Renderer Process** (`src/renderer/`)
|
||||
- React 19 + TypeScript UI
|
||||
- Uses exposed preload APIs for all main process communication
|
||||
- Authentication-based routing with role-based access control
|
||||
|
||||
### Service Architecture
|
||||
|
||||
The main process is organized around domain-specific services in `src/main/services/`:
|
||||
|
||||
- **ERP Services** (`services/erp/`): Browser automation using Playwright
|
||||
- `ExtractorService` - Downloads material plan data
|
||||
- `CleanerService` - Deletes specified materials with dry-run support
|
||||
- `ErpAuthService` - Handles ERP authentication
|
||||
- `OrderResolverService` - Validates and resolves order numbers
|
||||
- `locators.ts` - ERP element selectors
|
||||
|
||||
- **Database Services** (`services/database/`): Dual database support
|
||||
- `MySqlService` / `mysql.ts` - MySQL operations
|
||||
- `SqlServerService` / `sql-server.ts` - SQL Server operations
|
||||
- DAO pattern: `discrete-material-plan-dao.ts`, `materials-to-be-deleted-dao.ts`
|
||||
|
||||
- **User Services** (`services/user/`): Authentication and session management
|
||||
- `BipUsersDao` - User data access
|
||||
- `SessionManager` - Active session tracking
|
||||
|
||||
- **Other Services**:
|
||||
- `config/` - Configuration management
|
||||
- `excel/` - Excel file parsing
|
||||
|
||||
### IPC Handler Pattern
|
||||
|
||||
All IPC communication follows a consistent pattern:
|
||||
- Handlers are in `src/main/ipc/`, organized by domain (8 modules)
|
||||
- Each handler module exports a `register*Handlers()` function
|
||||
- All handlers are registered in `src/main/ipc/index.ts`
|
||||
- Channel naming follows `domain:action` convention (e.g., `extractor:run`, `auth:login`)
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
The application implements a multi-stage authentication system:
|
||||
|
||||
1. **Silent Login**: On startup, attempts automatic login using computer name
|
||||
2. **Fallback**: Shows login dialog if silent login fails
|
||||
3. **Admin User Selection**: Admin users can switch to other user accounts
|
||||
4. **Session Management**: Persistent sessions with role-based permissions (Admin/User/Guest)
|
||||
|
||||
Admin users see logout buttons and can access user switching. Non-admin users have restricted access based on the user who initiated their session.
|
||||
|
||||
### Type System
|
||||
|
||||
- Separate TypeScript configs: `tsconfig.node.json` (main/preload) and `tsconfig.web.json` (renderer)
|
||||
- Types are co-located with features: `src/main/types/` contains domain-specific type definitions
|
||||
- The preload script exposes a typed API surface that's available in renderer
|
||||
|
||||
### Path Aliases
|
||||
|
||||
- `@renderer` → `src/renderer/src` (renderer process)
|
||||
- `@main` → `src/main` (main process, tests only)
|
||||
- `@services` → `src/main/services` (main process, tests only)
|
||||
- `@types` → `src/main/types` (main process, tests only)
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
The application requires a `.env` file in the project root. Reference `.env.example` for the full structure. Key configurations:
|
||||
|
||||
- **ERP Settings**: URL, credentials, headless mode, HTTPS error handling
|
||||
- **Database**: MySQL and SQL Server connection configs (dual support)
|
||||
- **App Settings**: Log level, download/temp directories
|
||||
|
||||
## Key Technologies
|
||||
|
||||
- **Electron 39** - Desktop framework
|
||||
- **React 19** - UI framework
|
||||
- **TypeScript 5.9** - Type safety
|
||||
- **Playwright 1.58** - Browser automation for ERP interaction
|
||||
- **electron-vite + Vite 7** - Build tooling
|
||||
- **Zod** - Runtime validation
|
||||
- **Vitest** - Unit tests
|
||||
- **Playwright Test** - E2E tests
|
||||
Reference in New Issue
Block a user