taxbaik/ROADMAP_WBS.md

TaxBaik 개선 로드맵 WBS

이 문서는 "완료 보고"가 아니라 검증 가능한 작업 목록이다. 각 WBS는 성공 기준을 통과해야 완료로 본다.

---

완료 판정 원칙

• 코드 변경만으로 완료 처리하지 않는다.
• 서버 배포 대상 기능은 CI/CD 성공과 실제 동작 확인을 요구한다.
• API 기능은 단위 테스트 또는 통합 테스트와 함께 실제 HTTP 호출 결과를 확인한다.
• DB 변경은 마이그레이션과 롤백 위험을 문서화한다.
• 비밀값은 Gitea Secrets 또는 서버 환경변수로만 관리한다.

---

── 홈페이지 · SEO · UX ───────────────────────────

WBS-UX-01 공개 홈페이지 UX/SEO 검증

목표: 공개 홈페이지가 검색 유입과 상담 전환에 맞는 구조인지 검증한다.

성공 기준:

• 홈/블로그 목록/블로그 상세/상담 문의 페이지 200
• 주요 페이지 title/description 존재
• 모바일 viewport에서 주요 CTA가 보인다.
• 상담 문의 제출 Playwright E2E가 통과한다.
• 블로그 상세 SEO 메타 검증이 배포본 기준으로 통과한다.

Todo:

• 공개 페이지 Playwright smoke E2E 추가
• 상담 문의 제출 E2E 추가
• 블로그 상세 SEO 메타 검증 추가

검증 파일:

• tests/e2e/public-smoke.spec.ts
• tests/e2e/blog-seo.spec.ts
• tests/e2e/contact-submit.spec.ts
• tests/e2e/inquiry-detail.spec.ts

WBS-UX-02 홈페이지 FAQ 섹션 (정적)

목표: 방문자가 상담 전 자주 묻는 질문에서 직접 답을 얻고 전환율을 높인다.

성공 기준:

• 홈페이지에 4개 FAQ 아코디언 표시 (기장료, 양도세 상담, 무료 상담, 첫 상담 준비물)
• 아코디언 열림/닫힘 동작
• 모바일에서 가독성 확인

Todo:

• Index.cshtml에 FAQ 아코디언 섹션 추가 (최종 CTA 앞)
• site.css faq-accordion / faq-item / faq-question / faq-answer 스타일
• 배포 완료 (12070b7)
• 배포 후 브라우저 아코디언 동작 확인

WBS-UX-03 FAQ 관리 (어드민 CRUD)

목표: 세무사가 관리자 화면에서 FAQ 항목을 직접 등록·수정·삭제·순서 조정한다. 홈페이지 FAQ가 하드코딩에서 DB 기반으로 전환되어, 코드 수정 없이 운영 가능해진다.

설계 방향:

• FAQ 항목: 질문(question), 답변(answer), 정렬 순서(sort_order), 활성화 여부(is_active)
• 홈페이지는 is_active=TRUE 항목을 sort_order 오름차순으로 표시
• 카테고리 태그(선택): "기장·세금신고", "부동산", "증여·상속", "기타" — 홈페이지에서 탭 필터 가능

성공 기준:

• 관리자 /taxbaik/admin/faqs 목록/생성/수정/삭제/순서변경 동작
• 홈페이지 FAQ 섹션이 DB에서 로드 (하드코딩 제거)
• 비활성 항목은 홈페이지 미표시
• sort_order 기준 정렬

DB 스키마:

• faqs 테이블 (V007 마이그레이션)
  • id SERIAL PK
  • question VARCHAR(300) NOT NULL
  • answer TEXT NOT NULL
  • category VARCHAR(50) — 기장·세금신고, 부동산, 증여·상속, 기타
  • sort_order INT DEFAULT 0
  • is_active BOOLEAN DEFAULT TRUE
  • created_at TIMESTAMPTZ
  • updated_at TIMESTAMPTZ

Todo:

• V007__CreateFaqs.sql 마이그레이션
• Faq 엔티티 (Domain)
• IFaqRepository 인터페이스 (Domain)
• FaqRepository 구현 (Infrastructure) — GetActiveAsync, CRUD
• FaqService 구현 (Application)
• FaqList.razor 관리자 목록 (활성/비활성 토글, sort_order 편집)
• FaqEdit.razor 관리자 등록/수정
• Index.cshtml FAQ 섹션 하드코딩 → DB 로드로 교체
• IndexModel에 ActiveFaqs 프로퍼티 추가
• MainLayout.razor FAQ 관리 메뉴 추가 (홈페이지 그룹 하위)
• 배포 후 관리자에서 FAQ 추가 → 홈페이지 반영 확인

