그룹웨어 캘린더 시스템

사용자 매뉴얼 및 관리자 가이드

버전: 1.0

작성일: 2025년 6월

Toast UI Calendar 기반 그누보드 연동

📋 목차

1. 시스템 개요

1.1 소개

그룹웨어 캘린더 시스템은 Toast UI Calendar를 기반으로 한 웹 기반 일정 관리 도구입니다. 그누보드 회원 시스템과 완전히 연동되어 개인별 일정 관리가 가능합니다.

📌 현재 버전 정보
• Toast UI Calendar: v1.15.3
• 그누보드: v5.x 이상 호환
• PHP: 7.4 이상 권장
• MySQL: 5.7 이상 권장

1.2 주요 특징

🗓️ 다양한 뷰

월간, 주간, 일간 보기를 지원하여 원하는 형태로 일정을 확인할 수 있습니다.

👥 개인별 관리

그누보드 회원 시스템과 연동되어 개인별 일정이 안전하게 관리됩니다.

🎨 직관적 UI

Toast UI Calendar의 세련된 인터페이스로 쉽고 편리한 일정 관리가 가능합니다.

📱 반응형 디자인

PC, 태블릿, 모바일 등 다양한 기기에서 최적화된 화면을 제공합니다.

1.3 시스템 요구사항

구분 최소 요구사항 권장 사항
웹서버 Apache 2.2+ / Nginx 1.8+ Apache 2.4+ / Nginx 1.14+
PHP PHP 7.2+ PHP 7.4+ / PHP 8.0+
데이터베이스 MySQL 5.6+ / MariaDB 10.0+ MySQL 5.7+ / MariaDB 10.3+
그누보드 5.4+ 5.5+

2. 설치 및 초기 설정

2.1 파일 업로드

1

캘린더 폴더 생성

그누보드 루트 디렉토리에 calendar 폴더를 생성합니다.

그누보드 루트/ ├── admin/ ├── bbs/ ├── calendar/ ← 새로 생성 ├── css/ └── ...
2

필수 파일 업로드

다음 파일들을 calendar 폴더에 업로드합니다:

  • index.php - 메인 캘린더 화면
  • _common.php - 공통 설정 파일
  • install.php - 테이블 설치 스크립트
  • api_events.php - 일정 조회 API
  • api_event_create.php - 일정 생성 API

2.2 데이터베이스 설정

3

테이블 설치 실행

웹 브라우저에서 다음 URL에 접속하여 테이블을 생성합니다:

http://도메인/calendar/install.php
⚠️ 주의사항
install.php는 관리자 권한으로만 실행 가능합니다. 관리자로 로그인한 후 실행하세요.
4

테이블 구조 확인

설치가 완료되면 다음과 같은 테이블이 생성됩니다:

테이블명: {접두어}calendar_events 컬럼 구조: - event_id: 일정 고유 ID (AUTO_INCREMENT) - mb_id: 회원 ID (그누보드 연동) - calendar_id_ref: 캘린더 구분 ID - event_title: 일정 제목 - event_content: 일정 내용 - start_datetime: 시작 일시 - end_datetime: 종료 일시 - is_allday: 종일 일정 여부 - event_color: 일정 색상 - location: 장소

2.3 권한 설정

📝 참고사항
캘린더 시스템은 그누보드 회원 인증을 사용합니다. 별도의 권한 설정은 필요하지 않으며, 로그인한 회원만 자신의 일정을 관리할 수 있습니다.

3. 사용자 가이드

3.1 캘린더 접속

그누보드에 로그인한 후 다음 URL로 접속합니다:

http://도메인/calendar/

3.2 화면 구성

1

상단 메뉴바

  • 이전/다음 버튼: 날짜 범위 이동
  • 오늘 버튼: 현재 날짜로 이동
  • 날짜 표시: 현재 보고 있는 날짜 범위
  • 뷰 선택: 월간/주간/일간 보기 전환
2

메뉴 버튼 예시

다음과 같은 버튼들로 캘린더를 조작할 수 있습니다:

2025년 06월

3.3 일정 생성

1

새 일정 만들기

캘린더의 원하는 날짜나 시간을 클릭하면 일정 생성 팝업이 나타납니다.

2

일정 정보 입력

  • 제목: 일정의 제목 (필수)
  • 시작일/종료일: 일정 기간 설정
  • 종일 일정: 체크하면 시간 없이 하루 종일
  • 장소: 일정이 진행되는 장소
  • 설명: 일정에 대한 상세 내용
  • 캘린더 구분: 개인 일정 또는 회사 일정
3

일정 저장

모든 정보를 입력한 후 '저장' 버튼을 클릭하면 일정이 등록됩니다.

💡 팁: 제목은 반드시 입력해야 하며, 시작일과 종료일은 자동으로 설정됩니다.

3.4 일정 조회 및 관리

1

일정 보기

등록된 일정은 캘린더에 색상별로 표시됩니다:

  • 개인 일정 - 파란색
  • 회사 일정 - 녹색
2

일정 상세보기

등록된 일정을 클릭하면 상세 정보를 확인할 수 있습니다.

3

뷰 전환하기

  • 월간 보기: 한 달 전체 일정을 한눈에 확인
  • 주간 보기: 1주일 단위로 시간별 일정 확인
  • 일간 보기: 하루 단위로 시간별 상세 일정 확인

4. 주요 기능

4.1 캘린더 뷰 기능

뷰 타입 특징 사용 용도
월간 보기 한 달 전체 일정을 격자 형태로 표시 월별 전체 일정 파악, 장기 계획 수립
주간 보기 1주일 단위로 시간별 일정 표시 주간 일정 관리, 시간별 스케줄 확인
일간 보기 하루 단위로 시간별 상세 일정 표시 일일 상세 스케줄 관리, 시간 단위 계획

4.2 일정 관리 기능

📝 일정 생성

  • 드래그 앤 드롭으로 간편 생성
  • 종일 일정 / 시간 일정 구분
  • 반복 일정 설정 (향후 업데이트)
  • 알림 설정 (향후 업데이트)

🎨 캘린더 구분

  • 개인 일정 (파란색)
  • 회사 일정 (녹색)
  • 색상별 구분으로 직관적 관리
  • 필터링 기능 (향후 업데이트)

📱 반응형 디자인

  • PC, 태블릿, 모바일 최적화
  • 터치 인터페이스 지원
  • 다양한 화면 크기 대응
  • 직관적인 사용자 경험

🔒 보안 기능

  • 그누보드 회원 인증 연동
  • 개인별 일정 격리
  • CSRF 토큰 검증
  • SQL 인젝션 방지

4.3 네비게이션 기능

1

날짜 이동

  • 이전/다음 버튼: 현재 뷰 기준으로 이전/다음 기간으로 이동
  • 오늘 버튼: 현재 날짜가 포함된 기간으로 즉시 이동
  • 날짜 클릭: 월간 보기에서 특정 날짜 클릭으로 일간 보기 전환
2

뷰 전환

  • 상단 메뉴의 월간/주간/일간 버튼으로 즉시 전환
  • 현재 날짜 유지하면서 뷰만 변경
  • 각 뷰별 최적화된 레이아웃 제공

4.4 데이터 연동

🔗 그누보드 연동 기능
• 회원 시스템: 그누보드 회원 정보와 완전 연동
• 세션 관리: 그누보드 세션을 활용한 로그인 상태 확인
• 권한 관리: 개인별 일정 접근 권한 자동 제어
• 데이터베이스: 그누보드 DB 구조와 호환되는 테이블 설계

5. 관리자 가이드

5.1 시스템 관리

1

테이블 관리

캘린더 데이터는 다음 테이블에 저장됩니다:

테이블명: {그누보드접두어}calendar_events 주요 컬럼: • event_id: PRIMARY KEY, AUTO_INCREMENT • mb_id: 회원 ID (g5_member.mb_id 참조) • calendar_id_ref: 캘린더 구분 ('1' 또는 '2') • event_title: 일정 제목 • start_datetime: 시작 일시 • end_datetime: 종료 일시 • is_allday: 종일 일정 여부 (0 또는 1)
2

