---
name: domain-repository-port-generator
description: "Use when creating or modifying domain repository port interfaces and contracts without infra/framework dependencies."
---

# Domain Repository Port Generator

## Overview
Generates pure domain repository interfaces that express persistence intent in domain terms, free of infrastructure details.
**REQUIRED:** Follow `GENERATOR_SKILL_STRUCTURE.md`. Variables in `VARIABLES.md`.

Templates: See `references/templates.md`.

## When to Use
- `{{basePackage}}.domain.{{bcName}}.repository.*` interfaces

### Don't use when
- You need the implementation (PO/Mapper/RepositoryImpl) — use `infra-bc-repository-generator`.
- The port is an app-layer concern (store/transport/gateway) — use `app-port-generator`.
- You need a query-side read model — use `infra-bc-query-generator`.

## Inputs Required
- Aggregate name + identifier type
- Required operations (save, find, uniqueness checks) expressed in domain terms
- Consistency expectations (optimistic locking? unique constraints?)

## Outputs
- `{{domainModuleDir}}/src/main/java/{{basePackagePath}}/.../<XxxRepository>.java`

## Naming & Packaging
- Port names: `*Repository` (domain) or `*Gateway` (external systems)
- Keep interfaces in `domain.{{bcName}}.repository`

## Rules
- No persistence details (SQL/MyBatis annotations) in domain.
- Methods should express domain intent (e.g., `save`, `findById`), not table operations.

## Reference Implementations
- `{{domainModuleDir}}/src/main/java/{{basePackagePath}}/domain/{{bcName}}/repository/package-info.java`

## Tests
- Usually none for pure interfaces.

## Common Mistakes
| Mistake | Why It Happens | Fix |
|---------|---------------|-----|
| Adding `Page`, `QueryWrapper`, `Mapper` types into domain ports | Copy-pasting from infra layer | Domain ports must use only domain types; pagination belongs in app/infra |
| Leaking SQL concepts (e.g., `updateByCondition`) | Thinking in table operations | Express methods in domain intent: `save`, `findById`, `existsByName` |
| Adding implementation logic to the interface | Trying to provide defaults | Keep ports as pure interfaces; implementation goes to infra module |

## Checklist
- [ ] Pure interface/contract
- [ ] No framework imports
- [ ] Covered by app/infra implementations (separate module)

## Integration
- **Called by:** `scaffold-router`, `dev-workflow-ddd-implementation-workflow`
- **Pairs with:** `domain-model-generator` (aggregate types the port operates on), `infra-bc-repository-generator` (implements this port), `app-usecase-generator` (handlers that depend on this port)

## Commit Gate

- pass required tests (`mvn -q clean test` minimum, `mvn -q clean verify` if DB behavior changed)
- run `requesting-code-review`
- resolve Critical/Important findings
- keep the commit focused