shop-back-end/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is **AgileBoot** - a Spring Boot 2.7.10 + Vue3 full-stack development framework with **DDD/CQRS architecture**. The project specializes in e-commerce business scenarios and integrates Enterprise WeChat, WeChat Pay, and Smart Cabinet systems.

**Key Features:**
- DDD (Domain-Driven Design) with CQRS pattern
- Multi-level caching (Caffeine + Guava + Redis)
- Enterprise WeChat integration (supports corpid)
- Smart cabinet device management
- WeChat Pay integration (JSAPI)
- JWT-based authentication with Spring Security

## Technology Stack

- **Backend**: Spring Boot 2.7.10, Java 8
- **Database**: MySQL 8.0, MyBatis Plus 3.5.2
- **Cache**: Caffeine (local), Redis (distributed), Guava (config)
- **Security**: Spring Security + JWT
- **Documentation**: SpringDoc OpenAPI 3.0
- **Build Tool**: Maven 3.9+ (use `./mvnw` wrapper)
- **Testing**: JUnit, Mockito

## Project Structure

```
agileboot (multi-module Maven project)
├── agileboot-admin          # Management backend interface module
├── agileboot-api            # Open API module (for clients)
├── agileboot-common         # Common utilities module
├── agileboot-domain         # Business domain module (DDD)
├── agileboot-infrastructure # Infrastructure module (config, integration)
└── agileboot-orm            # ORM configuration (legacy)

agileboot-domain (DDD structure - CQRS pattern)
├── {business-module}/
│   ├── command/             # Command objects (data update)
│   ├── dto/                 # Data Transfer Objects
│   ├── query/               # Query objects (data retrieval)
│   ├── model/               # Domain models
│   ├── db/                  # Database layer
│   │   ├── entity/          # Entity classes
│   │   ├── service/         # Database service
│   │   └── mapper/          # MyBatis mapper
│   └── {Module}ApplicationService.java  # Application service layer
```

## Common Commands

### Build and Run

```bash
# Build entire project
./mvnw clean install

# Build specific module
./mvnw clean package -pl agileboot-admin -am

# Build with tests (tests are skipped by default)
./mvnw clean package -pl agileboot-admin -am -DskipTests=false

# Run tests
./mvnw test
./mvnw test -pl agileboot-domain  # Test specific module
./mvnw test -Dtest=UserModelTest  # Run single test class

# Use build script
build.bat

# Run admin module
cd agileboot-admin
./mvnw spring-boot:run

# Or run with embedded database/Redis
java -jar agileboot-admin/target/agileboot-admin.jar
```

### Application Profiles

**Configuration file**: `agileboot-admin/src/main/resources/application.yml`

- **dev**: Development profile (MySQL + Redis required)
- **test**: Test profile (embedded H2 + embedded Redis)
- **prod**: Production profile

```yaml
spring:
  profiles:
    active: basic,dev  # Change to basic,test for embedded services

agileboot:
  embedded:
    mysql: true   # Set to true to use H2 (no external DB needed)
    redis: true   # Set to true to use embedded Redis
```

**Startup classes:**
- Admin module: `com.agileboot.admin.AgileBootAdminApplication`
- API module: `com.agileboot.api.AgileBooApiApplication`
- Integration tests: `com.agileboot.integrationTest.IntegrationTestApplication`

### Running the Application

```bash
# With external MySQL and Redis (default dev profile)
1. Import database: sql/agileboot_*.sql (latest version)
2. Configure: agileboot-admin/src/main/resources/application-dev.yml
3. Run: ./mvnw spring-boot:run -pl agileboot-admin

# Without external dependencies (test profile)
1. Change spring.profiles.active to: basic,test
2. Set agileboot.embedded.mysql: true
3. Set agileboot.embedded.redis: true
4. Run: ./mvnw spring-boot:run -pl agileboot-admin
```

**Access points:**
- API Documentation: http://localhost:8080/v3/api-docs
- Druid Monitor: http://localhost:8080/druid/ (admin/123456)
- Login credentials: admin/admin123

## Architecture Patterns

### Request Flow (CQRS)

**Queries**: Controller → `{Module}Query` → `{Module}ApplicationService` → `{Module}Service` (Db) → `{Module}Mapper`

**Commands**: Controller → `{Module}Command` → `{Module}ApplicationService` → `{Module}Model` → save/update

### Module Organization

Each business domain follows DDD structure. Example: `agileboot-domain/src/main/java/com/agileboot/domain/{module}/`

