계층	기술
백엔드	ASP.NET Core 10, C#
공개 사이트	Razor Pages (SSR)
관리자	Blazor Server + MudBlazor
데이터베이스	PostgreSQL 18.4
ORM	Dapper
리버스 프록시	Nginx
배포	Gitea Actions CI/CD, systemd 단일 서비스
아키텍처	DDD (Domain-Driven Design), Layered Architecture

프로젝트 구조

TaxBaik/
├── TaxBaik.Domain/           # 비즈니스 규칙, 엔티티, 인터페이스
├── TaxBaik.Infrastructure/   # DB 접근, Dapper 구현체, 마이그레이션
├── TaxBaik.Application/      # 서비스, DTO, 비즈니스 워크플로우
├── TaxBaik.Web/              # Razor Pages + 관리자 통합 앱 (port 5001)
├── db/migrations/            # 데이터베이스 마이그레이션 SQL
├── deploy/                   # systemd 서비스 파일, Nginx 설정
└── .gitea/workflows/         # CI/CD 파이프라인

주요 기능

공개 사이트 (TaxBaik.Web)

SEO 최적화 블로그 (5개 카테고리)
- 사업자 세무
- 부동산 세금
- 종합소득세
- 부가가치세
- 가족자산·증여
온라인 상담 폼
- 이름, 연락처, 이메일
- 상담 분야 선택
- 문의 내용
반응형 디자인
- 모바일 우선 (375px+)
- 데스크톱 최적화
- 접근성 고려
성능 최적화
- gzip 압축
- 이미지 lazy load
- CSS/JS 최적화

관리자 백오피스 (TaxBaik.Web 내 Blazor Server)

대시보드
- 이번달 문의 수
- 신규 문의 수
- 포스트 통계
블로그 관리
- CRUD 기능
- 카테고리 관리
- SEO 메타데이터
- 발행/임시저장
문의 관리
- 문의 목록
- 상태 변경 (신규 → 연락함 → 완료)
- 상세 보기
사이트 설정
- 연락처 정보
- 소셜 미디어 링크

빠른 시작

개발 환경 설정

필수 요구사항:

.NET 10.0 SDK
PostgreSQL 18.4
Git

설정 단계:

# 1. 저장소 클론
git clone http://178.104.200.7/kjh2064/taxbaik.git
cd taxbaik

# 2. 데이터베이스 생성
createdb taxbaikdb
psql -d taxbaikdb -f db/migrations/V001__InitialSchema.sql
psql -d taxbaikdb -f db/migrations/V002__SeedData.sql
psql -d taxbaikdb -f db/migrations/V003__SeedAdminAndBlogPosts.sql
psql -d taxbaikdb -f db/migrations/V004__CreateSiteSettings.sql

# 3. 환경 변수 설정
export ConnectionStrings__Default="Host=localhost;Database=taxbaikdb;Username=postgres;Password=password"

# 4. 빌드 및 실행
dotnet build TaxBaik.sln
dotnet run --project TaxBaik.Web

# 5. 브라우저 열기
# 공개 사이트: http://localhost:5001/taxbaik
# 관리자: http://localhost:5001/taxbaik/admin/login

초기 로그인 정보

username: admin
password: <TAXBAIK_ADMIN_TEST_PASSWORD> or current rotated admin password

⚠️ 중요: 프로덕션 배포 시 비밀번호 변경 필수이며, 검증용 비밀번호는 Gitea Secrets로 관리

배포

배포 방식

배포는 Gitea Actions CI/CD만 사용합니다.

master 브랜치에 푸시하면 파이프라인이 다음 단계를 수행합니다.

.NET 빌드 (Release)
단위 테스트 실행
Playwright 브라우저 검증 실행
TaxBaik.Web 게시
원격 서버 배포 디렉토리 업로드 및 taxbaik_active 심링크 교체
systemd taxbaik 단일 서비스 재시작
/taxbaik/, /taxbaik/admin/login, /taxbaik/blog/{slug}, /taxbaik/api/auth/login 검증

배포 완료 판정은 위 단계가 모두 성공하고, 배포본 기준 Playwright E2E가 통과했을 때만 한다.

필수 Gitea Secrets 설정:

DEPLOY_USER: kjh2064
DEPLOY_HOST: 178.104.200.7
DEPLOY_SSH_KEY_B64: base64로 인코딩한 SSH 개인키
TAXBAIK_ADMIN_TEST_PASSWORD: 배포 검증용 관리자 비밀번호
Admin__PasswordResetToken: 관리자 비밀번호 재설정 API용 서버 비밀값

수동 배포는 비상 롤백 절차 외에는 사용하지 않습니다. 실패 시 DEPLOYMENT_GUIDE.md의 CI 점검 절차를 따릅니다.