백업 관리

정기적인 데이터 백업을 위한 SQL 명령어:

# 캘린더 데이터 백업 mysqldump -u사용자명 -p패스워드 데이터베이스명 g5_calendar_events > calendar_backup.sql # 특정 기간 데이터만 백업 SELECT * FROM g5_calendar_events WHERE start_datetime BETWEEN '2025-01-01' AND '2025-12-31' INTO OUTFILE '/path/to/calendar_2025.csv';

5.2 성능 최적화

1

인덱스 확인

최적 성능을 위한 인덱스 설정:

# 기본 인덱스 (설치 시 자동 생성) KEY `mb_id` (`mb_id`) KEY `idx_start_datetime` (`start_datetime`) KEY `idx_end_datetime` (`end_datetime`) # 추가 성능 향상을 위한 복합 인덱스 (선택사항) ALTER TABLE g5_calendar_events ADD INDEX `idx_member_date` (`mb_id`, `start_datetime`);
2

캐시 설정

  • 브라우저 캐시: CSS/JS 파일의 적절한 캐시 헤더 설정
  • CDN 활용: Toast UI Calendar 라이브러리는 CDN 사용
  • 데이터 캐시: 자주 조회되는 일정 데이터의 임시 캐시 고려

5.3 보안 설정

⚠️ 보안 주의사항
• CSRF 토큰 검증을 운영 환경에서는 반드시 활성화하세요
• api_event_create.php의 토큰 검증 주석을 해제하세요
• 디버깅 모드는 운영 환경에서 비활성화하세요
1

CSRF 토큰 활성화

api_event_create.php에서 다음 주석을 해제하세요:

// 이 부분의 주석을 해제하세요 $received_token = isset($_POST['token']) ? trim($_POST['token']) : ''; $session_token = get_session('ss_token'); if (empty($received_token) || empty($session_token) || $received_token !== $session_token) { $response['message'] = '토큰이 유효하지 않습니다.'; @header('Content-Type: application/json; charset=utf-8'); echo json_encode($response); exit; }
2

디버깅 모드 비활성화

api_events.php에서 운영 환경용 설정:

// 이 줄들을 주석 처리하세요 // error_reporting(E_ALL); // ini_set('display_errors', 1); // 디버깅 출력 대신 일반 출력 사용 // echo json_encode($debug_output); ← 주석 처리 echo json_encode($schedules_result_array); ← 주석 해제

5.4 모니터링

1

로그 확인

  • 웹서버 로그: access.log, error.log 확인
  • PHP 에러 로그: PHP 설정에 따른 에러 로그 모니터링
  • 그누보드 로그: data/log/ 폴더의 SQL 에러 로그
2

성능 모니터링

# 캘린더 테이블 크기 확인 SELECT COUNT(*) as total_events, COUNT(DISTINCT mb_id) as unique_users FROM g5_calendar_events; # 최근 일정 활동 확인 SELECT DATE(start_datetime) as date, COUNT(*) as events FROM g5_calendar_events WHERE start_datetime >= DATE_SUB(NOW(), INTERVAL 30 DAY) GROUP BY DATE(start_datetime) ORDER BY date DESC;

6. 문제 해결

6.1 일반적인 문제

Q1. 캘린더가 로딩되지 않아요

✓
해결 방법:
  1. 브라우저 개발자 도구(F12)의 Console 탭에서 JavaScript 오류 확인
  2. Toast UI Calendar CDN 연결 상태 확인
  3. jQuery가 정상적으로 로드되었는지 확인
  4. 그누보드 common.php 경로가 올바른지 확인
// 브라우저 콘솔에서 확인 console.log(typeof jQuery); // "function"이 출력되어야 함 console.log(typeof moment); // "function"이 출력되어야 함 console.log(typeof tui); // "object"이 출력되어야 함

