# 자동화/크론/저장소 신뢰성 표준 v1

- Paperclip Issue: NEX-8
- 담당: Automation and Cron Reliability Engineer
- 작성일: 2026-05-04T22:21:08+09:00
- 적용 범위: NextLab 통합운영체계, Hermes cron/heartbeat, Paperclip 로컬 운영, Z드라이브 산출물 저장

## 1. 목표

자동화 작업이 “돌아갔다/안 돌아갔다” 수준으로 끝나지 않도록, 실행 전 조건 확인, 실행 중 기록, 실패 시 복구, 완료 후 검증을 하나의 운영 표준으로 묶는다.

핵심 원칙:

1. 사전점검(preflight) 실패 시 본 작업을 시작하지 않는다.
2. 모든 크론/자동화 실행은 결과 파일과 Paperclip 댓글 중 최소 1곳에 기록한다.
3. Z드라이브·Gateway·Paperclip 중 하나라도 장애가 있으면 대체 경로와 복구 루틴을 명시한다.
4. “성공”은 산출물 존재, API 상태, 링크 접근성 중 해당 작업의 검증 조건을 통과해야만 선언한다.

## 2. 표준 상태 모델

| 상태 | 의미 | 다음 전이 조건 |
|---|---|---|
| `scheduled` | 크론/heartbeat 등록 또는 호출 대기 | 실행 트리거 수신 |
| `preflight` | Z드라이브, API, 토큰, 포트, 경로 점검 | 필수 항목 pass |
| `running` | 실제 작업 수행 | 작업 프로세스 정상 종료 |
| `verify` | 결과물/API/링크 검증 | 검증 항목 pass |
| `recorded` | 로그·Paperclip·대시보드 기록 완료 | 기록 위치 확인 |
| `done` | 완료 | 없음 |
| `degraded` | 대체 경로로 진행 | 후속 복구 이슈 생성 |
| `failed` | 실행 불가 또는 검증 실패 | 복구 루틴 수행 |

## 3. Preflight 체크리스트

### 3.1 Z드라이브 저장소

필수 확인:

- `/mnt/z` 존재 여부
- 작업 대상 상위 폴더 쓰기 가능 여부
- 대체 경로 존재 여부

기본 경로:

- 주 작업: `/mnt/z/docker/work/YYYY/MM/<project>`
- Hermes 리포트: `/mnt/z/.hermes/reports/...`
- 대체 리포트: `/mnt/z/docker/.hermes/reports/...`
- Z드라이브 불가 시 임시 대체: `$HOME/.hermes/workrooms/...`

판정:

- pass: `/mnt/z` 존재 + 대상 폴더 쓰기 가능
- degraded: `/mnt/z` 존재하지만 특정 폴더 쓰기 불가 → `/mnt/z/docker/.hermes` 또는 Linux 홈으로 대체
- failed: `/mnt/z` 자체 미마운트 + 결과물을 외부 전달해야 하는 작업

### 3.2 Paperclip Health

필수 호출:

```bash
curl -fsS http://127.0.0.1:3100/api/health
curl -fsS http://127.0.0.1:3100/api/companies/<COMPANY_ID>
```

판정:

- pass: `status: ok`, 회사 조회 성공
- degraded: health ok이나 회사/이슈 조회 실패 → 작업은 파일 기록으로 진행하고 Paperclip 기록 재시도 이슈 생성
- failed: health API 접근 불가이고 작업이 Paperclip 상태 변경을 요구함

주의: Paperclip API는 localhost이므로 Hermes `terminal` + `curl`로 호출한다. browser/web 계열 도구를 사용하지 않는다.

### 3.3 Gateway/도구 Health

Gateway가 필요한 작업은 작업별 포트를 명시하고 확인한다.

예시:

```bash
curl -fsS http://127.0.0.1:3200/health || echo unavailable
```

판정:

- pass: health 응답 정상
- degraded: 해당 Gateway가 선택 기능이면 비활성으로 기록 후 진행
- failed: Gateway가 핵심 기능이면 작업 중단 및 복구 루틴 실행

## 4. Cron 결과 기록 표준

각 실행은 다음 위치 중 최소 하나에 JSONL로 남긴다.

권장 위치:

```text
/home/jinkidi/.hermes/workrooms/dalgeumi/integrated-dashboard/operations/cron-run-logs/YYYY-MM.jsonl
```

Z드라이브 동기화 위치:

```text
/mnt/z/docker/.hermes/logs/cron-run-logs/YYYY-MM.jsonl
```

필드:

```json
{
  "timestamp": "ISO-8601",
  "issue": "NEX-8",
  "job_name": "heartbeat-or-cron-name",
  "state": "done|degraded|failed",
  "preflight": {
    "z_drive": "pass|degraded|failed",
    "paperclip": "pass|degraded|failed",
    "gateway": "pass|degraded|failed|not_required"
  },
  "artifacts": ["absolute/path/or/url"],
  "verification": ["checked item"],
  "recovery_next": "필요 시 다음 조치"
}
```

## 5. 실패 복구 루틴

### 5.1 Z드라이브 실패

1. `/mnt/z` 존재 확인.
2. 쓰기 실패 경로와 errno를 로그에 기록.
3. Linux 홈 대체 경로에 결과 저장.
4. Paperclip 댓글 또는 대시보드 상태에 `degraded`로 기록.
5. Z드라이브 복구 후 rsync로 동기화:

```bash
rsync -a --ignore-existing "$HOME/.hermes/workrooms/.../" "/mnt/z/docker/.../"
```

### 5.2 Paperclip 실패

1. `curl -fsS http://127.0.0.1:3100/api/health` 재시도.
2. 실패 시 Paperclip 댓글 대신 로컬 `PAPERCLIP_PENDING_COMMENTS.md`에 기록.
3. Paperclip 복구 후 pending 댓글을 API로 반영.
4. 상태 변경 실패 시 완료 선언 금지. 파일 산출물은 “작업 완료, Paperclip 기록 대기”로 구분한다.

### 5.3 Cron 실행 실패

1. 로그에서 `failed` 레코드 확인.
2. 동일 입력으로 1회만 즉시 재시도.
3. 재시도 실패 시 Paperclip에 복구 이슈 생성.
4. 원인 분류: 환경(preflight), 인증, 네트워크/API, 경로/권한, 코드/데이터.

## 6. 운영 게이트

완료 전 필수 게이트:

- Gate A: Preflight 결과가 pass 또는 명시적 degraded인가?
- Gate B: 산출물이 실제 존재하거나 URL/API가 검증되었는가?
- Gate C: 결과 로그가 JSONL 또는 Paperclip 댓글로 남았는가?
- Gate D: degraded/failed 항목에 복구 next action이 있는가?

Gate B 또는 C 실패 시 `done` 금지.

## 7. 현재 적용 결과

2026-05-04 22:21 KST 기준 점검:

- Z드라이브: present, writable
- Paperclip: ok, local_trusted/private, authReady true
- 회사: NextLab Integrated Operating System Office
- Gateway 3200 health: unavailable → 본 표준 문서 작성에는 not_required/degraded로 기록

## 8. 산출물

- 표준 문서: `AUTOMATION_CRON_RELIABILITY_STANDARD.md`
- 대시보드 페이지: `index.html`
- 실행 매니페스트: `manifest.json`
- Preflight 스크립트: `scripts/cron-preflight.sh`