weather-data/CLAUDE.md

CLAUDE.md

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

See also AGENTS.md for module breakdown, framework choices, conventions, and gotchas. This file supplements it with build commands and architectural patterns.

Build & Run

# Full build (tests skipped by default per pom.xml <skipTests>true</skipTests>)
mvn clean install -DskipTests

# Build with tests
mvn clean install -DskipTests=false

# Run single test class
mvn -pl system-admin -DskipTests=false -Dtest=YourTestClass test

Run applications from IntelliJ:

• Admin backend: com.weather.AdminApplication (system-admin/) — port 8080, context path /system-admin
• API service: com.weather.ApiApplication (system-api/) — port 8081
• Code generator: com.weather.GeneratorApplication (renren-generator/)

Database: weather_data_system (MySQL). Init from system-admin/db/mysql.sql. Default admin: admin / admin.

Architecture

Multi-module Maven project (Java 17, Spring Boot 3.5.x)

weather-data (pom)
├── system-common        → shared lib (all modules depend on this)
├── system-admin         → main admin backend
├── system-api           → external API service
├── system-dynamic-datasource → multi-DS support (placeholder)
└── renren-generator     → code generator

Service layer pattern

All services extend one of two base classes from system-common:

• CrudService<Dao, Entity, DTO> — generic CRUD with page(), get(), save(), update(), delete(). The DTO type param is used for query criteria wrapping.
• BaseService<Dao> — lighter base without DTO generic.

New modules follow this convention:

modules/<name>/
├── controller/  → @RestController, returns Result
├── dao/         → extends BaseMapper<Entity> (MyBatis-Plus)
├── dto/         → request/query DTOs (often extends BaseEntity for auto-fill)
├── entity/      → @TableName JPA entity
├── service/     → interface extends CrudService/BaseService
│   └── impl/    → @Service implementation
├── excel/       → EasyExcel VO classes (optional)
└── vo/          → response VO classes (optional)

Mapper XMLs: src/main/resources/mapper/<domain>/**/*.xml

Key cross-cutting mechanisms

Mechanism	How it works
Data permissions	@DataFilter annotation on controller → DataFilterAspect → DataFilterInterceptor injects dept-based SQL filtering into MyBatis
Auto-fill	FieldMetaObjectHandler fills creator/createDate/updater/updateDate via MyBatis-Plus meta-object handler
Scheduled jobs	Quartz. Jobs in schedule_job table, implement ITask, annotated @Component("beanName"). JobCommandLineRunner auto-registers at startup
File scanning	Three-part weather module: WatchService (primary, FileWatchServiceManager) + Quartz fallback (FileScanTask) + startup scan (FileScanStartupRunner). Files served via FileDownloadController
Excel import	EasyExcel with async progress tracking via WeatherDataImportManager
API responses	Always wrapped in Result class (system-common)
Validation	Hibernate Validator on DTOs. XSS filter via XssFilter

PK strategy

ASSIGN_ID (Snowflake via IdUtil.getSnowflakeNextId()), set globally in MyBatis-Plus config. All entities extend BaseEntity which declares the id field.

Auth flow

• Apache Shiro 1.12 (Jakarta classifier) with OAuth2 token auth
• Login → get token → pass token header on subsequent requests
• API module (system-api) uses @Login annotation + AuthorizationInterceptor

Redis

Optional, controlled by project-options.redis.open (default false in dev). Cache aspect: RedisAspect.

API docs

Knife4j (Swagger UI) at /doc.html. Disabled by default (knife4j.enable: false). Enable only in dev profile.

Custom Weather Domain

Three sub-modules under system-admin/.../modules/weather/:

Sub-module	Purpose	Key detail
dailydata/	Daily weather observations	Excel batch import (async), EasyExcel listener pattern
station/	Weather station CRUD	Linked to dept via dept_id, data-permission aware
filescan/	File monitoring & serving	WatchService → record → serve via FileDownloadController

File format convention (from 需求文档.md): <地区>地区-<指标>.png for charts, <地区>地区631信息.txt for text data. FileNameParser extracts region/indicator keywords.

Database

Custom tables: weather_daily_data, weather_station, weather_file_scan_record. Seed scripts in system-admin/db/ (mysql.sql + Oracle/SQLServer/PostgreSQL/Dameng variants). Parameter scan_root_path in sys_params controls the file-scan base directory.