관리비 실제 제품 1:1 대조 — AI 검수 계약

독자: 실제 프론트엔드 개발자와 함께 검수하는 AI 에이전트 사람용 절차와 페이지 원장: 관리비 실제 제품 1:1 대조 — 사람 검수 가이드

역할

AI는 두 제품을 닮게 만드는 일괄 변환기가 아니다. 한 페이지의 코드·상태·API를 근거로 차이를 분류하고, 사람이 확정한 판정만 구현·검수한다.

• 선도 제품: leyve-console-proto main
• 실제 제품: leyve-admin-frontend v3-style
• 디자인 정본: leysys-design과 실제 제품이 소비하는 exact @leysys/eds
• 진행 단위: 사람용 원장의 현재 페이지 한 개

시작 전에 반드시 읽을 자료

1. 작업하는 각 저장소의 AGENTS.md
2. 사람 검수 가이드의 현재 페이지 행과 체크리스트
3. 관리비 IA 맵
4. 현재 페이지와 직접 연결된 FE·BE 핸드오프
5. 양쪽 route component, 자식 render tree, composable·store, API 호출

현재 페이지 밖 문서는 필요한 경계가 있을 때만 추가로 읽는다. 이전 페이지의 미확정 메모를 확정 사실로 사용하지 않는다.

절대 규칙

1. 한 번에 한 페이지: 현재 페이지 밖 UI를 함께 정리하지 않는다.
2. 근거 없는 대칭 금지: 한쪽에 있다고 다른 쪽에도 자동으로 추가하지 않는다.
3. 선도와 운영 사실을 분리: IA·사용 흐름은 선도 제품을 우선하되, 실제 API·권한·상태 불변식은 운영 근거로 다시 판정한다.
4. 미구현 숨김 금지: 계획된 기능은 정해진 위치에 비활성 미구현으로 표시한다. 가짜 성공·빈 클릭·완성처럼 보이는 placeholder를 만들지 않는다.
5. EDS 역패치 금지: 제품 페이지의 local CSS override, !important, wrapper 변형으로 디자인 시스템 차이를 덮지 않는다. 결함은 leysys-design에서 Token → Component → Pattern → Page 순으로 고친다.
6. 서버 추측 금지: query, count, 삭제, 잠금, 감사 불변식을 프론트 코드만 보고 서버 지원으로 단정하지 않는다.
7. 파괴 동작 확대 금지: 삭제·취소·확정·재오픈은 명시된 상태와 권한 계약 없이는 추가하지 않는다.
8. 검증 정직성: 사설 패키지 인증 등으로 실행하지 못한 테스트를 통과로 기록하지 않는다.

사설 Pro 의존성 경계

실제 제품은 @revolist/revogrid-pro@1.7.7을 공식 https://npm.rv-grid.com registry에서 소비한다.

1. 프로젝트 .npmrc에는 registry 주소만 둔다.
2. access token은 사용자 ~/.npmrc 또는 CI secret에만 저장하며 출력·문서·commit에 포함하지 않는다.
3. package가 없다고 제품 source import를 제거하거나 Vite alias·영구 shim을 추가하지 않는다.
4. 로컬 시각 확인용 임시 shim은 검수 근거가 아니며 공식 package 설치 후 제거한다.
5. AI는 token 생성·재발급 직전에 사람의 확인을 받고, 설치 결과에서는 token이 아니라 package exact version과 import 성공만 보고한다.
6. Vite overlay의 Failed to resolve import "@revolist/revogrid-pro"는 페이지 결함이 아니라 실행환경 차단으로 분류한다. 공식 package 설치 후 같은 route를 reload해 다시 판정한다.

페이지 입력 계약

AI에게 페이지 검수를 요청할 때 다음 정보를 함께 제공한다.

페이지 번호와 이름:
선도 제품 route:
실제 제품 route:
선도 제품 기준 commit:
실제 제품 기준 commit:
제품 오너가 확정한 결정:
확인할 상태와 행동:
관련 API 또는 아직 미확정인 서버 질문:
이번 검수에서 수정 가능한 저장소:

