# 로그 파일 정책

## 폴더 구조

```
logs/
└── YYYY-MM-DD/
    ├── 00_INDEX.txt          ← 증상 → 볼 파일 안내 (자동 생성)
    ├── 01_INTEGRATED/
    ├── 02_CLUSTER/
    │   ├── _CLUSTER-2026-10-27.log   ← 소량 모듈 통합 파일
    │   └── BUFFER-2026-10-27.log     ← 대용량 모듈 개별 파일
    ├── 03_EZIIO/
    └── ...
```

- **날짜 폴더 안에서 도메인별로** 나눕니다.
- 각 날짜 폴더에 **증상 → 볼 파일** 안내 파일을 자동으로 만들어 둡니다.

> 왜 — 장애가 났을 때 "어느 날, 어느 도메인"부터 좁혀 들어가는 것이 가장 빠릅니다. 한 폴더에 수백 개 파일이 쌓이면 찾는 데만 시간이 걸립니다.

## 경로는 한 모듈에서만 만든다

로그 경로와 카테고리를 정하는 **단일 출처 모듈**을 하나 두고, 다른 곳에서는 경로를 직접 조립하지 않습니다.

```js
// O — 모듈 이름만 넘기면 카테고리·경로는 공용 모듈이 정한다
const log = (...args) => logToFile(path.basename(__filename, '.js'), ...args);

// X — 경로를 직접 조립
fs.appendFileSync(path.join(logDir, 'my.log'), msg);
```

- 파일(모듈) 이름이 곧 로그 접두사가 되고, 공용 모듈이 카테고리를 자동으로 정합니다.
- 규칙에 없는 새 접두사는 **미분류(`99_ETC`)** 로 가고 경고가 1회 남습니다. 이 경고를 보면 분류 규칙에 **반드시 추가**합니다.
- 파일에 직접 써야 할 때도 경로는 공용 모듈에서 받습니다. 공용 모듈이 폴더를 만들어 주기 때문입니다.

> 왜 — 날짜 폴더가 아직 없을 때 직접 쓰면 "폴더 없음(ENOENT)" 오류로 **로그가 통째로 사라집니다.**

## 카테고리 — 번호 = 조사 순서

| 폴더 | 담는 것 |
|---|---|
| `01_INTEGRATED` | 여러 도메인을 시간순으로 모은 통합 로그 |
| `02_CLUSTER` | 세척·우유밀기·버퍼탱크·밸브·냉각기 (판정 = 논리 계층) |
| `03_EZIIO` | 입출력장치 액션·핀·장비 통신 (물리 계층) |
| `04_MQTT` | 메시지 원문·발행 |
| `05_GATE` | 스마트게이트 / 슬라이딩도어 |
| `06_ROBOT` | 로봇·착유 |
| `07_FEED` | 급이기·사료·소 |
| `08_ALERT` | 문자·메신저·푸시·오류 창 |
| `09_BATCH` | 야간 배치·집계·내보내기 |
| `10_DB` | DB·느린 쿼리·디스크·파일 전송·실패 SQL |
| `11_WEB` | HTTP 접근·설정 캐시·외부 연동 |
| `99_ETC` | 미분류 — 여기 파일이 생기면 규칙에 추가하라는 신호 |

번호 순서대로 보면 **통합 흐름 → 판정 → 물리 동작 → 통신 원문** 순으로 원인을 좁힐 수 있습니다.

## 개별 파일과 통합 파일

- **대용량이거나 장애 때 통째로 읽는 핵심 로그**만 자기 파일을 갖습니다. (기준 예: 하루 1MB 이상)
- 나머지 소량 모듈은 카테고리 통합 파일(`_<카테고리>-날짜.log`)에 `[모듈명]` 태그와 함께 합칩니다.

```bash
# 통합 파일에서 특정 모듈만 보기
grep "\[gateComControl\]" _GATE-2026-10-27.log
```

## 보존

- 보존 로직은 **한 모듈에만** 둡니다. 새로 만들지 않습니다.
- 날짜 폴더 단위로, 정한 기간(예: 15일)이 지나면 폴더째 삭제합니다.
- 여러 로그 출력기가 보존 장부(audit 파일)를 공유하지 않게 합니다 — 서로 덮어써서 보존이 깨집니다.

## 로그에 남기지 않는 것

- 비밀번호·토큰·키 등 비밀값
- 필요 이상의 개인정보(전화번호 전체 등). 꼭 필요하면 일부를 가립니다.

자세한 내용은 '보안 기본 규칙' 문서를 참조하세요.