- 프로젝트 개요 및 포지셔닝 - 기술 스택 및 아키텍처 - 주요 기능 (공개사이트, 관리자) - 빠른 시작 가이드 - 배포 프로세스 (자동/수동) - 개발 지침 (코드 컨벤션) - 문제 해결 (FAQ) - 개발 로그 (W0~W6 완료) 프로젝트 완성! Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,336 @@
|
||||
# TaxBaik - 세무사 백원숙 전문성 표현 홈페이지
|
||||
|
||||
**온라인 세무 상담 플랫폼** | 블로그 SEO 최적화 | 전국 고객 확보
|
||||
|
||||
---
|
||||
|
||||
## 개요
|
||||
|
||||
TaxBaik는 세무사 백원숙의 전문성을 온라인으로 표현하기 위해 설계된 풀스택 웹 애플리케이션입니다.
|
||||
|
||||
### 핵심 포지셔닝
|
||||
> "사업자 세금 + 부동산 + 가족자산 = 맞춤형 세무 파트너"
|
||||
|
||||
### 전문가 자격
|
||||
- 세무사 (세무 대리인, 기획세무사)
|
||||
- 부동산중개사
|
||||
- 보험설계사
|
||||
|
||||
---
|
||||
|
||||
## 기술 스택
|
||||
|
||||
| 계층 | 기술 |
|
||||
|-----|------|
|
||||
| **백엔드** | ASP.NET Core 8, 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)
|
||||
├── TaxBaik.Admin/ # Blazor Server 관리자 (port 5002)
|
||||
├── db/migrations/ # 데이터베이스 마이그레이션 SQL
|
||||
├── deploy/ # systemd 서비스 파일, Nginx 설정
|
||||
└── .gitea/workflows/ # CI/CD 파이프라인
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 주요 기능
|
||||
|
||||
### 공개 사이트 (TaxBaik.Web)
|
||||
|
||||
- **SEO 최적화 블로그** (5개 카테고리)
|
||||
- 사업자 세무
|
||||
- 부동산 세금
|
||||
- 종합소득세
|
||||
- 부가가치세
|
||||
- 가족자산·증여
|
||||
|
||||
- **온라인 상담 폼**
|
||||
- 이름, 연락처, 이메일
|
||||
- 상담 분야 선택
|
||||
- 문의 내용
|
||||
|
||||
- **반응형 디자인**
|
||||
- 모바일 우선 (375px+)
|
||||
- 데스크톱 최적화
|
||||
- 접근성 고려
|
||||
|
||||
- **성능 최적화**
|
||||
- gzip 압축
|
||||
- 이미지 lazy load
|
||||
- CSS/JS 최적화
|
||||
|
||||
### 관리자 백오피스 (TaxBaik.Admin)
|
||||
|
||||
- **대시보드**
|
||||
- 이번달 문의 수
|
||||
- 신규 문의 수
|
||||
- 포스트 통계
|
||||
|
||||
- **블로그 관리**
|
||||
- CRUD 기능
|
||||
- 카테고리 관리
|
||||
- SEO 메타데이터
|
||||
- 발행/임시저장
|
||||
|
||||
- **문의 관리**
|
||||
- 문의 목록
|
||||
- 상태 변경 (신규 → 연락함 → 완료)
|
||||
- 상세 보기
|
||||
|
||||
- **사이트 설정**
|
||||
- 연락처 정보
|
||||
- 소셜 미디어 링크
|
||||
|
||||
---
|
||||
|
||||
## 빠른 시작
|
||||
|
||||
### 개발 환경 설정
|
||||
|
||||
**필수 요구사항:**
|
||||
- .NET 8.0 SDK
|
||||
- PostgreSQL 18.4
|
||||
- Git
|
||||
|
||||
**설정 단계:**
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
# 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:5002/taxbaik/admin
|
||||
```
|
||||
|
||||
### 초기 로그인 정보
|
||||
|
||||
- **username**: `admin`
|
||||
- **password**: `admin123`
|
||||
|
||||
> ⚠️ **중요**: 프로덕션 배포 시 비밀번호 변경 필수
|
||||
|
||||
---
|
||||
|
||||
## 배포
|
||||
|
||||
### 자동 배포 (Gitea Actions)
|
||||
|
||||
master 브랜치에 푸시하면 자동으로:
|
||||
1. ✅ .NET 빌드 (Release)
|
||||
2. ✅ 단위 테스트 실행
|
||||
3. ✅ Web & Admin 게시
|
||||
4. ✅ 서버에 rsync로 업로드
|
||||
5. ✅ 심링크 스왑 (무중단 배포)
|
||||
6. ✅ 서비스 재시작
|
||||
|
||||
**필수 Gitea Secrets 설정:**
|
||||
- `DEPLOY_USER`: kjh2064
|
||||
- `DEPLOY_HOST`: 178.104.200.7
|
||||
- `DEPLOY_SSH_KEY`: SSH 개인키 (줄바꿈 포함)
|
||||
|
||||
### 수동 배포
|
||||
|
||||
[DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md) 참고
|
||||
|
||||
---
|
||||
|
||||
## 개발 지침
|
||||
|
||||
### 코드 컨벤션
|
||||
|
||||
모든 UI 문자열은 **한국어**로 작성합니다.
|
||||
|
||||
```csharp
|
||||
// ✅ Good
|
||||
public async Task<bool> SaveAsync() { ... }
|
||||
var message = "저장되었습니다.";
|
||||
|
||||
// ❌ Bad
|
||||
public bool Save() { ... }
|
||||
var message = "Saved";
|
||||
```
|
||||
|
||||
### SQL 쿼리 (Dapper)
|
||||
|
||||
```csharp
|
||||
// ✅ 파라미터화된 쿼리 (안전)
|
||||
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 패턴
|
||||
|
||||
```csharp
|
||||
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>(...);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 마이그레이션
|
||||
|
||||
```sql
|
||||
-- db/migrations/V004__AddNewColumn.sql
|
||||
ALTER TABLE blog_posts ADD COLUMN status VARCHAR(50) DEFAULT 'draft';
|
||||
```
|
||||
|
||||
마이그레이션은 자동으로 시작시 실행됩니다.
|
||||
|
||||
---
|
||||
|
||||
## 문제 해결
|
||||
|
||||
### 마이그레이션 오류
|
||||
|
||||
```bash
|
||||
# 마이그레이션 테이블 확인
|
||||
SELECT * FROM schema_migrations;
|
||||
|
||||
# 실패한 마이그레이션 롤백 (수동 실행 필요)
|
||||
psql -U taxbaik -d taxbaikdb -c "DELETE FROM schema_migrations WHERE version='004';"
|
||||
```
|
||||
|
||||
### 포트 충돌
|
||||
|
||||
```bash
|
||||
# 포트 확인
|
||||
lsof -i :5001
|
||||
lsof -i :5002
|
||||
|
||||
# 프로세스 종료
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
### 데이터베이스 연결
|
||||
|
||||
```bash
|
||||
# 연결 테스트
|
||||
psql -U taxbaik -d taxbaikdb -c "SELECT 1;"
|
||||
|
||||
# 환경 변수 확인
|
||||
echo $ConnectionStrings__Default
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 문서
|
||||
|
||||
- [CLAUDE.md](./CLAUDE.md) - LLM 개발 지침 (9개 섹션)
|
||||
- [DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md) - 배포 완전 가이드
|
||||
- [SERVER_SETUP.sh](./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
|
||||
|
||||
---
|
||||
|
||||
**최종 상태**: ✅ **프로덕션 준비 완료**
|
||||
|
||||
모든 커밋이 한국어로 작성되었으며, Gitea에 업로드된 상태입니다.
|
||||
Reference in New Issue
Block a user