Wisdom-Data/CLAUDE.md

CLAUDE.md

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

Project Overview

This is RuoYi v3.9.0 (若依), a Chinese Spring Boot + Vue admin framework customized for IoT/Energy Storage Management (储能运营平台). It extends the standard RuoYi RBAC system with IoT device management, time-series data ingestion, MQTT messaging, and vehicle/equipment tracking.

• Backend: Spring Boot 2.5.15, Java 8, Spring Security 5.7.12, JWT authentication
• Frontend: Vue 2 + Element UI (separate repository, not in this workspace)
• Documentation: http://doc.ruoyi.vip

Build & Run Commands

This is a Maven multi-module project. All commands should be run from the repository root.

# Compile all modules
mvn clean compile

# Package into executable JAR (skips tests — there are no tests in this project)
mvn clean package -Dmaven.test.skip=true

# Run the application (after packaging)
cd ruoyi-admin/target
java -jar ruoyi-admin.jar

# Or use the provided script
./ry.sh start    # start / stop / restart / status

The application starts on port 8887. The executable JAR is ruoyi-admin/target/ruoyi-admin.jar.

Module Architecture

ruoyi-admin       → Web layer: REST controllers, Swagger config, application.yml entrypoint
ruoyi-framework   → Infrastructure: Spring Security config, JWT filter, Druid datasource,
                    Redis config, MyBatis config, AOP aspects (logging, rate limit, data scope)
ruoyi-system      → Business layer: domain models, mappers (MyBatis), services,
                    service implementations — this is where custom IoT logic lives
ruoyi-common      → Shared utilities: constants, enums, exception types, utils (StringUtils,
                    SecurityUtils, DateUtils, ServletUtils, etc.)
ruoyi-quartz      → Scheduled job engine (standard RuoYi)
ruoyi-generator   → Code generation templates (standard RuoYi)

Dependency flow: admin → framework → system → common. quartz and generator are optional add-ons.

Data Architecture

Dual MySQL Databases (Druid connection pool)

• Master (data): RuoYi system tables (users, roles, menus, logs, custom business tables)
• Slave (cnc): Secondary data — configured in application-druid.yml
• Both hosted on 47.104.204.180:3306
• Dynamic datasource switching via @DataSource annotation

TDengine (Time-Series Database)

• Used for high-frequency IoT telemetry ingestion
• Connection pool: HikariCP via TDengineService (ruoyi-system/.../service/TDengineService.java)
• Connects to jdbc:TAOS://localhost:6030/
• Super-table pattern: CREATE STABLE ... (ts TIMESTAMP, surfacename VARCHAR(64)) TAGS (location BINARY(64))
• Column caching in memory (stableColumnCache) to avoid repeated DESCRIBE calls

Redis

• Host: localhost:6379
• Key patterns used by custom code:
  • DSB:active:devices — Set of active IoT device Redis keys
  • DSB:<controllerId>:<metricName> — Hash storing device telemetry fields
  • workorder:coordinate:<controllerId> — Hash storing vehicle GPS (latitude, longitude)
  • <controllerId>:<topicName> / <controllerId>_cmd:<topicName> / <controllerId>_fault:<topicName> — MQTT topic metadata

Custom Business Domains (Beyond Standard RuoYi)

Standard RuoYi provides users, roles, menus, depts, posts, dicts, config, notices, operlog, logininfor. This project adds:

