BookOasis 일반·성인 도서, 오디오북과 비디오 라이브러리를 백그라운드에서 미리 집계하고, 저장된 스냅샷을 ECharts 기반 대시보드로 빠르게 보여주는 독립 카테고리 플러그인입니다.
| 항목 | 값 |
|---|---|
| 플러그인 버전 | 1.6.0 |
| 플러그인 ID | statistics |
| 클래스 | StatisticsMetadataProvider |
| 모듈 | plugins.metadata.statistics.statistics |
| 유형 | 백그라운드 사전 집계형 라이브러리 통계 카테고리 UI 제공자 |
| 확인한 BookOasis 버전 | 2.4.7 |
| 확인한 업데이트 계약 | BookOasis 2.4.8 (eb1d0be) |
| 확인한 독서 로그 계약 | BookOasis 2.4.8의 user_reading_log |
| 확인한 관리자 알림 계약 | BookOasis 2.8.4 (3aaaaa0), 선택 지원 |
| 지원 DB | SQLite, MariaDB |
| 현재 지원 세션 | general, adult, audiobook, video |
| 문서 작성일 | 2026-10-02 |
이 플러그인은 BookOasis의 폴더형 플러그인 구조, PluginDatabaseGateway, category_tab, start_background_service()와 스캔 완료 훅을 사용합니다. BookOasis 공통 UI나 코어 파일을 수정하지 않습니다.
BookOasis 2.4.7의 최신 plugins/metadata/base.py에 포함된 start_background_service() 계약이 필요합니다.
- BookOasis 시작 후 네 세션의 통계를 독립된 백그라운드 런타임에서 사전 집계합니다.
- 통계 화면을 열 때 원본 미디어 테이블을 다시 집계하지 않고 현재 세션의 마지막 정상 스냅샷을 즉시 사용합니다.
- 기본 6시간 주기 자동 갱신을 제공합니다.
- 일반·성인 도서와 오디오북은 신규 항목 스캔 감지 후 45초 debounce를 적용해 재집계를 예약합니다.
- 상단
통계 갱신버튼으로 즉시 백그라운드 재집계를 요청할 수 있습니다. - BookOasis
2.8.4이상에서는 집계·저장 및 백그라운드 시작 실패를 관리자 문제 카드로 알리고, 재시도와 정상 복구 시 자동 해결을 지원합니다. - 전체 보관함과 개별 보관함별 통계를 같은 스냅샷에서 전환합니다.
- 도서 세션은 도서·저자·시리즈·출판사 중심 KPI를, 오디오북과 비디오는 항목·트랙/에피소드·재생시간 중심 KPI를 제공합니다.
- 포맷 분포와 포맷별 저장 공간을 도넛 차트로 표시합니다.
- 메타데이터 평균 완성도, 점수 분포와 누락 현황을 제공합니다.
- 보관함별 메타데이터 완성도 Heatmap은 최대 15개 보관함을 한 화면에 표시하고 내부 세로 스크롤을 제공합니다.
- 상위 60개 장르/태그 분포 Treemap과 장르 동시 출현 Chord를 제공합니다. 태그는 일반·성인 도서에서 선택합니다.
- 상위 저자, 상위 시리즈와 상위 출판사를 표시합니다.
- 항목 추가 추이, 출판/출시 시대, 연도 타임라인과 최근 포맷 비중 변화를 제공합니다.
- 페이지·트랙·에피소드 수 분포와 용량이 큰 항목을 표시하며 저장 공간 축은 MB/GB 단위로 자동 변환합니다.
- 용량 상위 100개 트리맵에서 포맷별 묶음 또는 구분 없는 용량순을 선택하며 기존 용량 막대 카드도 유지합니다.
- 상단
카드 설정에서 요약 카드·차트·독서 달력을 각각 표시하거나 숨길 수 있습니다. - Muuri 기반 카드 드래그 정렬, 빈 공간 채우기와 레이아웃 초기화를 제공합니다.
- 카드 순서는 세션별로 브라우저
localStorage에 저장합니다. - 일반 카드는 1단, Heatmap·장르 연관성은 2단 높이를 사용해 재배치 시 정렬을 맞춥니다. 장르/태그 분포와 용량 트리맵은 가로 2열 폭·1단 높이, 용량 막대 카드는 1열 폭·1단 높이입니다.
- 모든 카드 헤더는 제목과 구분선 사이의 최소 간격을 유지합니다.
- 일반·성인 도서 화면 맨 아래에 로그인한 사용자의 올해 독서 달력을 전체 너비로 표시합니다.
- 올해 일별 읽은 권수를 월~일로 합산한
요일별 독서 패턴레이더 카드를 제공합니다. - BookOasis 테마 CSS 변수를 사용해 다크/라이트 계열 테마에 맞춰 표시합니다.
statistics는 category_tab 계약을 사용하는 좌측 사이드바의 통계 카테고리입니다.
상단에는 전체/개별 보관함 선택, 마지막 집계 시각, 집계 소요 시간, 수동 갱신, 레이아웃 초기화와 카드 설정이 표시됩니다. 그 아래에는 KPI와 차트 카드가 배치됩니다.
카드 우측 상단의 그립 아이콘을 드래그하면 원하는 순서로 재배치할 수 있습니다. 데스크톱에서는 Muuri masonry 레이아웃을 사용하고, 작은 화면에서는 단일 열에 가깝게 반응형으로 표시합니다.
상단은 사용자 활동·독서 업적과 같은 아이콘형 헤더를 사용하며, 보관함 선택과 갱신·설정 버튼을 함께 배치합니다. 전체 화면의 폭 제한 없이 좌우 여백을 두고 표시하며, 실제 콘텐츠 폭이 1600px 이상이면 작은 카드가 한 줄에 4개 들어갑니다. 그보다 좁으면 기존 반응형 열 수를 사용합니다. 4열에서는 2칸짜리 카드가 전체 폭의 절반을 차지하므로 행 배치와 차트 라벨 밀도가 달라질 수 있습니다. 카드 높이·저장된 순서·표시 설정은 유지합니다.
도서 읽은 날 카드는 드래그 대상에서 제외되어 켜져 있을 때 항상 맨 아래에 표시됩니다. ECharts Calendar Heatmap 예제처럼 하루 칸 높이를 13px로 유지하고, 올해 1~12월을 가로로 펼칩니다. 좁은 화면에서는 달력 안에서 좌우로 스크롤할 수 있습니다.
카드 설정을 열고 각 스위치로 요약 카드와 차트를 켜고 끕니다. 현재 세션에서 지원하는 카드만 설정에 나타나며, 기본값은 모두 표시입니다.
- 선택은 이 브라우저의
localStorage에 일반·성인·오디오북·비디오별로 저장합니다. 다른 브라우저나 기기에 동기화되지는 않습니다. - 숨긴 차트는 배치에서 빠지고 다시 켜면 현재 보관함 데이터로 표시됩니다. 드래그 순서는 숨김 여부와 별도로 보존합니다.
레이아웃 초기화는 카드 순서만 되돌리며 표시 설정은 유지합니다.- 독서 달력과 요일별 독서 패턴은 한 번의 개인 기록 조회를 공유합니다. 두 카드를 모두 숨기면 조회를 멈추고 하나라도 다시 켜면 새로 조회합니다. 공용 라이브러리의 백그라운드 집계는 계속됩니다.
용량이 큰 도서 · 트리맵은 ECharts Disk Usage 예제를 참고했으며 2열 폭·1단 높이를 사용합니다. 좁은 화면에서는 1열 폭으로 맞춰집니다. 카드 오른쪽에서 표시 기준을 선택합니다.
포맷별은 포맷 → 항목 구조입니다. 포맷 영역을 클릭하면 확대되고 아래 경로로 돌아갈 수 있습니다. 상위 제목과 합산 용량은epub · 12.66 GB처럼 한 줄로 표시합니다.용량순은 포맷 구분 없이 큰 항목부터 배치합니다. 면적은 파일 크기에 비례하고 색은 큰 항목일수록 진하게, 작은 항목일수록 옅게 표시합니다. 색 농도는 현재 보관함의 표시 항목 범위 기준입니다.- 모든 세션의 전체/개별 보관함에서 용량 상위 최대 100개를 제공합니다. 전체 디스크나 전체 라이브러리의 용량 비중이 아니며, 막대그래프는 별도 카드에서 상위 50개를 표시합니다.
- 작은 칸은 텍스트를 숨기고 마우스를 올리면 툴팁으로 제목·용량을 보여줍니다. 확대하거나 카드가 넓어지면 표시 가능한 라벨이 다시 나타납니다.
- 선택한 기준은 세션별로 이 브라우저에 저장합니다. 새 버전 적용 후
통계 갱신을 한 번 실행하면 기존 상위 15/20개 스냅샷이 100개로 확대됩니다.
용량이 큰 도서는 기존 일반 카드와 같은 1열 폭·1단 높이로 용량 상위 최대 50개를 표시합니다. 큰 항목부터 10개씩 보이며 차트 위에서 마우스 휠을 굴리거나 오른쪽 세로 스크롤바를 이동해 나머지를 확인합니다. 항목이 10개 이하면 스크롤바를 숨깁니다. 좁은 화면에서는 화면 너비에 맞춰집니다.
기존 상위 100개 스냅샷을 재사용하므로 이 변경에 추가 집계나 DB 변경은 필요하지 않습니다. 막대에 마우스를 올리면 전체 이름과 용량을 확인할 수 있으며 저장 공간 축의 MB/GB 자동 변환도 유지합니다. 좁은 화면에서는 겹치는 축 눈금 글자를 숨깁니다.
분포 카드는 가로 2열 폭·1단 높이이며 상위 최대 60개를 표시합니다. 좁은 화면에서는 1열 폭으로 맞춰집니다. 일반·성인 도서에서는 카드 오른쪽에서 장르 또는 태그를 선택하고, 선택은 세션별로 이 브라우저에 저장합니다. 장르 연관성 카드는 기존 장르 기준을 유지합니다.
작은 영역을 클릭하면 확대되며 하단 경로의 장르 분포 또는 태그 분포를 누르면 전체 보기로 돌아갑니다. 두 표시 기준 모두 작은 칸의 라벨 숨김과 툴팁을 유지하고, 확대 후 공간이 충분해지면 라벨을 다시 표시합니다.
태그는 books.tags를 보관함별로 집계하고 쉼표·세미콜론·파이프로 분리합니다. 한 도서의 같은 태그는 대소문자와 중복 표기를 합쳐 한 번만 셉니다. 작은 칸의 글자는 숨기고 툴팁으로 이름·권수를 표시합니다. 갱신 전 스냅샷에 태그 분포가 없으면 통계 갱신 안내를 표시합니다.
공식 미디어 스키마에 태그 필드가 없는 비디오는 장르만 표시하고, 오디오북은 기존처럼 분포/장르 연관성 카드를 제공하지 않습니다. 다른 세션의 태그를 가져오거나 장르를 태그로 대신 표시하지 않습니다.
| 영역 | 제공 항목 |
|---|---|
| 요약 | 도서 또는 미디어, 트랙/에피소드, 재생시간, 저장 공간, 보관함, 출시 연도, 올해 추가 |
| 포맷 | 포맷 분포, 포맷별 저장 공간, 포맷 비중 변화 |
| 메타데이터 | 평균 완성도, 점수 분포, 누락 현황, 보관함별 Heatmap |
| 장르/태그 | 장르·태그 분포 Treemap(태그는 일반·성인), 장르 동시 출현 Chord |
| 카탈로그 | 세션 데이터에 맞는 상위 저자, 시리즈, 출판사 |
| 시간 | 항목 추가 추이, 출판/출시 시대, 연도 타임라인 |
| 파일/분량 | 페이지·트랙·에피소드 수 분포, 용량이 큰 항목 |
| 내 독서 | 일반·성인 도서의 올해 날짜별 읽은 권수·독서일 수·요일별 독서 패턴 |
도서 메타데이터 완성도는 저자, 출판사, 소개, 장르, 태그, ISBN, 표지, 출간일, 페이지 수와 파일 크기의 존재 여부를 기준으로 계산합니다. 오디오북과 비디오는 해당 세션의 제목, 제작 정보, 출시일, 표지, 재생시간과 트랙/에피소드 수를 사용합니다.
메타데이터 누락 현황은 기존 완성도 집계 결과의 전체 건수 - 채워진 건수로 계산하므로 별도의 원본 전체 스캔 쿼리를 추가하지 않습니다.
- 서버 날짜 기준 올해의
user_reading_log에서 읽은 페이지 증가량이 양수인 로그를 사용합니다. 같은 날짜의 같은 책은 여러 로그가 있어도 한 권으로 셉니다. 완독 권수가 아니라 그날 읽은 도서 수입니다. - 로그인한 사용자 본인의 기록만 조회하며, 현재 일반·성인 세션과 상단 보관함 선택을 따릅니다. 삭제된 도서와 접근 권한이 없는 보관함은 제외합니다.
- 날짜별 읽은 권수를 색상과 툴팁으로 보여 주며 기록이 없는 날은 빈색으로 표시합니다. 오디오북·비디오는 같은 일별 로그 계약이 없어 이 카드를 표시하지 않습니다.
- 개인 기록은 공용 통계 스냅샷에 저장하지 않고, 화면 진입·보관함 전환·상태 갱신·수동 갱신 시 별도로 조회합니다. 조회 실패 시 빈 기록으로 오인하지 않도록 오류를 표시합니다.
- 코어가 DB에 저장한 기록만 반영합니다. Redis에만 남은 진행률은 DB 반영 후 표시되며, 기록되지 않은 과거 독서일은 복원하지 않습니다.
기본 1열 폭·1단 높이의 ECharts Radar 카드입니다. 월~일 7개 축에 서버 날짜 기준 올해의 일별 읽은 권수를 합산합니다. 모든 축은 같은 범위를 사용하며, 마우스를 올리면 요일별 합계를 확인할 수 있습니다.
- 완독 권수나 기간 전체의 고유 도서 수가 아닙니다. 같은 책을 월요일 두 번 읽으면 그날은 1권, 서로 다른 월요일 두 날에 읽으면 월요일 합계는 2권입니다. 요일별 하루 평균이 아니라 누적 합계입니다.
- 독서 달력과 동일한 로그인 사용자·일반/성인 세션·보관함 필터 및 접근 권한을 따릅니다. 오디오북·비디오에는 표시하지 않습니다.
- 달력을 숨겨도 이 카드만 켜서 사용할 수 있습니다. 카드 설정과 드래그 정렬을 지원하며, 저장된 달력 응답을 재사용해 추가 DB 조회나 백그라운드 집계를 만들지 않습니다.
- 기록이 없으면 빈 기록 안내를, 조회가 실패하면 오류를 표시합니다. 보관함 전환 시 이전 요청의 응답은 무시합니다.
1.6.0부터 BookOasis 2.8.4의 report_problem() / resolve_problem() 선택 계약을 사용합니다. 집계·스냅샷 저장 또는 백그라운드 시작이 실패하면 상단 알림센터에 관리자용 조치 필요 문제 카드가 표시됩니다. 통계 화면을 열지 않아도 오류를 확인할 수 있습니다.
- 일반·성인·오디오북·비디오의 실패를 별도 코드로 구분합니다. 같은 세션·종류의 실패는 코어가 한 카드에 묶습니다.
통계 재시도버튼은 관리자만 실행할 수 있으며 해당 세션의 백그라운드 갱신을 예약합니다. 재시도를 눌렀다는 이유만으로 문제를 해결 처리하지 않습니다.- 집계와 스냅샷 저장이 모두 성공하면 해당 세션의 집계 실패와 시작 실패 문제를 자동으로 해결합니다. 실패한 동안에는 마지막 정상 통계가 있으면 계속 표시합니다.
- 실패 안내를 보면 DB 연결과
plugins/data/statistics저장 경로의 쓰기 권한·여유 공간을 확인한 후 재시도합니다. 원문 오류는 관리자 문제 카드에 보관합니다. - 상태 조회·정기 성공·빈 독서 기록은 새 문제 알림을 만들지 않습니다. 개인 독서 달력 조회 오류는 기존 화면의 오류 안내를 사용합니다.
- 구버전 코어에 알림 헬퍼가 없거나 알림 등록·해결에 오류가 나도 통계 기능은 계속 동작합니다. 알림 기능을 사용하려면 실행 중인
plugins/metadata/base.py에 두 헬퍼가 있어야 합니다. 전체plugins볼륨을 사용하는 환경에서는 코어 이미지 버전뿐 아니라 실제 로드되는 파일도 확인합니다.
플러그인 시작 시 start_background_service()가 통계 런타임을 시작합니다. 1.1.1부터는 화면의 상태 요청도 현재 세션 런타임을 멱등하게 시작하므로 시작 훅이 누락된 환경에서 무한 대기하지 않습니다. 최초 집계는 BookOasis 시작 직후 약간의 지연 뒤 실행되고, 성공한 결과는 다음 위치의 SQLite 스냅샷에 저장됩니다.
plugins/data/statistics/statistics.db
plugins/data/statistics/statistics-adult.db
plugins/data/statistics/statistics-audiobook.db
plugins/data/statistics/statistics-video.db
라이브러리 통계 요청은 이 스냅샷을 읽은 메모리 상태만 반환합니다. 개인 독서 달력과 요일별 패턴은 별도 요청에서 조회한 일별 로그를 공유합니다. 새로운 라이브러리 집계가 진행 중이거나 실패하더라도 마지막 정상 스냅샷은 유지됩니다.
주요 DB 집계는 GROUP BY 중심으로 수행하며 삭제된 항목은 제외합니다.
BookOasis current session DB
│
│ background aggregation
▼
statistics.db snapshot
│
▼
memory snapshot
│
▼
statistics UI / ECharts
프론트엔드는 다음 버전을 HTTPS CDN에서 동적으로 로드합니다.
| 라이브러리 | 버전 | 용도 |
|---|---|---|
| ECharts | 6.1.0 |
도넛, 막대, 라인, Gauge, Heatmap, Treemap, Chord, Radar |
| Muuri | 0.9.5 |
드래그 카드 정렬과 masonry 레이아웃 |
BookOasis 기본 CSP는 HTTPS 스크립트를 허용하지만, 관리자가 SECURITY_CSP_POLICY를 별도로 제한한 환경에서는 CDN 로딩이 차단될 수 있습니다. 외부 CDN에 접근할 수 없는 환경에서도 플러그인 백그라운드 집계는 동작하지만 차트 렌더링은 제한됩니다.
최종 폴더 구조는 다음과 같습니다.
plugins/metadata/
└── statistics/
├── __init__.py
├── statistics.py
├── statistics_core.py
├── index.html
├── style.css
├── script.js
└── VERSION
BookOasis의 plugins/metadata/에서 다음 명령을 실행합니다.
git clone https://github.com/colaiuta77/statistics.git statistics- BookOasis
2.4.7이상과 최신plugins/metadata/base.py가 적용되어 있는지 확인합니다. - BookOasis 서버 또는 컨테이너를 재시작합니다.
환경설정 > 플러그인 설정에서통계가 활성화되어 있는지 확인합니다.- 좌측 사이드바의
통계카테고리를 엽니다. - 최초 백그라운드 집계가 완료되면 저장된 통계가 표시됩니다.
Docker 환경에서는 BookOasis plugins 디렉터리가 연결된 호스트 볼륨 또는 컨테이너의 동일한 경로에 설치해야 합니다.
1.1.2부터 BookOasis 공식 update_manifest 계약을 지원합니다. 환경설정 > 플러그인 설정에서 통계 카드를 펼쳐 업데이트 버튼을 사용할 수 있습니다. 버튼 이름은 BookOasis 버전에 따라 샘플 업데이트로 표시될 수 있습니다.
- 저장소
main의VERSION이 설치 버전보다 높을 때만 갱신합니다. 동일하거나 낮은 버전이면 업데이트하지 않습니다. - 갱신 대상은
statistics.py,statistics_core.py,__init__.py,index.html,style.css,script.js,VERSION7개입니다. 스냅샷 DB, 공통base.py, README와 이미지는 변경하지 않습니다. - 갱신 완료 후 기존 백그라운드 워커가 새 코드로 시작하도록 BookOasis 서버 또는 컨테이너를 재시작하고 통계 화면을 새로고침합니다.
1.1.1 이하에는 manifest가 없어 업데이트 버튼이 표시되지 않습니다. Git으로 설치했다면 최초 한 번 BookOasis의 plugins/metadata/에서 다음 명령으로 1.1.2 이상을 받은 뒤 서버 또는 컨테이너를 재시작합니다. 수동 설치한 경우에는 위 7개 파일을 함께 교체합니다.
git -C statistics pull --ff-onlyGit 방식으로 계속 관리해도 됩니다. 버튼 업데이트는 파일만 교체하고 Git 이력은 갱신하지 않으므로 두 방식을 혼용하면 git pull 시 로컬 변경 충돌이 발생할 수 있습니다. 직접 수정한 파일은 업데이트 전에 별도로 백업합니다.
/app/plugins 전체를 호스트 볼륨으로 연결하면 BookOasis 이미지가 갱신되어도 볼륨에 이미 존재하는 plugins/metadata/base.py는 유지될 수 있습니다. 다음 확인 결과가 False이면 현재 컨테이너가 구형 플러그인 계약을 로드한 상태입니다.
CONTAINER=bookoasis
docker exec "$CONTAINER" python -c "from plugins.metadata.base import BaseMetadataProvider as B; print(hasattr(B, 'start_background_service'))"BookOasis 2.4.7 이상에서는 다음 명령으로 기존 파일을 볼륨 내부에 백업하고 현재 이미지의 기본 원본으로 교체할 수 있습니다. 컨테이너 이름이 다르면 CONTAINER 값만 변경합니다.
CONTAINER=bookoasis
if docker exec "$CONTAINER" sh -lc '
set -eu
src=/app/_plugin_framework_defaults/base.py
dst=/app/plugins/metadata/base.py
backup_dir=/app/plugins/.framework-backups
grep -q "def start_background_service" "$src"
if ! grep -q "def start_background_service" "$dst" 2>/dev/null; then
stamp=$(date +%Y%m%d-%H%M%S)
mkdir -p "$backup_dir"
cp -a "$dst" "$backup_dir/base.py-$stamp"
tmp="${dst}.new.$$"
trap "rm -f \"$tmp\"" EXIT
cp -a "$src" "$tmp"
mv -f "$tmp" "$dst"
trap - EXIT
echo "base.py 교체 완료. 백업 위치: $backup_dir/base.py-$stamp"
else
echo "현재 base.py는 이미 호환됩니다."
exit 20
fi
'; then
docker restart "$CONTAINER"
else
status=$?
if [ "$status" -ne 20 ]; then
echo "base.py 교체에 실패했습니다." >&2
false
fi
fi통계 플러그인의 자체 시작 보완은 통계 화면의 무한 대기를 방지하는 안전장치입니다. 다른 플러그인도 동일한 계약을 사용할 수 있으므로 최신 base.py 적용은 계속 권장합니다.
general과adult는libraries와books,audiobook은audiobooks와audiobook_tracks,video는videos와video_episodes를 집계합니다.COALESCE(is_deleted, 0) = 0조건으로 삭제된 항목을 제외합니다.- 전체 통계와 보관함별 통계를 한 번의 백그라운드 집계 과정에서 생성합니다.
- 가능한 통계는 DB의
COUNT,SUM,GROUP BY와 window function으로 집계합니다. - 장르처럼 문자열 분리가 필요한 데이터만 집계 결과를 Python에서 추가 처리합니다.
- 화면 진입과 보관함 전환은 원본 미디어의 전체 통계를 다시 집계하지 않습니다. 독서 달력과 요일별 패턴은 현재 사용자·올해·보관함 권한으로 제한한 일별 로그 조회를 공유합니다.
- 스냅샷 저장소는 원본 BookOasis DB와 분리되어 있으며 통계 데이터만 저장합니다.
- SQLite와 MariaDB의 월별 날짜 집계 표현을 각각 처리합니다.
- 25만 권급 MariaDB 라이브러리에서 백그라운드 집계와 스냅샷 생성 동작을 확인했습니다.
- BookOasis
2.4.7의 비디오 스캐너에는 플러그인 신규 항목 훅이 없어 비디오 통계는 시작 시, 기본 6시간 주기와 수동 갱신으로 최신화됩니다. - 언어 필드는 현재 BookOasis
books데이터 계약에 없어 언어 분포를 제공하지 않습니다. - 메타데이터 갱신 시각 전용 필드가 없어 BookOrbit 형태의 Metadata Freshness를 동일하게 제공하지 않습니다.
- 실제 파일 시스템을 전체 순회하지 않으므로 물리 파일 존재 여부를 검증하는 Integrity 통계는 제공하지 않습니다.
- 사용자별 상세 독서 시간·세션 분석은 제공하지 않으며, 일반·성인 도서의 일별 독서 달력과 요일별 읽은 권수 합계를 지원합니다.
created_at과release_date가 비어 있거나 비표준 형식이면 해당 시간 기반 차트에서 제외될 수 있습니다.- 장르 연관성은 함께 지정된 상위 장르만 사용하며 모든 장르 조합을 한 화면에 표시하지 않습니다.
- ECharts와 Muuri를 CDN에서 로드하므로 폐쇄망에서는 별도 정적 자산 제공 방식이 필요할 수 있습니다.
- BookOasis의 플러그인 계약 또는 DB 스키마가 변경되면 호환성 업데이트가 필요할 수 있습니다.
python3 -m py_compile __init__.py statistics.py statistics_core.py
node --check script.js개발 과정에서는 백그라운드 스냅샷, MariaDB SQL dialect, 보관함별 scope, 메타데이터 누락 계산, Heatmap 스크롤, MB/GB 축 변환과 드래그 카드 레이아웃을 검증합니다. 독서 달력·요일별 패턴의 사용자/보관함 필터와 공유 조회, 카드 표시 설정, 용량 트리맵·장르/태그 확대, 용량 막대 스크롤도 회귀 테스트에 포함합니다. 개발용 테스트와 작업 메모, NAS 적용 스크립트는 GitHub 배포본에 포함하지 않습니다.
- BookOasis 2.8.4 관리자 문제 카드에 세션별 집계·저장 실패 및 백그라운드 시작 실패를 표시합니다.
- 관리자 전용
통계 재시도액션을 추가하고, 집계와 저장이 모두 성공한 뒤 문제 카드를 자동 해결합니다. - 알림 헬퍼 기능 감지와 알림 오류 격리를 적용해 구버전 코어 호환 및 마지막 정상 스냅샷 유지를 지원합니다.
- 코어의
data-app-theme변경을 감지해 차트 색상을 다시 렌더링합니다. DB 스키마·SQL·업데이트 파일 목록과 외부 의존성 변경은 없습니다.
- 기본 어두운 테마에서 제목·요약·통계 카드 배경에 흰색을 3% 섞어 밝기를 살짝 높였습니다. 다른 테마의 배경은 유지합니다.
- 제목·요약·통계 카드에 테두리색 92%·글자색 8%를 섞은 1px 외곽선과
0 2px 8px rgba(0,0,0,.12)그림자를 적용했습니다. 어두운 테마에서는 외곽선이 밝게, 밝은 테마에서는 짙게 표시됩니다. - 사용자 활동·독서 업적과 통계의 아이콘형 헤더, 제목 크기와 보관함 선택 영역 디자인을 통일했습니다.
- 1680px 폭 제한을 제거하고 실제 콘텐츠 폭 1600px 이상에서 작은 카드 4열 배치를 지원합니다. Muuri와 CSS Grid에 같은 폭을 적용합니다.
- 기존 카드 높이·순서·표시 설정과 데이터 조회는 유지하며, 좁은 화면에서 헤더 조작 영역을 줄바꿈합니다.
- 일반·성인 도서에 올해 월~일별 읽은 권수 합계를 표시하는 1열·1단 레이더 카드를 추가했습니다.
- 달력과 단일 조회를 공유하며, 카드별 표시 설정·드래그 정렬·보관함 전환을 지원합니다. 두 독서 카드를 모두 숨기면 개인 기록 조회를 중단합니다.
- 날짜의 요일은 클라이언트 시간대와 무관하게 계산하고, 빈 기록·조회 실패·이전 보관함의 늦은 응답을 구분해 처리합니다. DB·SQL·공용 스냅샷·업데이트 파일 목록 변경은 없습니다.
- README에 최신 카드 사용법과 회귀 검증 범위를 정리하고 시각화 구성의 참고 출처 소개 문단을 삭제했습니다. 기존 라이선스는 유지합니다.
- 용량 트리맵 카드의 세로 크기를 2단에서 1단으로 줄였습니다. 가로 폭과 포맷별/용량순 전환, 확대·경로 복귀, 작은 칸 툴팁은 유지합니다.
- 용량 막대 카드의 폭을 2열에서 기존 1열로 복원했습니다. 높이와 상위 50개 스크롤 기능, 장르/태그 분포 및 용량 트리맵은 그대로 유지합니다.
- 장르/태그 분포에 클릭 확대와 하단 경로를 통한 전체 보기 복귀를 적용했습니다.
- 장르/태그 전환·상위 60개·작은 칸 툴팁을 유지하면서 분포를 가로 2열 폭·1단 높이로 변경했습니다.
- 용량 막대 카드를 가로형으로 넓히고 상위 50개를 10개씩 휠·세로 스크롤바로 이동하도록 변경했습니다. 기존 스냅샷을 사용하며 집계·DB 변경은 없습니다.
- 모든 세션·보관함의 용량 상위 집계를 최대 100개로 확대하고 기존 막대 카드의 상위 12개 표시는 유지했습니다.
- 용량 트리맵에 포맷별/용량순 선택과 세션별 저장을 추가했습니다. 용량순은 크기에 비례한 면적과 옅은색→진한색으로 표시합니다.
- 트리맵 상위·포맷 제목과 용량을 한 줄로 정리하고 작은 셀은 라벨만 숨겨 툴팁을 유지합니다.
- 장르 분포를 장르 연관성과 같은 세로형 카드로 변경하고 상위 60개 장르/태그 전환을 추가했습니다. 태그는 일반·성인의 활성 도서만 집계하며 태그 동시 출현 계산은 하지 않습니다.
- 기존 스냅샷은 그대로 읽으며 확대된 목록과 태그 집계는 다음 통계 갱신부터 반영됩니다. 업데이트 파일·코어·DB 스키마 변경은 없습니다.
- 기존 용량 막대 카드를 유지하고 큰 포맷별 용량 트리맵을 추가했습니다.
- 상단 카드 설정에서 요약 카드·차트·독서 달력을 개별 표시하거나 숨길 수 있습니다.
- 세션별 표시 설정 저장, 숨긴 카드의 순서 보존, 재표시 시 차트 재생성과 빈자리 재배치를 적용했습니다.
- 독서 달력을 숨기면 추가 개인 기록 조회를 중단합니다. 기존 집계와 업데이트 파일 계약은 유지합니다.
- 일반·성인 도서 화면 맨 아래에 전체 너비의 연간 독서 달력을 추가했습니다.
- 로그인 사용자·보관함 권한을 적용한 일별 읽은 권수, 빈 날짜와 툴팁을 표시합니다.
- 개인 로그를 공용 스냅샷과 분리하고, 보관함 전환 시 이전 응답이 새 결과를 덮어쓰지 않도록 처리했습니다.
- 모바일 달력 내부 가로 스크롤과 테마 색상·접근성 설명을 적용했습니다.
- 공식
update_manifest를 선언해 플러그인 설정의 업데이트 버튼을 활성화했습니다. - 저장소
main에서 필수 런타임·UI 파일과VERSION만 갱신하도록 등록했습니다. - 기존 버전의 최초 Git 갱신, 업데이트 후 재시작과 Git 방식 혼용 시 주의사항을 추가했습니다.
- 화면의 통계 상태 요청이 현재 세션 런타임을 자체 시작하도록 보완했습니다.
- 전체
plugins볼륨에 남은 구형base.py의 확인, 백업과 복구 절차를 추가했습니다.
- 일반도서, 성인도서, 오디오북과 비디오 세션별 독립 통계 런타임과 스냅샷을 추가했습니다.
- 오디오북 트랙과 비디오 에피소드의 포맷, 용량, 재생시간과 분량 통계를 추가했습니다.
- 현재 세션에 맞는 KPI, 카드 제목, 카드 표시와 세션별 레이아웃 저장을 추가했습니다.
- 모든 통계 카드에서 제목과 헤더 구분선이 겹치지 않도록 공통 헤더 높이를 수정했습니다.
- BookOasis
2.4.7의start_background_service()를 이용한 사전 통계 집계 추가. - 전체/보관함별 라이브러리 통계와 영구 스냅샷 저장 구조 추가.
- ECharts
6.1.0기반 도넛, Gauge, 막대, 라인, Heatmap, Treemap과 Chord 차트 추가. - Muuri
0.9.5기반 드래그 카드 정렬, 순서 저장과 레이아웃 초기화 추가. - 1단/2단 카드 높이 체계와 보관함 Heatmap 내부 세로 스크롤 추가.
- 메타데이터 완성도, 점수 분포와 누락 현황 추가.
- 파일 크기 차트 MB/GB 자동 단위 표시 추가.
- 실제 BookOasis 다크 테마 화면을 README에 추가.
이 저장소의 LICENSE를 따릅니다.