- **command/**: Command objects for data updates (Create/Update/Delete)
- **query/**: Query objects for data retrieval
- **dto/**: Data transfer objects for API responses
- **model/**: Domain models with business logic
- **db/**: Data access layer (entity, service, mapper)
- **ApplicationService**: Transaction script layer, orchestrates domain models

## Business Modules

Core modules in `agileboot-domain`:
- **system**: User, role, menu, dept, config, log, notice, post
- **cabinet**: Smart cabinet device management
- **shop**: E-commerce (products, orders)
- **wx**: WeChat user integration
- **qywx**: Enterprise WeChat integration (supports corpid)
- **ab98**: User management with tags and balance
- **mqtt**: MQTT server integration
- **asset**: Asset management

## Caching System

**Multi-level cache architecture:**
1. **Caffeine** (local): User, role, post, login user cache
2. **Guava** (config): System config, dict data, dept data
3. **Redis** (distributed, optional): Session, captcha, distributed locks

**Key classes:**
- `agileboot-infrastructure/src/main/java/.../cache/`
- `CacheCenter`: Cache management
- `AbstractCaffeineCacheTemplate`: Caffeine cache template

## Key Configuration Files

- `pom.xml`: Maven parent POM with all dependencies
- `GoogleStyle.xml`: Code formatting template (required for IntelliJ)
- `application.yml`: Main config (profiles, embedded services)
- `application-dev.yml`: Dev database/Redis config
- `application-test.yml`: Test with H2/embedded Redis
- `sql/`: Database migration scripts (latest first)

## Testing

**Test structure**: Each module has `src/test/java/`
- Unit tests in `*Test.java`
- Integration tests in `*IntegrationTest.java`

**Running tests:**
```bash
# All tests
./mvnw test

# Specific module
./mvnw test -pl agileboot-domain

# Single test class
./mvnw test -Dtest=UserModelTest

# With coverage
./mvnw jacoco:report  # If JaCoCo configured
```

**Note**: Tests are skipped by default in build (`<skipTests>true</skipTests>` in parent POM). Set `-DskipTests=false` to run them.

## Code Standards

**Required:**
- Import `GoogleStyle.xml` into IntelliJ: Settings → Editor → Code Style → Java → Import Schema
- Properties files encoding: Settings → Editor → File Encodings → Properties Files → Set to UTF-8
- Use enums instead of dictionary type data
- Centralized error handling with error codes
- Write unit tests for business logic

**IDE Setup:**
- **IntelliJ IDEA** (recommended)
- Lombok plugin installed
- Google code style applied

## Important Business Features

### Enterprise WeChat Integration
- Supports `corpid` field for multi-tenant enterprise WeChat
- Module: `agileboot-domain/qywx/`
- Documentation: `doc/智能柜系统指南.md`

### Smart Cabinet System
- Device management with cabinet/cell hierarchy
- Real-time cell status monitoring
- Operation logging (open/close/lock)
- Module: `agileboot-domain/cabinet/` and `agileboot-admin/controller/cabinet/`

### WeChat Pay Integration
- JSAPI payment support
- Refund functionality
- Module: `agileboot-domain/shop/`
- Documentation: `doc/微信支付集成指南.md`

## Database Schema

**Core tables** (~10 core tables in AgileBoot):
- `sys_user`, `sys_role`, `sys_menu`, `sys_dept`
- `sys_config`, `sys_dict_type`, `sys_notice`
- Plus business tables (cabinet, shop, ab98_user, etc.)

**Migration files** in `sql/` directory (latest first):
- `agileboot-*.sql`: Base schema
- `YYYYMMDD_*.sql`: Feature migrations (e.g., 20251029_wx_user.sql)

## Development Workflow

1. **New Feature**:
   - Create domain module in `agileboot-domain/{feature}/`
   - Implement DDD structure (command, query, model, db, service)
   - Add controllers in `agileboot-admin/controller/{feature}/`
   - Write unit tests
   - Update database with migration script

2. **Database Changes**:
   - Create new migration: `sql/YYYYMMDD_feature_name.sql`
   - Update CodeGenerator if needed
   - Test with test profile (H2 + embedded Redis)

3. **API Development**:
   - Document with `@Operation` annotation
   - Use proper DTOs
   - Add to `application.yml` springdoc group-configs if needed

## Troubleshooting

**Port 8080 busy**: Change `server.port` in `application.yml`

**Redis port conflict**: Modify `spring.redis.port` in `application-dev.yml`

**MacOS embedded Redis**: High versions may not support embedded Redis - use external Redis

**Build fails**: Check Java version (requires Java 8+), Maven 3.9+, ensure `./mvnw clean install` succeeds

## Documentation

- **README.md**: Project overview and setup guide
- **doc/项目概述.md**: Detailed architecture overview
- **doc/智能柜系统指南.md**: Smart cabinet system guide
- **doc/缓存系统指南.md**: Caching system guide
- **doc/微信支付集成指南.md**: WeChat Pay integration guide

## Recent Commits (for context)

```
eb41f35 feat(wx): 添加微信小程序登录功能支持
9562d1c 登录接口更新用户登录信息修复
7cd08c1 refactor(docs): 重构文档结构并迁移docker安装指南
e53ff77 feat(智能柜): 添加corpid字段支持企业微信集成
ddc3c91 feat: 添加企业微信用户ID缓存功能
```

## Tips

- Use test profile for quick development without external dependencies
- Check `application-dev.yml` for database/Redis configuration
- Druid monitor at `/druid/` shows SQL performance
- API docs available at `/v3/api-docs` and `/swagger-ui.html`
- Code style: Strictly follow GoogleStyle.xml formatting
- All business logic should have unit tests
- Domain models contain business logic, ApplicationService is transaction script layer
- Use multi-level cache for performance-critical data