충북교구레드플레그/효관 자동수집 코드리뷰 문서 원본 보기

{{DISPLAYTITLE:충북교구레드플레그/효관 자동수집 코드리뷰}}
= 충북교구레드플레그/효관 자동수집 코드리뷰 =

이 문서는 2026년 6월 23일 작성한 효관 출석자료 자동수집 코드의 설명과 코드리뷰 기록이다. 계정 ID와 비밀번호 원문은 문서에 기록하지 않는다.

== 대상 코드 ==

{| class="wikitable" style="width:100%;"
|-
! 항목 !! 위치
|-
| 자동수집기 || <code>/home/ruyjin/.openclaw/workspace/cbred_admin/hyogwan_collect.py</code>
|-
| 설정 파일 || <code>/home/ruyjin/.openclaw/workspace/cbred_admin/cbred_settings.json</code>
|-
| 관리자 화면 || <code>http://172.30.1.36/cbred</code>
|-
| 내부 홈페이지 코드 || <code>/home/ruyjin/.openclaw/workspace/church_homepage/app.py</code>
|-
| 계정 파일 || <code>/home/ruyjin/ffwpu.txt</code>
|}

== 구현 요약 ==

자동수집기는 Python 스크립트에서 <code>agent-browser</code> CLI를 호출해 효관 로그인, 출석조회 화면 이동, 엑셀/다운로드 버튼 탐색을 수행한다. 효관 계정은 코드에 직접 저장하지 않고 <code>ffwpu.txt</code> 형식의 외부 파일에서 읽는다.

기본 흐름은 다음과 같다.

# <code>cbred_settings.json</code>에서 로그인 URL, 출석 경로, 다운로드 폴더, 로그 폴더를 읽는다.
# <code>ffwpu.txt</code>에서 <code>ID:</code>, <code>PW:</code> 값을 읽는다.
# <code>agent-browser</code> 세션을 열고 효관 로그인 화면에 접속한다.
# 여러 후보 selector로 아이디/비밀번호 입력칸을 찾아 값을 입력한다.
# 로그인 버튼을 누르거나 Enter 키로 로그인한다.
# 출석조회 경로로 이동한다.
# <code>엑셀</code>, <code>Excel</code>, <code>다운로드</code> 버튼을 찾아 파일 다운로드를 시도한다.
# 실패 시 현재 URL, 접근성 snapshot, body HTML, screenshot을 로그 폴더에 저장한다.

== 설정 구조 ==

<code>cbred_settings.json</code>의 핵심 필드는 다음과 같다.

{| class="wikitable" style="width:100%;"
|-
! 필드 !! 의미
|-
| <code>enabled</code> || 자동수집 사용 여부
|-
| <code>credential_file</code> || 효관 계정 파일 경로
|-
| <code>login_url</code> || 효관 로그인 URL
|-
| <code>attendance_path</code> || 출석조회 상대경로 또는 전체 URL
|-
| <code>download_dir</code> || 다운로드 원자료 저장 폴더
|-
| <code>log_dir</code> || 실행 로그와 실패 진단 자료 저장 폴더
|-
| <code>church_scope</code> || 수집 범위 메모
|-
| <code>lookback_weeks</code> || 레드플레그 판별 주차
|-
| <code>browser_session</code> || agent-browser 세션명
|}

== 관리자 화면 ==

내부 홈페이지에는 <code>/cbred</code> 관리자 화면을 추가했다. 이 화면에서는 계정 파일 경로, 로그인 URL, 출석 경로, 다운로드 폴더, 로그 폴더, 운영 일정을 수정할 수 있다. 실제 ID/PW 원문은 화면에 표시하지 않는다.

관리자 화면 접근은 기존 내부 홈페이지 관리자 쿠키를 사용한다. 미로그인 사용자는 <code>/admin-login?next=/cbred</code>로 이동한다.

== 보안 검토 ==

{| class="wikitable" style="width:100%;"
|-
! 항목 !! 검토 결과
|-
| 계정 하드코딩 || 코드에 ID/PW를 직접 넣지 않았다.
|-
| 계정 파일 권한 || <code>/home/ruyjin/ffwpu.txt</code> 권한을 <code>600</code>으로 낮췄다.
|-
| 관리자 화면 노출 || 화면에는 계정 파일 경로만 표시하고 원문 비밀번호는 표시하지 않는다.
|-
| 로그 민감정보 || 현재 로그에는 명령 결과와 화면 진단이 남을 수 있으므로 효관 화면에 개인정보가 보이면 로그 폴더 접근을 제한해야 한다.
|-
| 외부 발송 || 자동수집 코드는 문자/메일/카카오 발송을 수행하지 않는다.
|}

== 코드리뷰 결과 ==

=== 좋은 점 ===

* 계정 정보를 코드에 직접 넣지 않고 외부 파일에서 읽도록 분리했다.
* 수집 실패 시 진단 파일을 남기므로 효관 화면 변경에 대응할 수 있다.
* 다운로드 폴더와 로그 폴더를 설정으로 분리했다.
* <code>--dry-run</code> 옵션으로 다운로드 버튼을 누르기 전에 로그인과 화면 상태를 확인할 수 있다.
* 내부 홈페이지 <code>/cbred</code>에서 운영자가 설정을 수정할 수 있다.

=== 주의할 점 ===

* 효관 화면의 실제 input name, 로그인 버튼, 엑셀 버튼이 현재 추정과 다르면 dry-run 후 selector 보정이 필요하다.
* <code>agent-browser</code> CLI가 서버에 설치되어 있어야 한다.
* 자동수집 성공 후 내려받은 엑셀 구조를 파싱하는 코드는 아직 별도 구현이 필요하다.
* 로그에는 화면 HTML과 screenshot이 저장될 수 있으므로 운영 후 로그 보존 기간과 접근 권한을 정해야 한다.
* 수요일 20:10 스케줄 등록은 아직 시스템 타이머/cron으로 연결하지 않았다.

== 남은 작업 ==

# 효관 실제 로그인 dry-run을 실행해 로그인 selector와 출석조회 경로를 확인한다.
# 실제 다운로드 파일이 생성되는지 확인한다.
# 다운로드한 엑셀/CSV 컬럼 구조를 분석한다.
# 4주 연속 미출석 판별 파서를 작성한다.
# 수요일 20:10 자동 실행 스케줄을 등록한다.
# 실패 시 사무장/관리자에게 알림을 보내는 작업을 붙인다.

== 수동 실행 명령 ==

<pre>
python3 /home/ruyjin/.openclaw/workspace/cbred_admin/hyogwan_collect.py --dry-run
python3 /home/ruyjin/.openclaw/workspace/cbred_admin/hyogwan_collect.py
</pre>

== 결론 ==

현재 코드는 자동수집 MVP의 첫 단계로 볼 수 있다. 로그인, 화면 이동, 다운로드 시도, 실패 진단 저장까지는 준비됐지만, 실제 효관 화면 검증과 다운로드 파일 파싱은 아직 남아 있다. 따라서 운영 투입 전에는 반드시 dry-run과 실제 다운로드 테스트를 거쳐야 한다.

[[분류:프로젝트]]
[[분류:충북교구]]
[[분류:코드리뷰]]