weeklyreport/README.md

# 📋 Weekly Report System

SI 프로젝트 팀을 위한 주간업무보고 작성 및 취합 시스템입니다.

## ✨ 주요 기능

### 📝 주간보고 작성
- 프로젝트별 금주 실적 / 차주 계획 작성
- Task 단위로 작업 내용, 시간, 완료 여부 관리
- 이슈/리스크, 휴가일정, 기타사항 입력
- 작성 → 제출 → 취합 워크플로우
- **이전 주 계획 → 이번 주 실적 자동 불러오기**
- **미래 주차 작성 차단** (URL 직접 접근 방지)

### 🤖 AI 기능
- **AI 자동채우기**: 텍스트/이미지 → 프로젝트별 실적/계획 자동 분류
  - 드래그앤드롭, 파일선택, **Ctrl+V 붙여넣기** 지원
  - OpenAI GPT-4o 기반 프로젝트 자동 매칭
- **PMO AI 리뷰**: 주간보고 품질 평가 (3단계 등급: 우수/적합/미흡)
- **관리자 일괄등록**: 여러 직원의 주간보고 일괄 파싱 및 등록

### 📊 취합 보고서
- 주차별 전체 보고서 취합
- 프로젝트별 실적/계획 AI 요약 (OpenAI)
- 인원별 투입 시간 현황
- 원문 보기 기능

### 🔐 인증 시스템
- **DB 기반 세션 관리** (Spring Session JDBC 방식)
- 세션 타임아웃: 10분 (Sliding Expiration)
- 로그인 이력 관리 (IP, 접속시간, 세션상태)
- 세션 상태: 접속중 / 활성 / 세션만료 / 로그아웃

### 👥 직원/프로젝트 관리
- 직원 등록 및 관리
- 프로젝트 생성 및 상태 관리
- 프로젝트별 투입 인력 현황

## 🛠 기술 스택

| 구분 | 기술 |
|------|------|
| Frontend | Vue 3, Nuxt 3 |
| Backend | Nitro (Nuxt Server) |
| Database | PostgreSQL |
| AI | OpenAI GPT-4o / GPT-4o-mini |
| UI | Bootstrap 5, Bootstrap Icons |
| Session | DB 기반 세션 (wr_session 테이블) |

## 📁 프로젝트 구조

```
weeklyreport/
├── frontend/                 # 프론트엔드 페이지
│   ├── components/          # 공통 컴포넌트
│   ├── composables/         # Vue Composables
│   ├── admin/               # 관리자 전용
│   │   └── bulk-import.vue  # AI 일괄 등록
│   ├── report/              # 주간보고 관련
│   │   ├── weekly/          # 개인 주간보고
│   │   └── summary/         # 취합 보고서
│   ├── employee/            # 직원 관리
│   ├── project/             # 프로젝트 관리
│   └── mypage/              # 마이페이지
├── backend/
│   ├── api/                 # API 엔드포인트
│   │   ├── auth/            # 인증
│   │   ├── admin/           # 관리자 API
│   │   ├── ai/              # AI API
│   │   ├── employee/        # 직원 API
│   │   ├── project/         # 프로젝트 API
│   │   └── report/          # 보고서 API
│   ├── utils/               # 유틸리티
│   │   ├── db.ts            # DB 연결
│   │   ├── session.ts       # 세션 관리
│   │   └── ip.ts            # IP 추출
│   └── sql/                 # DDL 스크립트
├── claude_temp/             # Claude 작업용 임시 파일
├── nuxt.config.ts           # Nuxt 설정
└── package.json
```

## 🗄 데이터베이스 스키마

### 주요 테이블

| 테이블명 | 설명 |
|----------|------|
| `wr_employee_info` | 직원 정보 |
| `wr_project_info` | 프로젝트 정보 |
| `wr_weekly_report` | 주간보고 마스터 |
| `wr_weekly_report_task` | 주간보고 Task (실적/계획) |
| `wr_aggregated_report_summary` | 취합 보고서 |
| `wr_session` | DB 세션 (인증) |
| `wr_login_history` | 로그인 이력 |

### 세션 테이블 (wr_session)

```sql
CREATE TABLE wr_session (
    session_id VARCHAR(64) PRIMARY KEY,  -- 랜덤 토큰 (64자 hex)
    employee_id INTEGER NOT NULL,
    login_history_id INTEGER,
    created_at TIMESTAMP DEFAULT NOW(),
    last_access_at TIMESTAMP DEFAULT NOW(),
    expires_at TIMESTAMP NOT NULL,       -- 10분 후 만료
    login_ip VARCHAR(45),
    user_agent TEXT
);
```

## 🔗 메뉴 구조

| 메뉴 | 경로 | 설명 | 권한 |
|------|------|------|------|
| 로그인 | `/login` | 로그인 페이지 | 전체 |
| 대시보드 | `/` | 대시보드 | 로그인 |
| **주간보고** | | | |
| ├ 목록 | `/report/weekly` | 주간보고 목록 | 로그인 |
| ├ 작성 | `/report/weekly/write` | 주간보고 작성 | 로그인 |
| └ 상세/수정 | `/report/weekly/[id]` | 주간보고 상세보기/수정 | 로그인 |
| **취합보고서** | `/report/summary` | 취합 보고서 | 로그인 |
| **관리자** | | | 관리자 |
| ├ 일괄등록 | `/admin/bulk-import` | AI 기반 일괄 등록 | 관리자 |
| ├ 직원관리 | `/employee` | 직원 관리 | 관리자 |
| └ 프로젝트관리 | `/project` | 프로젝트 관리 | 관리자 |
| **마이페이지** | `/mypage` | 내 정보, 로그인 이력 | 로그인 |
| **피드백** | `/feedback` | 개선의견 | 로그인 |