Q2. 일정이 저장되지 않아요

✓
해결 방법:
  1. 로그인 상태 확인 (비로그인 시 저장 불가)
  2. install.php 실행 여부 확인 (테이블 생성 필요)
  3. CSRF 토큰 문제인지 확인
  4. 데이터베이스 연결 상태 확인
📝 디버깅 팁
api_event_create.php에서 응답 데이터의 debug 배열을 확인하면 상세한 오류 정보를 볼 수 있습니다.

Q3. 일정이 표시되지 않아요

✓
해결 방법:
  1. 데이터베이스에 일정이 실제로 저장되어 있는지 확인
  2. api_events.php의 응답 데이터 확인
  3. 날짜 범위가 올바른지 확인
  4. 회원 ID가 일치하는지 확인
# 데이터베이스에서 직접 확인 SELECT * FROM g5_calendar_events WHERE mb_id = '회원ID' ORDER BY start_datetime DESC LIMIT 10;

6.2 설치 관련 문제

Q4. install.php 실행 시 오류가 발생해요

✓
해결 방법:
  1. 관리자 권한으로 로그인했는지 확인
  2. 데이터베이스 연결 권한 확인
  3. 테이블 생성 권한 확인
  4. 그누보드 data/log/ 폴더의 SQL 에러 로그 확인

Q5. _common.php 관련 오류가 발생해요

✓
해결 방법:
  1. 그누보드 루트 경로 확인
  2. calendar 폴더가 그누보드 루트에 있는지 확인
  3. 파일 권한 확인 (읽기 권한 필요)
# 올바른 폴더 구조 그누보드루트/ ├── admin/ ├── bbs/ ├── calendar/ ← 여기에 위치해야 함 │ ├── index.php │ ├── _common.php │ └── ... ├── common.php └── ...

6.3 성능 관련 문제

Q6. 캘린더 로딩이 느려요

✓
해결 방법:
  1. 데이터베이스 인덱스 확인 및 최적화
  2. 불필요한 일정 데이터 정리
  3. CDN 연결 상태 확인
  4. 서버 리소스 사용량 확인
💡 성능 개선 팁
많은 양의 일정 데이터가 있을 경우, 조회 범위를 제한하거나 페이징을 고려해보세요.

6.4 브라우저 호환성

브라우저 지원 버전 주요 제한사항
Chrome 60+ (권장: 최신) 없음
Firefox 55+ (권장: 최신) 없음
Safari 12+ (권장: 최신) 일부 CSS 효과 제한
Edge 79+ (권장: 최신) 없음
Internet Explorer 지원 안 함 모던 JavaScript 미지원

7. API 참조

7.1 일정 조회 API

📡

api_events.php

용도: 지정된 날짜 범위의 일정 목록을 조회합니다.

요청 파라미터
파라미터 타입 필수 설명
start string Y 조회 시작 날짜 (YYYY-MM-DD)
end string Y 조회 종료 날짜 (YYYY-MM-DD)
응답 형식
[ { "id": "1", "calendarId": "1", "title": "회의", "body": "프로젝트 진행 상황 논의", "isAllDay": false, "start": "2025-06-04T10:00:00+09:00", "end": "2025-06-04T11:00:00+09:00", "category": "time", "location": "회의실 A", "backgroundColor": "#00a9ff", "borderColor": "#00a9ff", "color": "#ffffff" } ]

7.2 일정 생성 API

📡

api_event_create.php

용도: 새로운 일정을 데이터베이스에 저장합니다.

