zcloud-gbs-primeport/AGENTS.md

AGENTS.md

This file provides guidance to agentic coding agents operating in this repository.

Project Overview

zcloud-gbs-primeport - A Spring Boot application for port access control management built with COLA framework and DDD architecture.

Build Commands

# Build the project
mvn clean install

# Build without running tests
mvn clean install -DskipTests

# Run the application
mvn spring-boot:run -pl start

# Package for deployment
mvn clean package

# Compile only
mvn compile

Test Commands

# Run all tests
mvn test

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

# Run a single test method
mvn test -Dtest=ClassNameTest#methodName

# Run tests in a specific module
mvn test -pl web-app

Code Style Guidelines

Architecture (COLA + DDD)

This is a multi-module Maven project with strict layer separation:

start/              # Application entry point
web-adapter/        # Controllers (HTTP request handling)
web-client/         # DTOs + API interface definitions
web-app/            # Executors + Service implementations (business orchestration)
web-domain/         # Entities + Gateway interfaces (core business logic)
web-infrastructure/ # DOs + Mappers + Repository implementations (data persistence)

Naming Conventions

Layer	Suffix	Example
Entity	E	MkmjE
Data Object	DO	MkmjDO
Client Object	CO	MkmjCO
Command DTO	Cmd	MkmjAddCmd, MkmjUpdateCmd
Query DTO	Qry	MkmjPageQry
Service Interface	ServiceI	MkmjServiceI
Service Impl	ServiceImpl	MkmjServiceImpl
Gateway Interface	Gateway	MkmjGateway
Gateway Impl	GatewayImpl	MkmjGatewayImpl
Repository	Repository	MkmjRepository
Repository Impl	RepositoryImpl	MkmjRepositoryImpl
Mapper	Mapper	MkmjMapper
Add Executor	AddExe	MkmjAddExe
Update Executor	UpdateExe	MkmjUpdateExe
Remove Executor	RemoveExe	MkmjRemoveExe
Query Executor	QueryExe	MkmjQueryExe
Convertor	CoConvertor	MkmjCoConvertor

Import Guidelines

• Imports should be organized alphabetically
• Use @AllArgsConstructor for constructor injection (preferred over @Autowired)
• Example import order:

import com.alibaba.cola.dto.PageResponse;
import com.zcloud.primeport.api.MkmjServiceI;
import com.zcloud.primeport.command.MkmjAddExe;
import lombok.AllArgsConstructor;
import org.springframework.stereotype.Service;

Annotations

• Use Lombok annotations: @Data, @AllArgsConstructor, @NoArgsConstructor, @Builder, @RequiredArgsConstructor
• Controller: @RestController, @RequestMapping, @AllArgsConstructor, @Api
• Service: @Service, @AllArgsConstructor
• Executor: @Component, @AllArgsConstructor
• Mapper: @Mapper (MyBatis)
• DO: @Data, @TableName, @EqualsAndHashCode(callSuper = true)

CQRS Pattern

Write and read operations are separated:

• Write: XxxAddExe, XxxUpdateExe, XxxRemoveExe in web-app/command/
• Read: XxxQueryExe in web-app/command/query/

Request Flow

Controller (web-adapter)
  -> ServiceI (web-client)
  -> ServiceImpl (web-app)
  -> Executor (web-app/command)
  -> Gateway (web-domain)
  -> GatewayImpl -> Repository -> Mapper (web-infrastructure)

MyBatis Plus Conventions

1. Non-database fields in DO: Use @TableField(exist = false)

@ApiModelProperty(value = "摄像头数量")
@TableField(exist = false)
private Integer videoCount;

2. Field naming: MyBatis Plus auto-converts snake_case to camelCase. Write SQL with underscore:

SELECT m.hg_auth_area AS hgAuthArea, m.mkmj_name AS mkmjName FROM mkmj m

3. Default ordering: Use ORDER BY m.create_time DESC or appropriate ordering in XML mappers.

Error Handling

• Use BizException from COLA for business exceptions:

if (!res) {
    throw new BizException("保存失败");
}

• Use @Transactional(rollbackFor = Exception.class) for transactional methods.

Validation

• Use JSR-303 annotations in Cmd classes:

@NotEmpty(message = "口门名称不能为空")
private String mkmjName;

@NotNull(message = "口门级别不能为空")
private Integer mkmjLevel;

• Use @Validated in Controller methods:

public SingleResponse<MkmjCO> add(@Validated @RequestBody MkmjAddCmd cmd)

MapStruct Convertors

Use MapStruct for DO to CO conversions:

@Mapper(componentModel = "spring")
public interface MkmjCoConvertor {
    List<MkmjCO> converDOsToCOs(List<MkmjDO> mkmjDOs);
    MkmjCO converDOToCO(MkmjDO mkmjDOs);
}

Adding New Features

When adding a new entity, create files in this order:

1. web-client/dto/clientobject/XxxCO.java
2. web-client/dto/XxxAddCmd.java, XxxUpdateCmd.java, XxxPageQry.java
3. web-client/api/XxxServiceI.java
4. web-adapter/web/XxxController.java
5. web-domain/model/XxxE.java
6. web-domain/gateway/XxxGateway.java
7. web-infrastructure/dataobject/XxxDO.java
8. web-infrastructure/mapper/XxxMapper.java
9. web-infrastructure/resources/mapper/XxxDO.xml
10. web-infrastructure/repository/XxxRepository.java
11. web-infrastructure/repository/impl/XxxRepositoryImpl.java
12. web-infrastructure/gatewayimpl/XxxGatewayImpl.java
13. web-app/command/XxxAddExe.java, XxxUpdateExe.java, XxxRemoveExe.java
14. web-app/command/query/XxxQueryExe.java
15. web-app/command/convertor/XxxCoConvertor.java
16. web-app/service/XxxServiceImpl.java

Database

• PostgreSQL (driver version 42.6.0)
• DDL location: web-infrastructure/src/main/resources/TableCreationDDL.sql
• Multi-tenant support via tenant_id and org_id columns
• Soft delete via delete_enum column (use 'false' for active records)

Response Types (COLA)

• Response - Simple success/failure
• SingleResponse<T> - Single object response
• MultiResponse<T> - List response
• PageResponse<T> - Paginated list response