## 🚀 설치 및 실행

### 요구사항
- Node.js 18+
- PostgreSQL 14+
- OpenAI API Key

### 환경 변수 (.env)
```env
DB_HOST=localhost
DB_PORT=5432
DB_NAME=weeklyreport
DB_USER=weeklyreport
DB_PASSWORD=xxx
OPENAI_API_KEY=sk-xxx
```

### 설치
```bash
npm install
```

### 개발 서버 실행
```bash
npm run dev
# http://localhost:2026
```

### 프로덕션 빌드
```bash
npm run build
npm run preview
```

### Docker 빌드
```bash
docker build -t weeklyreport:latest .
```

## 📡 주요 API

### 인증
| Method | Endpoint | 설명 |
|--------|----------|------|
| POST | `/api/auth/login` | 이메일+이름 로그인 |
| POST | `/api/auth/select-user` | 최근 사용자 선택 로그인 |
| POST | `/api/auth/logout` | 로그아웃 |
| GET | `/api/auth/current-user` | 현재 사용자 (세션 갱신) |
| GET | `/api/auth/me` | 사용자 상세 정보 |
| GET | `/api/auth/login-history` | 로그인 이력 |

### AI
| Method | Endpoint | 설명 |
|--------|----------|------|
| POST | `/api/ai/parse-my-report` | 텍스트 → 주간보고 파싱 |
| POST | `/api/ai/parse-my-report-image` | 이미지 → 주간보고 파싱 |
| POST | `/api/admin/parse-report` | 관리자 일괄 텍스트 파싱 |
| POST | `/api/admin/parse-image` | 관리자 일괄 이미지 파싱 |
| POST | `/api/admin/bulk-register` | 일괄 등록 |

### 주간보고
| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/api/report/weekly/list` | 주간보고 목록 |
| POST | `/api/report/weekly/create` | 주간보고 생성 |
| PUT | `/api/report/weekly/[id]/update` | 주간보고 수정 |
| POST | `/api/report/weekly/[id]/submit` | 주간보고 제출 |
| DELETE | `/api/report/weekly/[id]/delete` | 주간보고 삭제 |
| POST | `/api/report/review` | PMO AI 리뷰 요청 |

---

## 🤝 Claude 협업 가이드

이 프로젝트는 Claude AI와 협업하여 개발됩니다. 다음 사항을 숙지해주세요.

### ⚠️ 필수 준수사항

#### 1. Git 커밋 규칙
```
❌ Claude가 임의로 커밋/푸시하지 않음
✅ 사용자가 명시적으로 요청할 때만 커밋
```

#### 2. 임시 파일 관리
```
프로젝트 루트에 임시 파일 생성 금지
모든 임시 파일은 claude_temp/ 디렉토리에 저장
  - 마이그레이션 스크립트
  - 테스트 스크립트
  - 배치 파일 등
```

#### 3. 함수명 충돌 주의
```typescript
// ❌ h3 프레임워크와 충돌
export function getSession() { }

// ✅ 접두어로 구분
export function getDbSession() { }
```

Nuxt/h3 프레임워크에서 자동 import하는 함수명 주의:
- `getSession` → `getDbSession`
- `getQuery` → 그대로 사용 (h3 것 사용)
- `getCookie` → 그대로 사용 (h3 것 사용)

#### 4. 한글 커밋 메시지
```bash
# Windows CMD에서 한글 깨짐 발생
# 배치 파일 사용 시 영문 메시지 권장
git commit -m "feat: add session management"
```

### 📋 개발 컨벤션

#### API 응답 형식
```typescript
// 성공
return { success: true, data: ... }

// 목록
return { reports: [...], total: 100 }

// 에러
throw createError({ statusCode: 400, message: '에러 메시지' })
```

#### 인증 처리
```typescript
import { requireAuth, getAuthenticatedUserId } from '../../utils/session'

// 필수 인증 (미인증 시 401 에러)
const userId = await requireAuth(event)

// 선택 인증 (미인증 시 null)
const userId = await getAuthenticatedUserId(event)
```

#### 날짜/주차 계산
```typescript
// useWeekCalc composable 사용
const { getWeekInfo, getWeekDates, getActualCurrentWeekInfo } = useWeekCalc()

// ISO 8601 주차 기준 (월요일 시작)
```

### 🔧 자주 발생하는 이슈

| 이슈 | 원인 | 해결 |
|------|------|------|
| `npm ci` 실패 | package-lock.json 불일치 | `npm install` 후 lock 파일 커밋 |
| 세션 만료 안됨 | expires_at 비교 누락 | `expires_at > NOW()` 조건 확인 |
| 미래 주차 접근 | URL 직접 입력 | onMounted에서 주차 검증 |
| 함수명 충돌 경고 | h3 auto-import | 함수명 변경 (접두어 추가) |

### 📂 주요 파일 위치

| 기능 | 파일 |
|------|------|
| 세션 관리 | `backend/utils/session.ts` |
| DB 연결 | `backend/utils/db.ts` |
| 주차 계산 | `frontend/composables/useWeekCalc.ts` |
| 인증 상태 | `frontend/composables/useAuth.ts` |
| 헤더 컴포넌트 | `frontend/components/AppHeader.vue` |

---

## 📄 라이선스

Private - 터보소프트 내부용

---

© 2026 TurboSoft