zioinfo-mail/.claude/skills/system-sync-orchestrator/SKILL.md

name

description

system-sync-orchestrator

GUARDiA 5개 시스템(guardia-itsm, zioinfo-web, guardia-manager, guardia-messenger, guardia-docs) 배포 상태를 검증하고 이슈를 자동 수정하는 오케스트레이터. workspace ↔ repos ↔ Gitea ↔ 서버 4-way 동기화 불일치, /var/www 구버전, 서버 stash 잔존, app vs src 미동기화, uncommitted 변경을 탐지·수정한다. 다음 상황에서 반드시 사용: (1) '5개 시스템 확인', '배포 상태 점검', '서버 최신 확인'; (2) '동기화', 'sync', '최신본 올려줘', '배포 맞춰줘'; (3) Manager/ITSM/홈페이지/Messenger/Docs 배포 이슈; (4) 다시 실행, 업데이트, 수정, 보완.

GUARDiA 5개 시스템 배포 동기화 오케스트레이터

실행 모드: 하이브리드

• Phase 1 (검증): 서브 에이전트 (deploy-verifier)
• Phase 2 (수정): 에이전트 팀 (deploy-verifier + deploy-fixer 협업)
• Phase 3 (재검증): 서브 에이전트

---

Phase 0: 컨텍스트 확인

_workspace/ 존재 여부 확인:
- 없음 → 초기 실행 (Phase 1부터)
- 있음 + 사용자가 특정 시스템만 지정 → 부분 재실행 (해당 시스템만)
- 있음 + 전체 재검증 요청 → 전체 재실행

_workspace/ 디렉토리:

C:/GUARDiA/.claude/agents/_workspace/
├── verify_report.json   ← deploy-verifier 출력
└── fix_report.json      ← deploy-fixer 출력

---

Phase 1: 전체 검증 (서브 에이전트)

deploy-verifier 서브 에이전트로 실행:

5개 시스템 검증 항목

시스템	서비스	경로	정적 경로
guardia-itsm	guardia	/opt/guardia/src + /opt/guardia/app	—
zioinfo-web	zioinfo	/opt/zioinfo/src	/var/www/zioinfo
guardia-manager	guardia-manager	/opt/manager/src or /opt/manager/backend	/var/www/manager
guardia-messenger	EAS 빌드	Gitea only	—
guardia-docs	—	Gitea only	/var/www/docs (선택)

검증 스크립트 패턴

C:/GUARDiA/scripts/check/verify_all_systems.py 참조. Gitea API 인증: base64.b64encode(b'zio:Zio@Admin2026!').decode()

이슈 분류

코드	설명	심각도
STALE_WWW	/var/www 파일이 최근 배포보다 오래됨	critical
APP_SRC_DRIFT	/opt/{app}/app vs src 미동기화	critical
STASH_EXISTS	서버 git stash 잔존	warning
UNCOMMITTED	비빌드 파일 uncommitted	warning
COMMIT_MISMATCH	서버 커밋 != Gitea 커밋	critical
SERVICE_DOWN	systemctl not active	critical
WORKSPACE_DRIFT	workspace != repos	info

---

Phase 2: 이슈 수정 (에이전트 팀)

Phase 1에서 이슈가 없으면 → 완료 보고 후 종료. 이슈 있으면 → deploy-fixer와 팀 구성.

수정 우선순위

1. SERVICE_DOWN     → 서비스 재기동 먼저
2. APP_SRC_DRIFT    → rsync + restart
3. STASH_EXISTS     → stash 내용 평가 → 복원 또는 삭제
4. COMMIT_MISMATCH  → git fetch + reset --hard origin/main
5. STALE_WWW        → npm/mvn 빌드 + www 복사
6. UNCOMMITTED      → 파일 분류 (중요/임시) → workspace 반영 또는 clean
7. WORKSPACE_DRIFT  → sync_workspace_to_repos.py 실행

시스템별 수정 처리

guardia-itsm (APP_SRC_DRIFT 표준 처리):

rsync -a --exclude=__pycache__ --exclude=.git \
      --exclude="*.db" --exclude="uploads" \
      /opt/guardia/src/ /opt/guardia/app/
systemctl restart guardia
sleep 4 && systemctl is-active guardia

zioinfo-web (STALE_WWW 표준 처리):

cd /opt/zioinfo/src
git fetch origin main && git reset --hard origin/main
# stash 있으면 핵심 파일 cherry-pick
cd frontend && npm run build
cp -r ../backend/src/main/resources/static/. /var/www/zioinfo/
systemctl restart zioinfo

guardia-manager (STALE_WWW 표준 처리):

cd /opt/manager/src/frontend  # or /opt/manager/backend
# workspace/guardia-manager의 최신 frontend를 서버에 업로드
npm ci && npm run build
cp -r dist/. /var/www/manager/
systemctl restart guardia-manager

stash 처리 원칙:

• git stash show --stat 으로 변경 파일 목록 확인
• frontend/src/ 파일 포함 → git checkout stash -- frontend/src/ 로 선별 복원 후 빌드
• 빌드 산출물(static/assets/)만 있으면 → git stash drop

---

Phase 3: 재검증 (서브 에이전트)

Phase 2 완료 후 deploy-verifier 재실행. 모든 action_required 항목이 비어있으면 성공.

---

결과 보고 형식

=== GUARDiA 5개 시스템 배포 상태 ===

✅ guardia-itsm   — active | 커밋 일치 | app 동기화
✅ zioinfo-web    — active | 커밋 일치 | www Jun 1 최신
✅ guardia-manager— active | 커밋 일치 | www Jun 1 최신
✅ guardia-messenger — EAS v1.0.0 | Gitea 최신
✅ guardia-docs   — 36개 md | Gitea 최신

수정된 이슈: X개
남은 이슈: 0개

---

에러 핸들링

에러	처리
서비스 재기동 실패	journalctl -u {service} -n 20 로그 수집 후 보고
npm build 실패	node_modules 삭제 후 npm ci 재시도
git reset 충돌	git clean -fd 후 재시도
Gitea push 실패	bundle → 서버 → push 방식 (push_jenkinsfiles_api 패턴)
rsync 권한 오류	chown -R root:root /opt/{app} 후 재시도

---

테스트 시나리오

정상 흐름:

1. 검증 실행 → 이슈 탐지 (Manager STALE_WWW, ITSM APP_SRC_DRIFT)
2. 수정 팀 실행 → Manager npm build, ITSM rsync
3. 재검증 → 모두 ✅

에러 흐름:

• Manager npm build 실패 → npm ci 재시도 → 실패 시 보고서에 기록 후 다음 시스템 진행

---

should-trigger

• "5개 시스템 배포 확인해줘"
• "서버에 최신본 올라간 거 맞아?"
• "Manager 구버전 올라가 있는데 수정해줘"
• "guardia-itsm 배포 상태 점검"
• "홈페이지 최신 코드 반영됐나?"
• "전체 동기화 해줘"
• "다시 실행", "수정", "보완"

should-NOT-trigger

• "guardia-itsm 새 기능 만들어줘" → itsm-dev 에이전트
• "홈페이지 디자인 바꿔줘" → ui-overhaul-orchestrator
• "Jenkins 파이프라인 설정" → cicd-pipeline-orchestrator
• "코드 리뷰해줘" → code-review 스킬