refactor: 템플릿에서 기본적으로 제공하고 있는 워크 플로우에 디자인과 라우팅 흡수

This commit is contained in:
donghyeon-ka
2026-09-23 12:42:10 +09:00
parent afde2b1da1
commit aaa384c145
181 changed files with 12553 additions and 5280 deletions
@@ -0,0 +1,148 @@
# TechLog Application Boundary + Behavioral i18n Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox syntax for tracking.
**Goal:** Close the two remaining TechLog re-review items so the application API hides outbound gateways and TechLog behavioral copy is catalog-driven and enforced by `check:i18n`.
**Architecture:** `createTechLogStudioApplication()` owns `StudioGateway`, `StudioAssetGateway`, and `ManagementGateway` privately and exposes application-owned query/command capability objects. TechLog presentation keeps using server-state hooks, but server-state calls application capabilities rather than extracting gateway ports. Behavioral copy moves to the TechLog message catalog with interpolation, and `scripts/check-i18n.ts` gains a targeted TechLog behavioral scanner rather than a blanket Korean-literal ban.
**Tech Stack:** TypeScript 7, React, Vitest, pnpm, custom architecture/i18n check scripts.
**Spec:** `docs/superpowers/specs/2026-09-23-tech-log-application-boundary-i18n-design.md`
## Global Constraints
- Preserve all existing user changes; no reset/checkout/clean/commit/merge.
- Use Node 24.11.0 for verification without changing repository configuration.
- Do not intentionally change visible Korean copy or accessibility names.
- `TechLogStudioApplication` must not expose, alias, extend, or return `StudioGateway`, `StudioAssetGateway`, or `ManagementGateway` objects.
- Components/controllers must not gain direct gateway/application orchestration that belongs in server-state.
- TechLog i18n gate targets behavioral copy only; headings, field labels, help text, domain status labels, and dynamic noun labels remain allowed.
## Review Focus
- Application capability methods preserve signal/idempotency options exactly; focused delegation test covers both query and mutation paths.
- Management capability split does not drop any operation currently consumed by `studio-management-server-state.ts`; typecheck and TechLog tests pin the full surface.
- Dynamic delete announcements preserve interpolation values and Korean rendering.
- i18n gate rejects direct behavioral announcements/actions but permits headings/field labels/domain status literals.
- Existing accessible copy such as `저장 중` remains byte-for-byte unchanged.
---
### Task 1: Application-owned Studio capability boundary
**Files:**
- Modify: `src/features/tech-log/application/studio-application.ts`
- Modify: `src/features/tech-log/adapters/create-tech-log-feature-input.ts`
- Modify: `src/features/tech-log/presentation/studio/studio-workspace-server-state.ts`
- Modify: `src/features/tech-log/presentation/studio/studio-document-server-state.ts`
- Modify: `src/features/tech-log/presentation/studio/studio-asset-server-state.ts`
- Modify: `src/features/tech-log/presentation/studio/studio-management-server-state.ts`
- Test: `tests/features/tech-log/studio-application-boundary.test.ts`
**Interfaces:**
- Produces: `createTechLogStudioApplication({ studio, assets, management }): TechLogStudioApplication`
- Produces capability properties: `workspaceQueries`, `workspaceCommands`, `documentQueries`, `documentCommands`, `assetQueries`, `assetCommands`, `managementQueries`, `managementCommands`.
- Consumes existing DTOs/return types and request/idempotency option types; outbound port types are private factory dependencies only.
- [ ] **Step 1: Write failing boundary/delegation test**
Create a focused test that constructs spy-like in-memory gateways, calls representative application capability methods, and asserts delegation. Add static assertions that the public application value has no `documents`, `assets`, or `management` properties.
- [ ] **Step 2: Run the focused test and verify RED**
Run under Node 24.11.0:
`corepack pnpm exec vitest run tests/features/tech-log/studio-application-boundary.test.ts`
Expected: FAIL because `createTechLogStudioApplication` / application-owned capability properties do not exist yet.
- [ ] **Step 3: Implement minimal application capability API**
Define application-owned query/command capability types with explicit method signatures copied from current port operations, then implement `createTechLogStudioApplication()` with frozen capability objects delegating to the private gateways.
- [ ] **Step 4: Wire composition root and server-state**
Change `create-tech-log-feature-input.ts` to call the factory. Replace all `application.documents/assets/management` extraction in Studio server-state with the corresponding query/command capability object. Do not change component/controller public APIs unless type propagation requires it.
- [ ] **Step 5: Run focused + type/architecture checks**
Run:
`corepack pnpm exec vitest run tests/features/tech-log/studio-application-boundary.test.ts`
`corepack pnpm check:types`
`corepack pnpm check:architecture`
Expected: PASS.
### Task 2: TechLog behavioral copy catalog migration and i18n gate
**Files:**
- Modify: `src/features/tech-log/contracts/tech-log-message-catalog.ts`
- Modify: affected files under `src/features/tech-log/presentation/studio/**`
- Modify: affected files under `src/features/tech-log/presentation/public/**`
- Modify: `scripts/check-i18n.ts`
- Modify/Create: `tests/unit/i18n-contract.test.ts` and/or `tests/fixtures/i18n/**` as appropriate to the existing checker test harness.
**Interfaces:**
- Consumes: existing `useTechLogCopy()` / locale message interpolation API.
- Produces: catalog keys for behavioral notices/failures/public error states and interpolation keys for dynamic deletion announcements.
- Produces: targeted TechLog behavioral checker integrated into `check:i18n`.
- [ ] **Step 1: Add failing i18n checker tests/fixtures**
Add one forbidden fixture representing a direct TechLog behavioral literal such as `setNotice("삭제했습니다.")` and one allowed fixture representing a heading/field label/domain status literal. Ensure the checker distinguishes them.
- [ ] **Step 2: Run i18n test/check and verify RED**
Run `corepack pnpm check:i18n` and the focused i18n unit test command used by `tests/unit/i18n-contract.test.ts`.
Expected: the new behavioral negative fixture is not detected yet.
- [ ] **Step 3: Implement targeted TechLog behavioral scanner**
Keep the existing common-presentation blanket scan unchanged. Add TechLog presentation files as a separate source set and inspect targeted contexts: static Button action text, action-label props, `setRequestAnnouncement`, `setNotice`, `setSuccess`, failure/error/loading/empty/not-found fallback literals, and public error/retry surfaces. Catalog calls and interpolated message calls must pass. Editorial/domain literals must pass.
- [ ] **Step 4: Migrate actual behavioral literals**
Move the currently identified Studio/Public notices/failures/error states into `tech-log-message-catalog.ts` for `ko-KR` and `en-US`. Convert dynamic delete announcements to message interpolation. Preserve rendered Korean strings and existing accessibility names.
- [ ] **Step 5: Run focused i18n + TechLog tests**
Run:
`corepack pnpm check:i18n`
`corepack pnpm test:tech-log`
Expected: PASS with zero TechLog behavioral literal violations.
### Task 3: Final regression and re-review evidence
**Files:**
- Modify: `docs/reviews/2026-09-22-tech-log-template-utilization-rereview.md`
- Create or update: `docs/reviews/2026-09-23-tech-log-template-utilization-rereview.md`
**Interfaces:**
- Consumes Tasks 1-2 outputs.
- Produces final 10-item re-review evidence only after fresh verification passes.
- [ ] **Step 1: Run all required checks under Node 24.11.0**
Run exactly:
`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: all PASS.
- [ ] **Step 2: Collect static evidence**
Record counts for application gateway type exposure, presentation gateway port imports, raw gateway extraction, component/controller gateway direct calls, TechLog behavioral literal violations, raw native controls/form/dialog, and controller files.
Expected: gateway/i18n/raw DOM violations 0; controllers 5.
- [ ] **Step 3: Update re-review docs**
Only after fresh verification, update the review from `완료: 8 / 아직 더 봐야댐: 2` to `완료: 10 / 아직 더 봐야댐: 0`, with actual current test counts and commands.
- [ ] **Step 4: No commit**
Do not commit. Preserve the user's existing dirty worktree and report only changed files and fresh verification evidence.
@@ -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.