---

── 시즌별 마케팅 ───────────────────────────────

WBS-MKT-01 시즌별 홈페이지 자동 전환

목표: 세무 신고 시즌마다 홈페이지 Hero·CTA·서비스 카드 순서가 자동 변경된다.

성공 기준:

• 7개 시즌(vat-2nd, year-end-settlement, corporate-tax, income-tax, vat-1st, comprehensive-real-estate-tax, year-end-gift) 날짜 판정 정확
• 시즌 중 Hero에 UrgencyBadge 표시
• D-7일 이내 긴박감 메시지 표시
• FocusService 기준 서비스 카드 순서 자동 정렬
• 최종 CTA 시즌 문구 전환

Todo:

• TaxSeason / TaxSeasonCalendar 정의
• CurrentSeasonDto / SeasonalMarketingService 구현
• Index.cshtml Hero 시즌 분기 렌더링
• Index.cshtml 서비스 카드 cardOrder 정렬 로직
• Index.cshtml 최종 CTA 시즌 전환
• CLAUDE.md 섹션 13 세무 캘린더 하네스
• 배포 후 시즌 날짜 경계값 수동 확인

WBS-MKT-02 관리자 공지사항 (Announcement)

목표: 운영자가 홈페이지 최상단 배너를 등록·수정·삭제할 수 있다.

성공 기준:

• 관리자 /taxbaik/admin/announcements 목록/생성/수정/삭제 동작
• is_active=TRUE + 기간 조건(starts_at~ends_at)에 해당하는 공지만 홈페이지에 노출
• 유형(info/banner/urgent) 별 색상 배지 표시
• 홈페이지 최상단 announcement-bar 노출

Todo:

• V005__CreateAnnouncements.sql 마이그레이션
• Announcement 엔티티, IAnnouncementRepository, AnnouncementRepository
• AnnouncementService 구현
• AnnouncementList.razor, AnnouncementEdit.razor 관리자 화면
• Index.cshtml 공지사항 배너 렌더링
• MainLayout.razor 공지사항 메뉴 추가
• 배포 후 공지 등록 → 홈 노출 확인

WBS-MKT-03 블로그 시즌 연동

목표: 시즌 활성 중 홈페이지 블로그 섹션이 시즌 관련 글을 우선 노출한다.

배경: 세무 시즌에 맞는 콘텐츠를 전면에 배치해 상담 전환율과 SEO 체류시간을 높인다.

성공 기준:

• 시즌 중: 해당 카테고리 글 최대 2개(이번 시즌 추천 배지) + 최신 글로 3개 채움
• 평상시: 최신 글 3개 (기존 동작)
• 시즌별 전체 글 보기 버튼 (/taxbaik/blog?category=<slug>)
• 배너 헤더가 시즌명 표시

카테고리 → 시즌 슬러그 매핑:

• vat-2nd / vat-1st → vat
• income-tax → income-tax
• year-end-settlement / corporate-tax → business-tax
• comprehensive-real-estate-tax → real-estate-tax
• year-end-gift → family-asset

Todo:

• TaxSeason.RelatedCategorySlug 추가
• TaxSeasonCalendar 각 시즌에 카테고리 슬러그 매핑
• CurrentSeasonDto.RelatedCategorySlug 추가
• SeasonalMarketingService에 RelatedCategorySlug 전달
• IBlogPostRepository.GetByCategorySlugAsync 추가
• BlogPostRepository.GetByCategorySlugAsync 구현
• BlogService.GetSeasonalPostsAsync 추가
• IndexModel SeasonalPosts/RecentPosts 분리 로드
• Index.cshtml 블로그 섹션 시즌 분기 렌더링
• site.css 블로그 시즌 강조 스타일 추가
• 배포 후 시즌 활성 날짜에 블로그 카드 "이번 시즌 추천" 배지 확인

---

── 운영 인프라 ─────────────────────────────────

WBS-OPS-01 배포 검증 게이트 고도화

목표: curl/API만이 아니라 실제 브라우저 검증까지 통과해야 배포를 성공으로 본다.

성공 기준:

• dotnet build TaxBaik.sln -c Release 경고 0, 오류 0
• dotnet test TaxBaik.sln -c Release --no-build 전체 통과
• CI 배포 후 Playwright가 /taxbaik/admin/login에서 실제 로그인 수행
• 로그인 후 /taxbaik/admin/dashboard 도달
• 브라우저 console error 및 page error 0개

Todo:

• Playwright Test 프로젝트 추가
• 관리자 로그인 E2E 추가
• CI 배포 후 Playwright 실행 단계 추가
• Playwright가 발견한 Blazor DI 결함 수정
• CI run에서 Playwright 전체 통과 확인
• 배포 검증에 블로그 상세/문의/비밀번호 변경 성공 기준 반영 확인

WBS-OPS-02 배포 502 / Nginx 유지보수 페이지

목표: CI 배포 중 502 Bad Gateway 대신 한국어 유지보수 페이지를 제공한다.

성공 기준:

• Nginx error_page 502/503 → maintenance.html 직접 서빙
• 배포 중 방문자는 유지보수 페이지(15초 자동 새로고침)를 본다.
• 배포 완료 후 정상 서비스 복구

Todo:

• maintenance.html 작성
• Nginx error_page 502 503 @taxbaik_maintenance 설정
• 서버 측 헬스 루프 (40회×3초) 단일 SSH 연결로 처리
• CI 배포 단계 헬스 체크 고도화

WBS-OPS-03 관리자 401 수정

목표: 직접 URL 접근 시 관리자 Blazor 페이지가 401로 차단되지 않는다.

성공 기준:

• /taxbaik/admin/announcements 등 직접 접근 시 Blazor Shell 200 응답
• 미인증 사용자는 로그인 페이지로 리다이렉트

Todo:

• MapRazorComponents().AllowAnonymous() 적용
• AuthorizeRouteView → RedirectToLogin 인증 흐름 확인

---

── 인증 · 관리자 ─────────────────────────────────

WBS-AUTH-01 인증/비밀번호 운영 안정화

목표: DB 직접 수정 대신 API로 관리자 인증 운영 작업을 수행한다.

성공 기준:

• 비밀번호 변경 API가 현재 비밀번호를 요구한다.
• 비밀번호 재설정 API는 운영 secret 없이는 동작하지 않는다.
• 실패 응답은 민감 정보를 노출하지 않는다.

Todo:

• 로그인 API 검증
• 비밀번호 변경 API 추가
• 재설정 API 추가
• 관리자 UI에 비밀번호 변경 화면 추가
• 비밀번호 변경 Playwright E2E 추가

WBS-ADMIN-01 관리자 Blazor 안정화

목표: 관리자 화면을 일반 웹페이지처럼 명시적 사용자 액션에만 갱신하고, circuit 예외를 배포 전 차단한다.

성공 기준:

• 관리자 주요 메뉴 대시보드/블로그/문의/설정/공지사항 circuit error 0개
• 저장/삭제/상태 변경 액션은 성공/실패 메시지를 표시한다.

Todo:

• 중복 /admin 라우트 제거
• MudBlazor DI 타입 오류 수정
• 관리자 메뉴 smoke E2E 추가
• 설정 저장 TODO를 실제 DB 기반 기능으로 전환

---

── 고객지원 백오피스 (CRM) ──────────────────────

배경: 세무사 사무실에서 고객 정보와 상담 이력이 파편화(메모장·카톡·기억)되면 마감 누락, 서비스 연속성 단절, 재계약 기회 손실이 발생한다. 30년 경력 세무사가 혼자 또는 소수 인원으로 운영할 때 가장 먼저 필요한 것은 고객 카드와 상담 이력이다.

WBS-CRM-01 고객 카드 (Client Card) — Phase 1

목표: 고객별 기본 정보·서비스 유형·상태를 한 화면에서 관리한다.

성공 기준:

• 관리자 /taxbaik/admin/clients 목록/검색/생성/수정/삭제 동작
• 고객 카드: 이름, 회사명, 연락처, 이메일, 서비스 유형, 세금 유형, 상태, 유입 경로, 메모
• 상태 필터(활성/비활성)로 목록 조회
• 고객 저장 시 updated_at 자동 갱신

DB 스키마:

• clients 테이블 (V006 마이그레이션)
• 컬럼: id, name, company_name, phone, email, service_type, tax_type, status, source, memo, created_at, updated_at

Todo:

• V006__CreateClients.sql 마이그레이션
• Client 엔티티 (Domain)
• IClientRepository 인터페이스 (Domain) — GetPagedAsync 검색+상태 필터
• ClientRepository 구현 (Infrastructure) — ILIKE 검색, 페이징
• ClientService 구현 (Application) — ServiceTypes/TaxTypes/Sources 상수
• ClientList.razor 관리자 목록 화면 — 검색바, 상태 필터, 페이징
• ClientEdit.razor 관리자 등록/수정 화면 — 기본/세무/관리 섹션
• MainLayout.razor 고객 관리 NavGroup 추가
• 배포 후 고객 등록 → 목록 조회 확인

