sql server+java版本的数采平台
编辑 | blame | 历史 | 原始文档

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)
  1. 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
  1. 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)
  1. 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 文件中添加审查部分，总结所做的更改和其他相关信息
开发原则
⦁ 不懒惰: 绝不懒惰。如果有错误，找到根本原因并修复它。不要使用临时修复。你是一名高级开发人员，绝不懒惰。
⦁ 简单性: 使所有修复和代码更改尽可能简单。它们只应影响与任务相关的必要代码，不应影响其他内容。应尽可能少地影响代码。你的目标是不要引入任何错误。一切都关乎简单性。