weather-data/system-common/CLAUDE.md

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