asset workspace progress
This commit is contained in:
+98
@@ -0,0 +1,98 @@
|
||||
# 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/**`
|
||||
|
||||
@@ -78,6 +78,7 @@ The current production track for the standalone `prometeu-packer` project is:
|
||||
16. [`PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
|
||||
17. [`PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md)
|
||||
18. [`PR-18-legacy-service-retirement-and-regression-hardening.md`](./PR-18-legacy-service-retirement-and-regression-hardening.md)
|
||||
19. [`PR-19-api-surface-audit-model-separation-and-public-read-dtos.md`](./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md)
|
||||
|
||||
Current wave discipline from `PR-11` onward:
|
||||
|
||||
@@ -88,4 +89,4 @@ Current wave discipline from `PR-11` onward:
|
||||
|
||||
Recommended dependency chain:
|
||||
|
||||
`PR-01 -> PR-02 -> PR-03 -> PR-04 -> PR-05 -> PR-06 -> PR-07 -> PR-08 -> PR-09 -> PR-10 -> PR-11 -> PR-12 -> PR-13 -> PR-14 -> PR-15 -> PR-16 -> PR-17 -> PR-18`
|
||||
`PR-01 -> PR-02 -> PR-03 -> PR-04 -> PR-05 -> PR-06 -> PR-07 -> PR-08 -> PR-09 -> PR-10 -> PR-11 -> PR-12 -> PR-13 -> PR-14 -> PR-15 -> PR-16 -> PR-17 -> PR-18 -> PR-19`
|
||||
|
||||
Reference in New Issue
Block a user