요청 파라미터 (POST)
파라미터 타입 필수 설명
title string Y 일정 제목
start string Y 시작 일시 (YYYY-MM-DD HH:mm:ss)
end string Y 종료 일시 (YYYY-MM-DD HH:mm:ss)
calendarId string N 캘린더 구분 (기본값: "1")
isAllDay boolean N 종일 일정 여부 (기본값: false)
location string N 장소
body string N 일정 내용
token string Y* CSRF 토큰 (*운영 환경에서 필수)
성공 응답
{ "status": "success", "message": "일정이 성공적으로 저장되었습니다.", "schedule": { "id": "123", "calendarId": "1", "title": "새 일정", "body": "일정 내용", "isAllDay": false, "start": "2025-06-04T10:00:00+09:00", "end": "2025-06-04T11:00:00+09:00", "category": "time", "location": "", "backgroundColor": "#00a9ff", "borderColor": "#00a9ff", "color": "#ffffff" } }
오류 응답
{ "status": "error", "message": "필수 입력 항목이 누락되었습니다.", "debug": [ "[2025-06-04 10:30:00] api_event_create.php 시작", "[2025-06-04 10:30:00] 받은 데이터 확인..." ] }

7.3 데이터 형식

날짜/시간 형식

구분 형식 예시 용도
종일 일정 YYYY-MM-DD 2025-06-04 API 응답의 start/end
시간 일정 ISO 8601 2025-06-04T10:00:00+09:00 API 응답의 start/end
DB 저장 DATETIME 2025-06-04 10:00:00 데이터베이스 저장
입력 파라미터 DATETIME 2025-06-04 10:00:00 API 요청

캘린더 ID 및 색상

캘린더 ID 이름 배경색 테두리색
1 개인 일정 #00a9ff #00a9ff
2 회사 일정 #03bd9e #03bd9e
기타 기본 #d2d2d2 #d2d2d2

7.4 JavaScript 함수 참조

전역 함수

// 디버그 정보 출력 window.debugCalendar(); // 현재 캘린더 상태 확인 console.log('현재 뷰:', calendar.getViewName()); console.log('현재 날짜:', calendar.getDate()); console.log('날짜 범위:', { start: calendar.getDateRangeStart(), end: calendar.getDateRangeEnd() });

주요 이벤트

// 일정 생성 전 이벤트 calendar.on('beforeCreateSchedule', function(scheduleData) { console.log('새 일정 생성:', scheduleData); }); // 캘린더 렌더링 완료 이벤트 calendar.on('afterRender', function() { console.log('캘린더 렌더링 완료'); }); // 일정 클릭 이벤트 calendar.on('clickSchedule', function(e) { console.log('일정 클릭:', e.schedule); });

7.5 확장 개발 가이드

🛠️ 커스터마이징 가능 영역
시스템을 확장하거나 커스터마이징할 때 참고할 수 있는 주요 영역들입니다.

새로운 캘린더 타입 추가

1

index.php의 calendars 옵션에 새 캘린더 추가:

calendars: [ { id: '1', name: '개인 일정', backgroundColor: '#3b82f6', borderColor: '#3b82f6', color: '#ffffff' }, { id: '2', name: '회사 일정', backgroundColor: '#10b981', borderColor: '#10b981', color: '#ffffff' }, { id: '3', name: '프로젝트 일정', // 새 캘린더 backgroundColor: '#f59e0b', borderColor: '#f59e0b', color: '#ffffff' } ]
2

api_event_create.php에서 색상 매핑 업데이트:

$defaultColors = [ '1' => '#00a9ff', '2' => '#03bd9e', '3' => '#f59e0b' // 새 색상 추가 ]; $event_color = isset($defaultColors[$calendarId]) ? $defaultColors[$calendarId] : '#d2d2d2';

일정 수정/삭제 기능 추가

1

새로운 API 파일 생성 (api_event_update.php, api_event_delete.php)

// api_event_update.php 기본 구조 <?php include_once('./_common.php'); // 권한 확인 if (!$is_member) { echo json_encode(['status' => 'error', 'message' => '로그인 필요']); exit; } // 업데이트 로직 $event_id = $_POST['event_id']; $title = $_POST['title']; // ... 기타 필드 $sql = "UPDATE {$table_name} SET event_title = '".sql_real_escape_string($title)."' WHERE event_id = '{$event_id}' AND mb_id = '{$member['mb_id']}'"; ?>
2

JavaScript 이벤트 핸들러 추가:

calendar.on('beforeUpdateSchedule', function(e) { // 일정 수정 처리 updateScheduleViaAPI(e.schedule); }); calendar.on('beforeDeleteSchedule', function(e) { // 일정 삭제 처리 deleteScheduleViaAPI(e.schedule); });

권한 시스템 확장

1

부서별 또는 그룹별 일정 공유 기능:

// 테이블에 share_type, share_target 컬럼 추가 ALTER TABLE g5_calendar_events ADD COLUMN share_type ENUM('private', 'department', 'public') DEFAULT 'private', ADD COLUMN share_target VARCHAR(255) DEFAULT NULL; // API에서 공유 일정도 함께 조회 SELECT * FROM g5_calendar_events WHERE (mb_id = '{$member['mb_id']}' OR (share_type = 'department' AND share_target = '{$member['부서']}') OR share_type = 'public') AND start_datetime BETWEEN '{$start}' AND '{$end}'

알림 기능 추가

1

알림 테이블 생성 및 스케줄러 연동:

CREATE TABLE g5_calendar_notifications ( noti_id INT AUTO_INCREMENT PRIMARY KEY, event_id INT NOT NULL, mb_id VARCHAR(255) NOT NULL, noti_type ENUM('email', 'sms', 'push') DEFAULT 'email', noti_time DATETIME NOT NULL, is_sent TINYINT(1) DEFAULT 0, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (event_id) REFERENCES g5_calendar_events(event_id) );

8. 부록

8.1 라이센스 정보

📄 오픈소스 라이센스
• Toast UI Calendar: MIT License
• Moment.js: MIT License
• jQuery: MIT License
• 그누보드: GPL License

8.2 업데이트 히스토리

버전 날짜 주요 변경사항
1.0.0 2025-06-04 최초 릴리즈 - 기본 캘린더 기능 구현
1.0.1 예정 일정 수정/삭제 기능 추가 예정
1.1.0 예정 반복 일정, 알림 기능 추가 예정

8.3 참고 자료

8.4 지원 및 문의

💬 기술 지원
시스템 사용 중 문제가 발생하거나 추가 기능이 필요한 경우:
• 그누보드 커뮤니티 게시판 활용
• GitHub Issues를 통한 버그 리포트
• 개발자 이메일을 통한 직접 문의

8.5 개발 환경 설정

🔧

로컬 개발 환경

개발자를 위한 로컬 환경 설정 가이드:

# Apache 가상 호스트 설정 예시 <VirtualHost *:80> ServerName calendar.local DocumentRoot /path/to/gnuboard <Directory /path/to/gnuboard> AllowOverride All Require all granted </Directory> </VirtualHost> # hosts 파일에 추가 127.0.0.1 calendar.local
🐛

디버깅 설정

개발 시 유용한 디버깅 설정:

# PHP 디버깅 설정 (php.ini) error_reporting = E_ALL display_errors = On log_errors = On error_log = /path/to/php_errors.log # MySQL 쿼리 로그 활성화 SET GLOBAL general_log = 'ON'; SET GLOBAL general_log_file = '/path/to/mysql_queries.log';

8.6 성능 벤치마크

항목 측정값 기준 환경
페이지 로드 시간 < 2초 Apache 2.4, PHP 7.4, MySQL 5.7
일정 조회 (100개) < 500ms 인덱스 최적화 적용
일정 생성 < 300ms AJAX 요청 기준
메모리 사용량 < 32MB PHP 프로세스당
⚠️ 성능 주의사항
• 대량의 일정 데이터 (1000개 이상)가 있을 경우 페이징 고려
• CDN 사용 시 캐시 정책 설정 필요
• 데이터베이스 정기 최적화 권장

📚 매뉴얼 끝

그룹웨어 캘린더 시스템을 이용해 주셔서 감사합니다.

📞 지원 연락처

기술 지원: 개발팀

문서 버전: 1.0

최종 업데이트: 2025년 6월 4일

본 문서는 PDF로 인쇄하여 보관하실 수 있습니다.

그룹웨어 캘린더 시스템 매뉴얼 - 페이지