Skip to content
Skills Library
Programming · Building & coding

dto-implementation

/dto-implementation

DTO implementation guidelines for the HMIS project. Use when creating or modifying DTOs, writing JPQL constructor queries, implementing DTO-based reports, converting entity code to DTO patterns, or troubleshooting DTO query issues. Covers constructor rules, facade methods, null relationship handling, and navigation patterns.

Repository
hmis ↗
Licence
GPL-3.0
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

GPL-3.0, otwarta.

What it does and when to use it

DTO implementation guidelines for the HMIS project. Use when creating or modifying DTOs, writing JPQL constructor queries, implementing DTO-based reports, converting entity code to DTO patterns, or troubleshooting DTO query issues. Covers constructor rules, facade methods, null relationship handling, and navigation patterns.

Original author description

DTO implementation guidelines for the HMIS project. Use when creating or modifying DTOs, writing JPQL constructor queries, implementing DTO-based reports, converting entity code to DTO patterns, or troubleshooting DTO query issues. Covers constructor rules, facade methods, null relationship handling, and navigation patterns.

How it works

  1. Critical Rules
  2. Direct DTO Query Pattern
  3. Navigation Pattern: Use IDs, Not Entities
  4. Null Relationship Handling
  5. Constructor Rules
  6. Common Non-Persisted Properties (Cannot Use in JPQL)
Original SKILL.md headings · 72 lines, 304 words
SKILL.md preview
---
name: dto-implementation
description: >
  DTO implementation guidelines for the HMIS project. Use when creating or modifying DTOs,
  writing JPQL constructor queries, implementing DTO-based reports, converting entity code
  to DTO patterns, or troubleshooting DTO query issues. Covers constructor rules, facade
  methods, null relationship handling, and navigation patterns.
user-invocable: true
---

# DTO Implementation Guidelines

## Critical Rules

1. **NEVER modify existing constructors** - only add new ones
2. **Use direct DTO queries** - avoid entity-to-DTO conversion loops
3. **JPQL PERSISTED FIELDS ONLY**: NEVER use derived properties like `nameWithTitle`, `age`, `displayName` in JPQL

## Direct DTO Query Pattern

```java
// CORRECT - Direct DTO query from database
String jpql = "SELECT new com.divudi.core.data.dto.StockDTO("
    + "s.id, s.itemBatch.item.name, s.itemBatch.item.code, "
    + "s.itemBatch.retailsaleRate, s.stock, "
    + "s.itemBatch.dateOfExpire, s.itemBatch.batchNo) "
    + "FROM Stock s WHERE ...";

// MUST use findLightsByJpql() with cast
List<StockDTO> dtos = (List<StockDTO>) facade.findLightsByJpql(jpql, params, TemporalType.TIMESTAMP);
```

```java
// WRONG - Never do entity-to-DTO loops
List<Stock> stocks = stockFacade.findByJpql(sql, params);
List<StockDTO> dtos = new ArrayList<>();
for (Stock stock : stocks) { dtos.add(new StockDTO(stock.getField1(), ...)); }
```

## Navigation Pattern: Use IDs, Not Entities

```java
// CORRECT - IDs and names for navigation
public class OpdSaleSummaryDTO {
    private Long categoryId;      // For navigation
    private String categoryName;  // For display
    private Long itemId;          // For navigation
    private String itemName;      // For display
    private Double total;
}
```

## Null Relationship Handling

Accessing properties through nullable relationships causes **silent query failures** (0 results, no exception):

```java
// WRONG - Fails silently if cancelledBill is null
"b.cancelledBill.createdAt"

// CORRECT - Use LEFT JOIN
"FROM Bill b LEFT JOIN b.cancelledBill cb "
// Then use cb.createdAt with COALESCE
```

## Constructor Rules

- Always use **wrapper types** (`Boolean`, `Integer`, `Long`) for null safety
- Parameter count and order must match JPQL SELECT exactly
- Keep existing constructors intact; add new ones

## Common Non-Persisted Properties (Cannot Use in JPQL)

| Entity | Non-Persisted | Use Instead |
|--------|--------------|-------------|
| Person | nameWithTitle | name (or title, name separately) |
| Person | age | dob (calculate in Java) |
| Item | displayName | name |

For complete reference, read [developer_docs/dto/implementation-guidelines.md](../../developer_docs/dto/implementation-guidelines.md).

Versions

RepositoryScoreLicence
This page · hmislk/hmis100GPL-3.0
hmislk/hmis100GPL-3.0

Database snapshot: 13.11.2026 · package version 3b2f6ba3bc64 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95dto-sync-patterns
    Patterns for synchronizing DTOs between frontend and backend. Covers shared types, code generation, and validation sync. USE WHEN: user asks about "DTO sync", "shared types", "frontend backend types", "type consistency", "API models" DO NOT USE FOR: type generation tools - use…
  • 100laravel-dto
    Use when creating a Laravel/PHP DTO with the SimpleDto base class and attribute mapping. For DTOs in other stacks, use the stack-native skill (TypeScript, Python, Rust, Go).
  • 100dto-and-validation
    Use when creating request/response DTOs, applying Symfony Validator constraints, mapping payloads with #[MapRequestPayload]/#[MapQueryString], or mapping DTOs to/from entities. Use when the task mentions DTO, request validation, form input, or the Validator component.
  • 100add-dto
    Request/response shape exposed via public API to MCP tools, lives in api/public/dto. Triggers on "add DTO", "new request type for X tool", "add response shape", "новый DTO для tool'а". NOT for internal types — those live in contracts/, not public API surface.
  • 100documenting-contracts
    Use when documenting an HTTP API, message payloads, queue contracts, DTOs, file formats, or webhooks - or when writing the api-reference of a legacy campaign, or when callers keep asking what a field means or which errors an endpoint returns. Encodes the four detail levels, the…
  • 95zod-patterns
    Mix Space project Zod schema patterns. Apply when creating DTOs, validation schemas, or handling request validation.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.