hwss-investigation-agent-frontend · 커밋 d8fc7731 · 2026-09-15 18:05 KST 빌드

HWSS 프론트엔드 가이드

로컬 실행 방법, 화면마다 부르는 API, 폴더와 파일마다 맡은 역할을 정리했습니다. 역할 문장은 파일 맨 위 또는 첫 export 위 주석의 첫 문장을 옮겼고, UI 킷은 components/ui/README.md 에서 가져왔습니다. 파일 이름을 누르면 GitHub 소스로 가고, 최근 변경된 파일은 강조됩니다. 섹션 제목 옆 말풍선으로 댓글을, 이슈 버튼으로 GitHub 이슈를 남길 수 있습니다.

16화면
165소스
80Vitest 테스트
9E2E 스펙
38/92화면이 부르는 API

화면이 데이터를 가져오는 길

  1. proxy.ts1차 가드 — access 쿠키 없으면 /login
  2. app/…/page.tsx화면 진입점 → _components
  3. _lib/queries.tsqueryOptions → lib/api/client.ts(ky)
  4. /api/v1/*next.config.ts rewrites → 백엔드

화면은 백엔드 주소를 모릅니다. 같은 오리진의 /api/v1 로만 부르고 Next.js 가 넘깁니다. 백엔드 없이 개발할 때는 MSW 가 이 요청을 브라우저에서 가로챕니다.

폴더 이름이 뜻하는 것

(auth)
로그인·온보딩 (URL 에 안 붙음)
(workspace)
앱 쉘 안 화면
_components
그 화면 전용 컴포넌트
_lib
그 화면 쿼리·규칙
[reportNo]
동적 경로 파라미터
components/ui
프리미티브·UI 킷
mocks/
MSW 목 응답
e2e/
Playwright 스모크

시작하기

로컬 실행

Node 22 · pnpm(corepack) · 모든 명령은 hwss-investigation-agent-frontend/ 에서 실행

접속 주소

개발 서버http://localhost:3000 로그인http://localhost:3000/login
API 프록시/api/v1/* → BACKEND_ORIGIN (기본 http://localhost:8080, next.config.ts rewrites)
E2E 서버http://localhost:3187 — pnpm test:e2e 가 MSW 를 켜고 자동 기동
백엔드 실행백엔드 가이드 · 로컬 실행 · Swagger

브라우저는 같은 오리진의 /api/v1 로만 요청하고 Next.js 가 백엔드로 넘깁니다. 그래서 세션 쿠키(httpOnly)가 자동으로 붙고, 백엔드 주소를 바꿀 때는 BACKEND_ORIGIN 만 바꾸면 됩니다.

로그인과 가드

1차 가드 — proxy.ts 가 /user/*·/admin/*·/onboarding 요청에 access 쿠키가 없으면 /login?from=원래경로 로 보냅니다.

2차 가드 — 앱 쉘이 GET /api/v1/auth/me 로 세션을 확인합니다. 401 이면 재발급을 한 번 시도하고, 실패하면 로그인으로 보냅니다.

백엔드와 함께 띄울 때 로그인은 사번 H2016-0071(시드 시스템 관리자) / 비밀번호는 백엔드를 띄울 때 준 AUTH_LOCAL_PASSWORD 값입니다.

LNB 메뉴는 코드에 적혀 있지 않고 권한 API 응답으로 그립니다. 화면이 아직 없는 메뉴는 비활성으로 보이며, 화면을 붙일 때 components/common/workspace-menu.ts 의 MENU_ROUTES 에 한 줄 추가합니다.

개발 서버 띄우기 

# 최초 1회
corepack enable
pnpm install

# ① 백엔드와 함께 — 백엔드(8080)를 먼저 띄운다
pnpm dev

# ② 백엔드 없이 — MSW 가 /api/v1 요청을 가로채 계약 모양의 목 응답을 준다
NEXT_PUBLIC_API_MOCKING=enabled pnpm dev

# ③ 다른 백엔드 주소로
BACKEND_ORIGIN=http://10.0.0.5:8080 pnpm dev

환경변수는 매번 앞에 붙이는 대신 .env.local 에 적어 둬도 됩니다(커밋되지 않음). ② 에서 아직 화면용 더미가 없는 엔드포인트도 계약 스켈레톤(mocks/handlers.generated.ts)이 성공 응답을 돌려주므로 404 가 나지 않습니다.

환경변수 lib/env.ts

BACKEND_ORIGIN선택백엔드 origin — next.config.ts rewrites가 /api/v1을 이 주소로 프록시한다 — 값: URL, 기본 http://localhost:8080
AUTH_GUARD_DISABLED선택백엔드 auth 구현 전 로컬 개발용 가드 해제 스위치 — 값: true / false, 기본 false
NEXT_PUBLIC_API_MOCKING선택MSW 브라우저 모킹 활성화 (개발·E2E 전용, 클라이언트에서도 사용) — 값: enabled / disabled, 기본 disabled

새 환경변수는 lib/env.ts 의 zod 스키마에 등록하고 env.X 로 읽습니다. process.env 를 직접 읽지 않습니다(클라이언트 컴포넌트의 NEXT_PUBLIC_* 만 예외). 시크릿에는 NEXT_PUBLIC_ 접두사를 붙이지 않습니다.

pnpm 명령 package.json scripts

pnpm dev명령개발 서버 (http://localhost:3000).
pnpm build명령프로덕션 빌드 (standalone 출력 — Dockerfile 이 사용).
pnpm start명령빌드 결과 실행.
pnpm lint명령ESLint — 역할 경계 import 규칙·TanStack Query 규칙 포함.
pnpm format명령Prettier 일괄 적용.
pnpm format:check명령포맷이 안 된 파일 검사.
pnpm typecheck명령TypeScript 타입 검사.
pnpm test명령Vitest 단위·컴포넌트 테스트.
pnpm test:e2e명령Playwright E2E 스모크 — MSW 를 켠 dev 서버(3187)를 자동 기동. 최초 1회 pnpm exec playwright install chromium.
pnpm openapi:gen명령백엔드 openapi.json 스냅샷 → lib/api/schema.d.ts · mocks/handlers.generated.ts 생성.
pnpm check:openapi명령생성물이 스냅샷과 같은지 검사만 (갱신 안 함).
pnpm check명령PR 전 전체 검사 — format:check → lint → typecheck → check:openapi → test → build.

CI(.github/workflows/frontend-check.yml, 사내 러너)는 프론트 코드가 바뀐 PR·dev 푸시에서 pnpm check, pnpm check:openapi, pnpm test:e2e 를 돌립니다. 백엔드 API 계약이 바뀌면 백엔드에서 ./gradlew :hwss-api:exportOpenApiSpec 후 여기서 pnpm openapi:gen 을 같은 PR 에 커밋합니다.

시작하기

코드 배치·경계 규칙

원문: docs/guides/frontend-module-guide.md · docs/rules/frontend.md

코드를 어디에 둘까

app/<route>/_components한 화면에서만 쓰는 컴포넌트
app/<route>/_lib한 화면의 쿼리(queries.ts)·순수 계산·필터 규칙
components/user · admin한 콘솔의 여러 화면이 같이 쓰는 것
components/commonUser·Admin 양쪽에서 실제로 같은 의미로 쓰는 것 (예상만으로 올리지 않는다)
components/uishadcn 프리미티브와 UI 킷 — 업무 의미를 담지 않는다
lib/업무 의미가 없는 유틸, API 클라이언트, 두 콘솔 공용 세션·메뉴 쿼리

넘지 않는 경계 eslint no-restricted-imports

common · ui · libapp·components/user·components/admin 를 import 하지 않는다
user ↔ adminUser 화면·컴포넌트와 Admin 화면·컴포넌트는 서로 import 하지 않는다
frontend ↔ backendHTTP API 로만 통신한다 — 코드 직접 참조 금지

폴더 경계는 권한 보장이 아닙니다. 권한 검증은 서버(API)가 합니다.

상태는 섞지 않는다

서버 상태API 응답 — TanStack Query 캐시가 유일한 출처. 전역 스토어에 복사하지 않는다
URL 상태공유·새로고침에 살아야 하는 조건(필터·쪽 번호) — search param (lib/url)
폼React Hook Form + zod
전역 UI여러 화면이 공유하는 UI 상태만 Zustand
지역 상태그 외는 useState 우선

API 호출

lib/api/client.ts유일한 호출 경로(ky) — apiGet·apiPost… 401 이면 재발급 후 재시도, success:false 는 오류로 던진다
_lib/queries.ts화면별 queryOptions 팩토리. queryFn 안에서 fetch 를 직접 쓰지 않는다
lib/api/schema.d.ts백엔드 OpenAPI 스냅샷에서 생성한 타입 — 손으로 고치지 않는다

테스트 배치: 순수 함수는 옆에 Vitest, 상호작용은 Testing Library, API 의존 컴포넌트는 MSW(mocks/server.ts), 로그인 같은 핵심 흐름은 Playwright(e2e/).

변경 추적

최근 변경

최근 14일 · PR 14건

dev 에 머지된 PR 중 이 가이드 범위의 파일을 바꾼 것입니다. 파일을 누르면 아래 해당 행으로 이동하고, 7일 이내에 바뀐 파일 행은 주황색으로 강조됩니다.

#46609/14 · 어제제목은 로그인 후 표시
lib/api/schema.d.tsmocks/handlers.generated.ts
#42909/09 · 6일 전제목은 로그인 후 표시
lib/api/schema.d.ts
#42809/09 · 6일 전제목은 로그인 후 표시
lib/api/schema.d.tsmocks/handlers.generated.ts
#42409/08 · 7일 전제목은 로그인 후 표시
lib/api/schema.d.ts
#41009/08 · 7일 전제목은 로그인 후 표시
app/(workspace)/admin/audit-logs/_components/audit-log-filters.tsxapp/(workspace)/admin/audit-logs/_lib/audit-log.tsapp/(workspace)/admin/statistics/unmapped/_components/unmapped-queue-filters.tsxapp/(workspace)/user/collections/_components/collection-form-dialog.tsxapp/(workspace)/user/investigations/_components/investigation-list-filters.tsxapp/(workspace)/user/investigations/_lib/list-filter.tscomponents/ui/README.mdcomponents/ui/native-select.test.tsx+5
#40909/08 · 7일 전제목은 로그인 후 표시
app/(workspace)/admin/audit-logs/_components/audit-log-filters.tsxapp/(workspace)/admin/audit-logs/page.test.tsxapp/(workspace)/admin/statistics/unmapped/_components/unmapped-queue-view.tsxapp/(workspace)/admin/statistics/unmapped/page.test.tsxapp/(workspace)/user/investigations/_lib/list-filter.test.tsapp/(workspace)/user/investigations/_lib/list-filter.ts
#40809/08 · 7일 전제목은 로그인 후 표시
README.mdapp/(workspace)/user/investigations/_components/investigation-list-view.tsxapp/(workspace)/user/investigations/_lib/list-filter.test.tsapp/(workspace)/user/investigations/_lib/list-filter.tsapp/(workspace)/user/investigations/_lib/queries.tsapp/(workspace)/user/investigations/page.test.tsxe2e/investigation-list.spec.tslib/api/schema.d.ts+1
#40709/08 · 7일 전제목은 로그인 후 표시
README.mdapp/(workspace)/admin/page.tsxapp/(workspace)/admin/statistics/unmapped/_components/resolve-dialog.tsxapp/(workspace)/admin/statistics/unmapped/_components/unmapped-queue-filters.tsxapp/(workspace)/admin/statistics/unmapped/_components/unmapped-queue-view.tsxapp/(workspace)/admin/statistics/unmapped/_lib/queries.tsapp/(workspace)/admin/statistics/unmapped/_lib/unmapped-queue.test.tsapp/(workspace)/admin/statistics/unmapped/_lib/unmapped-queue.ts+4
#40609/08 · 7일 전제목은 로그인 후 표시
lib/api/schema.d.tsmocks/handlers.generated.ts
#40509/08 · 7일 전제목은 로그인 후 표시
lib/api/schema.d.tsmocks/handlers.generated.ts
#40409/08 · 7일 전제목은 로그인 후 표시
lib/api/schema.d.tsmocks/handlers.generated.ts
#39809/04 · 11일 전제목은 로그인 후 표시
lib/api/schema.d.ts
#39509/04 · 11일 전제목은 로그인 후 표시
README.mdapp/(workspace)/user/investigations/[reportNo]/_components/analysis-summary-center.test.tsxapp/(workspace)/user/investigations/[reportNo]/_components/analysis-summary-center.tsxapp/(workspace)/user/investigations/[reportNo]/_components/center-header.test.tsxapp/(workspace)/user/investigations/[reportNo]/_components/center-header.tsxapp/(workspace)/user/investigations/[reportNo]/_components/classification-review-center.test.tsxapp/(workspace)/user/investigations/[reportNo]/_components/classification-review-center.tsxapp/(workspace)/user/investigations/[reportNo]/_components/document-box.tsx+32
#35609/02 · 13일 전제목은 로그인 후 표시
lib/api/schema.d.ts

화면 · API

화면 지도

라우트 → 호출 API → 백엔드 컨트롤러 → E2E

화면마다 부르는 API — 각 라우트 폴더(_lib·_components 포함)의 apiGet·apiPost… 호출을 모아 백엔드 OpenAPI 계약의 컨트롤러와 짝지었습니다. 컨트롤러 이름을 누르면 백엔드 가이드의 해당 파일 행으로 갑니다. 메뉴 표시는 LNB 메뉴 코드(MENU_ROUTES)입니다.

/loginpage.tsx인증로그인 화면.
/onboardingpage.tsx인증최초 로그인 온보딩 화면.
/admin/approval-centerpage.tsx메뉴 APPROVAL_CENTERAdmin관리자 — 승인센터 (N06 승인 대기함).
GETcollection-approvals → CollectionApprovalController
POSTcollection-approvals/{…}/approve → CollectionApprovalController
POSTcollection-approvals/{…}/reject → CollectionApprovalController
/admin/audit-logspage.tsx메뉴 AUDIT_LOGAdmin조건·쪽 번호를 URL search param 으로 읽으므로(`useSearchParams`) 본체는 Suspense 경계 안에 둔다.
GETaudit-logs → AuditLogController
/admin/classification-mappingspage.tsx메뉴 CLASSIFICATION_MAPPINGAdmin고른 위탁사를 URL search param 으로 읽으므로(`useSearchParams`) 본체는 Suspense 경계 안에 둔다.
GETcustomer-companies/{…}/classification-mappings → ClassificationMappingController
PUTcustomer-companies/{…}/classification-mappings → ClassificationMappingController
/admin/mail-accountpage.tsx메뉴 MAIL_ACCOUNTAdmin관리자 · 메일 발송 계정 (`/admin/mail-account`) — 야간 20260827 N03.
GETadmin/mail-account → MailAccountController
POSTadmin/mail-account/password → MailAccountController
/admin/organizationpage.tsx메뉴 ORGANIZATIONAdmin고른 부서를 URL search param 으로 읽으므로(`useSearchParams`) 본체는 Suspense 경계 안에 둔다.
GETdepartments → DepartmentController
GETroles → RoleController
GETusers → UserController
PUTusers/{…}/roles → UserController
/adminpage.tsx메뉴 DASHBOARDAdmin관리자 대시보드 자리 카드.
/admin/permissionspage.tsx메뉴 PERMISSIONAdmin/admin/permissions 화면 진입점.
GETmenu-permissions → MenuPermissionController
PATCHmenu-permissions → MenuPermissionController
/admin/statistics/unmappedpage.tsxAdmin조건·쪽 번호를 URL search param 으로 읽으므로(`useSearchParams`) 본체는 Suspense 경계 안에 둔다.
GETadmin/statistics/dimensions/{…} → StatUnmappedQueueController
GETadmin/statistics/unmapped → StatUnmappedQueueController
POSTadmin/statistics/unmapped/resolve → StatUnmappedQueueController
/user/collections/[id]page.tsxUser사용자 지식 컬렉션 상세 (N03).
GETcollections/{…} → CollectionController
POSTcollections/{…}/files → CollectionController
/user/collectionspage.tsx메뉴 KNOWLEDGE_COLLECTIONUser탭 상태를 URL search param 으로 읽으므로(`useSearchParams`) 목록 본체는 Suspense 경계 안에 둔다.
GETcollections → CollectionController
POSTcollections → CollectionController
DELETEcollections/{…} → CollectionController
PATCHcollections/{…} → CollectionController
/user/investigations/[reportNo]page.tsxUser사고조사 워크스페이스 (P1-2).
GETcustomer-companies/{…}/classification-mappings → ClassificationMappingController
GETinvestigation-reports/{…} → InvestigationReportController
POSTinvestigation-reports/{…}/analysis-requests → AnalysisRequestController
GETinvestigation-reports/{…}/classification-results/latest → ClassificationResultController
POSTinvestigation-reports/{…}/classification-results/latest/ai-confirmations → ClassificationResultController
POSTinvestigation-reports/{…}/classification-results/latest/manual-assignments → ClassificationResultController
GETinvestigation-reports/{…}/extraction-results/latest → ExtractionResultController
GETinvestigation-reports/{…}/summary-results/latest → SummaryResultController
GETinvestigation-reports/{…}/workflow-progress → InvestigationReportController
/user/investigationspage.tsx메뉴 INVESTIGATION_AGENTUser조건·쪽 번호를 URL search param 으로 읽으므로(`useSearchParams`) 본체는 Suspense 경계 안에 둔다.
GETinvestigation-reports → InvestigationReportController
/userpage.tsxUser/user 화면 진입점.
/page.tsx루트/ 화면 진입점.
lib/auth/공용여러 화면이 함께 쓰는 호출
POSTauth/login → AuthController
POSTauth/logout → AuthController
GETauth/me → AuthController
POSTauth/onboarding → AuthOnboardingController
GETmenu-permissions/my → MenuPermissionController
lib/customer-companies/공용여러 화면이 함께 쓰는 호출
GETcustomer-companies → CustomerCompanyController

화면 · API

아직 화면이 부르지 않는 API

백엔드 계약 92개 중 54개

백엔드에는 있지만 어느 화면도 부르지 않는 엔드포인트 — 화면을 붙일 차례인 API 를 찾을 때 봅니다. 주소를 변수로 조합해 부르는 호출은 잡히지 않을 수 있습니다.

AnalysisRequestController2개
GETinvestigation-reports/{reportNo}/analysis-requests/latest 최신 분석 요청 조회
GETinvestigation-reports/{reportNo}/analysis-requests/{requestVersion} 분석 요청 버전 조회
AuthController1개
POSTauth/refresh 세션 재발급
BusinessStatisticsController1개
GETadmin/statistics/business/{dimension} 업무 통계 조회 (차원별 기간 Top N)
ClassificationResultController3개
POSTinvestigation-reports/{reportNo}/classification-results 문서분류 실행 (스텁)
GETinvestigation-reports/{reportNo}/classification-results/latest/corrections 분류 보정 이력 조회
GETinvestigation-reports/{reportNo}/classification-results/{classificationVersion} 문서분류 결과 버전 조회
CollectionApprovalController2개
POSTcollection-approvals 지식컬렉션 승인 요청 생성
POSTcollections/{id}/file-approvals 공용 컬렉션 파일 추가 승인 요청
CollectionController1개
POSTcollections/search 지식컬렉션 검색
CommonCodeController6개
GETcommon-codes 공통 코드 목록 조회
POSTcommon-codes 공통 코드 생성
DELETEcommon-codes/{id} 공통 코드 삭제
GETcommon-codes/{id} 공통 코드 단건 조회
PATCHcommon-codes/{id} 공통 코드 부분 수정
POSTcommon-codes/{id}/details 하위 코드값 추가
ExtractionResultController2개
POSTinvestigation-reports/{reportNo}/extraction-results/latest/field-corrections 최신 정보추출 결과의 항목 값 수정
GETinvestigation-reports/{reportNo}/extraction-results/{extractionVersion} 정보추출 결과 버전 조회
InvestigationController5개
GETinvestigations 조사 건 목록 조회
POSTinvestigations 조사 건 생성
DELETEinvestigations/{id} 조사 건 삭제
GETinvestigations/{id} 조사 건 단건 조회
PATCHinvestigations/{id} 조사 건 부분 수정
LifecycleStatisticsController1개
GETadmin/statistics/lifecycle 시스템 통계 조회 (생애주기 지표 — 기간 합계 + 일별)
MenuPermissionController1개
GETmenu-permissions/{roleCode} 레벨별 메뉴 권한 조회
ReportDraftController5개
GETinvestigation-reports/{reportNo}/report-drafts 초안 버전 이력
POSTinvestigation-reports/{reportNo}/report-drafts 확정 요약에서 초안 생성 (버전 증가)
GETinvestigation-reports/{reportNo}/report-drafts/latest 최신 초안 조회
PUTinvestigation-reports/{reportNo}/report-drafts/latest 최신 초안 본문 수정
GETinvestigation-reports/{reportNo}/report-drafts/{draftVersion} 초안 버전 조회
ReportMailController2개
GETinvestigation-reports/{reportNo}/report-mails 보고서 메일 발송 이력
POSTinvestigation-reports/{reportNo}/report-mails 보고서 메일 보내기
ReportPageImageController1개
GETinvestigation-reports/{reportNo}/pages/{sourcePageId}/image 페이지 원본 이미지 조회
ReportTemplateController8개
GETadmin/report-templates 활성 보고서 양식 목록
DELETEadmin/report-templates/{templateCode} 보고서 양식 삭제
GETadmin/report-templates/{templateCode} 보고서 양식 조회 (활성 버전)
POSTadmin/report-templates/{templateCode} 보고서 양식 등록
PUTadmin/report-templates/{templateCode} 보고서 양식 수정 (버전 증가)
POSTadmin/report-templates/{templateCode}/duplications 보고서 양식 복제
GETadmin/report-templates/{templateCode}/versions 보고서 양식 버전 이력
PUTadmin/report-templates/{templateCode}/versions/{templateVersion}/activation 보고서 양식 버전 활성화
StatisticsBackfillController1개
POSTadmin/statistics/backfill 통계 사실 재적재(backfill) 명령
SummaryResultController5개
PUTinvestigation-reports/{reportNo}/summary-results/latest/cards/{cardId}/items/{itemKey} 요약 항목 본문 수정
PUTinvestigation-reports/{reportNo}/summary-results/latest/cards/{cardId}/items/{itemKey}/report-reflection 항목별 보고서 반영 체크
POSTinvestigation-reports/{reportNo}/summary-results/latest/confirmation 요약 확정
POSTinvestigation-reports/{reportNo}/summary-results/latest/confirmation-reset 요약 확정 초기화(롤백)
GETinvestigation-reports/{reportNo}/summary-results/{summaryVersion} 요약 결과 버전 조회
UserController1개
GETusers/{employeeNo} 사용자 단건 조회
ImageIntegrationController6개시스템 간 연동 — 화면 대상 아님
PUTimage-integration/customers 위탁사 전체 동기화
PUTimage-integration/customers/{customerCompanyId}/document-types 문서분류 체계 동기화
POSTimage-integration/reports/{reportNo}/confirm 분류·추출 시작 확정
POSTimage-integration/transfers/complete 이미지 전송 결과 통지
POSTimage-integration/transfers/logical 논리 변경 전송
POSTimage-integration/transfers/start 이미지 전송 시작 통지

루트

hwss-investigation-agent-frontend/GitHub

빌드·린트·테스트·배포 설정

(루트)20GitHub

앱 루트 — 루트 레이아웃, Provider(TanStack Query·MSW), 전역 스타일.

proxy.ts이력가드1차 가드 — /user·/admin·/onboarding 요청에 access 쿠키가 없으면 /login?from= 로 보낸다 (Next 16 proxy, 구 middleware).
AGENTS.md이력문서Codex 작업 지침.
CLAUDE.md이력문서Claude Code 작업 컨텍스트 — 구조·API 호출·가드·환경변수 규칙.
README.md이력7일 전 · #408문서화면별 동작 규칙 — 목록 필터·URL 조건, 워크스페이스 진행 단계 등.
.dockerignore이력배포이미지 빌드 컨텍스트에서 뺄 파일.
Dockerfile이력배포3단 빌드 — pnpm install → next build(standalone) → node:22-alpine 에서 server.js 를 3000 포트로 실행.
.gitignore이력설정커밋하지 않을 파일 (.env.local, 빌드 산출물 등).
.prettierignore이력설정포맷 대상에서 뺄 경로 (생성물 등).
.prettierrc.json이력설정Prettier 규칙 (프로토타입과 동일).
components.json이력설정shadcn/ui 설정 (base-nova 스타일, lucide 아이콘, 경로 별칭).
eslint.config.mjs이력설정역할 경계 import 금지(common·ui·lib ↛ app·user·admin, user ↔ admin)와 TanStack Query lint 규칙.
next.config.ts이력설정standalone 출력, /api/v1/* 를 BACKEND_ORIGIN 으로 넘기는 same-origin 프록시(rewrites).
package.json이력설정스크립트·의존성, pnpm 버전 고정(packageManager).
playwright.config.ts이력설정E2E 스모크 — MSW 를 켠 dev 서버를 3187 포트로 자동 기동.
pnpm-lock.yaml이력설정단일 lockfile — 설치는 항상 --frozen-lockfile.
pnpm-workspace.yaml이력설정설치 스크립트 실행 허용 목록(allowBuilds).
postcss.config.mjs이력설정Tailwind CSS 4 PostCSS 플러그인.
tsconfig.json이력설정TypeScript strict 와 @/ 경로 별칭.
vitest.config.mts이력설정Vitest — e2e 제외, @ 별칭, vitest.setup.ts 연결.
vitest.setup.ts이력설정jest-dom 매처 등록, jsdom 에서 상대 경로 fetch 를 브라우저처럼 보정.

app/ · 화면

app/ (루트·앱 쉘)GitHub

루트 레이아웃·Provider·(workspace) 공통 레이아웃

app/6GitHub

앱 루트 — 루트 레이아웃, Provider(TanStack Query·MSW), 전역 스타일.

layout.tsx이력레이아웃/ 아래 화면이 함께 쓰는 레이아웃.
page.tsx이력화면/ 화면 진입점.
globals.css이력스타일Tailwind·shadcn 테마 토큰과 전역 스타일.
msw-provider.tsx이력컴포넌트NEXT_PUBLIC_API_MOCKING=enabled일 때만 MSW 워커를 기동한다.
providers.tsx이력컴포넌트설명 주석 없음
favicon.ico이력파일파비콘.

app/(workspace)/1GitHub

/ 화면.

layout.tsx이력레이아웃/ 아래 화면이 함께 쓰는 레이아웃.

app/ · 화면

app/(auth)/GitHub

로그인·최초 로그인 온보딩

app/(auth)/login/1GitHub

/login 화면.

page.tsx이력화면로그인 화면.

app/(auth)/login/_components/1GitHub

/login 화면에서만 쓰는 컴포넌트.

login-form.tsx이력테스트컴포넌트설명 주석 없음

app/(auth)/onboarding/1GitHub

/onboarding 화면.

page.tsx이력화면최초 로그인 온보딩 화면.

app/(auth)/onboarding/_components/1GitHub

/onboarding 화면에서만 쓰는 컴포넌트.

onboarding-form.tsx이력테스트컴포넌트설명 주석 없음

app/ · 화면

app/(workspace)/user/GitHub

User Console 화면

app/(workspace)/user/2GitHub

/user 화면.

layout.tsx이력레이아웃/user 아래 화면이 함께 쓰는 레이아웃.
page.tsx이력화면/user 화면 진입점.

app/(workspace)/user/collections/1GitHub

/user/collections 화면.

page.tsx이력테스트화면탭 상태를 URL search param 으로 읽으므로(`useSearchParams`) 목록 본체는 Suspense 경계 안에 둔다.

app/(workspace)/user/collections/[id]/1GitHub

/user/collections/[id] 화면.

page.tsx이력테스트화면사용자 지식 컬렉션 상세 (N03).

app/(workspace)/user/collections/[id]/_components/3GitHub

/user/collections/[id] 화면에서만 쓰는 컴포넌트.

collection-detail-view.tsx이력컴포넌트사용자 지식 컬렉션 상세 + 이름·설명 수정·삭제 (N03·N04).
collection-file-table.tsx이력컴포넌트컬렉션에 등록된 파일 표.
collection-file-upload-dialog.tsx이력컴포넌트컬렉션 파일 등록 대화상자 (N05) — 한 번에 한 건.

app/(workspace)/user/collections/[id]/_lib/2GitHub

/user/collections/[id] 화면의 쿼리(queryOptions)·순수 계산·규칙 — 다른 화면에서 import 하지 않는다.

collection-detail.ts이력테스트모듈지식컬렉션 상세 화면의 표시 규칙.
queries.ts이력쿼리queryOptions 팩토리 — queryKey와 queryFn을 한 곳에 묶는다.

app/(workspace)/user/collections/_components/2GitHub

/user/collections 화면에서만 쓰는 컴포넌트.

collection-form-dialog.tsx이력7일 전 · #410컴포넌트컬렉션 등록·수정 폼 (N04).
collection-list-view.tsx이력컴포넌트탭 상태가 실리는 URL search param 이름.

app/(workspace)/user/collections/_lib/3GitHub

/user/collections 화면의 쿼리(queryOptions)·순수 계산·규칙 — 다른 화면에서 import 하지 않는다.

collection-form.ts이력테스트모듈지식컬렉션 등록·수정 폼의 입력 규칙 (N04).
collection-list.ts이력테스트모듈지식컬렉션 목록 화면의 표시 규칙 — 백엔드 enum(CollectionSummary)을 화면 어휘로 옮긴다.
queries.ts이력쿼리queryOptions 팩토리 — queryKey와 queryFn을 한 곳에 묶는다.

app/(workspace)/user/investigations/1GitHub

/user/investigations 화면.

page.tsx이력테스트화면조건·쪽 번호를 URL search param 으로 읽으므로(`useSearchParams`) 본체는 Suspense 경계 안에 둔다.

app/(workspace)/user/investigations/[reportNo]/3GitHub

/user/investigations/[reportNo] 화면.

page.tsx이력테스트화면사고조사 워크스페이스 (P1-2).
workspace-analysis.test.tsx이력테스트추출완료 워크스페이스
workspace-classification.test.tsx이력테스트미분류검출 워크스페이스

app/(workspace)/user/investigations/[reportNo]/_components/13GitHub

/user/investigations/[reportNo] 화면에서만 쓰는 컴포넌트.

analysis-summary-center.tsx이력테스트컴포넌트분석완료 센터의 요약 **읽기 표시** (N06).
assistant-placeholder.tsx이력컴포넌트챗봇·요약 패널 자리 — 프로토타입 우측 독(요약·해석 / 챗)의 섹션 배치를 따른다.
center-header.tsx이력테스트컴포넌트결과 센터(분류 확인·추출완료·분석완료)의 머리 — 원형 아이콘 + 20px 제목 + 설명 한 줄.
classification-review-center.tsx이력테스트컴포넌트분류 확인 화면 (W07) — `미분류검출` 센터.
document-box.tsx이력컴포넌트스캔 문서함 — 문서 종류(분류 폴더) 단위 묶음과 그 안의 페이지.
extraction-review-center.tsx이력테스트컴포넌트추출완료 화면 (N06) — `EXTRACTION_COMPLETED` 센터.
investigation-workspace.tsx이력컴포넌트사고조사 워크스페이스 — 프로토타입 workspace-client 의 골격(GNB 70px + 스테퍼 68px + 좌 문서 패널 / 중앙 상태 센터 / 우 보조 패널)을 따르는 풀블리드 화면.
page-image-viewer.tsx이력테스트컴포넌트페이지 원본 이미지 뷰어 — N04 이미지 서빙 API 를 쿼리(`pageImage`, Blob)로 받아 object URL 로 그린다.
result-query-gate.tsx이력테스트컴포넌트결과 조회의 **로딩 → 산출 전(404) → 실패 → 성공** 분기 한 벌.
transfer-history.tsx이력컴포넌트전송 이력 — 확정 전까지 분할 스캔이 계속 들어오므로(S-004 §2), 조사자가 "지금까지 몇 번, 마지막이 언제"를 보고 확정 시점을 판단한다.
workflow-stepper.tsx이력컴포넌트진행 단계 스테퍼 — 프로토타입 investigation-workflow-stepper 의 표기(2줄 단계 + 진행 필)를 따른다.
workspace-center.tsx이력컴포넌트워크스페이스 가운데 영역 — 프로토타입 workflow-status-centers 의 센터 카드 스케일(원형 아이콘 + 24px 제목 + 16px 본문)을 따른다.
workspace-header.tsx이력컴포넌트워크스페이스 GNB — 프로토타입 investigation-workspace-gnb 의 배치(뒤로가기 + 에이전트 아이콘 + 제목·뱃지 / 오른쪽 메타 칩)를 따른다.

app/(workspace)/user/investigations/[reportNo]/_lib/8GitHub

/user/investigations/[reportNo] 화면의 쿼리(queryOptions)·순수 계산·규칙 — 다른 화면에서 import 하지 않는다.

analysis-request.ts이력테스트모듈분석 요청(W09)의 화면 입력 → 계약(`AnalysisRequestCommand`) 변환 — 순수 계산만 둔다.
extraction-review.ts이력테스트모듈추출 결과(`GET .../extraction-results/latest`)를 화면이 읽는 규칙 — 순수 계산만 둔다.
workflow-progress.ts이력테스트모듈워크플로우 진행 상태(`GET .../workflow-progress`) 를 화면이 읽는 규칙 — 순수 계산만 둔다.
workspace-pages.ts이력테스트모듈문서함 낱장을 뷰어가 다루는 형태로 펴는 순수 계산 — 화면 상태는 없다.
workspace-refresh.ts이력테스트모듈사용자 조치(분류 확정·분석 요청 …)가 백엔드에서 상태 전이를 일으켰을 수 있을 때, 워크스페이스의 **진행 상태와 상세**를 다시 받게 한다.
workspace-steps.ts이력테스트모듈워크스페이스 상단 스테퍼의 단계 정의.
queries.ts이력쿼리목록 쿼리와 같은 ["investigation-reports", …] 네임스페이스 아래 둔다 — 나중에 확정·재분류로 목록과 상세를 함께 무효화할 때 접두사 하나로 잡히게 하기 위해서다.
use-progress-sync.ts이력훅진행 상태가 바뀌었을 때 화면의 나머지를 따라 맞춘다 — **주소(`status=`)와 상세 캐시** 둘이다.

app/(workspace)/user/investigations/_components/3GitHub

/user/investigations 화면에서만 쓰는 컴포넌트.

investigation-list-filters.tsx이력7일 전 · #410컴포넌트사고조사 목록 필터 줄 — 프로토타입 목록 필터 바의 구성(위탁사 · 청구유형 · 상태 · 접수일자 범위 · 초기화 · 조회)을 실제 계약에 맞춰 다시 쓴 것(야간 플랜 20260903 N07).
investigation-list-view.tsx이력7일 전 · #408컴포넌트사고조사 목록 (P1-1).
secondary-flag-badges.tsx이력컴포넌트보조 상태 플래그 뱃지들 — 목록의 `위험 · 변경` 열과 워크스페이스 헤더가 함께 쓴다.

app/(workspace)/user/investigations/_lib/4GitHub

/user/investigations 화면의 쿼리(queryOptions)·순수 계산·규칙 — 다른 화면에서 import 하지 않는다.

list-filter.ts이력테스트7일 전 · #410모듈화면이 다루는 조건.
list-status.ts이력테스트모듈S-004 §4-1·§5 목록 표시 상태 → 라벨·뱃지 톤 매핑.
secondary-flags.ts이력테스트모듈S-004 §4-1 보조 상태 플래그(변경감지·미분류·저신뢰) → 라벨·뱃지 톤 매핑.
queries.ts이력7일 전 · #408쿼리queryOptions 팩토리 — queryKey와 queryFn을 한 곳에 묶는다.

app/ · 화면

app/(workspace)/admin/GitHub

Admin Console 화면

app/(workspace)/admin/2GitHub

/admin 화면.

layout.tsx이력레이아웃/admin 아래 화면이 함께 쓰는 레이아웃.
page.tsx이력7일 전 · #407화면관리자 대시보드 자리 카드.

app/(workspace)/admin/approval-center/1GitHub

/admin/approval-center 화면.

page.tsx이력테스트화면관리자 — 승인센터 (N06 승인 대기함).

app/(workspace)/admin/approval-center/_lib/2GitHub

/admin/approval-center 화면의 쿼리(queryOptions)·순수 계산·규칙 — 다른 화면에서 import 하지 않는다.

approval.ts이력테스트모듈관리자 지식컬렉션 승인 대기함의 표시 규칙 (N06).
queries.ts이력쿼리승인 원장 조회 캐시의 뿌리 — 승인·반려 뒤 이 키 하나로 대기함을 다시 받는다.

app/(workspace)/admin/audit-logs/1GitHub

/admin/audit-logs 화면.

page.tsx이력테스트화면조건·쪽 번호를 URL search param 으로 읽으므로(`useSearchParams`) 본체는 Suspense 경계 안에 둔다.

app/(workspace)/admin/audit-logs/_components/2GitHub

/admin/audit-logs 화면에서만 쓰는 컴포넌트.

audit-log-filters.tsx이력7일 전 · #410컴포넌트감사 로그 필터 줄.
audit-log-view.tsx이력컴포넌트설명 주석 없음

app/(workspace)/admin/audit-logs/_lib/2GitHub

/admin/audit-logs 화면의 쿼리(queryOptions)·순수 계산·규칙 — 다른 화면에서 import 하지 않는다.

audit-log.ts이력테스트7일 전 · #410모듈셀렉트 항목 순서 — 적재 지점이 늘어나면 백엔드 enum 이 먼저 늘고 여기가 따라간다.
queries.ts이력쿼리한 쪽의 행 수.

app/(workspace)/admin/classification-mappings/1GitHub

/admin/classification-mappings 화면.

page.tsx이력테스트화면고른 위탁사를 URL search param 으로 읽으므로(`useSearchParams`) 본체는 Suspense 경계 안에 둔다.

app/(workspace)/admin/classification-mappings/_components/2GitHub

/admin/classification-mappings 화면에서만 쓰는 컴포넌트.

classification-mapping-table.tsx이력컴포넌트설명 주석 없음
classification-mapping-view.tsx이력컴포넌트위탁사가 실리는 URL search param 이름.

app/(workspace)/admin/classification-mappings/_lib/2GitHub

/admin/classification-mappings 화면의 쿼리(queryOptions)·순수 계산·규칙 — 다른 화면에서 import 하지 않는다.

mapping.ts이력테스트모듈분류체계 매핑의 편집 상태 계산 — 화면(page.tsx)에서 떼어 낸 순수 함수들.
queries.ts이력쿼리매핑을 저장한다(전량 치환 `PUT`).

app/(workspace)/admin/mail-account/1GitHub

/admin/mail-account 화면.

page.tsx이력테스트화면관리자 · 메일 발송 계정 (`/admin/mail-account`) — 야간 20260827 N03.

app/(workspace)/admin/mail-account/_components/2GitHub

/admin/mail-account 화면에서만 쓰는 컴포넌트.

mail-account-summary.tsx이력컴포넌트계정 정보 · 변경 주기 상태 · 변경 이력 (읽기 전용).
password-reset-form.tsx이력컴포넌트비밀번호 재설정 폼.

app/(workspace)/admin/mail-account/_lib/3GitHub

/admin/mail-account 화면의 쿼리(queryOptions)·순수 계산·규칙 — 다른 화면에서 import 하지 않는다.

mail-account.ts이력테스트모듈관리자 "메일 발송 계정" 화면이 응답을 읽는 규칙 (야간 20260827 N03).
reset-form.ts이력테스트모듈비밀번호 재설정 폼의 입력 규칙 (야간 20260827 N03).
queries.ts이력쿼리비밀번호 재설정.

app/(workspace)/admin/organization/1GitHub

/admin/organization 화면.

page.tsx이력테스트화면고른 부서를 URL search param 으로 읽으므로(`useSearchParams`) 본체는 Suspense 경계 안에 둔다.

app/(workspace)/admin/organization/_components/3GitHub

/admin/organization 화면에서만 쓰는 컴포넌트.

department-tree.tsx이력컴포넌트조직도 트리 — 부서 하나를 고르는 목록.
organization-view.tsx이력컴포넌트고른 부서가 실리는 URL search param 이름.
user-role-edit-dialog.tsx이력컴포넌트사용자 한 명의 보유 레벨 편집창.

app/(workspace)/admin/organization/_lib/3GitHub

/admin/organization 화면의 쿼리(queryOptions)·순수 계산·규칙 — 다른 화면에서 import 하지 않는다.

role-edit.ts이력테스트모듈사용자 레벨 편집(N02)의 순수 로직 — 화면(다이얼로그)에서 떼어 낸 계산만 모은다.
tree.ts이력테스트모듈조직도 트리의 노드 하나 — 계약 타입 그대로다.
queries.ts이력쿼리부서별 사용자 목록 캐시 전체를 가리키는 키 — 저장 뒤 무효화 대상이다.

app/(workspace)/admin/permissions/1GitHub

/admin/permissions 화면.

page.tsx이력테스트화면/admin/permissions 화면 진입점.

app/(workspace)/admin/permissions/_components/1GitHub

/admin/permissions 화면에서만 쓰는 컴포넌트.

permission-matrix-table.tsx이력컴포넌트한 콘솔의 메뉴 × 레벨 매트릭스.

app/(workspace)/admin/permissions/_lib/2GitHub

/admin/permissions 화면의 쿼리(queryOptions)·순수 계산·규칙 — 다른 화면에서 import 하지 않는다.

matrix.ts이력테스트모듈권한 매트릭스의 편집 상태 계산 — 화면(page.tsx)에서 떼어 낸 순수 함수들.
queries.ts이력쿼리바뀐 셀만 반영한다(PATCH).

app/(workspace)/admin/statistics/unmapped/1GitHub

/admin/statistics/unmapped 화면.

page.tsx이력테스트7일 전 · #407화면조건·쪽 번호를 URL search param 으로 읽으므로(`useSearchParams`) 본체는 Suspense 경계 안에 둔다.

app/(workspace)/admin/statistics/unmapped/_components/3GitHub

/admin/statistics/unmapped 화면에서만 쓰는 컴포넌트.

resolve-dialog.tsx이력7일 전 · #407컴포넌트미매핑 원문값 하나(묶음)의 처리 창 — 병합·신규 등록·무시 중 행에서 고른 하나만 다룬다.
unmapped-queue-filters.tsx이력7일 전 · #410컴포넌트미매핑 큐 필터 줄 — 감사 로그 필터와 같은 동작이다(`useFilterDraft`).
unmapped-queue-view.tsx이력7일 전 · #409컴포넌트설명 주석 없음

app/(workspace)/admin/statistics/unmapped/_lib/2GitHub

/admin/statistics/unmapped 화면의 쿼리(queryOptions)·순수 계산·규칙 — 다른 화면에서 import 하지 않는다.

unmapped-queue.ts이력테스트7일 전 · #407모듈셀렉트 항목 순서 — 백엔드 `StatDimension` enum 순서를 따른다.
queries.ts이력7일 전 · #407쿼리한 쪽의 행 수.

components/

components/ui/GitHub

shadcn 프리미티브·UI 킷

components/ui/32GitHub

shadcn 프리미티브와 프로젝트 UI 킷. 업무 의미(상태 이름·라벨)는 담지 않고 표현만 둔다.

README.md이력7일 전 · #410문서UI 킷 사용법 — 프리미티브와 프로젝트 UI 킷의 구분, 컴포넌트별 예시.
alert-banner.tsx이력테스트컴포넌트UI 킷 — 알림 배너 (사용법은 components/ui/README.md).
alert-dialog.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
badge.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
button.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
card.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
checkbox.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
confirm-dialog.tsx이력테스트컴포넌트UI 킷 — 확인 대화상자 (사유 입력 변형 포함) (사용법은 components/ui/README.md).
data-table.tsx이력테스트컴포넌트UI 킷 — 데이터 테이블 (사용법은 components/ui/README.md).
dialog.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
dropdown-menu.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
empty-state.tsx이력테스트컴포넌트UI 킷 — 빈 상태 (사용법은 components/ui/README.md).
field.tsx이력테스트컴포넌트UI 킷 — 폼 컨트롤 래퍼 (사용법은 components/ui/README.md).
filter-bar.tsx이력테스트컴포넌트UI 킷 — 목록 필터 줄 (사용법은 components/ui/README.md).
inline-edit-text.tsx이력테스트컴포넌트UI 킷 — 그 자리에서 고치는 텍스트 (사용법은 components/ui/README.md).
input.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
kebab-menu.tsx이력테스트컴포넌트UI 킷 — 행 액션 메뉴 (사용법은 components/ui/README.md).
label.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
modal-frame.tsx이력테스트컴포넌트UI 킷 — 모달 프레임 (사용법은 components/ui/README.md).
native-select.tsx이력테스트7일 전 · #410컴포넌트UI 킷 — 기본 셀렉트 (사용법은 components/ui/README.md).
page-heading.tsx이력테스트컴포넌트UI 킷 — 페이지 제목 (사용법은 components/ui/README.md).
pagination.tsx이력테스트컴포넌트UI 킷 — 데이터 테이블 (사용법은 components/ui/README.md).
radio-group.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
section-card.tsx이력테스트컴포넌트UI 킷 — 구획 카드 (사용법은 components/ui/README.md).
select.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
skeleton.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
sonner.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
status-badge.tsx이력테스트컴포넌트UI 킷 — 상태 뱃지 (사용법은 components/ui/README.md).
table.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
tabs.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
textarea.tsx이력컴포넌트shadcn/ui 프리미티브 — CLI 생성물이라 손으로 고치지 않는다.
three-column-layout.tsx이력테스트컴포넌트UI 킷 — 워크스페이스 3컬럼 (사용법은 components/ui/README.md).

components/

components/common/GitHub

두 콘솔 공용

components/common/9GitHub

User·Admin 두 콘솔이 같은 의미로 쓰는 앱 쉘(LNB·GNB)·가드·배너.

workspace-menu.ts이력테스트모듈LNB 메뉴 구성 — 권한 API(`GET /api/v1/menu-permissions/{roleCode}`) 응답을 화면이 쓸 형태로 바꾼다.
console-switcher.tsx이력컴포넌트User ↔ Admin 콘솔 전환 (프로토타입 LNB 상단의 전환 버튼 패턴을 재작성).
onboarding-guard.tsx이력테스트컴포넌트3차 가드 — 세션은 있으나 온보딩(부수정보 설정)이 끝나지 않은 사용자를 워크스페이스에서 차단한다.
page-container.tsx이력컴포넌트바깥 `<main>`은 앱 쉘(components/common/workspace-shell.tsx)이 소유한다.
request-error-banner.tsx이력테스트컴포넌트서버가 문구를 주지 않았을 때의 기본 안내.
workspace-nav.tsx이력테스트컴포넌트LNB — 프로토타입 사이드바(`components/user/app-sidebar.tsx`)의 구조를 재작성한 것이다.
workspace-shell.tsx이력컴포넌트앱 쉘 프레임 — LNB + GNB + 본문.
workspace-top-bar.tsx이력컴포넌트GNB — 현재 위치(콘솔·메뉴)와 세션 사용자를 보여주는 상단 바.
brand-tokens.test.ts이력테스트브랜드 색 토큰화

components/

components/user · admin/GitHub

콘솔별 공용

components/admin/4GitHub

Admin Console 공용 — 관리자 접근 가드, 초안 저장 알림 등.

admin-access-guard.tsx이력테스트컴포넌트관리자 콘솔 접근 가드 — 세션 레벨에 관리자 콘솔 허용 메뉴가 하나도 없으면 본문 대신 차단 안내를 보여준다 (2026-08-26 지시).
admin-shell.tsx이력컴포넌트Admin Console 쉘 — 프레임은 공통, 콘솔 구분만 준다.
draft-save-actions.tsx이력테스트컴포넌트관리자 설정 화면의 "변경 취소 / 저장" 버튼 쌍 (`PageHeading` 의 `actions` 에 넣는다).
draft-save-notices.tsx이력테스트컴포넌트관리자 설정 화면의 저장 결과 배너 묶음 — 실패 → 성공 → 미저장 경고 순서.

components/user/1GitHub

User Console 공용 — 콘솔 구분만 넘기는 얇은 쉘 래퍼.

user-shell.tsx이력컴포넌트User Console 쉘 — 프레임은 공통, 콘솔 구분만 준다.

lib · 보조

lib/GitHub

유틸·API 클라이언트·세션

lib/2GitHub

업무 의미가 없는 유틸.

env.ts이력모듈환경변수 검증 — 잘못된 값·오타는 기동 시점에 바로 실패시킨다.
utils.ts이력모듈설명 주석 없음

lib/api/6GitHub

API 클라이언트(ky) 단일 진입점, 응답 봉투·오류, QueryClient, OpenAPI 생성 타입.

client.ts이력테스트모듈API 클라이언트 단일 진입점 — docs/decisions/20260810-frontend-auth-and-api-client.md 모든 queryFn은 fetch를 직접 쓰지 않고 이 파일의 apiGet/apiPost/apiPatch/apiDelete만 사용한다.
envelope.ts이력테스트모듈docs/rules/api.md 표준 응답 구조(success/data/error)의 파싱과 오류 변환.
error-message.ts이력테스트모듈API 오류를 화면 문구로 옮긴다.
query-client.ts이력테스트모듈설명 주석 없음
single-flight.ts이력테스트모듈동시에 여러 번 호출돼도 in-flight Promise 하나를 공유하게 만든다.
schema.d.ts이력어제 · #466생성물pnpm openapi:gen 생성물 — 백엔드 OpenAPI 스냅샷에서 만든 계약 타입. 손으로 고치지 않는다.

lib/auth/4GitHub

세션·로그인·온보딩·내 메뉴 권한 — 두 콘솔이 함께 쓰는 쿼리와 쿠키 이름.

api.ts이력모듈세션 API 호출 — 백엔드 auth 모듈(20260810 §1 쿠키 계약)의 /api/v1/auth/*.
cookies.ts이력모듈쿠키 계약: docs/decisions/20260810-frontend-auth-and-api-client.md 백엔드 auth 모듈이 같은 이름으로 발급한다.
redirect.ts이력테스트모듈로그인 후 되돌아갈 경로 정리 — proxy.ts 가드가 붙이는 `?from=` 값을 그대로 믿지 않는다.
queries.ts이력쿼리세션·메뉴 권한 queryOptions 팩토리.

lib/customer-companies/1GitHub

여러 화면이 함께 쓰는 위탁사 목록 쿼리.

queries.ts이력테스트쿼리위탁사 마스터 조회 — User/Admin 두 콘솔이 함께 쓰는 queryOptions 팩토리.

lib/filter/1GitHub

필터 초안(입력 중) 상태 훅 — 조회를 눌러야 적용.

use-filter-draft.ts이력테스트7일 전 · #410훅"초안으로 들고 있다가 조회에서 한 번에 적용하는" 필터 줄의 상태 규칙.

lib/format/2GitHub

날짜·시간 입력과 표시 형식.

date-input.ts이력테스트7일 전 · #410모듈`<input type="date">` 가 주는 `YYYY-MM-DD` 읽기 — 형식과 달력 유효성만 보는 순수 계산.
date-time.ts이력테스트모듈일시 표시 — ISO 문자열을 사람이 읽는 한국어 표기로 옮기는 순수 계산.

lib/guard/1GitHub

소스 텍스트 규칙 검사 테스트.

source-text.test.ts이력테스트프론트 소스 텍스트 가드

lib/test/2GitHub

테스트 도우미 — Query Provider 렌더, 가짜 내비게이션.

fake-navigation.ts이력모듈테스트용 `next/navigation` 대역.
render-with-query.tsx이력컴포넌트테스트 전용 렌더 헬퍼 — TanStack Query Provider 로 감싼다.

lib/url/2GitHub

화면 조건을 URL search param 에 싣고 읽는 순수 계산과 훅.

search-params.ts이력테스트모듈URL search param 다루기 — 화면 조건을 주소에 싣는 순수 계산.
use-search-param-nav.ts이력훅화면 조건을 URL search param 으로 읽고 쓰는 훅.

lib · 보조

mocks/GitHub

MSW 핸들러

mocks/4GitHub

MSW 핸들러 — 손으로 쓴 화면 더미(앞)와 계약 생성 스켈레톤(뒤), 브라우저·Node 진입점.

browser.ts이력모듈브라우저(개발 서버·E2E)용 MSW 워커.
handlers.ts이력테스트7일 전 · #408모듈MSW 핸들러 — 백엔드 API가 준비되기 전 개발·테스트용 목 응답.
server.ts이력모듈Node(Vitest)용 MSW 서버.
handlers.generated.ts이력테스트어제 · #466생성물pnpm openapi:gen 생성물 — 모든 엔드포인트의 MSW 계약 스켈레톤. 손으로 고치지 않는다.

lib · 보조

e2e/GitHub

Playwright 스모크

e2e/9GitHub

Playwright E2E 스모크 — 가드·API 레이어·핵심 흐름처럼 한 번에 통째로 깨지는 경로만.

admin-approval-center.spec.ts이력E2ELNB 의 승인센터 메뉴로 승인 대기함에 들어간다
admin-filter-url-sync.spec.ts이력E2E감사 로그 — 조회한 조건과 쪽 번호가 주소에 실리고 새로고침해도 유지된다
admin-organization-roles.spec.ts이력E2E사용자 레벨을 더해 저장하면 목록의 보유 레벨이 갱신된다
admin-unmapped-queue.spec.ts이력7일 전 · #407E2E관리자 홈의 진입 링크로 미매핑 큐에 들어가 병원 원문값을 기존 마스터로 병합한다
investigation-list.spec.ts이력7일 전 · #408E2E상태를 고르고 조회하면 그 상태의 건만 남고, 조건이 주소에 실려 새로고침해도 유지된다
investigation-workspace.spec.ts이력E2E목록에서 건을 고르면 워크스페이스가 열린다
login.spec.ts이력E2E로그인하면 원래 가려던 화면과 앱 쉘이 보인다
smoke.spec.ts이력E2E미인증 접근은 /login으로 리다이렉트된다
user-collections.spec.ts이력E2E탭을 바꾸면 URL 에 실리고 새로고침해도 유지된다

lib · 보조

scripts/GitHub

코드 생성 스크립트

scripts/1GitHub

OpenAPI 스냅샷 → 타입·MSW 스켈레톤 생성 스크립트.

openapi-codegen.mjs이력테스트모듈백엔드 OpenAPI 계약 스냅샷 → 프론트 생성물 파이프라인 (P0-6).

lib · 보조

public/GitHub

정적 파일

public/6GitHub

정적 파일.

mockServiceWorker.js이력모듈MSW 서비스 워커 (msw init 생성물) — NEXT_PUBLIC_API_MOCKING=enabled 일 때 브라우저가 등록한다.
file.svg이력파일create-next-app 기본 아이콘 — 2026-09-15 기준 코드 어디에서도 참조하지 않는다.
globe.svg이력파일create-next-app 기본 아이콘 — 2026-09-15 기준 코드 어디에서도 참조하지 않는다.
next.svg이력파일create-next-app 기본 아이콘 — 2026-09-15 기준 코드 어디에서도 참조하지 않는다.
vercel.svg이력파일create-next-app 기본 아이콘 — 2026-09-15 기준 코드 어디에서도 참조하지 않는다.
window.svg이력파일create-next-app 기본 아이콘 — 2026-09-15 기준 코드 어디에서도 참조하지 않는다.

파일 목록·화면 지도·환경변수·명령·변경 표시는 dev 에 머지될 때마다 코드와 git 이력에서 다시 뽑습니다. 설명이 비어 있는 파일은 맨 위나 export 위에 한 줄 주석을 달면 다음 빌드부터 채워집니다. 옆에 테스트가 있는 파일은 테스트 표시가 붙습니다.