> For the complete documentation index, see [llms.txt](https://kopens.gitbook.io/plantpulse-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kopens.gitbook.io/plantpulse-platform/developer/api-manual/calendar-service.md).

# 11. Calendar 서비스

`client.calendar()` 으로 접근합니다. 일정(점검·휴일·검사 등)을 자산/사이트에 부착해 운영합니다.

## 10.1 메서드 일람

| 메서드                                      | 반환 타입                          | HTTP   | 엔드포인트                                     |
| ---------------------------------------- | ------------------------------ | ------ | ----------------------------------------- |
| `create(CalendarRequestV5)`              | `CalendarResponseV5` 또는 `null` | POST   | `/api/v5/calendar`                        |
| `update(calendar_id, CalendarRequestV5)` | `CalendarResponseV5` 또는 `null` | PUT    | `/api/v5/calendar/{id}`                   |
| `delete(calendar_id)`                    | `boolean`                      | DELETE | `/api/v5/calendar/{id}`                   |
| `get(calendar_id)`                       | `CalendarResponseV5` 또는 `null` | GET    | `/api/v5/calendar/{id}`                   |
| `list()`                                 | `List<CalendarResponseV5>`     | GET    | `/api/v5/calendar`                        |
| `search(from_iso, to_iso)`               | `List<CalendarResponseV5>`     | GET    | `/api/v5/calendar/search?from=...&to=...` |

## 10.2 일정 타입 (target\_type)

| 코드           | 의미                  |
| ------------ | ------------------- |
| `MTN`        | 정기 점검 (Maintenance) |
| `HOLIDAY`    | 휴일 / 비조업            |
| `INSPECTION` | 정기 검사               |
| `MEETING`    | 회의                  |
| `TRAINING`   | 교육                  |

## 10.3 CalendarRequestV5 / CalendarResponseV5

| 필드                                       | 타입     | 설명                |
| ---------------------------------------- | ------ | ----------------- |
| `calendar_id`                            | String | 일정 ID (PK)        |
| `target_type`                            | String | 타입 코드             |
| `site_id`                                | String | 소속 사이트            |
| `asset_id`                               | String | 대상 자산 (Equipment) |
| `fix_start_timestamp`                    | long   | 시작 시각 (밀리초)       |
| `fix_end_timestamp`                      | long   | 종료 시각 (밀리초)       |
| `description`                            | String | 설명                |
| `type_color` / `type_name` / `type_kind` | String | 타입 표시 정보          |

## 10.4 사용 예시

### 일정 생성

```java
import plantpulse.api.v5.dto.request.CalendarRequestV5;
import plantpulse.api.v5.dto.response.CalendarResponseV5;

CalendarRequestV5 cal = new CalendarRequestV5();
cal.setCalendar_id("CAL_20260520_0001");
cal.setSite_id("SITE_DJ");
cal.setAsset_id("ASSET_DJ_M_0001");
cal.setTarget_type("MTN");
cal.setDescription("CNC #1 정기 점검 — 베어링 교체");

long now = System.currentTimeMillis();
cal.setFix_start_timestamp(now + 6 * 24 * 3600_000L);
cal.setFix_end_timestamp(now + 7 * 24 * 3600_000L);

CalendarResponseV5 created = client.calendar().create(cal);
```

### 단건 조회

```java
CalendarResponseV5 c = client.calendar().get("CAL_20260520_0001");
if (c != null) {
    System.out.println(c.getDescription());
    System.out.println("시작: " + c.getFix_start_timestamp());
}
```

### ISO 날짜 범위 검색

```java
import java.util.List;

List<CalendarResponseV5> may = client.calendar().search(
        "2026-05-01 00:00:00",
        "2026-05-31 23:59:59");
```

### 전체 목록

```java
List<CalendarResponseV5> all = client.calendar().list();
for (CalendarResponseV5 c : all) {
    System.out.println(c.getCalendar_id() + " — " + c.getTarget_type());
}
```

### 자산별 점검 일정 필터링 (클라이언트 측)

```java
import java.util.stream.Collectors;

String targetAsset = "ASSET_DJ_M_0001";

List<CalendarResponseV5> mtnEvents = client.calendar()
        .search("2026-01-01 00:00:00", "2026-12-31 23:59:59")
        .stream()
        .filter(c -> targetAsset.equals(c.getAsset_id()))
        .filter(c -> "MTN".equals(c.getTarget_type()))
        .collect(Collectors.toList());
```

### 수정 / 삭제

```java
// 수정 — 전체 필드를 다시 보내야 함
CalendarRequestV5 update = new CalendarRequestV5();
update.setCalendar_id("CAL_20260520_0001");
update.setSite_id("SITE_DJ");
update.setAsset_id("ASSET_DJ_M_0001");
update.setTarget_type("MTN");
update.setDescription("점검 연기 — 5월 25일로 변경");
long now = System.currentTimeMillis();
update.setFix_start_timestamp(now + 11 * 24 * 3600_000L);
update.setFix_end_timestamp(now + 12 * 24 * 3600_000L);
client.calendar().update("CAL_20260520_0001", update);

// 삭제
client.calendar().delete("CAL_20260520_0001");
```

## 10.5 활용 시나리오

### 시나리오 — 다가오는 7일 일정 알림

```java
import java.text.SimpleDateFormat;
import java.util.Date;

SimpleDateFormat fmt = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
long now = System.currentTimeMillis();
String from = fmt.format(new Date(now));
String to   = fmt.format(new Date(now + 7L * 24 * 3600_000L));

List<CalendarResponseV5> upcoming = client.calendar().search(from, to);
for (CalendarResponseV5 c : upcoming) {
    if ("MTN".equals(c.getTarget_type())) {
        sendNotification("점검 예정: " + c.getDescription());
    }
}
```

### 시나리오 — 점검 일정이 있는 자산은 OEE 계산에서 제외

```java
long now = System.currentTimeMillis();
String today = fmt.format(new Date(now));

List<CalendarResponseV5> activeEvents = client.calendar()
        .search(today, today)
        .stream()
        .filter(c -> c.getFix_start_timestamp() <= now
                  && c.getFix_end_timestamp() >= now)
        .filter(c -> "MTN".equals(c.getTarget_type()))
        .collect(Collectors.toList());

Set<String> excludedAssets = activeEvents.stream()
        .map(CalendarResponseV5::getAsset_id)
        .collect(Collectors.toSet());

// OEE 계산 시 excludedAssets 의 자산은 건너뜀
```

## 다음 단계

* [Order 서비스](/plantpulse-platform/developer/api-manual/order-service.md) — 작업지시와 일정 연동
* [Asset 서비스](/plantpulse-platform/developer/api-manual/asset-service.md) — 일정이 부착될 자산