H-MAS release notes (2026-05-17~05-23)

9 minute read

Published:

H-MAS 주간 작업 노트

2026년 5월 17일 - 5월 23일 (Iteration 23)

주요 개발 내용 요약

이번 주는 배포 페이지 멀티스텝 위자드 UX 개선(#271), 인증/인가 고도화 3건 완료(#266, #268, #269), DB 기반 최적화 프리셋 관리 구현(#120)에 중점을 둔 기간이었습니다. 총 50개의 커밋, 5개의 PR 머지, 1개의 이슈 생성, 6개의 이슈 해결이 완료되었으며, Iteration 23에 할당된 6개 항목을 모두 완료(100%) 달성했습니다. Iteration 22에서 수립한 인증/인가 고도화 로드맵의 핵심 3건(API Key 동적 수정, 사용자 관리, RBAC)을 연속 착수·완료하고, 장기 과제였던 최적화 프리셋 DB 전환(#120)과 배포 UX 대폭 개선을 동시에 달성한 주간이었습니다.

새로운 기능 (New Features)

1. 배포 페이지 멀티스텝 위자드 UX 개선 (#271 → PR #272)

구현 완료: 단일 롱 스크롤 폼이었던 배포 페이지를 4단계 위자드(모델&런타임 → 배치&리소스 → 최적화 → 검토)로 전환하여 사용자 인지 부하를 대폭 감소

주요 성과:

  • Frontend:
    • StepIndicator 컴포넌트 — 단계 표시 + 우측 액션 버튼 통합, 완료/현재 상태 시각화
    • ReviewCard 컴포넌트 — 배포 전 최종 검토 화면, 섹션별 “수정” 클릭으로 해당 스텝 이동
    • 런타임 선택: 카드 그리드 → 라디오 리스트로 직관화
    • 배치 전략: 카드 그리드 → 라디오 리스트 + 상세 패널로 변경
    • 시나리오 프리셋: 카드 그리드 → 접이식 pill 버튼으로 변경 (Progressive Disclosure)
    • 배포 결과: Dialog 팝업 제거 → Step 4 인라인 성공/실패 배너로 전환
    • 하단 고정 네비게이션 버튼 → StepIndicator 우측 통합
    • 전체 너비 레이아웃으로 변경 (기존 max-w-3xl 제약 제거)

해결된 기술 문제:

문제원인해결
Enter 키 입력 시 의도치 않은 배포 실행HTML form의 암묵적 제출 동작명시적 제출 제어로 전환하여 Step 3 이외에서 배포 차단
미방문 단계가 완료로 표시completedSteps 상태 관리 오류방문 여부 기반 완료 상태 판정으로 수정

관련 커밋: 5f3dbc0 외 14건 (PR #272, Closes #271)

2. API Key 동적 수정 API 및 UI 구현 (#266 → PR #273)

구현 완료: 키 원문(해시)을 유지한 채 이름, 만료일, 허용 배포 범위, RPM/TPM 한도를 동적으로 변경 가능 — 기존에는 키 삭제 후 재생성이 필요했던 운영 부담 해소

주요 성과:

  • Backend:
    • PATCH /api/api-keys/:id 엔드포인트 — partial update 지원 (null vs 생략 구분)
    • Rate Limit 한도 변경 시 In-Memory 버킷 즉시 리셋하여 새 한도 즉시 적용
    • ratelimit.Store 인터페이스에 Delete(key) 메서드 추가
  • Frontend:
    • API 키 생성 UI를 Dialog에서 Sheet(드로어)로 리팩터링 — 프로젝트 UI 패턴 통일
    • 편집 Sheet 신규 구현 — 이름, 만료일, 배포 범위, RPM/TPM 수정 가능
    • 키 목록에 수정(Pencil) 버튼 추가

의사결정 사항:

결정내용
Partial Update 방식json.RawMessage 기반 null vs 생략 구분 — 명시적 초기화(null)와 미변경(생략)을 구분
UI 패턴Dialog → Sheet 전환 — 사용자 관리 등 다른 관리 UI와 패턴 통일

관련 커밋: 1c187a1 외 4건 (PR #273, Closes #266)

3. 사용자 관리 시스템 구현 (#268 → PR #274)

구현 완료: v0.4 단일 admin 계정 환경에서 멀티 사용자 환경으로 확장 — admin이 사용자를 추가/수정/삭제하고, 모든 사용자가 본인 프로필을 관리할 수 있는 체계 구축

주요 성과:

  • Backend:
    • 사용자 CRUD API: GET/POST/PATCH/DELETE /api/users (admin 전용)
    • 프로필 API: GET/PATCH /api/auth/profile, POST /api/auth/change-password
    • 비밀번호 초기화: POST /api/users/:id/reset-password (admin 전용)
    • 비즈니스 규칙: 자기 삭제 방지, 마지막 admin 보호, username 불변, 비밀번호 8자 이상
    • ExternalID 빈 문자열 → NULL 변환 버그 수정 (유니크 제약 위반 방지)
  • Frontend:
    • 사용자 관리 페이지 (/settings/users) — Sheet 드로어 기반 추가/수정
    • 프로필 페이지 (/profile) — 정보 수정 + 비밀번호 변경
    • 헤더 프로필 메뉴 활성화

관련 커밋: 1855af2 외 10건 (PR #274, Closes #268)

4. RBAC 역할 기반 인가 시스템 (#269 → PR #275)

구현 완료: admin/member/viewer 3계층 역할별 API 접근 제어 및 프론트엔드 권한 게이팅 구현 — 사용자 관리(#268) 완료 직후 연속 착수하여 멀티 사용자 환경의 보안 체계 완성

주요 성과:

  • Backend:
    • auth.Role 타입/상수 정의, RequireMinRole 미들웨어로 3계층 접근 제어
    • 모든 API 라우트를 adminOnly / memberUp / viewerUp 3계층 그룹으로 재구성
    • 권한 부족 시 403 Forbidden + 감사 로그 자동 기록
    • API Key 소유권 기반 필터링 — admin은 전체 조회, member는 본인 키만
  • Frontend:
    • usePermission 훅 + PERMISSIONS 맵으로 사이드바/버튼 조건부 렌더링
    • admin 전용 페이지 라우트 가드 (사용자 관리, 감사 로그)
    • toastApiError / extractErrorMessage 유틸로 403 에러 처리 통일
    • 21개 컴포넌트에 에러 처리 일관성 적용

해결된 기술 문제:

문제원인해결
미정의 Role이 viewer로 취급되는 보안 결함AtLeast() 비교 로직 미비미정의 Role 명시적 거부 처리
권한 없는 사용자의 불필요한 API 요청프론트엔드에서 권한 확인 없이 호출권한 기반 사전 차단 로직 추가

관련 커밋: 0921abc 외 8건 (PR #275, Closes #269)

5. DB 기반 최적화 프리셋 관리 (#120 → PR #276)

구현 완료: 하드코딩 최적화 프리셋을 PostgreSQL DB로 이관하여 관리자가 동적으로 생성/수정/삭제/활성화 토글 가능 — v0.2부터 이어온 장기 과제(#120) 완료

주요 성과:

  • Backend:
    • optimization_presets 테이블 마이그레이션(000028) + 14개 빌트인 시드
    • OptimizationPreset GORM 모델 및 Repository (List, GetByID, GetBySlug, Create, Update, Delete)
    • PresetHandler CRUD 엔드포인트: POST/PUT/DELETE + toggle + 런타임별 조회
    • ResolveOptimization()에 DB 프리셋 조회 경로 연동
  • Frontend:
    • Settings > 최적화 프리셋 관리 페이지 (목록/생성 Sheet/수정 Sheet/삭제/토글)
    • 배포 폼에서 모델 크기 + 런타임 + enabled 조건으로 프리셋 자동 필터링 개선

해결된 기술 문제:

문제원인해결
비활성화된 프리셋으로 배포 요청 가능resolvePresetParams에서 enabled 확인 누락비활성화 프리셋 차단 + 400 에러 반환
slug 중복 시 소프트 삭제 충돌unique index가 삭제된 레코드 포함partial unique index로 변경

관련 커밋: b409851 외 9건 (PR #276, Closes #120)

문서화 (Documentation)

기술 문서 업데이트 (3건)

문서내용관련 커밋
USER_MANAGEMENT_DESIGN.md사용자 관리 설계 결정 6건 문서화1855af2 (PR #274)
멀티테넌시 설계 문서Organization > Group 계층, SaaS/Enterprise 듀얼 모델로 전면 개정b47ea10 (PR #275)
RUNTIME_SETTINGS_MODEL_LOADING.md프리셋 결정 알고리즘 5단계 흐름 상세 문서화b409851 (PR #276)

기타 작업 (Chores)

  • GPU 공유/격리 방식 비교 조사(#213) 연구 완료 확인 후 수동 종료 — Iteration 21에서 PR #220으로 연구 완료, 후속 검증 이슈(#216~#219) 수립 완료 상태

Iteration 23 할당 항목 달성도

GitHub Projects에 할당된 6개 항목 모두 완료 (100%):

#이슈제목상태
1#271배포 페이지 UX 개선: 멀티스텝 위자드 + Progressive Disclosure 적용Done (PR #272)
2#266API Key 동적 수정 API (PATCH /api/api-keys/:id)Done (PR #273)
3#268사용자 관리 시스템 구현 (CRUD API + UI + 프로필 + 비밀번호 변경)Done (PR #274)
4#269RBAC 인가 미들웨어 구현 (역할별 권한 분기)Done (PR #275)
5#120DB 기반 최적화 프리셋 관리 (CRUD API + UI)Done (PR #276)
6#213리서치: GPU 공유/격리 방식 비교 조사 (xxx, xxxx, xxx, xxx, xxxx-xxxxxxx)Done (수동 종료)

이전 Iteration 계획 달성도

Iteration 22에서 계획한 4개 항목 1개 완료, 3개 미착수 — API Key 동적 수정(#266)을 완료하고, 나머지 시간은 인증/인가 고도화 의존 체인(#268→#269) 연속 완료 + 배포 UX 개선(#271) + 장기 과제 프리셋 DB 전환(#120)에 집중:

계획이슈상태비고
API Key 동적 수정 API#266완료PR #273으로 구현 완료
추론 프록시 Phase 2: 멀티클러스터 라우팅#192미착수인증/인가 고도화 + UX 개선에 우선순위 전환
hmas-agent 핵심 컴포넌트 구현 착수#190미착수동일 사유
런타임 자동 튜닝 설계 상세화#114미착수동일 사유

추가 달성: 계획에 없던 배포 페이지 UX 전면 개편(#271), 사용자 관리 시스템(#268), RBAC 인가(#269), DB 기반 프리셋 관리(#120) 4건 추가 완료, GPU 공유/격리 리서치(#213) 종료.

미해결 이슈 (Open Issues)

인증/인가 후속 이슈 체인

이슈제목상태
#254API Key 인증 시스템Iteration 22 완료
#255Rate LimitingIteration 22 완료
#266API Key 동적 수정 API (PATCH)Iteration 23 완료
#268사용자 관리 시스템 (CRUD + 프로필)Iteration 23 완료
#269RBAC 인가 미들웨어 (역할별 권한 분기)Iteration 23 완료
#267JWT 사용자별 커스텀 Rate Limit미착수 — 멀티 사용자 + RBAC 선행 완료
#264Rate Limit Redis 전환 (수평 확장 대비)미착수
#270TPM 토큰 사전 추정 리서치미착수

인증/인가 고도화 로드맵 8건 중 5건 완료 (#254, #255, #266, #268, #269), 잔여 3건 (#267, #264, #270)

추론 프록시 이슈 체인

이슈제목상태
#191Phase 1: 기본 프록시 구현Iteration 20 완료
#193요청 로깅 및 메트릭 수집Iteration 21 완료
#227요청 로그 조회 UIIteration 21 완료
#194API Key 인증 + Rate Limiting (상위)Iteration 22 완료
#192Phase 2: 멀티클러스터 라우팅 (agent 터널 통합)미착수

이번 주 통계

항목수치
Iteration 할당 달성6/6건 완료 (100%)
총 커밋 수50개 (5개 PR 내 feature branch 커밋)
머지된 PR5개 (#272, #273, #274, #275, #276)
생성된 이슈1개 (#271)
해결된 이슈6개 (#120, #213, #266, #268, #269, #271)
미해결 이슈29개
신규 기술 문서3건 (사용자 관리 설계, 멀티테넌시 설계 개정, 프리셋 결정 알고리즘)
코드 변경량+8,508줄 / -1,265줄

결론

이번 주는 인증/인가 고도화 로드맵의 핵심 3건을 연속 완료하고, 배포 UX와 프리셋 관리 체계를 대폭 개선한 기간이었습니다. API Key 동적 수정(#266)으로 키 재발급 없는 설정 변경이 가능해졌고, 사용자 관리(#268) → RBAC(#269)를 의존 순서대로 연속 착수·완료하여 멀티 사용자 환경의 인증/인가 체계를 완성했습니다. 배포 페이지 4단계 위자드 전환(#271)으로 사용자 인지 부하를 크게 낮추었고, 장기 과제였던 최적화 프리셋 DB 전환(#120)으로 관리자가 프리셋을 동적으로 관리할 수 있게 되었습니다.

핵심 성과:

  1. 인증/인가 고도화 3건 연속 완료: API Key PATCH(#266) + 사용자 관리(#268) + RBAC(#269) — 로드맵 8건 중 5건 달성 (62.5%)
  2. 배포 UX 전면 개편: 4단계 위자드 + Progressive Disclosure + 검토 화면으로 사용성 대폭 향상
  3. 최적화 프리셋 DB 전환 완료: 하드코딩 → PostgreSQL 기반 동적 관리, 14개 빌트인 시드 + 커스텀 프리셋 CRUD
  4. RBAC 보안 체계 완성: admin/member/viewer 3계층 접근 제어 + 프론트엔드 권한 게이팅 + 감사 로그 연동

다음 주 계획:

  • 추론 프록시 Phase 2: 멀티클러스터 라우팅 (agent 터널 통합) (#192)
  • hmas-agent 핵심 컴포넌트 구현 착수 (#190)
  • 런타임 자동 튜닝 설계 상세화 (#114)
  • JWT 사용자별 커스텀 Rate Limit (#267)

문서 작성일: 2026년 5월 24일