5.8 KiB
5.8 KiB
KBX UX/AX Review
- 기존 9개 Screen Type 중 하나를 사용했다.
- 신규 Component보다 기존 KBX Component 재사용을 먼저 검토했다.
- 업무 모듈에서 PrimeVue/AG Grid를 직접 import하지 않는다.
- 주요 명령 위치가 KBX Command Bar 규칙과 같다.
- Keyboard 흐름(F2/F3/F8/Tab/Enter/Esc)을 검토했다.
- 입력 가능한 대량 데이터 화면의 Excel 정책을 정의했다.
- 정상 건을 사용자가 불필요하게 확인하는 단계가 없는지 검토했다.
- 오류 메시지가 원인과 다음 행동을 설명한다.
- Client validation을 업무 정합성의 최종 방어선으로 사용하지 않는다.
- 상태 변경, Audit, Concurrency, Idempotency 영향도를 검토했다.
- AI가 없어도 동일 업무를 수행할 수 있다.
- AI Action은 Proposal → Validation → Command 경계를 지킨다.
- 현장 화면은 실제 장비/네트워크 조건의 수용시험 항목을 정의했다.
Architecture
node scripts/validate-kbx.mjs통과- Screen ID / Version 갱신 여부 검토
- 기술부채 또는 KBX 예외가 있다면 이유와 재검토 시점을 기록했다.
Production readiness
- Long operations do not block the page with a modal spinner
- Mutation retries are idempotent or explicitly disabled
- 409/version conflicts cannot silently overwrite newer data
- Stale operational data exposes freshness/reload where material
- Unexpected errors expose a correlation reference, not stack traces
- Degraded/read-only behavior is defined for affected workflows
Component verification
- 공통 Component 변경이면
COMMON-DS-001에서 Default/Readonly/Disabled/Error/Loading 상태를 확인했다. - Keyboard/Focus 계약 변경이면 E2E scenario를 갱신했다.
- 의도된 시각 변경이면 Compact/Comfortable/Touch baseline 변경 사유를 기록했다.
- 공통 Component의 동작/표현 변경이면 Component Version을 검토했다.
- 색상만으로 상태를 전달하거나 Focus Indicator를 제거하지 않았다.
Design ↔ Code parity / release
- Design Token 변경은
packages/kbx-ui/src/tokens/source/kbx.tokens.json에서 시작했다. - Semantic/Component Token 값 변경이면 Visual Regression 영향도를 검토했다.
- Core Component 상태가
COMMON-DS-001과 Figma contract에 모두 존재한다. - 새 raw color/px literal을 추가하지 않았다. 필요한 경우 먼저 Token 승격을 검토했다.
- Component/Screen/Token 공개 계약 변경이면
generated/release-impact.json의 요구 bump를 확인했다. - Breaking 변경이면 Migration Guide를 작성했다.
API contract / Problem governance
- 업무 모듈에서 raw
/api/...,axios,fetch를 직접 사용하지 않는다. - 신규/변경 Endpoint는
contracts/api/kbx.api.json과 동일한 Method/Route/Permission을 가진다. - Mutation Retry 가능 여부와 Idempotency 정책을 정의했다.
- Validation/Business/Conflict/Permission/NotFound/Integration/System 오류를 KBX Problem으로 표현한다.
- API 공개 계약 변경이면
generated/release-impact.json의 SemVer 요구수준을 확인했다. - Host에서 실제 Swashbuckle OpenAPI snapshot diff를 수행했다.
Authorization / Sensitive Data
- 신규 Permission은
contracts/authorization/kbx.authorization.json에 등록했습니다. - Frontend 숨김/Disabled만으로 보안을 처리하지 않고 Backend 최종 검증이 있습니다.
- Sensitive Field는 기본 Masking이며 전체보기/비마스킹 Export 권한을 구분했습니다.
- Sensitive 원문을 Telemetry/AI Context에 넣지 않았습니다.
- 전체보기 또는 민감 데이터 공개가 필요한 경우 Audit 경로를 정의했습니다.
KBX v18 Scenario / Test Data
- 변경된 Golden Screen/업무 경계의 canonical scenario를 갱신했다.
- Fixture는 synthetic-only이며 Production dump를 포함하지 않는다.
idempotency=requiredCommand의 replay scenario가 있다.- Host에서 실행한 경우 Scenario Evidence/Correlation ID를 남겼다.
External integration / resilience
- Business State와 Integration State를 분리했다.
- 새 외부연계는
contracts/integrations/kbx.integrations.json에 등록했다. - at-least-once 전달은 idempotency 경계를 가진다.
- 짧은 transient retry는 bounded Polly pipeline이고 장기 retry는 Hangfire가 소유한다.
- permanent failure는 사용자 업무 재실행이 아니라 Operations Exception으로 노출된다.
- 실패주입 Scenario가 있다.
External data / provenance
- 외부 Provider 응답을 화면이 직접 해석하지 않고 canonical normalizer를 거칩니다.
- providerObservedAt / receivedAt / ingestedAt 의미를 혼합하지 않았습니다.
- Stale/Expired 데이터가 최신값처럼 보이지 않습니다.
- request_descriptor에는 Secret/Token이 없고 raw payload 저장은 명시적 검토 없이는 금지합니다.
- KRX 승인 서비스의 TTL/Schema를 공식 서비스 명세 없이 추정하지 않았습니다.
Configuration / deployment governance
- 신규 설정은
contracts/configuration/kbx.configuration.json에 등록했고 직접Environment.GetEnvironmentVariable()을 사용하지 않았다. - Secret에는 기본값/예제값을 넣지 않았고 generated env example도 빈 값이다.
- Production은
predeploymigration + HTTPS 원칙을 유지한다. - 환경별 다른 바이너리를 다시 빌드하지 않고 동일 Release Artifact를 승격한다.
- destructive migration이 필요하다면 명시적 승인 marker와 Migration Guide가 있다.
- 배포 전 Configuration Validation / Migration Dry Run / Release Governance evidence를 확인했다.