admin123
/
shop-back-end
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
shop-back-end/CLAUDE.md

10 KiB
Raw Blame History

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

# 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
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

# 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:

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:

# 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