AGENTS.md - Agricultural E-commerce Platform

Agricultural product e-commerce management platform with Vue 3 frontend and Spring Boot backend.

Project Structure

agri-platform/
├── backend/                 # Spring Boot (Java 17)
│   └── src/main/java/com/henan/agri/{config,common,user,merchant,product,order,live,category,tag,announcement,statistic,upload}/
├── manage/                  # Vue 3 frontend
│   └── src/{components/pages/services/stores/composables/router}/
├── client/                  # Documentation
└── workspace/               # Scripts, temp files, misc (project-agnostic)

Build/Lint/Test Commands

Frontend (manage directory)

pnpm install          # Install dependencies
pnpm dev              # Development server
pnpm build            # Production build
pnpm lint             # Lint (oxlint + eslint with --fix)
pnpm format           # Format with prettier

Backend (backend directory)

./mvnw spring-boot:run                      # Run backend
./mvnw test                                 # Run all tests
./mvnw test -Dtest=AgriApplicationTests     # Run single test class
./mvnw test -Dtest=AgriApplicationTests#contextLoads  # Run single test method
./mvnw clean package                        # Build JAR
./mvnw clean package -DskipTests            # Build without tests

Quick Management Scripts

Backend Service (workspace/start-backend.ps1)

powershell -File "C:\Users\Tribbt\Desktop\Ming\workspace\start-backend.ps1" start
powershell -File "C:\Users\Tribbt\Desktop\Ming\workspace\start-backend.ps1" stop
powershell -File "C:\Users\Tribbt\Desktop\Ming\workspace\start-backend.ps1" restart
powershell -File "C:\Users\Tribbt\Desktop\Ming\workspace\start-backend.ps1" status
powershell -File "C:\Users\Tribbt\Desktop\Ming\workspace\start-backend.ps1" log
powershell -File "C:\Users\Tribbt\Desktop\Ming\workspace\start-backend.ps1" build

Token Retrieval (workspace/get-tokens.ps1)

powershell -File "C:\Users\Tribbt\Desktop\Ming\workspace\get-tokens.ps1"
powershell -File "C:\Users\Tribbt\Desktop\Ming\workspace\get-tokens.ps1" -listUsers

Tokens saved to .[username].token files. Use token in curl:

TOKEN=$(cat .admin.token)
curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/user/info

API Testing (workspace/test-api.ps1)

powershell -File "C:\Users\Tribbt\Desktop\Ming\workspace\test-api.ps1" -endpoint merchant/list -user admin
powershell -File "C:\Users\Tribbt\Desktop\Ming\workspace\test-api.ps1" -endpoint user/info -user admin
powershell -File "C:\Users\Tribbt\Desktop\Ming\workspace\test-api.ps1" -endpoint merchant/1 -method PUT -body '{"name":"新名称"}' -user admin
powershell -File "C:\Users\Tribbt\Desktop\Ming\workspace\test-api.ps1" -help

Environment & Database

Database

• URL: jdbc:mysql://stivenkuper-mysql.mysql.database.azure.com/agri-platform
• Username: stivenkuper
• Password: Stivenkuper123
• Schema: backend/sql/init.sql

Backend Service

• Port: 8080
• Context: /api
• Base URL: http://localhost:8080/api

Test Accounts

Code Style Guidelines

Frontend (Vue/JavaScript)

• Formatting: No semicolons, single quotes, 100 char width, 2-space indent, LF endings
• Components: Use <script setup> with Composition API; PascalCase filenames
• Imports: Vue first → third-party → local (use relative paths)
• API Services: Named exports, use get/post/put/del from ./api.js
• Styling: TailwindCSS; dark theme; primary color rgb(99 102 241)

import { ref, computed } from 'vue'
import { Loader2 } from 'lucide-vue-next'
import { useToast } from '../composables/useToast'
import * as productApi from '../services/productApi'

Backend (Java/Spring Boot)

• Package Structure: controller/service/mapper/domain/dto/vo/repository/
• Naming: {Name}Entity, {Name}DTO, {Name}VO, {Name}Controller, {Name}Service, {Name}Mapper
• Annotations: Use @RestController, @RequiredArgsConstructor for constructor injection
• Response: All APIs return Result<T> wrapper (Result.success() / Result.error())
• Exceptions: Throw BusinessException for business errors; global handler catches them
• Soft Delete: Entities have isDeleted (0=active, 1=deleted); queries filter isDeleted = 0

@Data
@TableName("product")
public class ProductEntity {
    private Long id;
    @TableField("is_deleted")
    private Integer isDeleted;
}

Authentication

• JWT-based; token in localStorage (token key)
• Headers: Authorization: Bearer {token}, userId: {id}
• Roles: ADMIN, MERCHANT

Common Patterns

Adding a New Backend Module

1. Create package under com.henan.agri.{module}
2. Create Entity (@Data, @TableName), Mapper (extends BaseMapper), DTO (validation), VO
3. Create Service (@Service, @RequiredArgsConstructor) with LambdaQueryWrapper queries
4. Create Controller with Result<T> responses

Adding a New Frontend Page

1. Create component in src/pages/
2. Add route in src/router/index.js
3. Add API service in src/services/
4. Use UI components from src/components/ui/

Global Rules

• Run MySQL queries directly (leave trace in comments)
• Run SQL migration scripts after creating, mark as "已迁移" in comments
• Run curl to test API responses (Windows environment)
• Scripts must be Windows-compatible, non-blocking for services
• Frontend: use pnpm only (no npm)
• Project-agnostic files go in workspace/
• Backend context-path is /api, all endpoints include this prefix

Troubleshooting

Pre-commit Requirements

1. pnpm lint (frontend)
2. ./mvnw compile (backend)
3. ./mvnw test (backend)