# CLAUDE.md

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

## Project Overview

NumericalCollection is a Spring Boot 2.6.13 application that collects and synchronizes device metrics data from manufacturing equipment. It integrates with an Oracle database and external device APIs to fetch real-time device data, daily statistics, and production order information. The application runs scheduled tasks to poll device data and provides REST endpoints for manual synchronization.

## Build and Run Commands

**Build the project:**
```bash
mvn clean install
```

**Run the application locally:**
```bash
mvn spring-boot:run
```
The server starts on port 9095 (configured in application.yml).

**Run tests:**
```bash
mvn test
```

**Compile without tests:**
```bash
mvn compile -DskipTests
```

**Package for deployment:**
```bash
mvn clean package -DskipTests
```
Produces `target/NumericalCollection.jar`.

## Architecture

### Core Package Structure

- `config/` - Spring configuration classes, including DataAcquisitionConfiguration, MybatisPlusConfig, and result wrappers
- `controller/` - REST controllers, primarily KMController which handles manual synchronization endpoints
- `service/` and `service/impl/` - Business logic layer
  - `INumericalService` - Core service for device data retrieval and synchronization
  - `INumericalNoOrderService` - Service for device operations without order context (device list, real-time data, daily statistics)
  - `DeviceMetricsService` - Handles manual synchronization operations and PDF conversion
  - Entity-specific services follow naming pattern `{Entity}Service` (e.g., DeviceService, MesNumericalService)
- `mapper/` - MyBatis-Plus mapper interfaces for database operations
- `entity/` - JPA/MyBatis entities representing database tables
- `dto/` - Data transfer objects for API requests/responses
- `task/` - Scheduled task components, specifically ScheduledTasks for automated data collection

### Data Flow Architecture

1. **Scheduled Data Collection** (`ScheduledTasks.java`):
   - Every 2 minutes: Fetches real-time device data for main devices and BYCL devices (offset by 30 seconds)
   - Daily at 1 AM: Syncs production orders from Womdaa to MesOrderSelect
   - Daily at 2 AM: Collects previous day's device statistics
   - Weekly on Sunday: Cleans up old data (removes records older than 1 week)

2. **External API Integration**:
   - Uses OkHttp3 for HTTP calls to external device management systems
   - ApiService handles request/response serialization with Gson/FastJSON
   - Device data retrieved via `INumericalService` methods

3. **Database Layer**:
   - MyBatis-Plus with Oracle JDBC driver (ojdbc8)
   - Druid connection pool (5-30 connections)
   - XML-based SQL mappings in `src/main/resources/mapper/`
   - Automatic camelCase mapping enabled (`map-underscore-to-camel-case: true`)

4. **Manual Synchronization Endpoints** (`KMController`):
   - `/Numerical/manualSynchronization` - Sync device metrics for a specific order
   - `/Numerical/manualSynchronizationBycl` - Sync BYCL device metrics
   - `/Numerical/RefreshDev` and `/Numerical/RefreshDevBycl` - Refresh device data
   - `/Numerical/PdfToBase64` - Convert PDF reports to Base64

### Key Dependencies

- Spring Boot 2.6.13 (Java 8)
- MyBatis-Plus 3.5.4 for database operations
- Druid 1.2.16 for connection pooling
- OkHttp 4.9.3 for HTTP client
- Hutool 5.8.18 for utilities (date handling, etc.)
- FastJSON 2.0.32 and Gson 2.8.9 for JSON processing
- Apache POI 4.1.2 for Excel handling
- PDFBox 2.0.27 for PDF operations
- Lombok for boilerplate reduction

## Development Notes

### Database Configuration

The application connects to Oracle database at 192.168.0.94:1521/orcl with credentials in `application.yml`. Override these for local development using environment variables or Spring profiles:
```bash
mvn spring-boot:run -Dspring-boot.run.arguments="--spring.datasource.url=jdbc:oracle:thin:@localhost:1521/orcl --spring.datasource.username=user --spring.datasource.password=pass"
```

### MyBatis Mapper Development

- Mapper interfaces in `mapper/` package are auto-scanned via `@MapperScan` annotation
- Corresponding XML files must be in `src/main/resources/mapper/` with matching names
- SQL result columns use snake_case, automatically mapped to camelCase entity fields
- Multi-statement execution is enabled in Druid configuration

### Service Layer Pattern

Services extend `IService<Entity>` from MyBatis-Plus for CRUD operations. Implementations follow the pattern:
```java
@Service
@RequiredArgsConstructor
public class EntityServiceImpl extends ServiceImpl<EntityMapper, Entity> implements EntityService
```

Use constructor injection via Lombok's `@RequiredArgsConstructor` for dependencies.

### Scheduled Task Development

Add new scheduled methods to `ScheduledTasks.java` component. Cron expressions follow standard format. Ensure error handling wraps API calls in try-catch blocks as shown in existing tasks.

### Testing Considerations

- Tests should extend Spring Boot test framework
- Mock external API calls to avoid dependencies on external systems during testing
- Test database operations using embedded H2 or test Oracle schema
- Run full test suite before committing: `mvn clean test`

## Common Operations

### Adding a New Device Endpoint

1. Add method to `INumericalService` interface
2. Implement in corresponding `ServiceImpl` class
3. Add REST endpoint in `KMController` if manual trigger needed
4. Create/update mapper interface and XML for database operations
5. Add entity/DTO classes if new data structures needed

### Modifying Scheduled Tasks

Edit `ScheduledTasks.java` and adjust cron expressions. Remember existing offsets:
- Main device polling: every 2 minutes at :00 seconds
- BYCL device polling: every 2 minutes at :30 seconds
- Order sync: daily at 1 AM
- Statistics collection: daily at 2 AM
- Data cleanup: weekly Sunday at midnight

### Database Schema Changes

1. Apply schema changes to Oracle database
2. Update entity classes with new fields (use Lombok annotations)
3. Update mapper XML files with new column mappings
4. Regenerate any affected DTOs
5. Update service layer logic to handle new fields

开发工作流程
问题解决流程
1.	首先思考问题，阅读代码库中的相关文件，并将计划写入 tasks/todo.md
2.	计划应包含可以勾选完成的待办事项列表
3.	开始工作前，与我确认计划
4.	然后开始处理待办事项，完成时标记为完成
5.	每一步都提供高层次的变化说明
6.	使每个任务和代码更改尽可能简单，避免大规模或复杂的更改
7.	每个更改应尽可能少地影响代码，一切以简单性为核心
8.	最后，在 todo.md 文件中添加审查部分，总结所做的更改和其他相关信息
      开发原则
      ⦁	不懒惰: 绝不懒惰。如果有错误，找到根本原因并修复它。不要使用临时修复。你是一名高级开发人员，绝不懒惰。
      ⦁	简单性: 使所有修复和代码更改尽可能简单。它们只应影响与任务相关的必要代码，不应影响其他内容。应尽可能少地影响代码。你的目标是不要引入任何错误。一切都关乎简单性。