Naming Conventions¶

Türkçe

Bu sayfa ICOSYS'taki tüm isimlendirme kurallarını kapsar: Java sınıfları, paketler, veritabanı tabloları, React bileşenleri ve API endpoint'leri dahil.

Java — Backend¶

Package Structure¶

com.icom.icosys.{module}.service.zapi.{entity}/
├── controller/
│   └── {Entity}Controller.java
├── service/
│   └── {Entity}Service.java
├── converter/
│   ├── {Entity}EditDtoConverter.java
│   └── {Entity}ListDtoConverter.java
├── specification/
│   └── {Entity}Specification.java
└── {Entity}Repository.java

Türkçe

zapi paketi REST API katmanını temsil eder. Her entity kendi alt paketinde controller, service, converter ve specification sınıflarıyla birlikte bulunur.

Examples from the codebase:

Package	Description
`com.icom.icosys.bpm.service.zapi.branch`	BPM Branch module
`com.icom.icosys.bpm.service.zapi.accrual`	BPM Accrual module
`com.icom.icosys.dms.service.zapi.dmsaccountconfig`	DMS Account Config
`com.icom.icglb.service.zapi.country`	Core Country module
`com.icom.service.api.codes`	Shared error codes

Class Naming¶

Type	Pattern	Examples
Entity	`{EntityName}`	`Accrual`, `Branch`, `BusinessPartner`, `DmsFile`
Edit DTO	`{Entity}EditDto`	`AccrualEditDto`, `BranchEditDto`
List DTO	`{Entity}ListDto`	`AccrualListDto`, `BranchListDto`
Filter DTO	`{Entity}FilterDto`	`AccrualFilterDto`, `BranchFilterDto`
Controller	`{Entity}Controller`	`AccrualController`, `BranchController`
Service	`{Entity}Service`	`AccrualService`, `BranchService`
Repository	`{Entity}Repository`	`AccrualRepository`, `DmsAccountConfigRepository`
Edit Converter	`{Entity}EditDtoConverter`	`AccrualEditDtoConverter`
List Converter	`{Entity}ListDtoConverter`	`AccrualListDtoConverter`
Specification	`{Entity}Specification`	`AccrualSpecification`, `BranchSpecification`
Enum	`{Entity}Status` / `{Field}Type`	`AccrualStatus`, `StorageProviderType`, `AllowedMimeGroup`
Error Codes	`ServiceErrorMsgCodes`	One per service module

Türkçe

Entity sınıfları herhangi bir suffix almaz (Branch, Accrual). DTO'lar ise mutlaka amaçlarını belirten suffix alır: EditDto, ListDto, FilterDto.

Method Naming¶

Repository Methods¶

Pattern	Return Type	Example
`findBy{Field}()`	`Optional<Entity>`	`findByCrProcess_Id(Long)`
`findBy{Field}And{Field}()`	`List<Entity>`	`findByCrProcess_IdAndStatus(Long, Status)`
`existsBy{Field}()`	`boolean`	`existsByCrProcess_Id(Long)`
`existsBy{Field}And{Field}Not()`	`boolean`	`existsByCrProcess_IdAndIdNot(Long, Long)`
`countBy{Field}()`	`long`	`countByCrProcess_Id(Long)`
`findBy{Field}OrderBy{Field}Desc()`	`List<Entity>`	`findByContractIdOrderByPeriodStartDesc(Long)`

Türkçe

Spring Data nested property erişiminde underscore kullanılır: findByCrProcess_Id(). Bu, entity.crProcess.id alanına karşılık gelir.

Service Methods (Inherited from AbstractCrudService)¶

Method	Signature	Purpose
`findById`	`Optional<EditDto> findById(Long id)`	Single entity fetch
`create`	`EditDto create(EditDto dto)`	Create new entity
`update`	`EditDto update(Long id, EditDto dto)`	Update existing
`delete`	`void delete(Long id)`	Delete by ID
`findPaged`	`PageResponse<ListDto> findPaged(PageRequest<FilterDto>)`	Paginated list
`getStats`	`EntityStatsDto getStats()`	Entity statistics

Service Methods (Custom)¶

Pattern	Example
`findBy{Field}()`	`findByContractId(Long contractId)`
`findBy{Criteria}()`	`findByStatus(AccrualStatus status)`
`{action}()`	`approve(Long id)`, `cancel(Long id, String reason)`

Converter Methods¶

Method	Direction	Purpose
`from(entity)`	Entity → DTO	Read conversion
`to(dto)`	DTO → Entity	Create conversion
`to(dto, entity)`	DTO → existing Entity	Update conversion

Specification Methods¶

Method	Purpose
`build(filter, searchTerm)`	Build JPA Specification
`addFilterPredicates(...)`	Apply filter fields (private)
`addSearchPredicate(...)`	Apply free-text search (private)

Variable Naming¶

Constants — `UPPER_SNAKE_CASE`¶

// Field name constants (Specification)
private static final String FIELD_ID = "id";
private static final String FIELD_STATUS = "status";
private static final String FIELD_NAME = "name";

