claude

CLAUDE.md

@@ -0,0 +1,125 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Java-based NFT (Non-Fungible Token) API built with the JFinal framework. The application provides RESTful APIs for NFT trading, user management, payment processing, and order management.
+
+## Technology Stack
+
+- **Framework**: JFinal 5.0.5 with Undertow server
+- **Java Version**: Java 8
+- **Database**: MySQL 8.0 with Druid connection pool
+- **Build Tool**: Maven
+- **Key Libraries**: FastJSON, Hutool, BouncyCastle (for cryptography), SLF4J + Logback
+- **Payment Integration**: Allinpay SDK, BSN (Blockchain Service Network)
+- **SMS Service**: JD Cloud SMS
+- **Containerization**: Docker
+
+## Development Commands
+
+### Maven Commands
+```bash
+# Clean and compile
+mvn clean compile
+
+# Run tests
+mvn test
+
+# Package application (creates executable JAR)
+mvn clean package -DskipTests
+
+# Run application locally (requires environment variables)
+java -jar target/dalian-nft-api.jar
+
+# Run with environment variables
+DB_PASSWORD=123456 DB_URL=jdbc:mysql://mysql-container:3306/dalian-nft-db DB_USER=root DEV_MODE=0 UPLOAD_BASE_PATH=/app/uploads URL_BASE=http://117.72.208.239 java -jar target/dalian-nft-api.jar
+```
+
+### Docker Commands
+```bash
+# Build Docker image
+docker build -t dalian-nft-api .
+
+# Run with Docker Compose (if available)
+docker-compose up -d
+
+# Manual Docker run with environment variables
+docker run -d --name nft-api -p 8888:8888 --network dalian-nft-network \
+  -e DB_URL=jdbc:mysql://mysql-container:3306/dalian-nft-db \
+  -e DB_USER=root \
+  -e DB_PASSWORD=your_password \
+  -e DEV_MODE=0 \
+  dalian-nft-api
+```
+
+## Architecture Overview
+
+### Core Structure
+The application follows JFinal's MVC pattern with these key components:
+
+- **Controllers** (`src/main/java/modules/*/`): Handle HTTP requests and responses
+- **Services** (`src/main/java/modules/*/`): Business logic layer
+- **Models** (`src/main/java/common/model/`): Active Record pattern data models
+- **Interceptors** (`src/main/java/common/interceptor/`): Cross-cutting concerns (auth, validation, exceptions)
+- **Utils** (`src/main/java/common/utils/`): Shared utilities including payment SDKs
+
+### Key Modules
+- **User Management**: Registration, authentication, balance management
+- **NFT Trading**: NFT creation, trading, status maintenance
+- **Order Processing**: Order lifecycle management with status tracking
+- **Payment Integration**: Multiple payment providers (Allinpay, BSN)
+- **File Upload**: Media file handling for NFT assets
+- **News Management**: Content management system
+
+### Database Layer
+- Uses JFinal's Active Record pattern with auto-generated base models
+- Models inherit from `common.model.base.Base*` classes
+- SQL mappings defined in `_MappingKit.java`
+- Custom SQL templates in `src/main/java/common/all.sqlt` (referenced but file may be in resources)
+
+### Background Tasks
+- `OrderStatusMaintenanceTask`: Updates order statuses
+- `NfttStatusMaintenanceTask`: Maintains NFT statuses
+- `WithdrawMaintenanceTask`: Processes withdrawal requests
+- Uses a custom `TaskScheduler` with thread pool management
+
+### Environment Configuration
+Critical environment variables:
+- `DB_URL`, `DB_USER`, `DB_PASSWORD`: Database connection
+- `DEV_MODE`: Enable/disable development mode (0=production, 1=development)
+- `URL_BASE`, `URL_BASE_ADMIN`: Base URLs for API endpoints
+- `UPLOAD_BASE_PATH`: File upload directory
+- Payment provider credentials (BSN, JD, Allinpay, HYG)
+
+## Security Considerations
+
+The application integrates with multiple payment and blockchain services:
+- BSN (Blockchain Service Network) for NFT operations
+- Allinpay SDK for payment processing
+- HYG (慧用工) for payment services
+- RSA/AES encryption utilities in `common.utils.hyg`
+
+## Database Setup
+
+Use Docker to set up MySQL:
+```bash
+# Create network
+docker network create dalian-nft-network
+
+# Run MySQL container
+docker run -d --name mysql-container --network dalian-nft-network \
+  -p 3306:3306 -v /path/to/data:/var/lib/mysql \
+  -e MYSQL_ROOT_PASSWORD=your_password \
+  -e MYSQL_ROOT_HOST=% mysql:8.0
+```
+
+## Development Notes
+
+- Main application entry point: `common.jfinal.AppConfig.main()`
+- Server runs on port 8888 by default
+- Uses Maven Shade plugin to create fat JAR with all dependencies
+- CORS handling configured via `AllCorsHandler`
+- Global interceptors handle exceptions, validation, and role-based access
+- SQL logging can be enabled via `arp.setShowSql(true)` in AppConfig