# 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

```bash
# 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.