WBS-CRM-02 상담 이력 (Consultation Log) — Phase 1

목표: 고객별 상담 일자·내용·결과·수수료를 기록해 "이 고객 지난번에 뭐 상담했더라?"를 해결한다.

성공 기준:

• 고객 상세에서 상담 이력 목록/추가/삭제 동작
• 상담 이력 필드: 날짜, 서비스 유형, 상담 요약, 결과(계약/보류/거절/완료), 수수료
• 이력 없는 고객은 빈 목록 표시

DB 스키마:

• consultations 테이블 (V007 마이그레이션)
• 컬럼: id, client_id(FK), consultation_date, service_type, summary, result, fee, created_at

Todo:

• V007__CreateConsultations.sql 마이그레이션
• Consultation 엔티티 (Domain)
• IConsultationRepository 인터페이스 (Domain)
• ConsultationRepository 구현 (Infrastructure)
• ConsultationService 구현 (Application)
• ClientDetail.razor (고객 상세 + 상담 이력 탭)
• 배포 후 고객 상세에서 상담 이력 추가 확인

WBS-CRM-03 문의 → 고객 전환 — Phase 1

목표: 홈페이지 문의 접수 건을 클릭 한 번으로 고객 카드로 등록한다.

성공 기준:

• 문의 상세에 "고객으로 등록" 버튼 표시
• 버튼 클릭 시 이름·연락처 자동 채워진 고객 생성 폼으로 이동
• 이미 연결된 고객이 있으면 버튼 대신 고객 카드 링크 표시
• inquiries 테이블에 client_id 컬럼 추가

Todo:

• inquiries 테이블에 client_id FK 컬럼 추가 (V008 마이그레이션)
• InquiryDetail.razor에 "고객으로 등록" 버튼 추가
• ClientEdit.razor에 inquiry_id 파라미터 지원 (자동 채우기)
• 배포 후 문의 → 고객 전환 흐름 확인

---

── 고객지원 백오피스 Phase 2 ──────────────────────

WBS-CRM-04 신고 일정 캘린더 — Phase 2

목표: 고객별 신고 예정일과 마감일을 추적해 가산세 리스크를 방지한다.

성공 기준:

• 관리자에서 고객별 세금 신고 일정 등록/수정/완료 처리
• D-Day 표시 (D-7일 이내 강조)
• 이번 달 마감 목록을 대시보드 위젯으로 표시

DB 스키마:

• tax_filings 테이블 (V009 마이그레이션)
• 컬럼: id, client_id(FK), filing_type, due_date, status(pending/filed/overdue), memo

Todo:

• V009__CreateTaxFilings.sql
• TaxFiling 엔티티, Repository, Service
• TaxFilingList.razor (관리자 신고 일정 화면)
• Dashboard.razor에 이번 달 마감 위젯 추가
• 배포 후 신고 일정 등록 → D-Day 표시 확인

WBS-CRM-05 문의 접수 현황 강화 — Phase 2

목표: 문의 상태를 세분화하고 담당자 메모를 기록해 처리 흐름을 추적한다.

성공 기준:

• 문의 상태: 신규/상담중/계약완료/거절/종결 5단계
• 목록에서 상태 칩 필터로 빠른 분류
• 상태 변경 시 변경 일시 자동 기록

Todo:

• inquiries.status 컬럼 확장 (V010 마이그레이션)
• InquiryList.razor 상태 필터 추가
• InquiryDetail.razor 상태 변경 버튼 추가

---

── 고객지원 백오피스 Phase 3 ──────────────────────

WBS-CRM-06 텔레그램 자동 리포트 — Phase 3

목표: 세무사에게 일/주 단위 신규 문의·처리 현황·마감 임박 건을 텔레그램으로 전송한다.

성공 기준:

• 매일 오전 9시 신규 문의 수, 처리 대기 수 자동 전송
• 매주 월요일 주간 리포트 (신규 고객, 이번 주 마감 신고 건)
• 텔레그램 전송 실패 시 로그만 남기고 앱 정상 운영 유지

Todo:

• BackgroundService 또는 Hangfire 기반 스케줄러 추가
• 일간/주간 리포트 메시지 템플릿
• TelegramNotificationService에 리포트 메서드 추가

WBS-CRM-07 고객 포털 (읽기 전용) — Phase 3

목표: 기장 고객이 본인 신고 현황과 중요 알림을 직접 확인한다.

성공 기준:

