refactor: 템플릿에서 기본적으로 제공하고 있는 워크 플로우에 디자인과 라우팅 흡수
This commit is contained in:
@@ -0,0 +1,398 @@
|
||||
# TechLog Application Boundary and Behavioral i18n Design
|
||||
|
||||
## Context
|
||||
|
||||
The 2026-09-23 TechLog frontend re-review re-opened two items that had previously been marked complete:
|
||||
|
||||
1. `TechLogFeatureInput / StudioContext application boundary`
|
||||
2. `behavioral action/error/loading/empty copy i18n`
|
||||
|
||||
The current implementation is otherwise considered complete for the remaining eight review axes. This design intentionally limits scope to these two open items and the regression evidence required to close them.
|
||||
|
||||
The existing worktree contains substantial unrelated user changes. Those changes must be preserved. No reset, checkout, clean, commit, merge, or other destructive Git operation is part of this work.
|
||||
|
||||
## Goals
|
||||
|
||||
### Goal A — Hide outbound gateway ports behind an application-owned API
|
||||
|
||||
`TechLogStudioApplication` must stop exposing `StudioGateway`, `StudioAssetGateway`, and `ManagementGateway` as public properties.
|
||||
|
||||
Presentation server-state code must consume application-owned query/command capabilities instead of extracting raw outbound ports from the application facade.
|
||||
|
||||
### Goal B — Make TechLog behavioral copy verifiably catalog-driven
|
||||
|
||||
Behavioral action, success, error, loading, empty-state, not-found, and validation-facing copy in TechLog presentation must use the TechLog message catalog, including dynamic announcements through interpolation.
|
||||
|
||||
`check:i18n` must include a TechLog-specific behavioral-copy gate so a passing i18n check is actual evidence that these literals are not reintroduced.
|
||||
|
||||
## Non-goals
|
||||
|
||||
This work does not migrate every Korean literal in TechLog presentation into the catalog.
|
||||
|
||||
The following remain intentionally allowed when they are domain/editorial copy rather than behavioral UI copy:
|
||||
|
||||
- headings
|
||||
- long-form explanatory text
|
||||
- help text
|
||||
- field labels
|
||||
- publication/domain status labels
|
||||
- document titles and other content values
|
||||
- dynamic noun-based labels where the noun itself is domain content
|
||||
|
||||
This work does not redesign HTTP, route, design-system, server-state runtime, Taxonomy projection, controller boundaries, or management allowed-value SSOT beyond changes strictly required by the two open review items.
|
||||
|
||||
## Current problem 1 — Application facade leaks outbound ports
|
||||
|
||||
The current public type is effectively:
|
||||
|
||||
```ts
|
||||
export type TechLogStudioApplication = Readonly<{
|
||||
documents: StudioGateway;
|
||||
assets: StudioAssetGateway;
|
||||
management: ManagementGateway;
|
||||
}>;
|
||||
```
|
||||
|
||||
Although `TechLogFeatureInput` and `StudioContextValue` no longer expose three gateway factories directly, server-state code still performs operations such as:
|
||||
|
||||
```ts
|
||||
const { documents: gateway } = useStudioApplication();
|
||||
const gateway = application.assets;
|
||||
```
|
||||
|
||||
This means presentation still receives outbound port objects. The boundary has been renamed but not raised to an application use-case API.
|
||||
|
||||
## Application boundary design
|
||||
|
||||
### Public application shape
|
||||
|
||||
`TechLogStudioApplication` will expose application-owned query and command capabilities, grouped by responsibility rather than by outbound adapter.
|
||||
|
||||
The target shape is:
|
||||
|
||||
```ts
|
||||
export type TechLogStudioApplication = Readonly<{
|
||||
workspaceQueries: StudioWorkspaceQueries;
|
||||
workspaceCommands: StudioWorkspaceCommands;
|
||||
documentQueries: StudioDocumentQueries;
|
||||
documentCommands: StudioDocumentCommands;
|
||||
assetQueries: StudioAssetQueries;
|
||||
assetCommands: StudioAssetCommands;
|
||||
managementQueries: StudioManagementQueries;
|
||||
managementCommands: StudioManagementCommands;
|
||||
}>;
|
||||
```
|
||||
|
||||
The exact grouping follows current server-state responsibilities. The grouping is an application API; none of these exported capability types may alias, extend, or expose `StudioGateway`, `StudioAssetGateway`, or `ManagementGateway`.
|
||||
|
||||
### Capability ownership
|
||||
|
||||
#### `StudioWorkspaceQueries`
|
||||
|
||||
Owns read operations used by dashboard/list/publication/catalog workflows, including the current equivalents of:
|
||||
|
||||
- get dashboard
|
||||
- list documents
|
||||
- list publications
|
||||
- get publication snapshot
|
||||
- get catalog
|
||||
|
||||
#### `StudioWorkspaceCommands`
|
||||
|
||||
Owns workspace-level mutations currently used outside the document editor lifecycle, including the current equivalents of:
|
||||
|
||||
- create document
|
||||
- unpublish publication
|
||||
|
||||
#### `StudioDocumentQueries`
|
||||
|
||||
Owns document-editor reads:
|
||||
|
||||
- get document
|
||||
- get current preview
|
||||
|
||||
#### `StudioDocumentCommands`
|
||||
|
||||
Owns document-editor mutations:
|
||||
|
||||
- save document
|
||||
- validate document
|
||||
- create preview
|
||||
- publish document
|
||||
|
||||
#### `StudioAssetQueries`
|
||||
|
||||
Owns asset reads:
|
||||
|
||||
- list assets
|
||||
- get asset
|
||||
|
||||
#### `StudioAssetCommands`
|
||||
|
||||
Owns asset mutations:
|
||||
|
||||
- upload asset
|
||||
- update asset metadata
|
||||
- delete asset
|
||||
|
||||
#### `StudioManagementQueries` and `StudioManagementCommands`
|
||||
|
||||
Expose the management read/write operations currently consumed by `studio-management-server-state.ts`, grouped by query versus mutation ownership.
|
||||
|
||||
The public application contract can preserve current command/query DTOs and return values where they already represent application-level concepts. The requirement is specifically that the outbound gateway interfaces themselves are hidden.
|
||||
|
||||
### Factory
|
||||
|
||||
A dedicated application factory will own outbound ports as private dependencies:
|
||||
|
||||
```ts
|
||||
export function createTechLogStudioApplication(dependencies: Readonly<{
|
||||
studio: StudioGateway;
|
||||
assets: StudioAssetGateway;
|
||||
management: ManagementGateway;
|
||||
}>): TechLogStudioApplication
|
||||
```
|
||||
|
||||
The implementation will build frozen capability objects whose methods delegate to the private dependencies.
|
||||
|
||||
`create-tech-log-feature-input.ts` will construct the three adapters as it does today and pass them into `createTechLogStudioApplication(...)`. It will no longer construct an object literal that exposes the gateways.
|
||||
|
||||
### Presentation integration
|
||||
|
||||
`StudioContextValue` continues to expose one `studioApplication` value.
|
||||
|
||||
Server-state modules will switch from raw port extraction:
|
||||
|
||||
```ts
|
||||
application.documents
|
||||
application.assets
|
||||
application.management
|
||||
```
|
||||
|
||||
to application capabilities:
|
||||
|
||||
```ts
|
||||
application.workspaceQueries
|
||||
application.workspaceCommands
|
||||
application.documentQueries
|
||||
application.documentCommands
|
||||
application.assetQueries
|
||||
application.assetCommands
|
||||
application.managementQueries
|
||||
application.managementCommands
|
||||
```
|
||||
|
||||
Components and controllers continue to consume server-state hooks and must not gain direct application capability orchestration that belongs in server-state.
|
||||
|
||||
### Boundary invariants
|
||||
|
||||
The final implementation must satisfy all of these:
|
||||
|
||||
```text
|
||||
TechLogStudioApplication references to *Gateway public property types = 0
|
||||
presentation imports from application/ports/*gateway* = 0
|
||||
presentation raw .documents/.assets/.management application extraction = 0
|
||||
component gateway direct calls = 0
|
||||
controller gateway direct calls = 0
|
||||
```
|
||||
|
||||
Outbound gateway types may remain in adapter/application implementation files where dependency inversion requires them.
|
||||
|
||||
## Current problem 2 — Behavioral i18n has feature-level blind spots
|
||||
|
||||
The TechLog catalog already contains many action/state/failure keys, but direct behavioral literals remain in presentation.
|
||||
|
||||
Observed examples include:
|
||||
|
||||
```text
|
||||
저장하지 못했습니다. 다시 시도해 주세요.
|
||||
검증하지 못했습니다. 다시 시도해 주세요.
|
||||
Public Preview를 만들지 못했습니다. 다시 시도해 주세요.
|
||||
게시하지 못했습니다. 다시 시도해 주세요.
|
||||
게시했습니다.
|
||||
홈에 표시할 항목을 저장했습니다.
|
||||
보관했습니다.
|
||||
삭제했습니다.
|
||||
대체 텍스트를 저장했습니다.
|
||||
페이지를 찾을 수 없습니다.
|
||||
최근 기록을 불러오지 못했습니다.
|
||||
페이지를 불러오지 못했습니다.
|
||||
```
|
||||
|
||||
Dynamic announcements also remain, for example deletion messages containing release, variant, document, topic, or project names.
|
||||
|
||||
The current `scripts/check-i18n.ts` hardcoded-locale scan checks shared `src/presentation/*` directories but not `src/features/tech-log/presentation`, so `check:i18n=PASS` does not prove TechLog behavioral-copy completeness.
|
||||
|
||||
## Behavioral i18n design
|
||||
|
||||
### Catalog migration
|
||||
|
||||
Behavioral literals will move into `tech-log-message-catalog.ts` for both `ko-KR` and `en-US`.
|
||||
|
||||
Static messages use ordinary keys, for example:
|
||||
|
||||
```text
|
||||
techLog.notice.published
|
||||
techLog.notice.homeFocusSaved
|
||||
techLog.notice.assetArchived
|
||||
techLog.notice.assetDeleted
|
||||
techLog.notice.assetAltTextSaved
|
||||
techLog.failure.saveRetry
|
||||
techLog.failure.validationRetry
|
||||
techLog.failure.previewRetry
|
||||
techLog.failure.publishRetry
|
||||
techLog.public.notFound
|
||||
techLog.public.latestLoadFailed
|
||||
techLog.public.pageLoadFailed
|
||||
```
|
||||
|
||||
Existing semantically equivalent keys must be reused instead of duplicated.
|
||||
|
||||
### Interpolated announcements
|
||||
|
||||
Dynamic success/announcement copy must use interpolation parameters rather than template literals in presentation.
|
||||
|
||||
Representative target pattern:
|
||||
|
||||
```ts
|
||||
copy("techLog.notice.documentDeleted", {
|
||||
title: item.title || copy("techLog.state.untitled"),
|
||||
});
|
||||
```
|
||||
|
||||
with matching locale entries such as:
|
||||
|
||||
```text
|
||||
ko-KR: 작업본 {title} 을(를) 삭제했습니다.
|
||||
en-US: Deleted working copy {title}.
|
||||
```
|
||||
|
||||
The exact key naming may follow the existing catalog organization, but interpolation parameter names must match across locales and continue to pass the existing catalog interpolation contract check.
|
||||
|
||||
### TechLog-specific i18n gate
|
||||
|
||||
`check-i18n.ts` will keep the existing blanket common-presentation scan unchanged for shared UI.
|
||||
|
||||
TechLog presentation will be added through a separate behavioral rule set, not through the blanket Korean-literal regex. This avoids falsely rejecting allowed domain/editorial Korean copy.
|
||||
|
||||
The TechLog behavioral gate must detect direct user-facing behavioral literals in at least these contexts:
|
||||
|
||||
- static `Button` action text
|
||||
- action-like props such as `pendingLabel`, `closeLabel`, `resetLabel`, and similar control labels
|
||||
- `setRequestAnnouncement("...")`
|
||||
- `setNotice("...")`
|
||||
- `setSuccess("...")`
|
||||
- direct fallback strings used for error/failure/loading/empty/not-found behavior
|
||||
- direct behavioral literals in public error/empty/retry surfaces
|
||||
|
||||
The rule must permit catalog calls and interpolated message calls.
|
||||
|
||||
The gate should be implemented as a targeted source checker rather than a blanket ban on Korean literals under the whole feature directory.
|
||||
|
||||
### Gate testability
|
||||
|
||||
The checker must have negative fixtures or equivalent explicit test inputs demonstrating that it fails for representative TechLog behavioral literals and does not fail for allowed domain/editorial copy.
|
||||
|
||||
At minimum, fixture coverage must pin these two distinctions:
|
||||
|
||||
1. a direct behavioral announcement/action literal fails;
|
||||
2. a heading/field-label/domain-status literal is allowed.
|
||||
|
||||
## Compatibility requirements
|
||||
|
||||
The refactor must not intentionally change visible Korean copy or accessibility names unless an existing copy contract is already inconsistent.
|
||||
|
||||
If moving a string to the catalog would change punctuation, ellipsis, spacing, or an accessible button name, preserve the existing rendered value with a dedicated key rather than changing tests to accept the new copy.
|
||||
|
||||
The existing `저장 중` versus `저장 중…` regression is the precedent: preserve the concrete UI contract and represent distinct copy as distinct keys when necessary.
|
||||
|
||||
## Test strategy
|
||||
|
||||
### Application boundary tests
|
||||
|
||||
Add or update focused tests that prove the application factory delegates through application-owned capabilities without exposing outbound ports.
|
||||
|
||||
Static architecture checks must prove:
|
||||
|
||||
```text
|
||||
TechLogStudioApplication public gateway type exposure = 0
|
||||
presentation raw gateway extraction = 0
|
||||
presentation gateway port imports = 0
|
||||
```
|
||||
|
||||
Existing server-state behavior tests should continue to pass unchanged where observable behavior has not changed.
|
||||
|
||||
### i18n tests
|
||||
|
||||
Add or update checker fixtures/tests so `check:i18n` fails when TechLog behavioral literals are introduced into guarded contexts.
|
||||
|
||||
Catalog interpolation parity across locales must remain enforced.
|
||||
|
||||
### Full regression
|
||||
|
||||
Use Node 24.11.0 without changing repository configuration and run:
|
||||
|
||||
```text
|
||||
corepack pnpm check:types
|
||||
corepack pnpm lint
|
||||
corepack pnpm check:architecture
|
||||
corepack pnpm check:design-system
|
||||
corepack pnpm check:tech-log-contract
|
||||
corepack pnpm check:i18n
|
||||
corepack pnpm test:tech-log
|
||||
corepack pnpm test:component
|
||||
corepack pnpm build:app-only
|
||||
git diff --check
|
||||
```
|
||||
|
||||
Expected baseline:
|
||||
|
||||
```text
|
||||
TechLog: 60 files / 416 tests PASS
|
||||
Component: 27 files / 154 tests PASS
|
||||
```
|
||||
|
||||
If test counts change because new focused tests are added, the new larger counts become the final evidence.
|
||||
|
||||
## Final static evidence
|
||||
|
||||
The re-review is complete only when all final evidence is collected from the current worktree:
|
||||
|
||||
```text
|
||||
application gateway type exposure = 0
|
||||
presentation gateway port import = 0
|
||||
presentation raw gateway extraction = 0
|
||||
component/controller gateway direct call = 0
|
||||
behavioral literal violations = 0
|
||||
raw native control = 0
|
||||
raw form = 0
|
||||
raw dialog = 0
|
||||
controller files = 5
|
||||
```
|
||||
|
||||
## Completion criteria
|
||||
|
||||
The two re-opened review axes can be marked complete only when:
|
||||
|
||||
1. `TechLogStudioApplication` exposes application-owned query/command capabilities and no raw outbound gateway object;
|
||||
2. Studio/Public behavioral literals are catalog-driven, including dynamic announcements;
|
||||
3. `check:i18n` actively checks TechLog feature presentation behavioral copy;
|
||||
4. targeted i18n gate tests/fixtures demonstrate the rule catches regressions without blanket-rejecting domain/editorial copy;
|
||||
5. Node 24 full regression passes;
|
||||
6. final static evidence reports zero violations for the application-boundary and behavioral-i18n criteria.
|
||||
|
||||
At that point the 2026-09-23 re-review may move from:
|
||||
|
||||
```text
|
||||
완료: 8
|
||||
아직 더 봐야댐: 2
|
||||
```
|
||||
|
||||
to:
|
||||
|
||||
```text
|
||||
완료: 10
|
||||
아직 더 봐야댐: 0
|
||||
```
|
||||
|
||||
No completion claim is allowed before those checks pass.
|
||||
Reference in New Issue
Block a user