99 lines
4.8 KiB
Markdown
99 lines
4.8 KiB
Markdown
# PR-19 API Surface Audit, Model Separation, and Public Read DTOs
|
|
|
|
Domain Owner: `docs/packer`
|
|
Cross-Domain Impact: `docs/studio`
|
|
|
|
## Briefing
|
|
|
|
The current packer API still exposes some read payload types that are simultaneously acting as public transport objects and internal implementation models.
|
|
|
|
This is acceptable during early convergence, but it weakens the boundary between `prometeu-packer-api` and `prometeu-packer-v1`.
|
|
|
|
The next cleanup step is to make the API explicit about three different categories:
|
|
|
|
- domain contracts,
|
|
- request/response messages,
|
|
- public read DTOs.
|
|
|
|
At the same time, the internal implementation models used by `prometeu-packer-v1` should stop leaking through the API as if they were stable public models.
|
|
|
|
## Objective
|
|
|
|
Separate internal `v1` read models from public API read DTOs while preserving:
|
|
|
|
- request/response messages as immutable messages,
|
|
- domain contracts as domain contracts,
|
|
- exceptions as part of the public API,
|
|
- and Studio compatibility through explicit mapper-based conversion inside `prometeu-packer-v1`.
|
|
|
|
## Dependencies
|
|
|
|
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
|
|
- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
|
|
- [`./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md)
|
|
- [`./PR-18-legacy-service-retirement-and-regression-hardening.md`](./PR-18-legacy-service-retirement-and-regression-hardening.md)
|
|
|
|
## Scope
|
|
|
|
- audit the current public packer API against real external consumption
|
|
- preserve public exceptions in the API even when only `v1` currently throws them
|
|
- preserve request/response records as request/response messages rather than renaming them as generic DTOs
|
|
- move the current mixed model/transport read types out of the API and into `prometeu-packer-v1`
|
|
- introduce public read DTOs in the API for the information Studio actually consumes
|
|
- add explicit mapper classes in `prometeu-packer-v1` to convert internal models into API DTOs
|
|
- keep the active service wave limited to `initWorkspace`, `listAssets`, `getAssetDetails`, and `createAsset`
|
|
|
|
## Non-Goals
|
|
|
|
- no new packer capabilities
|
|
- no write API redesign
|
|
- no doctor or build/pack reintroduction
|
|
- no reconcile observer work
|
|
- no semantic change to asset identity, registry ownership, or snapshot authority
|
|
|
|
## Execution Method
|
|
|
|
1. Classify the current API surface into:
|
|
- public domain contracts,
|
|
- public request/response messages,
|
|
- public read DTOs,
|
|
- internal implementation models.
|
|
2. Keep domain contracts in `prometeu-packer-api` without `DTO` suffixes.
|
|
3. Keep request/response types in `prometeu-packer-api` as immutable message records with `Request` and `Response` naming.
|
|
4. Move the current mixed read shapes now exposed as `PackerAssetSummary`, `PackerAssetDetails`, and `PackerAssetIdentity` into `prometeu-packer-v1` as internal models.
|
|
5. Introduce explicit public DTOs in the API for runtime-backed read payloads, such as:
|
|
- `PackerAssetSummaryDTO`
|
|
- `PackerAssetDetailsDTO`
|
|
- `PackerAssetIdentityDTO`
|
|
- `PackerCodecConfigurationFieldDTO`
|
|
- and `PackerDiagnosticDTO` if diagnostics remain part of public responses.
|
|
6. Add explicit mapper classes in `prometeu-packer-v1` to convert internal models into API DTOs before responses cross the module boundary.
|
|
7. Update response messages to carry the new DTO types instead of leaking `v1` models through the API.
|
|
8. Update Studio consumers to read from the new DTO types while preserving the same user-facing behavior.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- the API surface is explicitly partitioned between domain contracts, request/response messages, and read DTOs
|
|
- request/response messages remain immutable message records and are not renamed as generic DTOs
|
|
- public exceptions remain in the API
|
|
- internal `v1` models are no longer exposed as if they were public API models
|
|
- Studio depends only on API contracts and DTOs, not on `v1` model semantics
|
|
- conversion from `v1` internal models to public API DTOs happens through explicit mapper code
|
|
- no behavior regression is introduced in `initWorkspace`, `listAssets`, `getAssetDetails`, or `createAsset`
|
|
|
|
## Validation
|
|
|
|
- compile-time audit proving `prometeu-studio` and `prometeu-app` consume only API contracts
|
|
- packer regression tests for read and write flows
|
|
- Studio regression tests for asset list, asset details, and add asset flows
|
|
- targeted tests for mapper coverage between internal models and public API DTOs
|
|
|
|
## Affected Artifacts
|
|
|
|
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/**`
|
|
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/**`
|
|
- `prometeu-studio/src/main/java/p/studio/**`
|
|
- `prometeu-studio/src/test/java/p/studio/**`
|
|
|