다크모드
관리비 실제 제품 1:1 대조 — 사람 검수 가이드
독자:
leyve-admin-frontend실제 프론트엔드 개발자, 코드 리뷰어, 제품 오너 선도 계약:leyve-console-protomain실제 제품:leyve-admin-frontendv3-styleAI 검수 절차: 관리비 실제 제품 1:1 대조 — AI 검수 계약
왜 페이지 단위로 닫는가
관리비는 목록, 콘솔 단계, 설정, 중간정산이 같은 상태와 API를 공유한다. 전 영역을 한 번에 맞추면 다음 문제가 생긴다.
- 어떤 제품의 동작이 정본인지 판단 근거가 사라진다.
- UI 차이와 서버 계약 차이가 한 커밋에 섞인다.
- 실제 프론트엔드 개발자가 확인하지 못한 변경이 다음 페이지의 전제가 된다.
- AI가 앞 페이지의 미확정 추정을 사실처럼 재사용할 수 있다.
따라서 한 페이지를 대조하고 양쪽 검수까지 완료한 뒤 다음 페이지로 이동한다. 공통 EDS 전환만 선행 기반 작업으로 예외 처리한다.
실제 제품 로컬 실행 준비
leyve-admin-frontend는 @revolist/revogrid-pro@1.7.7을 사용한다. 관리비 페이지가 RevoGrid를 직접 렌더하지 않아도 Vite가 전체 route import를 분석하므로 Pro 패키지가 없으면 페이지가 import overlay로 중단될 수 있다.
- 공식 registry:
https://npm.rv-grid.com - 프로젝트
.npmrc:@revolist:registry=https://npm.rv-grid.com만 보유한다. - 인증 token: 사용자
~/.npmrc또는 CI secret에만 저장한다. 제품 저장소에 token을 commit하지 않는다. - 계정·설치 안내:
https://pro.rv-grid.com/account,https://pro.rv-grid.com/guides/installation-npm - exact 확인: 설치 후
node_modules/@revolist/revogrid-pro/package.json의 version이1.7.7인지 확인한다.
사설 인증이 없을 때 제품 코드, Vite alias, registry wrapper에 shim을 commit하지 않는다. 로컬 시각 확인용 임시 shim을 썼다면 공식 패키지 설치 후 제거하고, package manifest·lockfile·소스에 잔여 변경이 없는지 확인한다.
한 페이지의 작업 단위
각 페이지는 다음 순서를 모두 통과해야 완료다.
- 기준 고정: 양쪽 route, 진입 경로, 관련 파일, API 호출을 기록한다.
- 상태 대조: 빈 상태, 로딩, 정상, 오류, 권한 없음, 준비 중, 확정 후 잠금을 비교한다.
- 행동 대조: 생성, 조회, 편집, 삭제, 재시도, 다음·이전 단계의 게이트를 비교한다.
- 판정: 각 차이를
동일,실제 제품 수정,선도 제품 수정,양쪽 수정,서버 선행,준비 중으로 분류한다. - 구현: 오너 확인이 필요한 큰 IA·서버 결정은 승인 뒤 구현한다. 저위험 정합 수정은 페이지 묶음 안에서 처리한다.
- 사람 검수: 실제 프론트엔드 개발자가 화면과 diff를 확인한다.
- AI 재검수: AI 검수 계약에 따라 누락과 회귀를 검사한다.
- 확정 기록: 검수자, 날짜, 양쪽 커밋, 남은 서버 작업을 이 문서의 페이지 원장에 남긴다.
페이지별 산출물
페이지마다 다음 자료를 한 묶음으로 남긴다.
- 양쪽 route와 진입 방법
- 비교 기준 화면 캡처 또는 재현 단계
- 관련 Vue·composable·store·API 파일 목록
- 상태·행동 대조표
- 수정 주체와 판정 근거
- 미구현 기능의 위치와
준비 중표시 방식 - 수행한 테스트와 수행하지 못한 테스트의 이유
leyve-console-proto커밋과leyve-admin-frontend커밋- 사람 검수 결과와 AI 재검수 결과
순차 진행 원장
상태는 대기 → 대조 중 → 구현 중 → 사람 검수 → AI 재검수 → 완료 순서로만 이동한다. 앞 페이지가 완료가 아니면 다음 페이지는 대조 자료 수집까지만 허용한다.
| 순서 | 페이지 | 선도 제품 | 실제 제품 | 현재 상태 | 큰 결정 |
|---|---|---|---|---|---|
| 00 | EDS 공통 기반 | @leysys/eds@1.0.14 소비 | @leysys/eds@1.0.14 소비 | 완료 | 없음 |
| 01 | 정기 관리비 목록·생성 진입 | /service-charge/actual | /umms/transaction/general-settlement | 대조 중 — 01-C 선도 구현·실제 제품 서버 확인 필요 | 정산 종류 분리, 빌더 위치 |
| 02 | 정기 관리비 콘솔 개요·단계 게이트 | /service-charge/actual/console/general | /umms/transaction/general-settlement/console/:id/general | 대기 | 단계 상태머신과 재오픈 권한 |
| 03 | 부과산정 | /service-charge/actual/console/charging/assessment | 같은 콘솔의 charging 탭 | 대기 | 실제 API와 선도 Fact 경계 |
| 04 | 부과 유닛·계약·멤버 명세 | actual 부과 하위 3축 | 실제 부과 하위 화면 | 대기 | 축별 합계·잠금·중간저장 |
| 05 | 청구 | actual invoicing 하위 3축 | 같은 콘솔의 invoicing 탭 | 대기 | 부과 확정본 연결과 버전 |
| 06 | 수납 | actual collecting 하위 3축 | 같은 콘솔의 collecting 탭 | 대기 | 수납 상태와 취소·감사 |
| 07 | 공지·고지서 | actual notice 하위 | 같은 콘솔의 notice 탭 | 대기 | 고지서 빌더와 공지 책임 경계 |
| 08 | 선수금·가수금 | actual advance-receipt | 실제 대응 화면 대조 시 확정 | 대기 | 실제 제품 미노출 여부 |
| 09 | 이월 | actual forwarding | 같은 콘솔의 forwarding 탭 | 대기 | 전기·차기 이월 불변식 |
| 10 | 연체료 | actual late-fee | 실제 대응 화면 대조 시 확정 | 대기 | 기준일·할증·중단 정책 |
| 11 | 세금계산서 | actual tax-invoice | 실제 대응 화면 대조 시 확정 | 대기 | 선택 상품 delivery 경계 |
| 12 | 중간정산 | /service-charge/provisional | /umms/transaction/interim-settlement | 대기 | 목록·콘솔 경계와 생성 소유권 |
| 13 | 관리비설정 일반 | /service-charge/setting/general | /umms/setting/general | 대기 | 설정 소유권·저장 범위 |
| 14 | 부과항목·그룹 | /service-charge/setting/item/* | /umms/setting/item | 대기 | 항목·그룹·할인 모델 |
| 15 | 기초데이터 | /service-charge/setting/initial-data/general | 실제 대응 화면 대조 시 확정 | 대기 | 마스터 소유권 |
| 16 | 충당 순서·연체료 할증 | /service-charge/setting/collecting, /surcharge | 실제 대응 화면 대조 시 확정 | 대기 | 서버 정책 버전 |
| 17 | 퀵검침 | /service-charge/metering/general | 실제 대응 화면 대조 시 확정 | 대기 | 검침값 원천과 확정 |
실제 대응 화면 대조 시 확정은 기능이 없다는 뜻이 아니다. route와 실제 render tree를 확인하기 전까지 경로를 추측하지 않는다는 뜻이다.
페이지 01 — 현재 확인 결과
01-A — 공통 셸과 조회조건 잔여물
첫 화면 대조에서 공통 셸과 목록 업무 UI를 분리해 판정했다. 셸 정합은 전역 변경이지만 페이지 01을 같은 조건으로 비교하기 위한 선행 슬라이스다.
| 차이 | 판정 | 적용 결과 |
|---|---|---|
| 실제 제품은 64rem 아래에서 aside만 숨고 대체 메뉴 진입이 없음 | 실제 제품 수정 | EDS 반응형 앱 셸 패턴을 적용해 상단 메뉴 열기와 같은 SideMenu를 쓰는 왼쪽 시트를 추가 |
양쪽 상단에 Workspace·Organization 전환 버튼이 남아 업무 헤더가 과밀함 | 양쪽 수정 | 두 버튼을 제거하고, 조직 페이지 권한이 있는 계정만 왼쪽 메뉴 하단 조직 설정으로 이동. 선도 제품은 Company 관리자→/headquarters/home, 실제품은 Company role/레이브 관리자→/account/organization-account |
| 실제 제품에 AI 비서 route·행동이 없음 | 준비 중 | 전역 위치는 보존하되 AI 비서를 저채도 disabled + 미구현 배지·호버 설명으로 표시 |
선도 제품 목록의 All, tag 1, tag 2 | 선도 제품 수정 | 도메인·API 계약이 없는 복제 예시라 제거 |
| 선도 제품 조회기간 확인 버튼이 목록에서 event를 소비하지 않음 | 선도 제품 수정 | 현재 연도 12개월 기본·최대 24개월의 월 범위 Criteria로 연결하고, 잘못된 범위는 선택 단계에서 차단. 설명은 상시 문장 대신 정보 아이콘 Popover로 제공 |
| 양쪽 control+해당 action 간격이 8px·4px로 혼재하고 선도 제품 검색 input+button 관계가 약함 | 양쪽·EDS 수정 | input과 button은 별도 control로 유지하고 같은 실행 단위에만 gap-0.5(2px)를 적용. EDS 감사와 양쪽 제품의 판정 위치도 같은 규칙으로 전역 정합 |
조회 버튼이 추가 버튼보다 크고 페이지네이션이 페이지·총·페이지당을 중복 노출함 | EDS·양쪽 수정 | Criteria·Action은 모두 sm 28px/12px. Pagination은 범위/전체 + 20개씩 + 이전/숫자/다음 compact footer로 통일하고 직접 입력·First/Last를 기본에서 제거 |
| 페이지 제목 80px·맥락 88px로 작업 영역 진입이 늦고 실제 제품 탭 띠가 56px임 | 양쪽·EDS 수정 | @leysys/eds@1.0.14 정본으로 전역 탐색 56px·제목 64px·맥락 72px minimum·로컬 탭 48px을 적용. 구조는 8px, 내부 보조 패딩은 필요한 곳만 4px 스케일 사용 |
페이지 헤더가 처음부터 열리고, 우측 …가 아무 동작도 하지 않음 | 양쪽·EDS 수정 | 기본 닫힘으로 시작하고 우측 끝에는 상태용 chevron만 둔다. 실제 페이지 액션은 chevron 왼쪽에 독립 배치하고, 동작하는 보조 메뉴가 있을 때만 …를 쓴다. 현재 목록의 빈 …는 제거 |
01-A에서 정산 종류, 고지서 빌더 위치와 삭제 서버 정책은 구현하지 않았다. 검색·기간·페이지네이션은 선도 제품 로컬 read model에 연결했고, 운영 서버의 동일 filter/count·최대 24개월 검증·안정 정렬은 페이지 01 본 검수에 남는다.
01-A 검증 결과
- 실제 제품
src/__tests__/app-shell.test.js: 3개 통과 - 실제 제품 SFC compile: 1,492개 통과
- 실제 제품 EDS class audit: 차단 위반 0, 기존 경고 201종
- 실제 제품 production build: 통과(기존 대형 chunk·브라우저 externalize 경고 유지)
- 브라우저: 64rem 미만 비교 iframe에서 메뉴 열기·닫기와 같은
SideMenu재사용 확인 - 선도 제품
CriteriaToolBarOrg.spec.js: 2개 통과 - 선도 제품 pre-commit 품질 검사: SSOT 미정의 class 0, placeholder action residue 0, product boundary baseline excess 0
- EDS 페이지 셸·disclosure 계약 test 4개·전체 unit 514개·production 문서 build·strict 품질 게이트 통과
01-A 사람 검수 항목
- [ ] 실제 제품 개발자가 Company role/레이브 관리자에게만 왼쪽 메뉴 하단
조직 설정이 보이고/account/organization-account로 이동하는지 확인했다. - [ ] 제품 오너가 선도 제품 헤더의 기본 범위가
Company · Office 0 · Office 이름으로 보이고 staff에게 조직 설정이 숨는지 확인했다. - [ ] 실제 제품 개발자가 좁은 화면에서 메뉴를 열고, 항목 이동 뒤 시트가 닫히는지 확인했다.
- [ ] 실제 제품 개발자가 AI 비서가 저채도 disabled +
미구현배지·호버 설명으로 보이고 빈 클릭이 없는지 확인했다. - [ ] 양쪽 정기 관리비 목록의 페이지 헤더가 처음에는 닫히고, chevron 또는 제목 행을 누르면 업무 맥락이 열리며 chevron 방향이 바뀌는지 확인했다.
- [ ] 양쪽 페이지 헤더에 기능 없는
…가 사라졌고, chevron이 별도 메뉴 버튼처럼 중복 클릭 영역을 만들지 않는지 확인했다. - [ ] 제품 오너가 선도 제품에서
All,tag 1,tag 2가 제거된 것을 확인했다. - [ ] 제품 오너가 조회기간의 현재 연도 12개월 기본값, 최대 24개월 선택 제한, 정보 아이콘 설명을 확인했다.
- [ ] 제품 오너가 양쪽 검색 입력과 실행 버튼이 별도 control로 보이면서 그 사이가 2px로 가깝게 묶인 것을 확인했다.
- [ ] 제품 오너가
Search → Criteria → Action → Table → Pagination순서와 Criteria·Action의 28px/12px 크기 정합을 확인했다. - [ ] 제품 오너가 양쪽 페이지네이션에서
페이지·총·페이지당문구가 사라지고1–20 / 전체,20개씩, 이전·숫자·다음만 보이는지 확인했다. - [ ] 양쪽 제품에서 전역 탐색·페이지 제목·업무 맥락·로컬 탭이 56px·64px·72px·48px이고, 업무 맥락이 줄바꿈될 때 잘리지 않고 확장되는지 확인했다.
- [ ] 선도 제품 정기 관리비 본문이 mobile 16px / EDS 24px 외곽 여백을 유지하면서
container최대 폭 없이 화면 폭을 사용하고, 넓은 화면에서 불필요한 표 가로 스크롤이 줄었는지 확인했다. - [ ] 선도 제품 카드 내부 16px, Search→Criteria 16px, Criteria→Action·Action→Table 8px, Table→Pagination 0px, 검색 입력+실행 버튼 2px이 각 계층의 소유권대로 적용되고 이중 패딩이 없는지 확인했다.
Workspace·Organization의 초기 상단 배치는 비교 중간안이었으며, 2026-07-22 오너 결정으로 폐기했다. 실제품의 Office 모델은 선도 제품과 다르므로 Office 0을 억지로 추가하지 않고 기존 단지/계정 컨텍스트를 유지한다.
01-A 기준 커밋
| 저장소 | 커밋 |
|---|---|
leyve-admin-frontend v3-style | f00713692, d4f49bc78 |
leyve-console-proto main | 308f90571, 8bcabe6e3, 8fffbc444 |
01-B — 첫 부과 준비 피드백
| 차이 | 판정 | 적용 결과 |
|---|---|---|
| 선도 제품의 큰 고정 경고가 목록 영역을 계속 차지함 | 선도 제품 수정 | 첫 미완료 항목과 해결 행동만 보이는 EDS 압축 Alert로 변경하고 닫기 제공 |
| 안내를 닫으면 생성이 비활성화된 이유를 다시 알기 어려움 | 선도 제품 수정 | 추가는 활성 행동으로 유지하고, 준비 미완료 시 전체 blocker·메뉴 경로·첫 해결 행동을 가진 Alert Dialog를 표시 |
| 준비 미완료와 기능 미구현이 모두 disabled처럼 보임 | 선도 제품 수정 | 데이터 선행조건은 활성 행동+차단 Dialog, 진짜 미구현은 저채도 disabled+미구현 상태로 분리 |
| 실제 제품에 첫 부과 준비상태 서버 응답이 없음 | 서버 선행 | 목록 행·기존 정산 유무로 추정하지 않는다. first_charge_readiness.ready + blockers[] 계약과 생성 API의 동일 게이트가 추가된 뒤 같은 UI를 연결 |
01-B 사람 검수 항목
- [ ] 제품 오너가 선도 제품 Alert를 닫아 목록 밀도를 낮출 수 있는지 확인했다.
- [ ] Alert를 닫은 뒤 추가를 누르면 생성 시트가 아니라 Alert Dialog가 열리는지 확인했다.
- [ ] Dialog의 나중에는 목록에 머물고, 강조 행동은 첫 미완료 설정 화면 또는 청구 대상 명부를 여는지 확인했다.
- [ ] 준비조건을 모두 완료하면 같은 추가가 생성 시트를 여는지 확인했다.
- [ ] 실제 제품 개발자가 readiness 서버 계약 없이는 임의 차단을 추가하지 않는다는 판정을 확인했다.
- [ ] 실제 제품 서버 응답이 추가될 때 blocker code를 실제 route·문구로 매핑하고 같은 상호작용을 적용하기로 확인했다.
01-C — 선택 삭제와 상태 불변식
| 차이 | 판정 | 적용 결과 |
|---|---|---|
| 실제 제품에는 선택 열·삭제가 있고 선도 제품에는 없음 | 선도 제품 수정 | 목록 첫 열 checkbox와 왼쪽 삭제 액션 추가 |
| 실제 제품은 화면상 모든 행을 선택해 DELETE를 호출함 | 실제 제품·서버 확인 | 초안 판정 필드와 서버 거부 조건 확인 전에는 안전하다고 판정하지 않음 |
| 진행·확정 이력이 있는 정산의 물리 삭제 위험 | 선도 제품·서버 수정 | 첫 단일 open·부과대기 초안만 선택 허용, 확인 Alert Dialog, Supabase before delete 불변식 적용 |
| 선택 삭제와 전체 선택의 범위가 모호함 | 양쪽 계약 | 전체 선택은 삭제 가능한 초안만 포함하고, 진행·과거 회차 checkbox는 disabled |
01-C 사람 검수 항목
- [ ] To-be에서 선택이 없을 때 왼쪽 삭제가 비활성화되는지 확인했다.
- [ ] 첫 단일 부과대기 초안을 체크하면 삭제가 활성화되고 선택 건수가 확인창에 표시되는지 확인했다.
- [ ] 부과를 시작하거나 이전 회차가 생긴 행은 체크박스가 비활성화되는지 확인했다.
- [ ] 삭제 확인 뒤 목록이 빈 상태로 바뀌고 같은 월의 새 정기 관리비를 다시 만들 수 있는지 확인했다.
- [ ] 실제 제품 개발자가
/feeV2/maintenance-fee/{id}의 삭제 허용 상태와 감사 보존을 서버 코드로 확인했다. - [ ] 실제 제품도 확정·발행·수납 이후 물리 삭제를 차단하고 취소·무효화 절차를 사용하도록 수정했다.
이미 확인한 사실
- 선도 제품은 정기 관리비와 중간정산 목록을 분리한다.
- 실제 제품 정기 관리비 목록의
/feeV2/maintenance-fee조회는is_mid_fee를 전달하지 않아 두 종류를 함께 받는다. - 실제 제품에는 별도 중간정산 route도 있어 현재 IA가 중복된다.
- 선도 제품은 정산 이름 클릭으로 콘솔에 진입하고, 실제 제품은 별도
콘솔관리 컬럼을 사용한다. - 실제 제품은 서버 검색·페이지네이션과 일괄 삭제가 있고, 선도 제품은 첫 부과 준비 게이트와 오류·재시도 표현이 더 명확하다.
- 실제 제품의 고지서 빌더는 클릭 가능한 탭이지만 내용은
준비 중이다.
권장안
- 정기 관리비와 중간정산을 분리한다. API가
is_mid_fee필터와 필터 기준 count를 함께 보장해야 한다. - 실제 제품도 정산 이름 클릭으로 콘솔에 들어가고 별도
콘솔컬럼을 제거한다. - 고지서 빌더는 숨기지 않되 실행 가능한 기능처럼 보이지 않도록 별도 도구 위치에 비활성
준비 중으로 표시한다. - 삭제는 첫 단일 부과대기 초안만 허용한다. 실제 제품 서버가 같은 불변식을 보장하는지 확인하고, 확정 이후에는 삭제 대신 취소·무효화와 감사 이력을 사용한다.
- 실제 제품의 검색·페이지네이션·실제 상태 코드는 선도 제품 서버 어댑터 계약에 반영한다.
사람 검수 체크리스트
- [ ] 실제 제품 개발자가 위 사실과 실제 API 동작이 일치함을 확인했다.
- [ ] 제품 오너가 정산 종류 분리와 빌더 위치를 확정했다. 삭제 정책은 01-C 기준으로 확정했다.
- [ ] 실제 제품 수정 diff가 페이지 01 범위만 포함한다.
- [ ] 선도 제품 수정 diff가 페이지 01 범위와 필수 문서만 포함한다.
- [ ] 정기 관리비·중간정산 각각 빈 상태와 데이터 상태를 확인했다.
- [ ] 검색 결과 count와 페이지 이동이 필터 결과에 맞는다.
- [ ] 준비 중 기능이 클릭 가능한 완성 기능처럼 보이지 않는다.
- [ ] 확정·발행·수납 이후 삭제가 UI와 서버 양쪽에서 차단된다.
- [ ] AI 재검수가 완료됐다.
- [ ] 양쪽 커밋과 검수 날짜를 아래 기록에 남겼다.
확정 기록
| 항목 | 값 |
|---|---|
| 실제 제품 검수자 | 미정 |
| 제품 오너 | 미정 |
| 사람 검수일 | 미정 |
| AI 재검수일 | 미정 |
| 선도 제품 커밋 | 01-A 308f90571, 8bcabe6e3, 8fffbc444; 헤더 disclosure 38050b590; 페이지 01 본 검수 미정 |
| 실제 제품 커밋 | EDS d125278e7, 1차 판정 5e8e89cab, 01-A 셸 f00713692, d4f49bc78; 헤더 disclosure 6cc4f33b6 |
| 남은 서버 작업 | is_mid_fee 필터·count, 삭제 상태 불변식 확인 |
완료 게이트
페이지는 다음 조건을 모두 만족해야 완료로 바꾼다.
- 양쪽 UI와 API 판정이 문서에 기록됨
- 미구현 기능이 숨겨지지 않고 준비 상태로 표시됨
- EDS 정본 밖 로컬 디자인 패치가 없음
- 범위 비례 테스트 통과
- 실행하지 못한 검증과 이유가 기록됨
- 실제 프론트엔드 개발자의 사람 검수 완료
- 독립된 AI 재검수 완료
- 양쪽 커밋이 원격에 존재함