개발 지침

코드 컨벤션

모든 UI 문자열은 한국어로 작성합니다.

// ✅ Good
public async Task<bool> SaveAsync() { ... }
var message = "저장되었습니다.";

// ❌ Bad
public bool Save() { ... }
var message = "Saved";

SQL 쿼리 (Dapper)

// ✅ 파라미터화된 쿼리 (안전)
await conn.QueryAsync<BlogPost>(
    "SELECT * FROM blog_posts WHERE id = @Id",
    new { Id = id });

// ❌ 문자열 연결 금지 (SQL injection)
var sql = "SELECT * FROM blog_posts WHERE id = " + id;

Repository 패턴

public interface IBlogPostRepository
{
    Task<BlogPost?> GetByIdAsync(int id);
    Task<IEnumerable<BlogPost>> GetPublishedAsync();
    // ...
}

public class BlogPostRepository : IBlogPostRepository
{
    private readonly IDbConnectionFactory _connectionFactory;
    
    public async Task<BlogPost?> GetByIdAsync(int id)
    {
        using var conn = _connectionFactory.CreateConnection();
        return await conn.QueryFirstOrDefaultAsync<BlogPost>(...);
    }
}

마이그레이션

-- db/migrations/V004__AddNewColumn.sql
ALTER TABLE blog_posts ADD COLUMN status VARCHAR(50) DEFAULT 'draft';

마이그레이션은 자동으로 시작시 실행됩니다.

문제 해결

마이그레이션 오류

# 마이그레이션 테이블 확인
SELECT * FROM schema_migrations;

# 실패한 마이그레이션 롤백 (수동 실행 필요)
psql -U taxbaik -d taxbaikdb -c "DELETE FROM schema_migrations WHERE version='004';"

포트 충돌

# 포트 확인
lsof -i :5001
lsof -i :5001

# 프로세스 종료
kill -9 <PID>

데이터베이스 연결

# 연결 테스트
psql -U taxbaik -d taxbaikdb -c "SELECT 1;"

# 환경 변수 확인
echo $ConnectionStrings__Default

문서

CLAUDE.md - LLM 개발 지침 (9개 섹션)
DEPLOYMENT_GUIDE.md - 배포 완전 가이드
SERVER_SETUP.sh - 서버 자동 설치 스크립트

연락처

전화: 010-4122-8268
이메일: taxbaik5668@gmail.com
카카오 채널: http://pf.kakao.com/_xoxchTX
인스타그램: https://www.instagram.com/taxtory5668/

라이선스

내부 사용 전용

개발 로그

W0 - 프로젝트 기반 구축

✅ Visual Studio 솔루션 + 5개 프로젝트 생성
✅ Git 초기화 및 Gitea 저장소 연결
✅ PostgreSQL 스키마 + 마이그레이션 파일
✅ Nginx 리버스 프록시 설정

W1 - LLM 개발 지침

✅ CLAUDE.md 작성 (9개 섹션, 500+ 라인)

W2 - Domain/Infrastructure/Application

✅ 엔티티: BlogPost, Category, Inquiry, AdminUser
✅ Dapper Repository 패턴 구현
✅ 서비스 레이어 (BlogService, InquiryService)
✅ DTO 및 예외 처리

W3 - 공개 홈페이지 (Razor Pages SSR)

✅ 레이아웃 및 네비게이션
✅ 메인 랜딩 페이지
✅ 블로그 (목록 + 상세)
✅ 문의 폼 (유효성 검증)
✅ SEO 최적화 (메타 태그, sitemap.xml)
✅ robots.txt

W4 - 관리자 백오피스 (Blazor Server + MudBlazor)

✅ 인증 (Cookie 기반, 8시간 세션)
✅ 대시보드 (KPI 카드)
✅ 블로그 CRUD
✅ 문의 관리
✅ 사이트 설정

W5 - 스타일링 & 모바일 UX

✅ CSS 디자인 시스템 (색상, 스페이싱, 전환)
✅ 모바일 반응형 (375px 초소형 화면까지)
✅ 성능 최적화 (gzip, lazy load, 폰트 preconnect)

W6 - 출시 준비

✅ 자동 DB 마이그레이션 (MigrationRunner)
✅ 초기 데이터 (관리자 + 블로그 5개 포스트)
✅ E2E 테스트 절차
✅ 배포 가이드
✅ 서버 자동 설치 스크립트
✅ Gitea Actions CI/CD

최종 상태: 진행 중

완료 판정은 실제 빌드, 테스트, 배포 검증, 브라우저 E2E 통과로만 한다.

Languages

C# 46.4%

HTML 38.9%

CSS 7%

TypeScript 4.9%

JavaScript 1.9%

Other 0.9%