AGENTS.md

This document provides guidance for agentic coding tools working on the UrbanOps (urbanops) codebase.

Build & Test Commands

Build Commands

# Clean and compile all modules
mvn clean compile

# Build entire project (skipping tests)
mvn clean install -DskipTests

# Build specific module with dependencies
mvn clean install -DskipTests -pl <module-name> -am

Test Commands

# Run all tests
mvn test

# Run all tests for a specific module
mvn test -pl urbanops-module-system

# Run a single test class
mvn test -Dtest=AdminUserServiceImplTest

# Run a single test method
mvn test -Dtest=AdminUserServiceImplTest#testCreateUser

# Run tests with specific profile
mvn test -Punit-test

Project Structure

• urbanops-server - Main Spring Boot application entry point
• urbanops-module-system - System management (users, roles, permissions, etc.)
• urbanops-module-infra - Infrastructure (files, jobs, configs, code generation)
• urbanops-module-bpm - Business Process Management (Flowable)
• urbanops-module-xxx - Business domain modules (garden, workorder, report, etc.)
• urbanops-framework - Shared framework components (security, redis, mybatis, etc.)
• urbanops-dependencies - Maven dependency version management

Code Style Guidelines

Package Structure

com.zteits.urbanops.module.{module-name}
├── controller/admin    - Admin API controllers
├── controller/app      - App API controllers
├── controller/bridge   - Legacy bridge controllers
├── service/.../impl    - Service implementations
├── dal/dataobject      - Database entities (DO classes)
├── dal/mysql           - MyBatis mappers
├── controller/.../vo   - View Objects (Request/Response VOs)
├── convert             - MapStruct converters
└── enums               - Module-specific enums

Naming Conventions

• Controllers: XxxController (e.g., UserController)
• Services: XxxService (interface) and XxxServiceImpl (implementation)
• Mappers: XxxMapper (e.g., AdminUserMapper)
• Data Objects: XxxDO (e.g., AdminUserDO)
• View Objects: XxxPageReqVO, XxxSaveReqVO, XxxRespVO, XxxSimpleRespVO
• Converters: XxxConvert (MapStruct interface)

Code Organization

• DO classes extend TenantBaseDO or BaseDO, use @TableName, @KeySequence, @Data, @EqualsAndHashCode(callSuper = true), @Builder
• VO classes use @Schema for documentation, @NotBlank/@NotNull/@Size for validation
• Controllers use @Tag, @Operation, @PreAuthorize, @Valid, CommonResult for responses
• Services use @Service, @Slf4j, @Transactional(rollbackFor = Exception.class), @Resource

Error Handling

• Use exception(ErrorCode) from ServiceExceptionUtil to throw business exceptions
• Define error codes in module's ErrorCodeConstants interface
• Error code format: 1-002-xxx-xxx-xxx (system module: 1-002-xxx-xxx-xxx)

Imports & Dependencies

• Organize: standard library → third-party → project packages
• No wildcard imports (e.g., avoid import java.util.*)
• Use Jakarta EE: jakarta.* imports
• Use Spring Boot 3.x and Spring Framework 6.x APIs

Validation

• Use Jakarta Bean Validation: @NotNull, @NotBlank, @Size, @Pattern, @Email
• Use @Valid for nested object validation
• Use @AssertTrue for complex validation with custom methods

Lombok Usage

• @Data for POJOs, @Builder for construction, @EqualsAndHashCode(callSuper = true) for DOs
• Configured in lombok.config: lombok.accessors.chain=true, lombok.tostring.callsuper=CALL

Testing Guidelines

• Extend BaseMockitoUnitTest (no DB) or BaseDbUnitTest (H2 database)
• Use JUnit 5: @Test, @BeforeEach, @BeforeAll
• Naming: test{MethodName}_{scenario}
• Use assertPojoEquals() for comparing DOs, assertServiceException() for exceptions
• Clean up test data via @Sql with /sql/clean.sql

Database

• Use MyBatis Plus, mappers extend BaseMapper<XxxDO>
• Use TenantBaseDO for multi-tenant tables, BaseDO for single-tenant

Security

• Use @PreAuthorize with format {module}:{resource}:{action} (e.g., system:user:create)
• Inject current user: SecurityFrameworkUtils.getLoginUserId()

Date/Time

• Use java.time, LocalDateTime for timestamps
• Format: DateUtils.FORMAT_YEAR_MONTH_DAY_HOUR_MINUTE_SECOND, @DateTimeFormat

Logging

• Use @Slf4j, levels: ERROR, WARN, INFO, DEBUG
• Log meaningful context, avoid sensitive info (passwords, tokens, PII)

API Documentation

• Use OpenAPI 3.0: @Tag, @Operation, @Parameter, @Schema
• Chinese descriptions in @Schema, mark required with requiredMode, provide example values

Module Communication

• Use module APIs (urbanops-module-api) for cross-module communication
• Use @Lazy to avoid circular dependencies

Adding New Features

1. Create DO class in dal/dataobject
2. Create Mapper interface in dal/mysql
3. Create Service interface and implementation
4. Create VO classes in controller/.../vo
5. Create Controller class
6. Create Convert interface (MapStruct)
7. Write unit tests extending appropriate base class
8. Add error codes to ErrorCodeConstants

Common Pitfalls

• Forgetting @Transactional on modifying service methods
• Using wrong DO base class (BaseDO vs TenantBaseDO)
• Not using @Valid for request body validation
• Not handling exceptions appropriately
• Direct database access bypassing Service layer
• Using System.out.println instead of logger