# AGENTS.md

## Repo

Fork of [renren-security](https://gitee.com/renrenio/renren-security) customized as a weather-data management system. Spring Boot 3.5.x multi-module Maven project, Java 17.

## Quick start

```bash
mvn clean install -DskipTests
```

Run `AdminApplication.java` (`system-admin/`), context path `/system-admin`, port 8080. DB = `weather_data_system` (MySQL). Init from `system-admin/db/mysql.sql`. Default admin: `admin` / `admin` (pw encoded w/ BCrypt).

Tests are **skipped by default** (`<skipTests>true</skipTests>` in pom). If running tests, pass `-DskipTests=false`.

## Modules

| Module | Purpose |
|---|---|
| `system-admin` | Main admin backend. Entrypoint: `com.weather.AdminApplication` |
| `system-api` | API service (separate process). Entrypoint: `com.weather.ApiApplication` |
| `system-common` | Shared lib: base entities, utils, Redis, XSS, validators |
| `system-dynamic-datasource` | Multi-DS support (stub, not populated) |
| `renren-generator` | Code generator. Entrypoint: `com.weather.GeneratorApplication` |

All sub-modules depend on `system-common`. Maven repo: Aliyun mirror.

## Key framework choices

- **Security**: Apache Shiro 1.12 (Jakarta classifier) with OAuth2 token auth, not Spring Security.
- **ORM**: MyBatis-Plus 3.5.8. Mapper XMLs in `src/main/resources/mapper/**/*.xml`.
- **Scheduled tasks**: Quartz via `schedule_job` table. All tasks implement `ITask` interface and are `@Component`-named beans. Jobs auto-register at startup via `JobCommandLineRunner`.
- **Data permissions**: `@DataFilter` annotation + `DataFilterAspect`. Dept-based filtering injected into MyBatis via `DataFilterInterceptor`.
- **Auto-fill**: `FieldMetaObjectHandler` fills `creator`/`createDate`/`updater`/`updateDate`.
- **API docs**: Knife4j (Swagger UI) at `/doc.html` when enabled (disabled by default).
- **Redis**: Optional. Toggle via `project-options.redis.open: false`.
- **Validation**: Hibernate Validator. XSS filter via custom `XssFilter`.
- **Excel**: EasyExcel. Async import with progress tracking (`WeatherDataImportManager`).

## Custom weather module (`modules/weather/`)

- `dailydata/` — daily weather observations. Supports Excel batch import (async, via `EasyExcel` listener pattern).
- `station/` — weather station CRUD. Stations are linked to departments (`dept_id`).
- `filescan/` — file scanning module (receive/display/archive). WatchService primary + Quartz fallback. Files served via `FileDownloadController` (`/filescan/file/display/{id}`).

## Database

- Scripts in `system-admin/db/` (mysql.sql + Oracle/SQLServer/PostgreSQL/Dameng variants).
- Custom tables: `weather_daily_data`, `weather_station`.

## Conventions

- `Result` wrapper class for all API responses (in `system-common`).
- `CrudService`/`BaseService` pattern for service layer.
- DTO/Entity/Excel VO separation per module.
- PK strategy: `ASSIGN_ID` (Snowflake via `IdUtil.getSnowflakeNextId()`).
- Lombok everywhere (`@Data`, `@AllArgsConstructor`, `@Slf4j`).

## Gotchas

- Do **not** introduce Spring Security dependencies — project uses Shiro exclusively.
- Swagger (Knife4j) is **disabled by default** (`knife4j.enable: false`). Enable in dev profile.
- `schedule_job` table seed includes a test task `testTask` (paused by default). New tasks must be `@Component("beanName")` implementing `ITask`.
- The `system-dynamic-datasource` module is a placeholder. Multi-DS config in `application-dev.yml` is commented out.
- No frontend sources in this repo (separate `renren-ui` Vue3 project).
- `.gitignore` excludes `.idea/` but `.idea/` is tracked (committed IDE config).