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)

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)

DB_HOST=localhost
DB_PORT=5432
DB_NAME=weeklyreport
DB_USER=weeklyreport
DB_PASSWORD=xxx
OPENAI_API_KEY=sk-xxx

설치

npm install

개발 서버 실행

npm run dev
# http://localhost:2026

프로덕션 빌드

npm run build
npm run preview

Docker 빌드

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. 함수명 충돌 주의

// ❌ h3 프레임워크와 충돌
export function getSession() { }

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

Nuxt/h3 프레임워크에서 자동 import하는 함수명 주의:

• getSession → getDbSession
• getQuery → 그대로 사용 (h3 것 사용)
• getCookie → 그대로 사용 (h3 것 사용)

4. 한글 커밋 메시지

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

📋 개발 컨벤션

API 응답 형식

// 성공
return { success: true, data: ... }

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

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

인증 처리

import { requireAuth, getAuthenticatedUserId } from '../../utils/session'

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

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

날짜/주차 계산

// 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