// Relationship constants
private static final String REL_CR_PROCESS = "crProcess";
private static final String REL_CONTRACT = "contract";

// Error message codes
private static final String ERROR_COUNTRY_NOT_FOUND = "error.country.not_found";
private static final String ERROR_ACCRUAL_PERIOD_EXISTS = "error.accrual_period_exists";

// Numeric constants
private static final int MAX_RETRY_COUNT = 3;
private static final int DEFAULT_PAGE_SIZE = 50;

Instance / Local Variables — `camelCase`¶

private final BranchRepository repository;
private final BranchEditDtoConverter editConverter;
Long crProcessId = dto.getCrProcessId();
List<BranchListDto> branches = repository.findAll();

Database¶

Schema & Catalog¶

Module	Schema	Catalog	ID Table
Core	`icglb2`	`icglb2`	`s_icglb_id`
BPM	`icbpm`	`icbpm`	`s_icbpm_id`
DMS	`icdms`	`icdms`	`s_icdms_id`
New module	`ic{mod}`	`ic{mod}`	`s_ic{mod}_id`

Table Naming — `snake_case`¶

Pattern	Examples
Domain tables	`d_accrual`, `d_branch`, `d_business_partner`, `d_contract`
Lookup/reference	`country`, `city`
ID generator	`s_icbpm_id`, `s_icdms_id`
Prefix per module	`dms_file`, `dms_file_metadata`

Column Naming — `snake_case`¶

Column	Type	Notes
`id`	BIGINT	Primary key
`cr_process_id`	BIGINT	FK — tenant isolation (inherited)
`version`	BIGINT	Optimistic locking (inherited)
`xref_id`	VARCHAR(255)	UUID cross-reference (inherited)
`creation_date`	DATETIME(6)	Audit: created timestamp (inherited)
`created_by`	VARCHAR(255)	Audit: creator (inherited)
`last_update_date`	DATETIME(6)	Audit: last modified (inherited)
`last_updated_by`	VARCHAR(255)	Audit: last modifier (inherited)
`{field_name}`	varies	Domain-specific, always `snake_case`
`{entity}_id`	BIGINT	Foreign key to related entity

Türkçe

entity_id kolon adı AbstractICEntity6.getEntityId() abstract metodu tarafından REZERVE edilmiştir. FK kolonu adlandırırken ref_entity_id kullanılmalıdır.

React — Frontend¶

File Naming¶

Type	Pattern	Examples
Page component	`PascalCase.tsx`	`BusinessPartnersPage.tsx`, `LoginPage.tsx`
Core component	`PascalCase.tsx`	`CrudPage.tsx`, `Sidebar.tsx`, `Topbar.tsx`
Dialog/modal	`PascalCase.tsx`	`AccountSwitcherDialog.tsx`, `LookupDialogModal.tsx`
Hook	`camelCase.ts`	`useAuth.ts`, `useRBAC.ts`, `useCrudHandler.ts`
Zustand store	`kebab-case.ts`	`auth-store.ts`, `navigation-stack-store.ts`
Utility	`kebab-case.ts`	`api-client.ts`, `error-handler.ts`, `id-encoder.ts`
Config	`kebab-case.ts`	`config-registry.ts`, `crud-types.ts`
Type definitions	`kebab-case.ts`	`api-error.ts`, `service-clients.ts`
Styles	`index.css`	Single global stylesheet with Tailwind

Directory Structure¶

src/
├── app/                    # App-level: auth, store, routing
│   ├── auth/               # useAuth, auth guards
│   ├── store/              # Zustand stores
│   └── routes/             # Route definitions
├── core/                   # Framework: CRUD engine, shared components
│   └── components/
│       └── crud/           # CrudPage, CrudRenderer, etc.
├── modules/                # Feature modules (1 per backend entity group)
│   ├── bpm/
│   │   ├── pages/          # BusinessPartnersPage, BranchesPage
│   │   └── config/         # Handler configs
│   └── dms/
├── shared/                 # Cross-cutting utilities
│   ├── api/                # api-client, service-clients
│   ├── errors/             # ApiError, error-handler
│   ├── i18n/               # useTranslation, locale files
│   └── utils/              # cn, id-encoder, url-stack-utils
└── index.css               # Tailwind + custom CSS variables

Component Naming — `PascalCase`¶

// Page components — suffix with "Page"
export function BusinessPartnersPage() { }
export function LoginPage() { }

// UI components — descriptive name
export function StatusBadge({ status }: { status: string }) { }
export function BooleanIcon({ value }: { value: boolean }) { }
export function AccountSwitcherDialog() { }

Hook Naming — `use` prefix¶

// Custom hooks
export function useAuth() { }
export function useRBAC(moduleName: string) { }
export function useCrudHandler(config: HandlerConfig) { }
export function useTranslation() { }
export function useFieldConfig(fields: FieldDef[]) { }

Store Naming — `use{Feature}Store`¶

// Zustand stores — "use" prefix + "Store" suffix
export const useAuthStore = create<AuthState>(/* ... */);
export const useNavigationStack = create<NavState>(/* ... */);

