xlcp/AGENTS.md

AGENTS.md

This file provides guidance for AI agents working on the XL Prison Management System codebase.

Project Overview

XL监狱综合管理平台 - A prison management platform built on the Yudao (芋道) framework.

Tech Stack: Java 17, Spring Boot 3.5.9, MyBatis-Plus, Vue 3.5.12, TypeScript 5.3.3, Element Plus, MySQL 8.0+

Essential Commands

Backend (Maven)

# Build all modules
cd backend && mvn clean install -DskipTests

# Build prison module only
cd backend/yudao-module-prison && mvn clean package

# Run dev server (port 48080)
cd backend/yudao-server && mvn spring-boot:run

# Run all tests
cd backend/yudao-module-prison && mvn test

# Run single test class
mvn test -Dtest=PrisonAreaControllerTest

# Force update dependencies
mvn clean install -U

Frontend (pnpm)

cd frontend

# Install dependencies
pnpm install

# Dev server (local mode)
pnpm dev

# TypeScript checking
pnpm ts:check

# Build for different environments
pnpm build:local   # Uses .env.local
pnpm build:dev     # Uses .env.dev
pnpm build:prod    # Uses .env.prod

# Linting
pnpm lint:eslint   # ESLint check & fix (.js,.ts,.vue)
pnpm lint:format   # Prettier format
pnpm lint:style    # Stylelint fix

Quick Start with Make

make frontend      # Start frontend dev server
make backend       # Start backend dev server
make run           # Start both

Code Style Guidelines

Java (Backend)

Imports: Grouped by: Spring → Yudao → Third-party → Java stdlib. No wildcard imports.

Naming Conventions:

• Classes: PascalCase (e.g., PrisonAreaController, ScoreDO)
• Variables/Methods: camelCase (e.g., getPage(), updateTime)
• Constants: UPPER_SNAKE_CASE (e.g., DEFAULT_PAGE_SIZE)
• Package: cn.iocoder.yudao.module.prison.{module}

VO Naming: SaveReqVO, PageReqVO, RespVO suffixes required.

Annotations: Place on separate lines. Order: @RestController → @RequestMapping → @Tag → @PreAuthorize.

Error Handling: Use CommonResult<T> return type. Throw ServiceException for business errors with error codes from ErrorCodeConstants.

Comments: No comments unless explaining complex business logic. Javadoc only on public APIs.

TypeScript/Vue (Frontend)

Imports: Sorted alphabetically. No unused imports. Use absolute imports (@/).

Naming:

• Interfaces: PascalCase (e.g., Area, QuestionnaireRecord)
• Variables/Props: camelCase
• Components: PascalCase file names, kebab-case usage

Types: Avoid any. Use explicit types or unknown for union types.

Vue Composition API: Use <script setup lang="ts">. Use composables from @/hooks.

Formatting: Use Prettier (80 char line width). Vue single-file components: <script> → <template> → <style>.

Error Handling: Wrap async API calls in try/catch with user feedback.

Architecture Patterns

Backend Structure

controller/admin/{module}/    # REST API + VOs
service/{module}/             # Business logic
dal/dataobject/{module}/      # MyBatis-Plus entities
dal/mysql/{module}/           # Mappers
convert/{module}/             # MapStruct converters
enums/                        # Enum definitions

Frontend Structure

views/prison/{module}/        # Page components
api/prison/{module}/          # API definitions + types
types/                        # Shared TypeScript types
hooks/                        # Composables

Data Flow

Vue Component → API Layer → Controller → Service → Mapper → MySQL

Database Conventions

• Table prefix: prison_{module} (e.g., prison_area, prison_score)
• Common fields: id, creator, create_time, updater, update_time, deleted, tenant_id
• Soft delete via deleted bit(1) field
• Use existing SQL migration scripts in backend/sql/

API Conventions

• Base path: /admin-api/prison/{module}
• Permission pattern: prison:{module}:{action} (e.g., prison:area:create)
• Mock auth: Authorization: Bearer emsoft{userId} + tenant-id: 1 header

Cursor Rules

• Follow CLAUDE.md for technical decisions
• Reference .cursor/rules/usecluade.mdc for Chinese language context

Testing

• Backend tests: src/test/java/... with -Test suffix
• Run specific test: mvn test -Dtest=ClassName
• Frontend: Manual testing via pnpm dev + browser dev tools

Important Notes

• Never commit secrets or credentials
• Use mock mode for API testing (enabled in application-local.yaml)
• Default backend port: 48080
• Use pnpm for frontend, not npm or yarn