# 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)
```bash
# 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)
```bash
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
```bash
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`