• 고객 전용 URL + 인증(소셜 로그인 또는 링크 토큰)
• 본인 신고 일정, 상담 요약(세무사 허용 항목만) 조회
• 개인정보 열람 범위는 세무사가 허용한 항목만

Todo:

• 고객 포털 설계 (인증 방식 결정 — WBS-CRM-08 선행)
• 고객 전용 Razor Pages 추가
• 세무사 허용 권한 설정 UI

WBS-CRM-08 고객 회원가입 · 소셜 로그인 — Phase 3

목표: 고객 포털 접근을 위한 회원가입과 소셜 로그인을 제공한다. 가입 마찰을 최소화해 상담 접수 → 고객 포털 전환율을 높인다.

설계 방향:

• 가입 입력 최소화: 이름 + 연락처(또는 이메일) 2필드면 충분
• 소셜 로그인 우선: 비밀번호 없이 바로 가입
• 기본 계정(이메일/비밀번호) 옵션도 제공 (소셜 없는 사용자 대비)
• 고객 포털 전용 인증 — 관리자(admin_users)와 완전히 분리

지원 소셜 로그인:

• 네이버 (Naver OAuth 2.0) — 국내 주요 채널
• 카카오 (Kakao Login) — 기존 카카오 채널 연계
• 구글 (Google OAuth 2.0) — 해외·젊은 고객층

성공 기준:

• 소셜 로그인 3종 모두 동작 (네이버·카카오·구글)
• 이메일/비밀번호 기본 계정 가입 + 로그인 동작
• 가입 폼: 이름·연락처 2필드만 요구 (소셜 프로필에서 자동 채우기)
• 로그인 후 고객 포털 (/taxbaik/portal) 접근
• 고객 계정이 백오피스 clients 테이블 레코드와 연결
• 회원 계정 미인증 상태에서 포털 접근 시 로그인 페이지 리다이렉트

DB 스키마:

• portal_users 테이블 (V011 마이그레이션)
  • id, client_id(FK, nullable), email, name, phone, provider(naver/kakao/google/local), provider_id, password_hash(nullable), created_at
• 소셜 로그인 provider_id는 각 플랫폼 식별자

기술 결정:

• ASP.NET Core OAuth Middleware (Microsoft.AspNetCore.Authentication.OAuth)
• 네이버: 커스텀 OAuth handler (공식 패키지 없음, 직접 구현)
• 카카오: AspNet.Security.OAuth.Kakao 패키지
• 구글: Microsoft.AspNetCore.Authentication.Google 패키지
• 고객 포털 세션: HttpOnly Cookie 기반 (JWT localStorage와 분리)

환경 변수 필요 (Gitea Secrets 추가):

• NAVER_CLIENT_ID / NAVER_CLIENT_SECRET
• KAKAO_CLIENT_ID / KAKAO_CLIENT_SECRET
• GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET

Todo:

• WBS-CRM-07 고객 포털 기본 구조 완성 (선행)
• OAuth 앱 등록 (네이버·카카오·구글 개발자 콘솔)
• V011__CreatePortalUsers.sql 마이그레이션
• PortalUser 엔티티 / IPortalUserRepository / PortalUserRepository
• 네이버 OAuth Handler 구현
• 카카오·구글 패키지 추가 및 설정
• 기본 계정 회원가입 폼 (/taxbaik/portal/register)
• 소셜 로그인 콜백 처리 → portal_users 자동 생성
• 신규 가입 시 clients 테이블 연결 또는 신규 생성
• 포털 로그인 페이지 (/taxbaik/portal/login) — 소셜 버튼 + 이메일 폼
• Gitea Secrets에 OAuth 키 추가
• 배포 후 소셜 로그인 3종 E2E 테스트

---

── 유지보수성 ─────────────────────────────────

WBS-MAINT-01 유지보수성/파편화 축소

목표: 문서와 실제 구조의 불일치를 줄이고 단일 앱 운영 기준을 유지한다.

Todo:

• README 테스트/배포 섹션 갱신
• CLAUDE.md E2E 기준 갱신
• 오래된 최종 보고 문서의 허위 완료 표현 정정
• CLAUDE.md 섹션 13 시즌별 마케팅 하네스 추가

---

현재 검증 메모

• dotnet build TaxBaik.sln 성공 (2026-06-27 기준, 경고 0 오류 0)
• 배포 커밋: 77a5c44 (FAQ 섹션 추가, 푸시 대기 중)
• WBS-MKT-01/02/03 구현 완료, 배포 후 시각 검증 필요
• WBS-CRM-01 구현 중 (Phase 1 고객 카드)
• WBS-CRM-02/03 Phase 1 구현 예정 (고객 카드 완료 후 순차 진행)