운영 FAQ

/설정 점검은 항목마다 번호를 붙이고, 마지막 줄에 고칠 수 있는 번호로 된 명령 (예: /설정 복구 항목:1,2,3)을 알려 줘요. (복구 불가: 이유)가 붙은 항목은 봇이 고칠 수 없어요(예: 봇 역할이 너무 낮음 → 서버 설정에서 봇 역할을 맨 위로).

/설정 복구는 먼저 계획을 보여 주고, 계획을 만든 본인(관리자)이 확인을 눌러야 실행돼요. 확인할 때 다시 점검해서 같은 항목만 고쳐요.

대기 역할처럼 다른 항목이 기대는 것을 지웠다 복구하면, 역할이 먼저 다시 생기고 그 역할에 기대는 항목(대기 부여, #대기실 오버라이드)은 그다음 점검에서야 보여요. 그래서 복구 결과 끝에 재점검 줄이 붙어요.

• 재점검: 정상 — 끝.
• 재점검: 남은 항목 N건 — /설정 복구 항목:전체 를 한 번 더 실행하세요 — 말 그대로 한 번 더. 두 번째 복구는 자동으로 하지 않아요.
• … · 복구 불가 M건은 /설정 점검에서 확인 — 봇이 못 고치는 항목이 남음. 점검에서 이유를 보고 손으로 처리.

[자동 수정 대상] 표시는 봇이 다시 시작할 때 조정에서 알아서 고치는 항목이에요(대기 역할 누락, 운영진 재계산, 서버 밖 사용자 탈퇴 반영, 신청 카드 재게시). 지금 고치려면 /설정 복구.

근거: 설계 6장·8.1, decisions 26·30 (M8 수동 테스트에서 대기 역할 삭제 후 복구)

#봇-로그에 「⚠️ 봇이 관리하는 역할(채널)이 삭제됐어요」가 떠요. 봇은 자동으로 다시 만들지 않아요.

• 시스템 역할·카테고리·채널(관리자, 운영진, 인증됨,대기, #대기실, #봇-로그 등): /설정 점검 →/설정 복구로 다시 만들어요. 위의 「두 번」 경우가 자주 생겨요.
• 무리·게임의 역할·카테고리·채널: 복구 불가예요. /그룹 삭제 후 /그룹 생성(게임은/게임 삭제 후 /게임 생성).
• 봇 역할: 봇을 다시 초대한 뒤 /설정 점검.

/그룹 삭제·/게임 삭제로 봇이 지운 것은 경고하지 않아요. #사진·라운지·#운영-회의은 ID로 추적하지 않아 경고 대신 점검이 보고해요.

근거: 설계 4.1·8.1, decisions 28

봇이 감사 로그에서 알아채고 그 사람을 제거됨(REMOVED)으로 기록해요. 사유는 「디스코드에서 직접 추방: 입력한 사유」, 실행자는 추방한 사람. #봇-로그에 「⚠️ 봇 명령을 거치지 않은 추방」 경고가 떠요.

되도록 /멤버 제거를 쓰세요. 사유를 남기고, 열린 신청을 취소하고, 추방까지 한 번에 해요. 서버를 이미 떠난 사람에게 쓰면 추방 없이 기록만 바꿔서 재입장 때 자동 복구를 막아요.

#봇-로그에 「감사 로그를 읽지 못해 탈퇴(LEFT)로 기록했어요 … 봇 역할의 「감사 로그 보기」 권한을 켜 주세요」가 떴다면, 추방이 그냥 탈퇴로 기록된 거예요. 그대로 두면 다시 들어올 때 자동 복구돼요. 권한을 켜고, 그 사람에게 /멤버 제거를 해 두세요.

근거: 설계 3.2·4.1, decisions 25·28·30 (M8 수동 테스트)

스스로 나갔던 인증 멤버 → 자동 복구

인증됨, 소속 무리의 역할, 닉네임 이름 (별명)을 되돌리고 #봇-로그에 그 무리 담당을 멘션해 알려요. 삭제된 무리의 역할은 건너뛰어요. 담당 역할은 복구하지 않아요 — 다시 맡기려면 /그룹 담당 추가. 닉네임을 못 바꾼 경우(봇보다 높은 역할)는 로그에 적혀요.

신청 전·신청 중에 나갔던 사람 → 처음처럼 대기

대기를 받고 #대기실 안내가 나가요. 거절 횟수와 재신청 대기 시간은 그대로라 나갔다 들어와서 우회할 수 없어요.

제거됨(REMOVED) → 대기 + 경고 카드

자동 복구 없이 대기를 받고, #승인-대기에 「⚠️ 이전에 제거된 멤버가 다시 입장했어요」 카드(제거 사유·제거자·시각·이전 거절 횟수)가 떠요. 거절 횟수는 0으로 돌아가 다시 신청할 수 있어요. 받아 줄 생각이 없으면 /멤버 제거.

근거: 설계 3.2·4.2, decisions 15·28 (M8 수동 테스트)

리마인더 — 매시 정각, #대기실

신청하지 않은 대기 멤버에게 입장(거절됐으면 마지막 거절) 뒤 1일·3일째에 「아직 합류 신청이 접수되지 않았어요」를 멘션해요. 봇이 꺼져 있다 켜져도 지난 날짜를 몰아 보내지 않고 가장 큰 날짜 하나만 보내요. 거절 2회(신청 불가), 재신청 대기 중, 서버에 없는 사람은 건너뛰어요. #봇-로그에는 남지 않아요.

누가 받았는지는 /대기 목록의 「리마인드 1일·3일」 또는 「리마인드 없음」으로 봐요.

일일 감사 — 매일 09:00, #봇-로그

/설정 점검과 같은 형식이에요. 「일일 감사: 정상」이면 문제 없음. 항목이 있으면 번호대로/설정 복구. 일일 감사는 보고만 하고 아무것도 고치지 않아요([자동 수정 대상]도 재시작 때까지 그대로).

시작 시 조정 — 봇이 켜질 때, #봇-로그

「조정 결과: 정상」, 또는 「자동 수정:」(고친 것)과 「확인 필요:」(/설정 점검 → /설정 복구) 목록.

기다리지 않고 지금 돌리기(소유자)

테스트 서버에서 리마인더를 바로 보려면 봇 쪽에서 pnpm seed:test --reminder-days 0(되돌리기--reminder-days "1,3"). 실행 뒤 출력의 「저장된 값」 줄로 실제 값을 확인하세요. M7 테스트에서 정각이 오기 전에 다른 실행이 값을 되돌려 리마인더가 안 간 적이 있어요. PowerShell에서는 쉼표 목록을 따옴표로 감싸야 그대로 전달돼요.

근거: 설계 8.1~8.4, decisions 26·27 (M7 수동 테스트 9)

1. 서버 멤버 목록에서 봇이 온라인인지 봐요. 명령 목록에 봇 명령이 아예 없으면 명령 등록이 안 된 것 —pnpm deploy-commands.
2. 배포 서버에서 컨테이너 상태를 봐요. 봇은 디스코드에 연결돼 있을 때만 30초마다 하트비트를 갱신하고, 120초 넘게 멈추면 unhealthy예요.
   docker compose ps복사
3. 로그를 봐요. 정상이면 「디스코드 로그인 완료」 다음에 조정 결과가 나와요. 「GUILD_ID 서버에 봇이 없습니다」면 봇이 그 서버에 초대되지 않은 것.
   docker compose logs --tail 200복사
4. 연결이 5분(WATCHDOG_MINUTES) 넘게 안 되면 봇이 스스로 종료하고 재시작 정책이 다시 띄워요. unhealthy만으로는 Docker가 재시작하지 않으니, 로그가 멈춰 있고 unhealthy면 직접 재시작해요.
   docker compose restart복사
5. 명령은 되는데 역할·닉네임 변경이 실패하고 #봇-로그에 50013(권한 부족)이 보이면, 봇 역할이 대상 역할·멤버보다 낮거나 권한이 빠진 거예요. 봇 역할을 맨 위로 올리고 /설정 점검.

근거: 설계 10·12장, README 배포 절

DB는 SQLite 파일 하나(data/gatekeeper.db)예요. 배포 호스트의 crontab으로 매일 04:00에sqlite3 .backup(봇이 돌고 있어도 일관된 사본)을 만들고 14일 보관해요. 주 1회 외부로 복사하는 방법은 배포 대상과 함께 M9에서 정해요.

복원

켜지면 시작 시 조정이 백업 이후 달라진 것을 자동 수정하거나 #봇-로그에 보고해요. 보고된 항목은/설정 점검 → /설정 복구.

근거: 설계 12장, README 백업·복구 절