108 lines
4.8 KiB
Markdown
108 lines
4.8 KiB
Markdown
|
# 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.
|