백오피스 개선기 - 타입 안전한 전역 단축키 시스템으로 운영 효율을 개선하다

해외주식 백오피스 개발을 진행하면서 운영 업무의 효율성을 더욱 높일 수 있는 방법에 대해 지속적으로 고민하고 있었다.

운영팀의 업무 특성상 반복적인 화면 전환과 입력 작업이 많았고 작은 UX 개선 하나가 실제 업무 시간에 큰 영향을 미치는 환경이었다.마침 국내주식 백오피스에서도 단축키 도입이 예정되어 있다는 이야기를 전달받아 해외주식 백오피스에도 동일한 수준의 생산성 개선이 필요하다고 판단했다. 다만 실제 사용자는 수십 명의 운영팀 구성원들이었기 때문에 개발자 관점의 판단보다는 현업의 니즈를 우선적으로 확인하는 과정이 필요했다.

 

 

운영팀의 니즈 수집하기

단축키 도입에 앞서, 평소 협업하던 POM에게 의견을 전달했고 운영팀 전원이 자유롭게 개선 요청을 남길 수 있도록 태그와 스레드를 생성해주셨다. 그 결과 예상보다 훨씬 많은 개선 의견이 수집되었고 단축키에 대한 수요 또한 명확히 확인할 수 있었다. 이때부터 내가 백오피스 개선에 대해 리딩해야 했다. 토스증권 들어와서 제일 재밌고 몰입되었던 순간이었던 것 같다. 백오피스 개선을 주도적으로 리딩하면서 문제 정의부터 설계까지 깊이 관여할 수 있었다.

단축키 도입 이전의 상태

기존 백오피스에는 전역 단축키라는 개념이 거의 존재하지 않았다.

홈 화면의 검색창 포커스 기능은 단축키로 제공되고 있었지만 운영팀은 이 기능을 인지하지 못하고 있었다.

일부 모달은 ESC로 닫히는 동작을 제공했으나 이건 각 컴포넌트 단위로 개별 구현된 형태였다.

컴포넌트 의존성이 없는 단순한 경우에는 키 이벤트를 등록하는 것이 쉬웠으나 여러 컴포넌트가 얽힌 상황에서는 이벤트 전파와 포커스 관리 문제로 일관성 있는 UX를 제공하기 어려웠다. (이벤트 버블링과 포커스 처리 관련 기술적 이슈는 다음 글에서 상세히 다룰 예정이다.)

 

---

전역 단축키 시스템의 목표

전역 단축키 시스템은 아래 두 가지 목표를 기준으로 설계하였다.

1. 다른 개발자가 내부 구현을 모르는 상태에서도 쉽게 단축키를 추가할 수 있도록 확장성을 보장한다.
2. 단축키 정의 과정에서 발생할 수 있는 오타나 잘못된 키 조합을 타입 수준에서 방지하여 런타임 오류를 줄인다.

이 두 목표를 만족시키기 위해 단축키 정의는 중앙 집중화하고 실행 로직은 분리하여 책임을 명확히 하였다.

 

설계 원칙과 전체 구조

설계의 핵심 원칙은 “정의는 한 곳에서, 실행은 자동으로”였다.

개발자는 단축키를 한 파일에 정의하기만 하면 전역 이벤트 등록과 가이드 UI 반영이 자동으로 이루어지도록 구성하였다. 구현은 아래 컴포넌트로 나누어 책임을 분리하였다.

• useGlobalShortcutKeys: 문서 레벨에서 keydown을 감지하고 단축키 매칭을 수행하는 전역 훅
• useShortcutActions: 각 단축키가 실행할 실제 액션을 함수 형태로 관리하는 훅
• constants/shortcutKeys.ts: 단축키 정의를 중앙에서 관리하는 레지스트리 파일

이 구조는 단축키 정의와 실행 로직의 결합도를 낮추고 확장성을 높였다.

 

단축키 정의의 중앙 집중화

모든 단축키는 constants/shortcutKeys.ts 파일에 정의되며 [단축키_조합/설명/실행_액션_이름]을 포함한다. 이 파일은 키 정의를 한눈에 확인할 수 있는 단일 소스 역할을 하며 타입을 통해 오타를 방지한다. 중앙 레지스트리만 갱신하면 시스템 전반에 자동으로 반영된다.

export type AlphabetKey = 'a' | 'b' | ... | 'z';
export type NumberKey = '0' | ... | '9';

export interface ShortcutDefinition {
  keys: (ModifierKey | AlphabetKey | NumberKey)[];
  description: string;
  action: string;
}

