BookOasis에 저장된 진행 기록을 이용해 사용자별 최근 도서 열람·오디오북 청취·비디오북 시청 활동과 진행률을 보여주는 플러그인입니다. 사이드바 전체 화면과 선택적으로 켤 수 있는 공통 데스크 카드를 함께 제공합니다.
| 항목 | 값 |
|---|---|
| 플러그인 버전 | 1.5.2 |
| 플러그인 ID | activity |
| 클래스 | ActivityMetadataProvider |
| 모듈 | plugins.metadata.activity.activity |
| 유형 | 읽기 전용 카테고리 UI 및 선택형 데스크 위젯 |
| 확인한 BookOasis 버전 | 2.8.4 (소스 계약 및 로컬 API 테스트 기준) |
| 문서 작성일 | 2026-10-02 |
이 플러그인은 BookOasis의 권장 폴더형 플러그인 구조와 PluginDatabaseGateway를 사용합니다. BookOasis 공통 UI나 코어 파일을 수정하지 않습니다.
- 사용자명 기준으로 활동을 구분합니다.
- 사용자별 최근 열람 도서를 마지막 열람 시각 내림차순으로 표시합니다.
- 도서 제목, 표지, 현재 페이지, 전체 페이지, 진행률과 마지막 열람 시각을 표시합니다.
- 진행 중과 완독 상태를 구분하고 제한적 HTML이 지원되는 화면에서는 색상으로 강조합니다.
- 제목이나 표지를 클릭하면 BookOasis 도서 상세 화면으로 이동합니다.
- 상세 이동 전에 일반·성인 서재 문맥을 동기화해 같은 숫자 ID를 가진 다른 서재 도서가 열리지 않도록 합니다.
- 사용자별 표시 제한을 적용하므로 한 사용자의 기록이 다른 사용자를 밀어내지 않습니다.
- Redis에 아직 쌓여 있는 최신 진행률과 첫 열람 기록을 DB 조회 결과에 병합합니다.
- 열람 기록이 없으면
아무도 읽은 책이 없습니다.안내를 표시합니다. - 활동 조회 중 오류가 발생하면 무한 로딩 대신 재시도 안내를 표시하고 서버 로그에 원인을 기록합니다.
- 관리자 세션에서만 전체 사용자 활동 데이터를 반환합니다.
- 코어의 관리자 전용 선언을 적용해 일반 사용자에게 메뉴·위젯을 노출하지 않습니다.
- 일반·성인 도서는 코어의 완독 상태와 EPUB 진행률을 반영하며 Redis의 최신 보류 기록도 병합합니다.
- BookOasis 2.8.4 이상에서 조회 실패를 관리자 알림센터의 문제 카드로 표시하고, 같은 서재를 정상 조회하면 자동 해결합니다. 구버전에서는 기존 오류 안내와 로그를 사용합니다.
- 일반 서재, 성인 서재, 오디오북과 비디오북 활동을 화면 상단에서 전환합니다.
- BookOasis의 모든 세션에서
사용자 활동카테고리를 노출합니다. - 사용자·기간·정렬 필터와 진행률 바가 있는 반응형 풀페이지 화면을 제공합니다.
- 상단 요약 카드에 활동 사용자, 전체 기록, 진행 중과 완독을 구분하는 아이콘을 표시합니다.
- 도서 컨텍스트 메뉴에서 해당 도서의 사용자별 열람 활동을 요약합니다.
activity는 category_tab 계약을 사용하는 좌측 사이드바의 사용자 활동 카테고리입니다. 전체 활동 요약, 사용자별 섹션과 해당 사용자의 최근 도서를 표시합니다.
1.5.0부터 별도 Activity Desk 설치 없이 플러그인 데스크에 표시 옵션으로 최근 활동 카드도 사용할 수 있습니다. 데스크에는 전체 요약과 사용자별 최근 최대 N건을 표시하며, 선택된 기록은 전체 최신순으로 정렬합니다. 예를 들어 N이 10이고 사용자가 2명이면 각 사용자에게 최대 10건씩 표시합니다. 옵션을 꺼도 사이드바 전체 화면은 유지됩니다.
별도 activity_desk 플러그인은 폐기 예정입니다. 데스크 기능은 Activity 1.5.0에 통합되었으므로 별도 Desk를 새로 설치하거나 업데이트할 필요가 없습니다. 이후에는 이 activity 저장소를 사용하세요.
activity를 1.5.0으로 업데이트하고 BookOasis 서버를 재시작합니다.- 기존
사용자 활동 데스크(activity_desk) 플러그인을 비활성화합니다. - 일반 서재의
환경설정 > 플러그인 설정 > 사용자 활동에서플러그인 데스크에 표시를 켜고공통 데스크 사용자별 표시 권수를 지정한 뒤 저장합니다. - 플러그인 데스크를 다시 열거나 새로고침합니다. 업데이트 후 옵션 변경만으로는 서버 재시작이 필요하지 않습니다.
두 플러그인을 동시에 켜면 카드가 중복됩니다. 기존 Desk 파일·설정은 자동 삭제하거나 변경하지 않으며, 기존 표시 권수 설정도 유지합니다.
| 키 | UI 유형 | 기본값 | 설명 |
|---|---|---|---|
SHOW_IN_DESK |
checkbox | false |
공통 데스크 카드 노출 여부. 꺼도 사이드바는 유지 |
ITEMS_PER_USER |
number | 20 |
사이드바 카테고리 화면에 사용자 한 명당 표시할 최근 도서 수. 허용 범위 1~100 |
DESK_ITEM_LIMIT |
number | 5 |
공통 데스크에 사용자별로 표시할 최신 활동 수. 사용자당 허용 범위 1~20이며, 카테고리 화면의 ITEMS_PER_USER와 별도로 적용 |
DEFAULT_SORT |
select | recent |
최근 열람순, 진행률 높은 순 또는 사용자명순 |
SHOW_COMPLETED |
checkbox | true |
완독 도서 표시 여부 |
SHOW_USER_SUMMARY |
checkbox | true |
사용자별 전체 기록 요약 표시 여부 |
설정은 환경설정 > 플러그인 설정 > 사용자 활동에서 저장합니다. 통합 데스크의 노출 여부와 표시 권수는 일반 서재에서 저장한 Activity 설정을 모든 서재에 공통 적용합니다. 활동 데이터는 현재 선택한 서재 DB에서 조회합니다.
최종 폴더 구조는 다음과 같습니다.
plugins/metadata/
└── activity/
├── __init__.py
├── activity.py
├── index.html
├── style.css
├── script.js
└── VERSION
BookOasis의 plugins/metadata/에서 다음 명령을 실행합니다.
git clone https://github.com/colaiuta77/activity.git activity- BookOasis 서버를 재시작합니다.
환경설정 > 플러그인 설정에서사용자 활동을 활성화합니다.- 좌측 사이드바의
사용자 활동카테고리를 확인합니다.
업데이트할 때는 BookOasis의 plugins/metadata/에서 다음 명령을 실행합니다.
git -C activity pull --ff-only버전 1.0.2부터 BookOasis의 update_manifest 계약과 VERSION 파일을 지원합니다. 1.1.0부터 업데이트 버튼이 Python 파일뿐 아니라 풀페이지 UI의 index.html, style.css, script.js도 함께 갱신합니다.
1.0.3 이하에서 바로 업데이트하면 구버전 매니페스트가 UI 파일을 내려받지 못할 수 있습니다. 이 경우 저장소에서 git pull --ff-only로 한 번 갱신한 뒤 이후 자동 업데이트를 사용하세요.
1.0.1 이하 설치본에는 업데이트 선언과 VERSION 파일이 없으므로 위 git pull 방식으로 1.0.2 이상을 한 번 설치해야 합니다. 이후에는 GitHub 버전이 현재 버전보다 높을 때만 자동 업데이트가 실행됩니다.
Docker 환경에서는 BookOasis 소스가 연결된 호스트 볼륨 또는 컨테이너의 동일한 경로에 설치해야 합니다. BookOasis 업데이트 후에도 플러그인 폴더가 유지되는지 확인하세요.
users,user_progress,books테이블을 DB Gateway를 통해 읽기 전용으로 조회하며 SQLite와 MariaDB를 모두 지원합니다.- 오디오북은
audiobook_progress,audiobooks의 청취 시간·진행률·완청 상태를 읽기 전용으로 조회합니다. - 비디오북은
video_progress,videos,video_episodes의 현재 에피소드·진행률·시청 완료 상태를 읽기 전용으로 조회합니다. - 일반·성인·오디오북·비디오북 사용자명은 로그인 사용자 기준 DB인 일반 DB에서 사용자 ID로 매핑합니다.
- BookOasis 1.2.1의
sync:progress:pending과user:progressRedis 키를 읽기 전용으로 병합합니다. - Redis를 사용할 수 없거나 데이터가 손상된 경우 해당 항목을 건너뛰고 DB 결과를 사용합니다.
- 삭제된 도서는 활동 목록에서 제외합니다.
- 위젯 데이터 요청 시 Flask 세션의 관리자 역할을 다시 확인합니다.
- 사용자명은 제한적 HTML 필드에 넣기 전에 HTML 이스케이프합니다.
- 메타데이터 검색과 적용은 지원하지 않습니다.
- 이 화면은 실시간 접속 목록이 아니라 DB
user_progress와 아직 flush되지 않은 Redis 진행률을 기준으로 한 최근 활동입니다. - BookOasis가 저장하지 않는 IP, 브라우저, 운영체제, 클라이언트 종류와 온라인 상태는 표시할 수 없습니다.
- 카테고리 메뉴와 풀페이지 UI는
category_tab계약이 있는 BookOasis 1.0.7 이상이 필요합니다. - 동적 사용자·도서 데이터는 임의 HTML로 삽입하지 않고 안전한 DOM
textContent로 렌더링합니다. - BookOasis의 플러그인 계약 또는 DB 스키마가 변경되면 호환성 업데이트가 필요할 수 있습니다.
- 동적 데스크 노출은 BookOasis 2.5.5의 클래스 속성 기반 플러그인 탐색 방식으로 검증했습니다. 설정을 읽지 못하면 데스크 카드는 숨기며 사이드바 기능은 유지합니다.
python -m py_compile __init__.py activity.py
node --check script.js사용자별 데스크 표시와 BookOasis 2.5.5 코어 API 계약은 별도 개발 환경의 회귀 테스트로 검증합니다. 배포 저장소에는 테스트·캐시·개발 메모를 포함하지 않습니다.
- BookOasis 2.8.4의
admin_only선언과 관리자 문제 카드 계약 적용. - 조회 실패를 빈 활동 목록과 구분하고, 서재별 문제를 정상 조회 시 자동 해결. 알림에 개인 독서 내역과 원문 DB 오류를 노출하지 않음.
- 일반·성인 도서의
is_completed와 EPUBlast_epub_percent를 DB 및 Redis에서 반영해 상태·진행률·필터·데스크·도서 활동 요약 일치. - 기존 Activity Desk도 Activity 공통 구현을 상속해 동일하게 적용. 통합 Activity 사용 시 별도 Desk 비활성화 권장.
- 제목·요약·사용자 카드 외곽선에 테두리색 92%와 글자색 8%를 혼합하고 옅은 그림자를 적용해 카드 구분 개선.
- 기본 어두운 테마에서 카드 배경을 3% 밝게 조정.
- 사용자 섹션 패딩을 20px에서 16px, 제목 아래 여백을 16px에서 12px, 섹션 간격을 24px에서 16px로 축소.
- 내부 도서 카드 크기와 활동 조회 기능은 유지.
- Activity에 공통 플러그인 데스크의 최근 활동 요약 기능 통합.
- 기본 OFF인
플러그인 데스크에 표시옵션 추가. 설정 변경 후 목록을 다시 조회하면 카드 전체를 노출하거나 숨김. - 사이드바의
view=category요청과 데스크 요약 요청을 구분해 기존 전체 목록·필터 유지. - 데스크 활동을 전체 최신 N건 대신 사용자별 최근 최대 N건으로 선택하고, 선택된 기록은 전체 최신순으로 표시.
공통 데스크 사용자별 표시 권수를 사이드바 표시 권수·정렬과 별도로 적용해 다른 사용자의 기록이 밀려나거나 미리 잘리지 않도록 개선.- 전체 사용자·활동 합계를 유지하고 데스크 요약에 사용자별 제한과 실제 표시 건수를 안내.
- 일반·성인·오디오북·비디오북을 지원하며 관리자 권한 검사와 DB Gateway 사용 유지.
- 별도 Activity Desk 폐기 예정 및 Activity 1.5.0으로의 전환 안내 추가. 기존 플러그인·설정 자동 변경 없음.
- BookOasis 2.1.4의 비디오북 진행 기록을 사용자 활동에 추가.
- 비디오북의 현재 에피소드, 전체 에피소드, 진행률, 시청 완료 상태와 전용 표지를 표시.
- 비디오북 카드 선택 전에 서재 타입을
video로 동기화해 비디오북 상세 화면으로 이동. category_tab.sessions를all로 명시해 모든 BookOasis 세션에 사용자 활동 메뉴를 노출.- 비디오 진행률은 MariaDB DB Gateway에서 직접 읽고 일반 DB의 사용자 ID·이름과 매핑.
- 오디오북·비디오북 세션에서는 일반 도서 전용 컨텍스트 메뉴를 숨겨 잘못된 테이블 조회를 방지.
- BookOasis 1.8.7의 SQLite·MariaDB 공용
PluginDatabaseGateway계약에 맞춰 활동 조회 SQL을 정리. - MariaDB에서 지원하지 않는
COLLATE NOCASE를 제거하고 사용자 정렬을 Python의 대소문자 비구분 정렬로 일원화. - 일반·성인·오디오북의 진행 기록은 각 서재 DB에서 읽고 사용자 ID·이름은 일반 DB에서 공통 매핑하도록 변경.
- Redis에만 남은 첫 열람 도서 조회도 서재 DB의
users테이블에 의존하지 않도록 수정. - 최신 BookOasis가 전달하는 서재 타입을 먼저 정규화한 뒤 Gateway와 플러그인 설정을 조회하도록 보강.
- 일반·성인·오디오북과 새로고침 버튼 크기를 독서 통계센터 버튼 규격과 동일하게 조정.
- 오디오북 활동 카드 선택 시 플레이어를 즉시 실행하지 않고 오디오북 상세 페이지로 이동.
- 상세 이동 전에 BookOasis의 현재 서재 타입을 오디오북으로 동기화해 올바른 작품을 조회.
- 오디오 재생은 상세 페이지의 재생 버튼에서 시작하도록 화면 역할을 분리.
- BookOasis 1.7.4에서 오디오 DB에 사용자 계정이 동기화되지 않아 청취 기록이 누락되는 문제 우회.
- 오디오 진행률은 오디오 DB에서 읽고 사용자 ID·이름은 일반 DB에서 매핑하도록 변경.
- 일반 DB에도 없는 고아 사용자 ID는 활동을 숨기지 않고
사용자 #ID로 표시.
- 일반·성인 도서 상세 이동 전에 BookOasis의 현재 서재 타입을 동기화하도록 수정.
- 서로 다른 서재에서 같은 숫자 도서 ID를 사용할 때 엉뚱한 도서나 오디오북이 열리는 문제 수정.
- 활동 응답에 원본
db_type을 포함하고 오디오북 이동을 응답 타입 기준으로 분기.
- 일반 서재, 성인 서재와 오디오북 활동 전환 버튼 추가.
- 서재 전환 시 선택한 DB의 활동·사용자·요약 정보를 다시 조회.
- 오디오북의 최근 청취 기록을
audiobook_progress에서 조회하고 청취 시간·진행률·완청 상태로 표시. - 오디오북 카드 선택 시 BookOasis 오디오 플레이어를 여는 이동 계약 적용.
- 활동 사용자, 전체 기록, 진행 중과 완독 요약 카드에 의미별 아이콘과 색상 추가.
- 모바일 화면에서 서재 버튼을 세로로 재배치하고 요약 카드를 2열로 표시.
- BookOasis 1.7.0의 최신 독서 통계 서재 전환 계약과 호환성 확인.
- 일반·성인·오디오북 전환과 요약 아이콘이 적용된 실제 화면으로 README 스크린샷 갱신.
- 좌측 사이드바의 1등 시민
사용자 활동카테고리와 풀페이지 UI 추가. - 사용자·기간·정렬 필터, 전체 요약 카드와 사용자별 진행률 카드 추가.
- 진행률 바, 진행 중·완독 배지, 반응형 모바일 레이아웃과 테마 CSS 변수 적용.
- 공통 데스크 표시 수, 기본 정렬, 완독 및 사용자 요약 표시 설정 추가.
- 도서 컨텍스트 메뉴의 사용자별 열람 활동 요약 추가.
- 구조화된 활동·요약·화면 설정 응답과 UI 자산 자동 업데이트 계약 추가.
- 실제 BookOasis 전용 카테고리 화면으로 README 스크린샷 갱신.
- 전체 사용자에게 열람 기록이 없을 때 명시적인 빈 상태 안내 추가.
- 활동 조회 실패 시 로딩 상태가 남지 않도록 오류 안내와 서버 로그 기록 추가.
- BookOasis 1.3.0 기준 호환성 확인 및 빈 상태 회귀 테스트 추가.
- BookOasis 플러그인 자동 업데이트용
update_manifest추가. - 공식 규격의
VERSION파일과plugin version키 추가. - GitHub
main의 런타임 파일만 갱신하도록 업데이트 범위 제한.
- 저장소 루트를
plugins/metadata/activity에 직접 clone할 수 있는 단일 플러그인 구조로 변경. - Activity Desk를 별도 저장소로 분리.
- BookOasis 1.2.1의 Redis 비동기 진행률 저장 방식 지원.
- SQLite에 아직 반영되지 않은 최신 페이지와 마지막 열람 시각을 Redis pending 데이터로 보정.
- Redis에만 존재하는 첫 열람 도서도 사용자별 최근 활동과 전체 건수에 포함.
- Redis 데이터 병합 후 사용자별 날짜 내림차순과 표시 권수 제한을 다시 적용.
- Redis 미사용, 연결 실패와 손상된 JSON에서 기존 SQLite 조회로 안전하게 폴백.
- 사용자별 최근 독서 활동 전용 탭 추가.
- 공통 플러그인 데스크용 세로 스크롤 위젯 추가.
- 사용자별 표시 권수 설정과 날짜 내림차순 정렬 추가.
- 제목과 표지의 도서 상세 이동 계약 지원.
- 전체 및 사용자별 요약과 진행·완독 상태 표시 추가.
- 제한적 HTML 강조와 사용자명 HTML 이스케이프 적용.
- 관리자 세션 확인과 삭제 도서 제외 처리 추가.
이 저장소의 LICENSE를 따릅니다.