Domain	Purpose	Key Files
SysDevice	IoT device telemetry key-value storage	domain/SysDevice.java, mapper/SysDeviceMapper.java, service/SysDeviceService.java
SysDeviceControl	Device configuration / metric whitelist	domain/SysDeviceControl.java, service/SysDeviceControlService.java
SysDeviceVo	Aggregated device view for frontend	domain/vo/SysDeviceVo.java, service/SysDeviceVoService.java
SysCar	Vehicle/equipment with GPS tracking	domain/SysCar.java, service/SysCarService.java
SysAlarm	Alarm events from devices	domain/SysAlarm.java, service/SysAlarmService.java
SysFault	Fault records	domain/SysFault.java, service/SysFaultService.java
SysWorkorder	Work orders / service tickets	domain/SysWorkorder.java, service/SysWorkorderService.java
SysCompany	Partner company management	domain/SysCompany.java, service/SysCompanyService.java
SysIndicators	Daily business KPIs (order count, profit)	domain/SysIndicators.java, service/SysIndicatorsService.java
SysController	MQTT topic registry per controller	domain/SysController.java, service/SysControllerService.java
Sysrealtime	Real-time device data sync from Redis → MySQL	domain/Sysrealtime.java, service/SysrealtimeService.java
ControllerData / topics	DTOs for MQTT JSON payload parsing	domain/ControllerData.java, domain/topics.java
MqttClientWrapper	Wrapper around Eclipse Paho MQTT client	domain/MqttClientWrapper.java

IoT Data Flow

MQTT Broker (47.104.204.180:1883)
    ↓  subscribes to "+/generics"
TdengineController2 / TdegnineController3 (MQTT listeners)
    ↓  parse JSON → ControllerData → topics
    ├─→ Redis (DSB:active:devices, DSB:<id>:<metric> hashes)
    ├─→ MySQL (sys_controller table — topic registry)
    └─→ TDengine (time-series telemetry)

SysCarController (scheduled tasks, every 30s)
    ↓ reads Redis DSB:* keys
    ├─→ syncs to sysrealtime (MySQL)
    ├─→ updates vehicle GPS in sys_car (MySQL)
    ├─→ updates sys_indicators KPIs (MySQL)
    └─→ triggers external webhook (https://esos-iot.com:9443/syscar/trigger)

There are 4 @Scheduled(fixedRate = 30000) tasks in SysCarController:

1. updatesyscar() — sync vehicle GPS from Redis to MySQL, trigger webhook on change
2. insertdevice() — sync device config from Redis to sys_device_vo
3. syncRedisToMySQL() — sync telemetry from Redis to sysrealtime
4. insertindicators() — aggregate daily KPIs per company into sys_indicators

Key Configuration Files

• ruoyi-admin/src/main/resources/application.yml — Main config (port 8887, Redis, MyBatis, PageHelper, Swagger, token settings)
• ruoyi-admin/src/main/resources/application-druid.yml — Database connection (master/slave MySQL, Druid pool)
• ruoyi-admin/src/main/resources/mybatis/mybatis-config.xml — MyBatis global settings
• ruoyi-admin/src/main/resources/logback.xml — Logging config

Authentication & Security

• JWT-based stateless auth (token header: Authorization)
• Spring Security config in ruoyi-framework/.../config/SecurityConfig.java
• JWT filter: JwtAuthenticationTokenFilter.java
• Password max retry: 5 attempts, lock time: 10 minutes
• Swagger enabled at /dev-api path mapping
• XSS filtering enabled for /system/*, /monitor/*, /tool/*

API Response Format

All controllers return AjaxResult (from ruoyi-common), which wraps:

{
  "code": 200,          // HttpStatus constant
  "msg": "操作成功",     // message
  "data": { ... }       // payload
}

Page queries use TableDataInfo which wraps:

{
  "code": 200,
  "msg": "查询成功",
  "rows": [ ... ],      // list data
  "total": 100          // total count
}

Important Implementation Notes

• No unit tests exist in this project. Test coverage is 0%.
• Field injection is used everywhere (@Autowired on fields), not constructor injection.
• MyBatis mappers are Java interfaces with XML mapping files in src/main/resources/mapper/
• Dynamic SQL provider: ruoyi-system/.../mapper/DynamicSqlProvider.java provides programmatic SQL for some queries
• Service naming convention: RuoYi standard services use ISysXxxService interface + SysXxxServiceImpl implementation. Custom services (added by this project) often omit the I prefix and use concrete classes directly.
• TDengine SQL is built with string concatenation in TDengineService.java — be careful with SQL injection if user input reaches those paths.
• MQTT credentials are hardcoded in TdengineController2.java and TdegnineController3.java.
• Database passwords are in plaintext in application-druid.yml.
• The project uses Alibaba Maven mirror (https://maven.aliyun.com/repository/public) configured in root pom.xml.