tangweijie
bc40155ef0
- 新增 deploy/ 目录包含 Docker 部署配置、数据库脚本、部署脚本 - 更新 .gitignore 忽略 deploy 构建产物 - 添加 AGENTS.md AI Agent 指南 - 添加项目构建脚本 build.sh
155 lines
4.5 KiB
Markdown
155 lines
4.5 KiB
Markdown
# 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`
|