zcloud-gbs-primeport/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**zcloud-gbs-primeport** - 智慧云港-港口首进门禁管理系统

A Spring Boot application based on DDD (Domain-Driven Design) architecture using the COLA framework. Manages port/area access control with multi-level area management, vehicle approval, and personnel access control.

## Build and Run

```bash
# Build the project
mvn clean install

# Run the application (main class: com.zcloud.primeport.Application)
mvn spring-boot:run -pl start

# Package for deployment
mvn clean package
```

## DDD Architecture

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

```
start/              # Application entry point (main class, configuration)
web-adapter/        # Adapter layer (Controllers) - HTTP request handling
web-client/         # Client layer (DTOs + API interface definitions)
web-app/            # Application layer (Command/Query executors) - Business orchestration
web-domain/         # Domain layer (Entity + Gateway) - Core business logic
web-infrastructure/ # Infrastructure layer (DO + Mapper) - Data persistence
```

### Key Architecture Patterns

**CQRS**: Read and write operations are separated
- Write operations: `XxxAddExe`, `XxxUpdateExe`, `XxxRemoveExe` in `web-app/command/`
- Read operations: `XxxQueryExe` in `web-app/command/query/`

**Naming Conventions**:
- Entities: `XxxE` (domain entities in `web-domain`)
- DTOs: `XxxCmd` (commands), `XxxQry` (queries), `XxxCO` (client objects)
- Data Objects: `XxxDO` (database objects in `web-infrastructure`)
- Gateways: `XxxGateway` interfaces in `web-domain`, implemented in `web-infrastructure`

**Request Flow**:
```
Controller (web-adapter)
  → ServiceI (web-client)
  → ServiceImpl (web-app)
  → Executor (web-app/command)
  → Gateway (web-domain)
  → Mapper (web-infrastructure)
```

## Database Schema

Database DDL is located at: `web-infrastructure/src/main/resources/TableCreationDDL.sql`

### Core Tables (9 main business entities)

**门禁管理**
- `mkmj` - 门口信息管理表 (gate info: 一级/二级口门)
- `mkmj_gate` - 门口闸机表 (gate equipment)
- `mkmj_passage` - 口门门禁通道表 (passageways: 人行/车行/综合)
- `mkmj_approval_user` - 一级口门门禁审批人
- `video` - 摄像头表 (video monitoring)

**人员管理**
- `person_apply` - 人员申请审批信息 (personnel applications with audit workflow)
- `person_message` - 审批通过的人员信息 (approved personnel for access control sync)

**车辆管理**
- `vehicle_apply` - 车辆申请审批信息 (vehicle applications with audit workflow)
- `vehicle_audit` - 车辆审批
- `vehicle_message` - 审批通过的固化车辆信息
- `vehicle_black` - 车辆黑名单管理
- `vehicle_violations` - 车辆违规记录

### Key Business Concepts

**审核状态** - audit_flag:
- 1: 审核中
- 2: 审核通过
- 3: 审核驳回
- 4: 无需审批 (检查部门车辆/长期人员)

**车辆/人员所属类型** - belong_type:
- 1: 股份员工车辆/人员
- 2: 股份单位车辆
- 3: 分公司员工车辆/人员
- 4: 分公司单位车辆
- 5: 相关方车辆
- 6: 临时车辆/人员
- 7: 检查部门车辆

**口门级别** - mkmj_level:
- 1: 一级口门
- 2: 二级口门

**通道/闸机类型**:
- 1: 人行
- 2: 车行
- 3: 综合

## Configuration

- Uses Nacos for centralized configuration
- Database: MySQL (Note: DDL shows MySQL syntax, but pom.xml has PostgreSQL driver - confirm actual DB)
- MyBatis Plus for ORM
- Main application config: `start/src/main/resources/bootstrap.yml`
- Nacos connection: `start/src/main/resources/nacos.yml`
- Multi-tenant support via `tenant_id` and `org_id` columns

## Module Dependencies

All modules depend on `web-client`. The `start` module only depends on `web-adapter` and pulls in transitive dependencies.

Current git branch: `koumen` (门禁审批功能 - gate access approval)
Main branch: `master`

## Code Generation Pattern

When adding new features, follow the existing pattern across all layers:
1. Create CO in `web-client/src/main/java/com/zcloud/primeport/dto/clientobject/`
2. Create Cmd/Qry in `web-client/src/main/java/com/zcloud/primeport/dto/`
3. Create ServiceI in `web-client/src/main/java/com/zcloud/primeport/api/`
4. Create Controller in `web-adapter/src/main/java/com/zcloud/primeport/web/`
5. Create Entity in `web-domain/src/main/java/com/zcloud/primeport/domain/model/`
6. Create Gateway interface in `web-domain/src/main/java/com/zcloud/primeport/domain/gateway/`
7. Create DO in `web-infrastructure/src/main/java/com/zcloud/primeport/persistence/dataobject/`
8. Create Mapper in `web-infrastructure/src/main/java/com/zcloud/primeport/persistence/mapper/`
9. Create GatewayImpl in `web-infrastructure/src/main/java/com/zcloud/primeport/gatewayimpl/`
10. Create Executors in `web-app/src/main/java/com/zcloud/primeport/command/`
11. Create ServiceImpl in `web-app/src/main/java/com/zcloud/primeport/service/`

## MyBatis Plus Development Conventions

### DO (Data Object) Field Conventions

1. **Non-database fields**: When adding a field to DO that does not exist in the database table (e.g., association query results), use `@TableField(exist = false)` annotation:
   ```java
   @ApiModelProperty(value = "摄像头数量")
   @TableField(exist = false)
   private Integer videoCount;
   ```

2. **Field naming**: MyBatis Plus automatically converts between underscore (snake_case) and camelCase. Write SQL with underscore column names directly - no need to manually convert to camelCase:
   ```xml
   <!-- SQL 中直接使用下划线字段名 -->
   SELECT m.hg_auth_area AS hgAuthArea, m.mkmj_name AS mkmjName FROM mkmj m
   ```

3. **Default ordering**: Unless specified otherwise, order by `create_time DESC` for list/page queries:
   ```xml
   ORDER BY m.create_time DESC
   ```