344 lines
8.5 KiB
Markdown
344 lines
8.5 KiB
Markdown
# TaxBaik - 세무사 백원숙 전문성 표현 홈페이지
|
|
|
|
**온라인 세무 상담 플랫폼** | 블로그 SEO 최적화 | 전국 고객 확보
|
|
|
|
CI deploy trigger verification note.
|
|
|
|
---
|
|
|
|
## 개요
|
|
|
|
TaxBaik는 세무사 백원숙의 전문성을 온라인으로 표현하기 위해 설계된 풀스택 웹 애플리케이션입니다.
|
|
|
|
### 핵심 포지셔닝
|
|
> "사업자 세금 + 부동산 + 가족자산 = 맞춤형 세무 파트너"
|
|
|
|
### 전문가 자격
|
|
- 세무사 (세무 대리인, 기획세무사)
|
|
- 부동산중개사
|
|
- 보험설계사
|
|
|
|
---
|
|
|
|
## 기술 스택
|
|
|
|
| 계층 | 기술 |
|
|
|-----|------|
|
|
| **백엔드** | 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
|
|
|
|
**설정 단계:**
|
|
|
|
```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
|
|
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 브랜치에 푸시하면 파이프라인이 다음 단계를 수행합니다.
|
|
1. .NET 빌드 (Release)
|
|
2. 단위 테스트 실행
|
|
3. Playwright 브라우저 검증 실행
|
|
4. `TaxBaik.Web` 게시
|
|
5. 원격 서버 배포 디렉토리 업로드 및 `taxbaik_active` 심링크 교체
|
|
6. systemd `taxbaik` 단일 서비스 재시작
|
|
7. `/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](./DEPLOYMENT_GUIDE.md)의 CI 점검 절차를 따릅니다.
|
|
|
|
---
|
|
|
|
## 개발 지침
|
|
|
|
### 코드 컨벤션
|
|
|
|
모든 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 :5001
|
|
|
|
# 프로세스 종료
|
|
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
|
|
|
|
---
|
|
|
|
**최종 상태**: 진행 중
|
|
|
|
완료 판정은 실제 빌드, 테스트, 배포 검증, 브라우저 E2E 통과로만 한다.
|