5.8 KiB

Raw Blame History

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

# 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:

Create CO in web-client/src/main/java/com/zcloud/primeport/dto/clientobject/
Create Cmd/Qry in web-client/src/main/java/com/zcloud/primeport/dto/
Create ServiceI in web-client/src/main/java/com/zcloud/primeport/api/
Create Controller in web-adapter/src/main/java/com/zcloud/primeport/web/
Create Entity in web-domain/src/main/java/com/zcloud/primeport/domain/model/
Create Gateway interface in web-domain/src/main/java/com/zcloud/primeport/domain/gateway/
Create DO in web-infrastructure/src/main/java/com/zcloud/primeport/persistence/dataobject/
Create Mapper in web-infrastructure/src/main/java/com/zcloud/primeport/persistence/mapper/
Create GatewayImpl in web-infrastructure/src/main/java/com/zcloud/primeport/gatewayimpl/
Create Executors in web-app/src/main/java/com/zcloud/primeport/command/
Create ServiceImpl in web-app/src/main/java/com/zcloud/primeport/service/

MyBatis Plus Development Conventions

DO (Data Object) Field Conventions

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

SELECT m.hg_auth_area AS hgAuthArea, m.mkmj_name AS mkmjName FROM mkmj m
```
Default ordering: Unless specified otherwise, order by create_time DESC for list/page queries:
```
ORDER BY m.create_time DESC
```

5.8 KiB Raw Blame History