정보가 없으면 안전한 read-only 대조는 계속할 수 있다. 다만 결과를 바꿀 큰 IA·서버 결정은 오너 확인 필요로 남기고 구현하지 않는다.

대조 방법

1. route와 render tree

• route가 실제로 mount하는 최상위 component를 확인한다.
• import만 있고 render되지 않는 dead component를 구현 기능으로 세지 않는다.
• 클릭·탭·sheet·dialog가 실제 handler와 상태에 연결되는지 확인한다.

2. 상태 매트릭스

최소한 다음 상태를 양쪽에서 확인한다.

상태	확인 내용
초기·빈 상태	다음 행동과 설정 경로가 보이는가
로딩	중복 제출과 화면 점프를 막는가
정상	목록·상세·합계가 같은 업무 의미를 갖는가
오류	실패 이유, 재시도, 보존된 입력이 있는가
권한 없음	단순 빈 화면이 아니라 권한 문제를 알리는가
준비 중	위치는 보이되 실행 가능한 완성 기능처럼 보이지 않는가
확정 후	편집·삭제가 UI와 서버에서 모두 잠기는가

3. 행동과 불변식

• 생성 전 준비 조건
• 저장의 valid·dirty 게이트
• 취소 시 변경분 처리
• 삭제 가능 상태
• 확정·재오픈 순서
• 실패 후 재시도와 idempotency
• 검색 filter와 count·pagination의 동일 기준
• 다른 상품으로 전달할 때 원본 확정과 delivery 실패의 분리

4. 판정

각 차이는 다음 값 중 하나 이상으로 기록한다.

판정	의미
동일	업무 의미와 상태·행동이 이미 같다
실제 제품 수정	선도 계약이 타당하고 실제 제품이 뒤따라야 한다
선도 제품 수정	실제 운영 계약이 더 정확해 선도 제품에 승격해야 한다
양쪽 수정	둘 다 불완전하거나 공통 계약이 새로 필요하다
서버 선행	프론트만으로 정합을 보장할 수 없다
준비 중	위치와 기대 계약만 확정됐고 기능은 아직 없다
오너 확인 필요	IA·권한·파괴 동작 등 제품 결정이 남아 있다

필수 결과 형식

AI의 최종 검수 결과는 아래 순서를 지킨다.

1. 결론: 통과 / 조건부 통과 / 반려
2. 페이지와 비교 기준 commit
3. 확인한 사실
4. 차이별 판정표
5. 차단 문제 — 파일과 근거
6. 오너 또는 서버 확인이 필요한 항목
7. 수행한 검증과 결과
8. 수행하지 못한 검증과 이유
9. 다음 페이지 진입 가능 여부

코드 리뷰 결함은 정확한 파일과 가능한 한 좁은 줄 범위를 제시한다. 취향 차이는 차단 문제로 올리지 않는다.

다음 페이지 진입 금지 조건

다음 중 하나라도 있으면 현재 페이지는 완료가 아니며 다음 페이지 구현을 시작하지 않는다.

• 사람 검수가 끝나지 않음
• AI가 차단 결함을 발견함
• 양쪽 commit이 원격에 없음
• 미구현 기능이 숨겨졌거나 완성 기능처럼 동작함
• 검색 filter와 count 기준이 다름
• 확정 후 편집·삭제를 서버가 차단하는지 확인되지 않음
• 로컬 디자인 패치로 EDS 차이를 덮음
• 테스트 실패 또는 미실행 사유가 기록되지 않음

페이지 01 AI 검수 초점

페이지 01은 정기 관리비 목록과 생성 진입이다.