export const SHORTCUTS: ShortcutRegistry = {
  closeAllWindows: { keys: ['cmd', 'd'], description: '열린 창 모두 닫기', action: 'closeAllWindows' },
  focusSearch:      { keys: ['cmd', 'l'], description: '홈 검색창 포커스', action: 'focusSearch' },
};

전역 키 이벤트 처리 방식

useGlobalShortcutKeys 훅은 document 레벨에서 keydown 이벤트를 수신하고 눌린 키와 SHORTCUTS 에 정의된 조합을 비교하여 일치하면 해당 액션을 트리거한다. 운영체제별 차이를 고려하여 cmd/ctrl 을 공통 인터페이스로 처리하며 브라우저의 기본 동작을 방지하기 위해 event.preventDefault() 를 적용한다. 이 훅은 애플리케이션 생애주기 동안 한 번만 등록되므로 단축키 추가 시 별도의 이벤트 등록 코드를 필요로 하지 않는다.

document.keydown -> SHORTCUTS 순회 -> modifier/normal key 매칭 -> action 호출

단축키 개수가 제한적인 백오피스 특성을 고려하면 모든 단축키를 순회하는 방식도 성능상 충분히 안전하다고 판단했다.

향후 단축키 수가 크게 증가할 경우에는 매칭 로직을 Map 기반으로 개선할 필요가 있을 것이다.

 

액션 로직의 분리와 메모이제이션

단축키가 수행하는 동작은 useShortcutActions 훅에서 관리한다.

각 액션을 useCallback으로 감싸 메모이제이션을 적용하여 불필요한 재생성을 방지하고 성능을 확보하였다.

전역 상태 변경이나 DOM 직접 조작이 필요한 로직은 이 훅에서 처리함으로써 단축키 정의와 실행 책임을 명확히 분리하였다.

export function useShortcutKeysActions() {
  return {
    closeAllWindows: useCallback(() => { /* 열린 창 닫기 */ }, []),
    focusSearch:     useCallback(() => { /* 검색창 포커스 */ }, []),
    // ...
  };
}

 

사이드바 단축키 가이드 제공

단축키는 존재만으로는 효과가 없으므로 운영팀이 언제든 확인할 수 있도록 사이드바에 단축키 가이드를 추가하였다. 가이드 UI는 SHORTCUTS 정의를 그대로 사용하여 Mac/Windows의 키 표기법을 동시에 표시하도록 구현되었다. 이 접근으로 단축키 추가 시 별도 문서 작업 없이 UI가 자동으로 갱신되도록 하였다.

export function ShortcutGuide() {
  return (
      <FlexCol>
        {Object.entries(SHORTCUTS).map(([actionName, shortcut]) => (
          <Flex key={actionName}>
            <Typography>{shortcut.description}</Typography>
            <Flex>
              <KeyboardTypography>{formatShortcutKeys(shortcut.keys, true)}</KeyboardTypography>
              <Typography>/</Typography>
              <KeyboardTypography>{formatShortcutKeys(shortcut.keys, false)}</KeyboardTypography>
            </Flex>
          </Flex>
        ))}
      </FlexCol>
  );
}

const formatShortcutKeys = (keys: string[], isMac: boolean): string => {
  return keys
    .map((key: string) => {
      const lowerKey = key.toLowerCase();
      switch (lowerKey) {
        case 'cmd':
          return isMac ? '⌘' : 'Ctrl';
        case 'ctrl':
          return isMac ? '⌃' : 'Ctrl';
        case 'shift':
          return isMac ? '⇧' : 'Shift';
        case 'alt':
          return isMac ? '⌥' : 'Alt';
        default:
          return lowerKey.toUpperCase();
      }
    })
    .join('+');
};

 

단축키 추가하기

단축키 추가 과정은 다음 세 단계로 단순화되어 있다. 이 절차로 새로운 단축키의 안전한 확장과 빠른 배포를 가능하게 한다.

1. constants/shortcutKeys.ts에 단축키 정의를 추가한다.
2. useShortcutActions.ts에 새로운 액션 함수를 추가한다.
3. 시스템이 자동으로 전역 등록 및 가이드 UI 반영을 수행한다.

---

회고

이번 작업은 “조직의 반복 작업을 어떻게 구조적으로 줄일 것인가”에 집중한 경험이라 뜻깊었다. 운영자들의 실제 사용 요구를 반영하면서 확장 가능한 구조를 고민한 점이 특히 유의미했다.

코드리뷰 과정에서 조건 분기(if-else, switch)와 컴파일 타임 에러 방지에 대한 논의가 이루어졌고 설계의 견고함을 다지는 기회가 되었다. 그외 개선 작업은 계속 진행중이며 라이브 배포는 1월 초로 예정되어 있다.

 

👍