1. 기술 스택 및 환경 설정

환경 설정

# 의존성 설치
npm install

# 로컬 개발 서버
npm run build && npm run dev:sandbox

# 프로덕션 배포
npm run deploy

2. 프로젝트 디렉터리 구조

webapp/
├── src/
│   ├── index.tsx          # 메인 라우터 (Hono 앱)
│   ├── types.ts           # TypeScript 타입 정의
│   ├── routes/
│   │   ├── api.ts         # 공개 API 라우트
│   │   └── admin.ts       # 관리자 API (CRUD)
│   ├── templates/
│   │   ├── home.tsx       # 홈 페이지 (카테고리 요약)
│   │   ├── pages.tsx      # 평가현황/공지/FAQ/문의 페이지
│   │   ├── layout.tsx     # 공통 레이아웃 (GNB, 푸터)
│   │   └── admin/
│   │       └── index.tsx  # 관리자 대시보드 레이아웃
│   ├── middleware/
│   │   └── auth.ts        # JWT 인증 미들웨어
│   └── utils/
│       ├── db.ts          # DB 유틸리티 (getSettings)
│       └── crypto.ts      # 암호화 유틸리티
├── public/
│   └── static/
│       ├── js/
│       │   └── admin-progress.js  # 관리자 평가현황 CRUD JS
│       └── docs/
│           ├── architecture-diagram.html
│           └── development-guide.html
├── migrations/
│   ├── 0001_initial_schema.sql
│   ├── 0002_about_pages.sql
│   ├── 0003_progress_schema_upgrade.sql
│   └── 0004_images_and_bg_settings.sql
├── seed.sql               # 기본 시드 데이터
├── seed-progress-v2.sql   # 10개 사업 평가현황 시드
├── wrangler.jsonc         # Cloudflare 설정
├── vite.config.ts         # Vite 빌드 설정
└── package.json

3. 10개 사업 카테고리 정의

4. 데이터베이스 마이그레이션

마이그레이션 적용 순서

# 로컬 개발
npx wrangler d1 migrations apply koist-website-db --local
npx wrangler d1 execute koist-website-db --local --file=./seed-progress-v2.sql

# 프로덕션
npx wrangler d1 migrations apply koist-website-db --remote
npx wrangler d1 execute koist-website-db --remote --file=./seed-progress-v2.sql

5. 백엔드 API 개발 가이드

새 카테고리 추가 시

1. pages.tsx의 CATEGORY_META에 카테고리 추가
2. home.tsx의 catMeta에 동일 항목 추가
3. admin-progress.js의 CATEGORIES에 동적 폼 필드 추가
4. 시드 데이터 SQL에 해당 카테고리 데이터 추가

API 응답 형식

// 성공
{ "success": true, "data": [...] }

// 에러
{ "error": "에러 메시지" }

6. 프론트엔드 개발 가이드

평가현황 페이지 구조

1. 카테고리 탭 바: 전체 + 10개 사업, 각 사업별 건수 표시
2. 검색/필터 바: 제품명 검색 + 상태(접수/진행/완료) 필터
3. 데이터 테이블: 카테고리별 동적 컬럼 헤더 변경
4. 페이지네이션: 15건 단위, 첫/이전/숫자/다음/끝 내비게이션

홈페이지 평가현황 위젯

카테고리별 요약 카드 (건수) + 최근 5건 테이블로 구성. 각 카드 클릭 시 해당 카테고리 상세로 이동.

7. 관리자 페이지 개발 가이드

admin-progress.js 구조

1. 카테고리 요약 카드: 전체 + 10개 사업별 건수 (클릭으로 필터링)
2. 동적 폼: 사업 분류 선택 시 등급/구분/유형 옵션이 자동 변경
3. CRUD 테이블: 인라인 수정/삭제, 카테고리별 필터링

8. 배포 절차

# 1. 빌드
npm run build

# 2. (최초 또는 스키마 변경 시) 마이그레이션
npx wrangler d1 migrations apply koist-website-db --remote

# 3. (최초 또는 데이터 변경 시) 시드 데이터
npx wrangler d1 execute koist-website-db --remote --file=./seed-progress-v2.sql

# 4. 배포
npx wrangler pages deploy dist --project-name koist-website

# 5. 확인
curl https://koist-website.pages.dev/support/progress

9. 테스트 체크리스트

10. 운영 및 유지보수

일상 운영

• 관리자 로그인: /admin (기본 계정: admin / admin1234)
• 평가현황 관리: /admin/progress 에서 사업별 입력/수정/삭제
• 사이트 설정: /admin/site-settings 에서 전화번호, 슬로건 등 변경

문제 해결

• 500 에러: DB 마이그레이션 미적용 확인 (no such table 오류)
• 빈 데이터: 시드 데이터 적용 여부 확인
• 로그인 실패: 기본 admin 계정 생성 → /api/init-db 호출