• 실제 제품 /feeV2/maintenance-fee 요청이 정기 관리비만 조회하는지, count도 같은 filter를 쓰는지 확인한다.
• 중간정산 생성 행동이 정기 관리비 목록과 중간정산 전용 route에 중복되지 않는지 확인한다.
• 이름 클릭으로 콘솔에 진입하고 별도 콘솔 관리 컬럼이 제거됐는지 확인한다.
• 첫 부과 준비 조건 누락 시 생성이 차단되고 해결 경로가 보이는지 확인한다.
• 첫 부과 준비 Alert가 닫을 수 있는 압축 형태인지, 닫은 뒤 추가를 눌렀을 때 Alert Dialog로 전체 blocker와 첫 해결 행동이 다시 노출되는지 확인한다.
• 미구현은 disabled·상태 배지로, 구현된 생성 행동의 데이터 선행조건은 활성 버튼+Alert Dialog로 서로 다르게 표현되는지 확인한다.
• 목록 첫 열의 선택 checkbox와 왼쪽 삭제 액션이 있는지, 전체 선택이 삭제 가능한 초안만 포함하는지 확인한다.
• 첫 단일 부과대기 초안만 선택 가능하고 진행·확정·과거 회차 checkbox는 disabled인지 확인한다.
• 선택 삭제가 확인 Alert Dialog와 서버 삭제 불변식을 거치며, 시작된 정산은 취소·재오픈·무효화로 보존되는지 확인한다.
• 고지서 빌더가 비활성 준비 중으로 정직하게 보이는지 확인한다.
• 일괄 삭제가 초안에만 허용되고 서버도 동일하게 차단하는지 확인한다.
• 빈 상태, API 오류, 재시도, 검색, 페이지 이동을 확인한다.
• 선도 제품 목록이 정본 PageBody를 소비하고 화면 gutter p-4 sm:p-6를 한 번만 소유하는지 확인한다.
• 다열 ERP 표의 폭 tier가 wide(w-full)이며 container mx-auto나 암묵적 max-w-*가 다시 들어오지 않았는지 확인한다.
• 카드 내부는 card-md, 블록 사이는 gap-4, 검색 입력+직접 실행 버튼만 gap-0.5를 유지하는지 확인한다.

현재 큰 결정은 다음 세 가지다. 사람이 확정하기 전 AI가 임의 구현하지 않는다.

1. 정기 관리비와 중간정산의 목록·생성 소유권 분리
2. 고지서 빌더의 별도 도구 위치
3. 초안 삭제와 확정 이후 취소·무효화 정책

페이지 01-A 선행 슬라이스 재검수

01-A는 공통 셸과 선도 목록의 복제 잔여물만 다룬다. AI는 다음을 독립적으로 확인한다.

