# CLAUDE.md - system-common

This file provides guidance to Claude Code when working in the system-common module.

## Purpose

Shared library module used by all other backend modules. Provides base classes, utilities, and cross-cutting concerns. This module has no main class and is not runnable on its own.

## Base Class Hierarchy

### BaseEntity (`com.weather.common.entity.BaseEntity`)

All entities must extend this. Provides:
- `id` (Long, `@TableId`)
- `creator` (Long, `@TableField(fill = INSERT)`)
- `createDate` (Date, `@TableField(fill = INSERT)`)

### BaseDao (`com.weather.common.dao.BaseDao<M, T>`)

Extends MyBatis-Plus `BaseMapper<T>`. Provides `getById(Long id)` as an alias.

### Service Layer

```
BaseService<T>                    # tag interface
  └── CrudService<T, D>          # page/list/get/save/update/delete
        └── BaseServiceImpl<M, T> # dao injection + insert/updateById wrappers
              └── CrudServiceImpl<M, T, D>  # generic CRUD with getWrapper()
```

`CrudServiceImpl` is the key base class for all business services. Subclasses only need to implement `getWrapper(Map<String, Object> params)` to define query conditions. Entity-to-DTO conversion uses `ConvertUtils.sourceToTarget()`.

## Redis

- `RedisConfig`: Creates `RedisTemplate<String, Object>` with Jackson JSON serialization
- `RedisUtils`: Wraps `RedisTemplate` operations -- `set/get/delete/deleteByPattern/hGet/hSet/hDelete/expire`
- `RedisKeys`: Static factory for standardized key names (e.g. `getWeatherSummarizeKey()`, `getWeatherSummarizePattern()`)
- `RedisAspect`: AOP aspect that logs Redis operation errors

## Validation

- `ValidatorUtils`: Bean Validation wrapper using Jakarta Validator
- `AssertUtils`: Assertion helpers that throw `CommonException` on failure
- `group/`: Validation groups -- `AddGroup`, `UpdateGroup`, `DefaultGroup`

## XSS Protection

- `XssFilter`: Servlet filter that wraps requests with `XssHttpServletRequestWrapper`
- `XssUtils`: HTML entity encoding using Jsoup

## Exception Handling

- `CommonException`: Application-level runtime exception with error code
- `ExceptionUtils`: Factory methods for creating typed exceptions
- `ErrorCode`: Interface with error code constants

## Utilities

- `ConvertUtils`: Bean copy with recursive conversion support for nested objects
- `DateUtils`: Date parsing/formatting
- `JsonUtils`: JSON serialization via Jackson
- `TreeUtils`: Build tree structures from flat lists (used for menus, depts, regions)
- `HttpContextUtils`: Servlet request/response helpers
- `IpUtils`: Extract client IP from request
- `MessageUtils`: i18n message resolution
- `SpringContextUtils`: Access Spring ApplicationContext statically
- `Result<T>`: Standard API response wrapper with `code`, `msg`, `data`
- `PageData<T>`: Paginated response with `total`, `list`
- `TreeNode`: Tree node interface with `getId/setId/getPid/setPid/getChildren/setChildren`