kjh2064/KArtSell.Aegis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: record KBX v36 design harness (V13-FE-001)

Browse Source
This commit is contained in:
김재현
2026-08-09 00:53:36 +09:00
parent 9ffb740f07
commit b70eab02d1
2 changed files with 89 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CURRENT/CATALOGS/WBS_PROGRESS_TRACKER.csv
+1
View File
@@ -39,3 +39,4 @@ AEG-VS-19-01,S5,VS-19,RunFrozenBacktest,BLOCKED,TBD,"CLAUDE.md: Requires evidenc
AEG-VS-28-01,S2,VS-28,"거래 실행 시스템 구현 (Trade Execution, KIS Integration)",COMPLETED,2026-08-07,"docs/CURRENT/SLICE_SPECS/VS-28-SLICE_SPEC.md; src/KArtSell.Modules.ModelOperations/TradeExecution/ (TradeEndpoints.cs, TradeHandlers.cs, TradeSql.cs, Trade.cs, KisTradeExecutionService.cs); db/migrations/0039_trades.sql; tests/KArtSell.Integration.Tests/TradeExecution/TradeExecutionTests.cs; commit b1e38ac (Phase 3 K, PR #28, merged to main)",BE Lead/Trading Ops,"New row — no prior tracker entry existed for this slice. ✅ Backend implementation + tests complete: Trade state machine (Pending→Submitted→Accepted→PartiallyFilled/FullyFilled→Confirmed→Reconciled), KIS order submission/poll/settlement. 13/13 tests PASS run in isolation (2026-08-07), but only after two real bugs were fixed on fix/dapper-underscore-mapping-and-build: (1) UpdateTradeStatusAsync only ever persisted status/kis_response/error_message and silently dropped kis_order_id, executed_quantity, unit_price, commission, net_proceeds and both timestamps on every single call since the slice merged — trade fills and settlements were not actually being recorded; (2) the same Dapper snake_case-mapping race condition described in AEG-VS-27-01's notes. ⚠️ Frontend UI built 2026-08-09 (frontend/src/features/trade-execution/, route /ops/trade-execution, pnpm typecheck/build clean, 13 new tests passing) after an earlier attempt failed on the session spend limit and was resumed — on isolated worktree branch worktree-agent-aae90f132a2daf359 (HEAD predates the VS-12→VS-28 renumbering, so that worktree's own tracker row is still AEG-VS-12-01), not yet merged into this branch. Found DEBT-025 there too: TradeEndpoints.cs is AllowAnonymous() with no Roles()/Policies() at all (unlike SellDecisionEndpoints.cs); collides with two other independently-numbered DEBT-025 entries on other unmerged branches — renumber on merge. Renumbered from VS-12 to VS-28 on 2026-08-08 per docs/DECISIONS/ADR-WBS-001-slice-renumbering.md — VS-12 in WBS_MASTER.csv ('RankBuyCandidates') was an unrelated, still-unimplemented slice and keeps its original number unchanged. 2026-08-08 (BE priority pass): DEBT-018 (outbox write not co-transactional with the trade status update) fixed — see TECH_DEBT_REGISTER.md; `dotnet build -c Release` clean, DB-backed tests still unverified (no reachable Postgres this session). 2026-08-09: DEBT-027 fixed — PollTradeStatusHandler/ConfirmSettlementHandler were registered in DI but never invoked by anything (no endpoint, no job); added src/KArtSell.Host/Jobs/TradeStatusPollingJob.cs as a Hangfire recurring job so submitted trades actually progress to Confirmed. `dotnet build -c Release` clean; no dedicated test added (see TECH_DEBT_REGISTER.md for why) and not run against a live database/KIS."
AEG-VS-29-01,S2,VS-29,포트폴리오 대사 구현 (Portfolio Reconciliation),COMPLETED,2026-08-07,"docs/CURRENT/SLICE_SPECS/VS-29-SLICE_SPEC.md; src/KArtSell.Modules.ModelOperations/PortfolioReconciliation/ (Endpoints.cs, ReconcileTradeHandler.cs, ReconciliationEngine.cs, ReconciliationSql.cs, MismatchDetector.cs, CostBasisCalculator.cs); tests/KArtSell.Integration.Tests/PortfolioReconciliation/ReconciliationEngineTests.cs; tests/KArtSell.ModelOperations.UnitTests/EvaluationReconciliationPlannerTests.cs; commit b1e38ac (Phase 3 L, PR #28, merged to main); commit 4059828 (fix: missing model_operations.models table breaking every fresh DB, PR #29, merged to main same day)",BE Lead,"New row — no prior tracker entry existed for this slice. ✅ Backend implementation + tests complete: Sell Decision → Trade → Holdings reconciliation, cost-basis calculation, mismatch detection. 18/18 tests PASS run in isolation (2026-08-07). Note this slice's own merge (PR #28) shipped with a missing model_operations.models table that broke every fresh-database migration; that was caught and fixed same day in PR #29 — a reminder that this branch's fresh-install DbUp path had not actually been rehearsed before merge. ⚠️ No frontend UI yet — an attempt was started 2026-08-08 but the background agent building it failed (hit the session's monthly spend limit) before producing any committed code; not resumed this session. Renumbered from VS-14 to VS-29 on 2026-08-08 per docs/DECISIONS/ADR-WBS-001-slice-renumbering.md — VS-14 in WBS_MASTER.csv ('GenerateDailyRecommendations') was an unrelated, still-unimplemented slice and keeps its original number unchanged. 2026-08-08 (BE priority pass): DEBT-018 (outbox writes for TradeReconciled/ReconciliationMismatchAlert not co-transactional with the holding/log write) fixed — see TECH_DEBT_REGISTER.md; `dotnet build -c Release` clean, DB-backed tests still unverified (no reachable Postgres this session)."
PHASE-1-SHADOW-RUN,S0-S5,Cross,252+ Trading Day Shadow Run,BLOCKED,TBD,"docs/CURRENT/PHASE-1_SHADOW_RUN_STATUS_CORRECTION.md; docs/CURRENT/AEG-X-004_DBUP_EVIDENCE.md; docs/CURRENT/PHASE-1_REQUEUE_READINESS.md; docs/CURRENT/PHASE-1_EXECUTION_EVIDENCE_PLAN.md; docs/CURRENT/PHASE-1_PREFLIGHT_20260806.md; docs/CURRENT/PHASE-1_PRODUCTION_PREFLIGHT_20260806.md; evidence/AEG-X-004/production-readonly-preflight-20260806.md; db/migrations/0032_shadow_run_queued_status_contract.sql; logs/phase-1-execution.log; logs/host-startup-20260804-173000.log",김재현/BE/SRE,"Read-only preflight: active DbUp journal public.kartsell_schema_versions contains 0032 and check_status includes Queued. Capabilities remain order/KIS/client publication OFF. Server-side dataset_manifest, model_version_registry, evidence_snapshot, and release_evidence_bundle contain no approved/frozen rows; no RunId/JobId/enqueue created. Blocked pending approved server-side VersionSet. Re-confirmed 2026-08-07: still no RunId/JobId exists anywhere in this workspace or its evidence trail; nothing changed on this row this session. Any future document that claims this row is RUNNING must cite a real RunId/JobId — do not restate the earlier (already-corrected) false claim."
V13-FE-001,S0,Cross,UI Vendor import boundary,COMPLETED,2026-08-09,"docs/CURRENT/V13-FE-001_KBX_V36_DESIGN_HARNESS_PROPOSAL.md; tools/validate_v16.py",FE Architect/QA,"Dependency AEG-X-003 is COMPLETED. KBX v36 was translated as a non-vendor design-evidence harness: preserve the shared UI adapter boundary, keep feature direct PrimeVue/AG Grid imports at zero, and defer token/recipe implementation to separately approved slices. Actual evidence: python tools/validate_v16.py exited 0 with PASS=1 WARN=2 FAIL=0 on 2026-08-09. Warnings are retained (no full source archive; approved runtime evidence absent); no runtime test/build/migration claim is made."
1 WBS_ID Sprint Slice_ID Task Status Completion_Date Evidence_Link Owner Notes
39 AEG-VS-28-01 S2 VS-28 거래 실행 시스템 구현 (Trade Execution, KIS Integration) COMPLETED 2026-08-07 docs/CURRENT/SLICE_SPECS/VS-28-SLICE_SPEC.md; src/KArtSell.Modules.ModelOperations/TradeExecution/ (TradeEndpoints.cs, TradeHandlers.cs, TradeSql.cs, Trade.cs, KisTradeExecutionService.cs); db/migrations/0039_trades.sql; tests/KArtSell.Integration.Tests/TradeExecution/TradeExecutionTests.cs; commit b1e38ac (Phase 3 K, PR #28, merged to main) BE Lead/Trading Ops New row — no prior tracker entry existed for this slice. ✅ Backend implementation + tests complete: Trade state machine (Pending→Submitted→Accepted→PartiallyFilled/FullyFilled→Confirmed→Reconciled), KIS order submission/poll/settlement. 13/13 tests PASS run in isolation (2026-08-07), but only after two real bugs were fixed on fix/dapper-underscore-mapping-and-build: (1) UpdateTradeStatusAsync only ever persisted status/kis_response/error_message and silently dropped kis_order_id, executed_quantity, unit_price, commission, net_proceeds and both timestamps on every single call since the slice merged — trade fills and settlements were not actually being recorded; (2) the same Dapper snake_case-mapping race condition described in AEG-VS-27-01's notes. ⚠️ Frontend UI built 2026-08-09 (frontend/src/features/trade-execution/, route /ops/trade-execution, pnpm typecheck/build clean, 13 new tests passing) after an earlier attempt failed on the session spend limit and was resumed — on isolated worktree branch worktree-agent-aae90f132a2daf359 (HEAD predates the VS-12→VS-28 renumbering, so that worktree's own tracker row is still AEG-VS-12-01), not yet merged into this branch. Found DEBT-025 there too: TradeEndpoints.cs is AllowAnonymous() with no Roles()/Policies() at all (unlike SellDecisionEndpoints.cs); collides with two other independently-numbered DEBT-025 entries on other unmerged branches — renumber on merge. Renumbered from VS-12 to VS-28 on 2026-08-08 per docs/DECISIONS/ADR-WBS-001-slice-renumbering.md — VS-12 in WBS_MASTER.csv ('RankBuyCandidates') was an unrelated, still-unimplemented slice and keeps its original number unchanged. 2026-08-08 (BE priority pass): DEBT-018 (outbox write not co-transactional with the trade status update) fixed — see TECH_DEBT_REGISTER.md; `dotnet build -c Release` clean, DB-backed tests still unverified (no reachable Postgres this session). 2026-08-09: DEBT-027 fixed — PollTradeStatusHandler/ConfirmSettlementHandler were registered in DI but never invoked by anything (no endpoint, no job); added src/KArtSell.Host/Jobs/TradeStatusPollingJob.cs as a Hangfire recurring job so submitted trades actually progress to Confirmed. `dotnet build -c Release` clean; no dedicated test added (see TECH_DEBT_REGISTER.md for why) and not run against a live database/KIS.
40 AEG-VS-29-01 S2 VS-29 포트폴리오 대사 구현 (Portfolio Reconciliation) COMPLETED 2026-08-07 docs/CURRENT/SLICE_SPECS/VS-29-SLICE_SPEC.md; src/KArtSell.Modules.ModelOperations/PortfolioReconciliation/ (Endpoints.cs, ReconcileTradeHandler.cs, ReconciliationEngine.cs, ReconciliationSql.cs, MismatchDetector.cs, CostBasisCalculator.cs); tests/KArtSell.Integration.Tests/PortfolioReconciliation/ReconciliationEngineTests.cs; tests/KArtSell.ModelOperations.UnitTests/EvaluationReconciliationPlannerTests.cs; commit b1e38ac (Phase 3 L, PR #28, merged to main); commit 4059828 (fix: missing model_operations.models table breaking every fresh DB, PR #29, merged to main same day) BE Lead New row — no prior tracker entry existed for this slice. ✅ Backend implementation + tests complete: Sell Decision → Trade → Holdings reconciliation, cost-basis calculation, mismatch detection. 18/18 tests PASS run in isolation (2026-08-07). Note this slice's own merge (PR #28) shipped with a missing model_operations.models table that broke every fresh-database migration; that was caught and fixed same day in PR #29 — a reminder that this branch's fresh-install DbUp path had not actually been rehearsed before merge. ⚠️ No frontend UI yet — an attempt was started 2026-08-08 but the background agent building it failed (hit the session's monthly spend limit) before producing any committed code; not resumed this session. Renumbered from VS-14 to VS-29 on 2026-08-08 per docs/DECISIONS/ADR-WBS-001-slice-renumbering.md — VS-14 in WBS_MASTER.csv ('GenerateDailyRecommendations') was an unrelated, still-unimplemented slice and keeps its original number unchanged. 2026-08-08 (BE priority pass): DEBT-018 (outbox writes for TradeReconciled/ReconciliationMismatchAlert not co-transactional with the holding/log write) fixed — see TECH_DEBT_REGISTER.md; `dotnet build -c Release` clean, DB-backed tests still unverified (no reachable Postgres this session).
41 PHASE-1-SHADOW-RUN S0-S5 Cross 252+ Trading Day Shadow Run BLOCKED TBD docs/CURRENT/PHASE-1_SHADOW_RUN_STATUS_CORRECTION.md; docs/CURRENT/AEG-X-004_DBUP_EVIDENCE.md; docs/CURRENT/PHASE-1_REQUEUE_READINESS.md; docs/CURRENT/PHASE-1_EXECUTION_EVIDENCE_PLAN.md; docs/CURRENT/PHASE-1_PREFLIGHT_20260806.md; docs/CURRENT/PHASE-1_PRODUCTION_PREFLIGHT_20260806.md; evidence/AEG-X-004/production-readonly-preflight-20260806.md; db/migrations/0032_shadow_run_queued_status_contract.sql; logs/phase-1-execution.log; logs/host-startup-20260804-173000.log 김재현/BE/SRE Read-only preflight: active DbUp journal public.kartsell_schema_versions contains 0032 and check_status includes Queued. Capabilities remain order/KIS/client publication OFF. Server-side dataset_manifest, model_version_registry, evidence_snapshot, and release_evidence_bundle contain no approved/frozen rows; no RunId/JobId/enqueue created. Blocked pending approved server-side VersionSet. Re-confirmed 2026-08-07: still no RunId/JobId exists anywhere in this workspace or its evidence trail; nothing changed on this row this session. Any future document that claims this row is RUNNING must cite a real RunId/JobId — do not restate the earlier (already-corrected) false claim.
42 V13-FE-001 S0 Cross UI Vendor import boundary COMPLETED 2026-08-09 docs/CURRENT/V13-FE-001_KBX_V36_DESIGN_HARNESS_PROPOSAL.md; tools/validate_v16.py FE Architect/QA Dependency AEG-X-003 is COMPLETED. KBX v36 was translated as a non-vendor design-evidence harness: preserve the shared UI adapter boundary, keep feature direct PrimeVue/AG Grid imports at zero, and defer token/recipe implementation to separately approved slices. Actual evidence: python tools/validate_v16.py exited 0 with PASS=1 WARN=2 FAIL=0 on 2026-08-09. Warnings are retained (no full source archive; approved runtime evidence absent); no runtime test/build/migration claim is made.
docs/CURRENT/V13-FE-001_KBX_V36_DESIGN_HARNESS_PROPOSAL.md
+88
View File
@@ -0,0 +1,88 @@
# V13-FE-001 — KBX v36 디자인 하네스 제안
## 작업 식별
| 항목 | 값 |
| --- | --- |
| WBS | V13-FE-001 |
| Slice | Cross-cutting / UIFoundation |
| Requirement / API / DB / Job / UI / Test | REQ-FE-ADAPTER / Cross / Cross / Cross / UI-FOUND-01 / T-FE-ARCH-01 |
| Gate / 의존성 | G0 / AEG-X-003 (COMPLETED, tracker 확인) |
| 단일 목적 | UI 공급자 경계를 유지한 채 KBX v36의 디자인 운영 원칙을 K-ArtSell 검증 계약으로 번역 |
| Artifact / 수용 기준 | architecture rule / feature의 PrimeVue·AG Grid 직접 import 0 |
## Source / Assumption / Unknown / Decision Required
### Source
- `docs/Design/kbx-foundation-v36/docs/design-token-policy-v4.md`: primitive → semantic → component 토큰, 밀도는 배치·form·keyboard 계약을 바꾸지 않음.
- `docs/Design/kbx-foundation-v36/docs/kbx-v36-standard-traceability.md`: template → recipe → canonical scenario → Vitest/Playwright 증거의 연결.
- `docs/Design/kbx-foundation-v36/docs/screen-recipe-verification-home-attention-v36.md`: `testProfile`은 UX/복구/보안 검증 범위이며, client business truth가 아님.
- `frontend/src/shared/ui/adapter/`, `tools/validate_v16.py`: 현재 UI provider/adapter 경계와 정적 vendor-import 검사.
- `frontend/src/shared/ui/screen-types/catalogue.ts`, `contracts/ui/screen-types.v2.json`: T01~T10 화면 유형, 상태·증거·anti-pattern 계약.
- `frontend/src/design-system/tokens.css`: 현재 primitive와 일부 semantic/component 토큰.
### Assumption
- KBX v36 디렉터리는 사용자 제공 참조이며, 그 코드·패키지·브랜드 토큰을 vendor/copy하지 않는다.
- K-ArtSell의 T01~T10 의미와 현 UI adapter v4 계약은 유지한다.
- 토큰 값 자체, density 기본값, 화면별 canonical scenario는 승인된 디자인/QA 기준이 없는 한 변경하지 않는다.
### Unknown
- 승인된 visual baseline, 디자인 소유자, target density, 화면별 keyboard/AT acceptance matrix가 없다.
- 31개 대상 파일에서 353개의 색상·spacing literal 후보가 발견됐지만, provider CSS와 의도된 시각화 scale을 제외하는 승인된 baseline은 없다.
- 실제 각 템플릿을 대표하는 Playwright scenario와 CI artifact retention 정책이 아직 계약화되지 않았다.
### Decision Required
1. `V13-FE-002`에서 semantic/component token 명명과 literal baseline을 승인할 UX/FE owner.
2. T01~T10에 `testProfile` 및 canonical scenario를 추가할 ADR/Issue와 QA owner.
3. compact/comfortable/touch 중 제품별 기본 밀도와 visual regression baseline 보관 위치.
## 적용 하네스
KBX의 구현물을 가져오지 않고 다음 불변식을 K-ArtSell의 현 경계에 적용한다.
| KBX v36 원칙 | K-ArtSell 현재 기반 | 승인 후 하네스 |
| --- | --- | --- |
| Template가 UX를 책임 | `screenTemplateCatalogue`의 상태·증거·anti-pattern | 각 template에 UX/복구/보안만 담는 `testProfile`을 추가. 도메인 정책·임계값은 포함하지 않음. |
| Recipe → canonical evidence | Vitest catalogue test, `AEG-V16-024` a11y evidence | template별 최소 대표 scenario와 실제 trace/screenshot/test log를 연결. 선언만으로 통과시키지 않음. |
| 3계층 토큰 | `tokens.css`의 primitive 및 일부 역할/컴포넌트 token | 화면은 primitive가 아닌 semantic/component token만 소비. primitive 값 변경은 token 파일 한 곳으로 제한. |
| Density는 학습 UX가 아님 | `[data-density='compact']`가 control/grid 높이만 변경 | comfortable/touch는 승인된 값과 state/keyboard characterization test가 있을 때에만 추가. |
| Design debt ratchet | 현재 정적 validator 및 353 literal 후보 | 승인된 baseline 이후 새/증가 literal을 차단하고, 기존 부채는 감소만 허용. provider CSS/visualization scale은 명시적인 allowlist로 분리. |
| Fail-closed provider boundary | `tools/validate_v16.py`의 adapter 외 vendor import 금지 | 화면/feature는 shared UI port만 사용. KBX로 바꾸는 것이 아니라 현재 adapter 경계를 검증 기반으로 보존. |
## 현재 디자인 진단과 개선 우선순위
2026-08-09 정적 후보 스캔(`*.vue`, `*.css`, `*.ts`, test 제외)은 31개 파일, 353개 literal을 반환했다. 이 값은 심미적 오류 수가 아니라 **승인 전 정규화 후보의 상한**이다.
| 우선순위 | 관측 근거 | 제안 Slice | 개선 방향 | 안전장치 |
| --- | --- | --- | --- | --- |
| P0 | `RiskDashboard.vue` 104, `MarketDataIngestion.vue` 57, `RebalanceForm.vue` 57, `IngestionStatus.vue` 41 후보 | V13-FE-002 | 페이지의 색상·spacing·radius를 semantic/component token으로 치환 | 화면별 visual/state matrix와 금융 의미 색상 검토; gradient/차트 scale은 임의 통합 금지 |
| P0 | 현재 `tokens.css`는 primitive와 역할 token이 한 계층에 섞여 있고 component 이름은 3개뿐 | V13-FE-002 | primitive/semantic/component를 CSS section과 이름으로 명시 분리 | 새 값·threshold·brand palette를 만들지 않고 기존 값만 alias로 이동 |
| P1 | 카탈로그는 mandatory evidence가 있으나 required check/scenario/evidence type이 없음 | 후속 ADR 승인 Slice | `testProfile`을 TypeScript contract와 JSON contract에 동시 추가 | client business truth 금지; 실행 가능한 test가 없는 template은 complete 주장 금지 |
| P1 | density는 compact만 존재 | V13-FE-002 이후 | density를 control/grid token에 한정하고 keyboard/focus 위치를 불변으로 test | layout/form 구조 변형 금지 |
| P2 | PrimeVue/AG Grid는 adapter 안에만 존재 | V13-FE-001 완료 | provider 교체 대신 포트/contract test로 독립성 유지 | 새 provider, library, direct import 금지 |
## 리팩터링 순서
1. 이 Slice에서 vendor boundary의 실제 정적 증거를 보존한다.
2. 승인 후 `V13-FE-002`에서 토큰 계약과 baseline을 먼저 확정한다. 화면 CSS를 그 전에 일괄 수정하지 않는다.
3. 같은 Slice에서 P0 네 화면을 한 화면씩 behavior-preserving으로 token화하고, 각 화면의 loading/empty/warn/error/readonly 및 keyboard/visual evidence를 남긴다.
4. 별도 승인 Slice에서 screen recipe `testProfile`과 대표 Playwright/Vitest evidence를 도입한다. 토큰 리팩터링과 섞지 않는다.
5. baseline이 승인된 뒤에만 ratchet을 CI에 강제한다. 기존 353 후보를 0으로 보이게 만드는 일괄 ignore/regex 우회는 금지한다.
## 이번 Slice 실행 증거
| 검증 | 실제 결과 |
| --- | --- |
| `python tools/validate_v16.py` | `PASS=1 WARN=2 FAIL=0`, exit 0 (2026-08-09) |
| Vendor boundary | validator가 `frontend/src`의 `.ts`/`.vue`에서 PrimeVue·AG Grid import를 검사하고 `shared/ui/adapter/primevue` 외 위치를 실패 처리 |
| 범위 | 코드/토큰 값/화면 동작은 변경하지 않음. 사용자 제공 `docs/Design/kbx-foundation-v36/`는 추적·수정하지 않음. |
경고 2건은 full source archive 및 승인 런타임이 없다는 내용이며, .NET/DB/Playwright/Shadow 결과를 통과로 주장하지 않는다.
## 다음 게이트
`V13-FE-002`는 이제 WBS 의존성은 해소되지만, 위 Decision Required에 대한 ADR/Issue 및 visual/QA baseline이 없으므로 실행 전 승인 상태를 확인한다.