// Usage
const { user, isAuthenticated } = useAuthStore();
const { levels, pushLevel } = useNavigationStack();

TypeScript Interfaces¶

Type	Pattern	Examples
Props	`{Component}Props`	`CrudPageProps`, `StatusBadgeProps`
DTO (from backend)	`{Entity}ListDto` / `{Entity}EditDto`	`BusinessPartnerListDto`
Config	`{Feature}Config`	`HandlerConfig`, `FieldDef`
State	`{Feature}State`	`AuthState`, `NavState`

CSS Custom Properties¶

/* Naming: --color-{semantic}-{shade} */
--color-primary-50 ... --color-primary-900
--color-surface
--color-card
--color-body-text
--color-status-active
--color-status-passive
--color-edge
--color-edge-strong
--color-edge-light

API Endpoints¶

URL Pattern¶

{scheme}://{host}:{port}/ic{module}/services/api/{entity}/{action}

Standard CRUD Endpoints¶

HTTP Method	URL	Purpose
`GET`	`/api/{entity}/{id}`	Get by ID
`POST`	`/api/{entity}`	Create
`PUT`	`/api/{entity}/{id}`	Update
`DELETE`	`/api/{entity}/{id}`	Delete
`POST`	`/api/{entity}/list`	Paginated list (filter in body)
`GET`	`/api/{entity}/stats`	Entity statistics

Custom Endpoint Patterns¶

Pattern	Example
`/api/{entity}/by-{relation}/{id}`	`GET /api/branch/by-partner/123`
`/api/{entity}/{lookup}/{value}`	`GET /api/country/iso2/TR`
`/api/{entity}/search`	`GET /api/country/search?q=tur`

Türkçe

Pagination POST /list ile yapılır — filtre body'de gönderilir, URL parametresi olarak değil. Bu, karmaşık filtre nesnelerinin temiz şekilde aktarılmasını sağlar.

Request/Response Format¶

Paginated list request:

{
    "page": 0,
    "size": 50,
    "sort": "name,asc",
    "filter": {
        "crProcessId": 1,
        "status": "ACTIVE"
    }
}

Paginated list response:

{
    "content": [{ }],
    "totalElements": 100,
    "totalPages": 2,
    "currentPage": 0,
    "pageSize": 50
}

Error response:

{
    "errorCode": "IC-BPM-2008",
    "message": "Accrual period already exists",
    "refId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "httpStatus": 409
}

Error Codes¶

Format: `IC-{MODULE}-{CATEGORY}{NUMBER}`¶

Module Code	Module
`SYS`	System-wide
`BPM`	Business Partner Management
`DMS`	Document Management

Category	Range	Description
Auth	`1xxx`	Authentication / authorization
Validation	`2xxx`	Input validation
API	`3xxx`	API / network
Data	`4xxx`	CRUD / data access
File	`5xxx`	File / upload
Config	`6xxx`	Configuration / system

Examples: IC-SYS-1001 (Session Expired), IC-BPM-2001 (Field Required), IC-DMS-5001 (File Empty)

Message Key Constants — `snake_case`¶

// In ServiceErrorMsgCodes.java (one per module)
public static final String ERROR_FIELD_REQUIRED = "error.field_required";
public static final String ERROR_ENTITY_NOT_FOUND = "error.not_found";
public static final String ERROR_ACCRUAL_PERIOD_EXISTS = "error.accrual_period_exists";

Türkçe

Hata mesajları messages.properties (İngilizce) ve messages_tr.properties (Türkçe) dosyalarında tanımlanır. Backend locale'e göre doğru mesajı döner.

Naming Conventions¶

Java — Backend¶

Package Structure¶

Class Naming¶

Method Naming¶

Repository Methods¶

Service Methods (Inherited from AbstractCrudService)¶

Service Methods (Custom)¶

Converter Methods¶

Specification Methods¶

Variable Naming¶

Constants — UPPER_SNAKE_CASE¶

Instance / Local Variables — camelCase¶

Database¶

Schema & Catalog¶

Table Naming — snake_case¶

Column Naming — snake_case¶

React — Frontend¶

File Naming¶

Directory Structure¶

Component Naming — PascalCase¶

Hook Naming — use prefix¶

Store Naming — use{Feature}Store¶

TypeScript Interfaces¶

CSS Custom Properties¶

API Endpoints¶

URL Pattern¶

Standard CRUD Endpoints¶

Custom Endpoint Patterns¶

Request/Response Format¶

Error Codes¶

Format: IC-{MODULE}-{CATEGORY}{NUMBER}¶

Message Key Constants — snake_case¶

Constants — `UPPER_SNAKE_CASE`¶

Instance / Local Variables — `camelCase`¶

Table Naming — `snake_case`¶

Column Naming — `snake_case`¶

Component Naming — `PascalCase`¶

Hook Naming — `use` prefix¶

Store Naming — `use{Feature}Store`¶

Format: `IC-{MODULE}-{CATEGORY}{NUMBER}`¶

Message Key Constants — `snake_case`¶