Skip to content
SaaS ERP SaaS ERP Docs

Web app refactor — continuation plan (기획)

본 문서는 Prego Web App Standard 및 **Web app standardization plan**을 전제로, 동작 보존 리팩터 프로그램의 현재까지 진행 요약과 앞으로의 과제를 기획서 형태로 정리한다. 세부 감사·변경 이력은 Web app safe refactor status §10을 따른다.

범위: apps/www, apps/admin-web, apps/client-web만 (문서 전용 스택·Starlight 등은 표준 §2.3과 동일하게 범위 밖).

공개 HTTP·게이트웨이: 변경 시 How to add an API 순서(OpenAPI in prego-zuplo 선행) 및 API gateway & BFF governance.

1. 진행 상황 요약 (2026-04 기준)

1.1 공유 계약·인증 표면

  • @platform/web-auth-schemas: 이메일·OTP 등 공유 Zod 스키마. admin-web·www·client-web에서 소비; 패키지 전용 CI·Vitest·모노레포 build:verify 연동.
  • admin-web: 온보딩·로그인·가입·AuthCard·EmailOtpVerifyPanel·CompanyInfoStep 등에 RHF + Zod 정렬; 트라이얼 핸드오프·결제 성공 경로 등은 ESLint react-hooks/* 규칙에 맞춘 비동기 처리(queueMicrotask 등)·pollJob/useWatch 정리.
  • client-web: 로그인·가입·비밀번호 찾기·이메일 인증·인보이스 등 §3.4에 해당하는 화면 RHF + 공유 스키마; 패스코드 키패드·/auth/verify·auth/verify-email (POST /auth/otp/verify) 등은 parsePasscodePin / parsePasscodePinFromInput + PASSCODE_PIN_LENGTH (lib/schemas/passcode-pin, otpCodeSchema); ERP 예시(checklist / leaves / expenses capture) 스키마·폼 패턴 확립; Assistant UI Prompt Wizard (/my-ai/prompt-wizard) — promptWizardFormSchema + RHF.
  • client-web — Assistant UI main route (/my-ai): @/app/my-ai/page-controller barrel (hook, param builders, shell pipeline exports), Vitest app/my-ai/page-controller/*.test.ts, ESLint no-restricted-imports on that import path — apps/client-web/AGENTS.md, Web app standard §3.4 client-web row, safe refactor status §10 (2026-04-16–17).
  • www: TrialEmailGate·수동 승인 workEmail 등 동일 패키지 사용.

1.2 라우팅·미들웨어·E2E

  • client-web: 상위 /signin·forgot 경로·isPublic 보정; Playwright top-level redirects; **playwright.config.ts에서 webpack dev·90s 타임아웃; 기본 workers: 1 (PW_WORKERS**로 병렬 가능); CI에서 verify:client-web(앱 **verify**에 Vitest test:unit 포함 → production next build) 후 E2E.
  • admin-web: Playwright 기본 workers: 1(단일 next dev·라우트 목 경쟁 완화), 로컬 **PW_WORKERS**로 병렬 가능; 문서화 완료.
  • www: 마케팅 스모크 Playwright는 **next dev**를 자체 기동하며 NEXT_PUBLIC_ZUPLO_API_URL=https://trial-e2e.invalid를 주입; /trial Zuplo 모킹은 CORS(OPTIONS·응답 헤더) 포함. **reuseExistingServer**는 **PW_REUSE_WEB_SERVER=1**일 때만(그렇지 않으면 Zuplo env 없는 기존 dev 서버 재사용으로 실패). **next.config.mjs**에 turbopack.root / outputFileTracingRoot → monorepo 루트(Turbopack이 next 해석). CI: .github/workflows/deploy-pages.yml 마케팅 E2E 단계.

1.3 레거시·정리

  • admin-web: 루트 정적 HTML 다섯 파일 → archive/legacy-html/; 루트 JS/CSS와 상대 경로 연결; verify 스크립트·README·lint 정합.

1.4 도구·품질·문서

  • 표준화 계획: Next.js 버전 표, client-web(next-on-pages) vs admin-web(OpenNext) 배포 포지션, packages/contracts 추출 전제 문서화.
  • 상태 문서 §11 백로그 스냅샷, §10 변경 이력 지속 갱신.
  • TypeScript (tsconfig): Next가 **include**에 넣는 **.next/dev/types**를 워크스페이스 **@platform/next-dev-scripts**의 **prego-strip-next-dev-types-from-tsconfig로 정리; exclude: [".next/dev"]; client-web / admin-web / www 각각 build(및 client pages:build, admin cf:build)·typecheck**에 strip 연동; www **verify**에 typecheck 포함.

2. 앞으로 진행할 과제 (우선순위·수용 기준)

아래는 Web app standardization plan §4·§5와 정합되도록 재구성한 후속 로드맵이다. 실제 스프린트·담당자 배정은 제품 일정에 맞게 조정한다.

단계과제수용 기준(예시)비고
A — Next 메이저 정렬세 앱을 16.0.11 + eslint-config-next 16으로 맞춤; admin next.config.mjs, www next build --webpackbuild / verify / admin cf:build 통과완료 시점: 표준화 계획 버전 표·Deploy ADR 참고
B — 공유 패키지packages/contracts: 동일 API/Zod 형태가 두 소비처 이상일 때만 추출(예: UI + Hono)타입/런타임 동작 동일; 스냅샷 또는 테스트현재 lib/schemas/auth는 Hono 한 경로 위주 → 조건 충족 시
C — forms동일 폼 패턴 3회 이상 반복 시 packages/forms 등 검토중복 감소; 번들·의존성 순환 없음표준의 “3+ dupes” 규칙
D — admin 깊은 표면청구·Stripe·결제 등: RHF+Zod는 E2E·회귀와 함께 단계 적용금전 경로 오류 없음; 기존 BFF 계약 유지리스크 맵 §2 참고
E — client-web 배포next-on-pages ↔ OpenNext 수렴 여부 의사결정 기록(Phase 4)ADR 또는 표준화 계획 § 보강; 마이그레이션 시 차이(미들웨어·캐시) 명시 — 실행 전 Deploy ADR Phase 4 migration delta checklist 표로 검증 항목 정리제품·인프라 합의 필요
F — ERP·화면 확장checklist / leaves / expenses 외 추가 ERP 화면을 화면별 PR로 RHF+Zod 정렬화면별 verify·필요 시 E2E도메인은 prego_saas와 계약 정합
G — 선택control-plane Hono 일관성(P6)별 RFC; 웹 표준 블로커 아님

2.1 금지·주의 (기획 준수)

  • 게이트웨이에 도메인 규칙 추가 금지 — Zuplo는 전달·정책만.
  • 공개 라우트·환경 변수 변경 시 런북·핸드오프 문서 동반 갱신.
  • 불확실한 동작 변경 대신 **safe refactor status**에 연기·리스크 기록.

3. 성공 지표 (프로그램 차원)

  • Prego Web App Standard가 웹 티어 작업의 첫 참조로 유지된다.
  • 신규 UI는 표준이 정한 경계에서 Zod를 사용한다.
  • 레거시·비정본 자산은 archive/ 등으로 격리되고 에이전트/문서가 경로를 가리킨다.
  • 공개 HTTP 변경은 OpenAPI 선행 원칙을 깨지 않는다.

4. 관련 문서

문서역할
Prego Web App Standard규범(스택·RHF·배포·패키지 이름)
Web app standardization plan프로그램 우선순위·로드맵·버전 표
Web app safe refactor status감사 스냅샷·§10 변경 이력·§11 백로그
Web app refactoring prompt (Cursor)IDE 보조 리팩터 프롬프트
Deploy convergence ADR (client-web)next-on-pages vs OpenNext — 목표·현재·이전 전제 · Phase 4 migration delta checklist

한국어 한 줄 요약

지금까지: 공유 @platform/web-auth-schemas·세 앱 인증/온보딩 표면 정렬, client/admin E2E·Playwright·ESLint 보강, admin 레거시 HTML 아카이브, client tsconfig/strip 스크립트로 tsc/빌드 안정화, 표준화·상태 문서 갱신이 진행되었다. 앞으로: Next 16 정렬, contracts/forms 조건부 추출, 청구/Stripe, 배포(OpenNext vs Pages) 의사결정, ERP 화면 확장을 단계·PR 단위로 진행하고, 게이트웨이·Zuplo·OpenAPI 순서와 동작 보존 원칙을 유지한다.

Help