📋 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→getDbSessiongetQuery→ 그대로 사용 (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