110 lines
4.9 KiB
Markdown
110 lines
4.9 KiB
Markdown
# Bank Composition Details DTO Projection Decision
|
|
|
|
Status: Decided
|
|
Cycle: 2026-03
|
|
Domain Owner: `docs/studio`
|
|
Cross-Domain Impact: `docs/packer`
|
|
|
|
## Context
|
|
|
|
The `Bank Composition` section inside `Asset Details` needs a stable UI-facing data shape before component, middleware, and persistence work can proceed.
|
|
|
|
The source information comes from two distinct places:
|
|
|
|
- runtime snapshot state derived from `walkResult`, which should feed `available` files;
|
|
- persisted `asset.json` composition state, which should feed `selected` files.
|
|
|
|
The Studio should not bind section UI directly to snapshot internals or raw manifest structures.
|
|
This needs a Studio-owned DTO projection boundary.
|
|
|
|
This decision closes the DTO direction discussed in:
|
|
|
|
- [`Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md`](../agendas/Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md)
|
|
|
|
## Decision
|
|
|
|
Adopt one dedicated Studio-owned DTO family for `Bank Composition` details data.
|
|
|
|
The first-wave projection rules are:
|
|
|
|
1. snapshot rows derived from `walkResult` become `available` rows in the Studio DTO layer;
|
|
2. persisted composition rows from `asset.json` become `selected` rows in the Studio DTO layer;
|
|
3. both flows must be projected into Studio DTOs before reaching `Asset Details` UI code;
|
|
4. the DTO family must be generic enough to support any bank type, even if family-specific fields are added later;
|
|
5. the DTO field set must stay intentionally small and grow only when concrete UI behavior requires it.
|
|
|
|
The first DTO revision starts with these fields:
|
|
|
|
- `path`
|
|
- `displayName`
|
|
- `size`
|
|
- `lastModified`
|
|
- `fingerprint`
|
|
- `metadata`
|
|
|
|
Availability and ordering rules are:
|
|
|
|
1. only non-blocking files become `available` DTO rows;
|
|
2. blocking files must not be projected into the `Bank Composition` DTO layer;
|
|
3. UI ordering is visual in the selected list;
|
|
4. persisted ordering in `asset.json` should use an explicit index representation such as `{ file, index }`.
|
|
|
|
## Justification
|
|
|
|
This direction keeps the Studio UI decoupled from packer/runtime internal shapes while still using runtime data as the source of truth.
|
|
|
|
One shared DTO family is the pragmatic middle ground:
|
|
|
|
- lighter than separate `available` and `selected` row models;
|
|
- safer than direct binding to snapshot and manifest structures;
|
|
- easier to reuse across section shell, transfer list, meter, and staged editing middleware.
|
|
|
|
Filtering blocking files before DTO projection also keeps the section contract simpler.
|
|
The UI should receive only rows that are actually eligible to appear as `available`.
|
|
|
|
Persisted order needs an explicit index in `asset.json` because list order is not a robust persistence contract by itself.
|
|
|
|
## Implications
|
|
|
|
The Studio details layer now owns a DTO projection step for `Bank Composition`.
|
|
|
|
This means:
|
|
|
|
- component work should consume Studio DTOs, not packer snapshot rows directly;
|
|
- middleware work should operate on DTO-based staged state;
|
|
- persistence work must translate selected DTO order into indexed `asset.json` entries;
|
|
- packer-facing details fetches must expose enough source data to populate the DTO fields above.
|
|
|
|
## Explicit Non-Decisions
|
|
|
|
This decision does not yet define:
|
|
|
|
- the exact Java classes or package layout for the DTOs;
|
|
- the section middleware/controller contract;
|
|
- the `workspaceBus` event contract;
|
|
- the concrete `asset.json` `artifacts` schema beyond the need for explicit indexed order;
|
|
- family-specific explanatory copy for tile versus sound exhaustion.
|
|
|
|
## Propagation Targets
|
|
|
|
- Studio agendas:
|
|
[`Agenda-02-Asset-Bank-Composition-Base-Components.md`](../agendas/Agenda-02-Asset-Bank-Composition-Base-Components.md)
|
|
[`Agenda-03-Asset-Bank-Composition-Section-Shell.md`](../agendas/Agenda-03-Asset-Bank-Composition-Section-Shell.md)
|
|
[`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](../agendas/Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md)
|
|
[`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](../agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md)
|
|
[`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](../agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md)
|
|
- Studio specs:
|
|
[`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
|
- Studio code:
|
|
`Asset Details` details fetch, DTO projection layer, and `Bank Composition` section inputs
|
|
- Packer code and docs:
|
|
details payload shaping and future `asset.json` persistence under the `artifacts` composition path
|
|
|
|
## Validation Notes
|
|
|
|
Examples implied by this decision:
|
|
|
|
- a file with blocking diagnostics does not produce an `available` DTO row at all;
|
|
- a selected file may appear in the UI with visual order `3`, while persistence writes something like `{ file: "...", index: 3 }`;
|
|
- adding new UI needs later should extend the DTO deliberately instead of pulling snapshot internals straight into the section.
|