• 실제 제품 App.vue가 직접 복제한 헤더 markup 대신 공통 GlobalAppHeaderOrg를 소비한다.
• 64rem 미만 메뉴 trigger와 AppNavigationSheetArt가 같은 SideMenu를 사용한다. 별도 메뉴 배열을 복제하지 않는다.
• 양쪽 GlobalAppHeaderOrg에 Workspace·Organization 전환 버튼이 없다.
• 조직 설정은 상단이 아니라 왼쪽 메뉴 mt-auto 하단 그룹에 있고, 선도 제품은 company-admin, 실제품은 Company role/레이브 관리자 표시 게이트를 갖는다. 표시 게이트를 서버 권한으로 간주하지 않는다.
• 선도 제품의 AccountScopeSwitcherMol은 신규 Company에서 Company · Office 0 · 이름을 표시한다. 실제품에는 동일 모델을 추측해 추가하지 않는다.
• 실제 제품에 없는 AI 비서는 저채도 disabled이며 보이는 미구현 배지, 호버 설명, 접근 가능한 이름을 함께 제공한다.
• 선도 제품 CriteriaToolBarOrg에 All, tag 1, tag 2 문자열과 tag control이 없다.
• 양쪽 제품의 수평 control+해당 action 직접 자식은 EDS same-unit 규칙 gap-0.5(2px)를 쓴다. 선도 제품 SearchToolBarOrg는 input-group-md와 sibling button-md button-icon button-neutral-subtle을 유지하고, 둘을 flex items-stretch gap-0.5로 묶는다. 검색 button을 input-group 안쪽 addon으로 합치지 않는다.
• 목록의 정식 순서는 Search → Criteria → Action → Table → Pagination이다. 아래 결과 집합을 바꾸는 구조화 조건의 정식 명칭은 Criteria이며 state/status로 부르지 않는다.
• 조회기간은 현재 연도 1–12월을 기본으로 하고 포함 최대 24개월이다. CriteriaToolBarOrg가 월 입력의 min·max로 잘못된 선택을 차단하고 InfoHint만 설명을 소유한다. 로컬 read model 연결을 운영 서버 완료로 세지 않으며 서버는 같은 filter/count와 24개월 검증을 반복해야 한다.
• Criteria 입력·조회와 Action 버튼은 모두 EDS sm(28px 높이·12px 글자)이다. pagination은 first–last / total의 body-xs와 20개씩 Select, Previous/숫자/Next만 기본 노출하며 Select와 페이지 버튼은 28px이다. 페이지, 총, 페이지당, 직접 페이지 입력, First/Last가 기본 조합에 남지 않았는지 확인한다.
• 카드 내부 리듬은 Search→Criteria 16px, Criteria→Action 8px, Action→Table 8px, Table→Pagination 0px이다. Pagination footer 내부 그룹 간격은 8px이며 외부 12px 같은 임의값을 추가하지 않는다.
• 실제 제품 셸에 local CSS override 또는 새 EDS class가 추가되지 않았다.
• 양쪽 제품이 exact @leysys/eds@1.0.14를 소비하고, disclosure-page-header-lg의 제목·맥락과 direct tabs-list의 로컬 탭 띠가 각각 64px·72px minimum·48px으로 계산된다. 전역 앱 헤더 56px과 합쳐 맥락을 펼친 데스크톱 기준 240px 리듬을 이루며 제품 로컬 CSS로 높이를 덮지 않는다.
• 구조 높이는 8px 스케일, 제목·맥락의 12px과 탭 스트립의 4px은 4px 보조 스케일, 2px은 same-unit control/action에만 사용되는지 확인한다.
• 현재 페이지의 <details class="disclosure-page-header ...">에는 기본 open attribute가 없고, 우측 끝에 .page-header-disclosure-indicator + expand_more가 있다. 닫힘은 아래, 열림은 위 방향이며 native summary가 단일 disclosure control이다.
• 페이지 헤더의 more_horiz 또는 빈 더보기 버튼이 제거됐다. 실제 페이지 액션이 추가될 때만 .page-header-action-group 안에서 indicator 왼쪽에 배치하고, summary 내부 action은 disclosure가 함께 토글되지 않도록 click propagation을 막는다.
• 이 기본 닫힘 전파는 현재 페이지 01 관리비 목록만 완료로 센다. 다른 페이지의 legacy open·빈 더보기는 각 페이지 대조에서 순차 처리하며 일괄 완료로 판정하지 않는다.

기준 커밋은 실제 제품 f00713692, d4f49bc78, 96b54d786, 헤더 disclosure 6cc4f33b6, 선도 제품 308f90571, 8bcabe6e3, 8fffbc444, 4b0d15a55, 헤더 disclosure 38050b590이다. 코드·대상 spec·SFC compile·EDS class audit·production build를 1차 확인했지만, 실제 프론트엔드 개발자의 사람 검수가 끝나기 전 페이지 01-A를 최종 완료로 바꾸지 않는다.

검수 응답 예시

결론: 조건부 통과
페이지: 01 정기 관리비 목록·생성 진입
기준: console <commit>, admin <commit>

확인한 사실:
- 정기 관리비 조회 query에 is_mid_fee=false가 전달된다.
- 검색어와 is_mid_fee가 같은 요청의 count에 적용된다.

차단 문제:
- 확정 상태 행에서도 삭제 선택이 활성화된다.
- 서버 삭제 차단 근거가 없어 UI 비활성만으로 완료할 수 없다.

미실행:
- 사설 패키지 인증 부재로 전체 build 미실행.
- 대상 SFC compile과 관련 spec은 통과.

다음 페이지 진입: 불가 — 삭제 서버 불변식 확인 후 재검수 필요.