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.
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
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
- Critical Rules
- Direct DTO Query Pattern
- Navigation Pattern: Use IDs, Not Entities
- Null Relationship Handling
- Constructor Rules
- Common Non-Persisted Properties (Cannot Use in JPQL)
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
| Repository | Score | Licence |
|---|---|---|
| This page · hmislk/hmis | 100 | GPL-3.0 |
| hmislk/hmis | 100 | GPL-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.