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

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

```bash
# 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:
```java
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)`
```java
@ApiModelProperty(value = "摄像头数量")
@TableField(exist = false)
private Integer videoCount;
```

2. **Field naming**: MyBatis Plus auto-converts snake_case to camelCase. Write SQL with underscore:
```xml
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:
```java
if (!res) {
    throw new BizException("保存失败");
}
```

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

### Validation

- Use JSR-303 annotations in Cmd classes:
```java
@NotEmpty(message = "口门名称不能为空")
private String mkmjName;

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

- Use `@Validated` in Controller methods:
```java
public SingleResponse<MkmjCO> add(@Validated @RequestBody MkmjAddCmd cmd)
```

### MapStruct Convertors

Use MapStruct for DO to CO conversions:
```java
@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