readme.md 작성

[Quirax]

readme.md를 작성합니다.

내용 구성

• [x] 실행 화면
• [x] 배경
• [x] 동작 원리
• [x] 목표 및 현황
• [x] 한계
• [x] 하고 싶은 말

[Quirax]

배경

자캐 커뮤니티(커뮤)란?

사람의 창작 본능은 때로는 자신이 상상하는 특성을 가지는 캐릭터를 만드는 형태로 나타납니다. 이렇게 만든 캐릭터를 '자작 캐릭터', 줄여서 '자캐'라고 합니다.이 자캐를 만든 사람을 '오너'라고 부릅니다.

각 오너들이 자신이 만든 자캐를 가지고 일종의 커뮤니티 활동을 하는 것을 '자캐 커뮤니티'라고 합니다. 일반적으로 '커뮤'라고 줄여 부릅니다. 커뮤에서 활동하는 것을 '러닝'이라고 하고, 활동하는 오너들을 '러너'라고 합니다. 또 이 커뮤를 운영하는 사람들을 '총괄진', 줄여서 '괄진'이라고 합니다. 커뮤는 일반적으로 기간제로 운영되며, 개장일 이전 '가개장'을 시작으로 개장 이후 종료하는 '엔딩'까지 이어지며, 이후 오너들끼리 뒷풀이 즉 '애프터'를 합니다.

커뮤니티가 형성되려면 이용자들이 모일 플랫폼이 필요합니다. 그 중 자캐 커뮤니티에 사용하는 플랫폼으로 '밴드'가 많이 사용됩니다. 밴드는 네이버 사에서 개발 및 운영하는 SNS로, 모임을 구성하고 운영하기 위해 각계각층에서 사용하는 온라인 플랫폼입니다. 이 외에도 X(구 트위터)나 마스토돈과 같은 다른 SNS에서도 커뮤가 운영됩니다.

편파 단속의 필요성

한편, 커뮤 내 오너들의 취향 기타 편향성으로 인하여 특정 자캐들만 우대받거나 반대로 홀대받는 경우도 존재합니다. 이러한 불평등한 대우를 '편파'라고 합니다. 편파로 인하여 특정한 자캐들만 주목받게 되므로 그에 비해 홀대받는 자캐들의 오너들이 이탈하거나 활동이 저조해지는 문제가 발생할 수 있습니다. 이에 일반적으로 커뮤에서는 편파를 금지하고 단속합니다. 경우에 따라서 커뮤가 조기에 엔딩을 맞이하는 경우도 발생합니다.

일반적으로 게시물별 조회수나 댓글 수, 표정 수를 비롯한 반응 수를 기준으로 하여, 특정 자캐들의 글에만 반응이 많거나 반대로 적은 경우에 편파가 있다고 판단합니다. 그러나 모든 게시물을 사람이 일일이 읽고 판단하여 결정해야 합니다. 이는 단속하는 사람의 경험에 의존해야 하므로, 정말로 편파가 있는지에 관한 논란을 야기할 우려가 있습니다. 또한 단속하는 사람의 피로감을 유발하여 커뮤 운영에 지장을 줄 우려가 있습니다.

이러한 이유로, 밴커에서의 편파 탐지를 위한 보다 전문화된 도구가 필요하게 되었습니다.

"밴드를 위한 자캐 커뮤니티 편파 탐색기"

"밴드를 위한 자캐 커뮤니티 편파 탐색기"는 이러한 요구에 충족하기 위하여, 커뮤에 게시된 모든 게시물과 댓글을 분석하고 통계하여 표시함으로써, 현재 편파가 발생하고 있는지, 또 어느 자캐에 대하여 얼마나 발생하고 있는지 확인할 수 있도록 합니다.

이로써 편파를 객관적인 데이터로 효율적으로 확인할 수 있습니다. 이는 편파를 탐지하는 일반적인 능률을 향상시키고, 편파 탐지의 방식을 표준화하며, 총괄진의 운영 난이도를 낮춤으로써, 안정적인 커뮤 운영에 이바지할 것으로 기대합니다.

[Quirax]

동작 원리

Extension으로 개발하는 이유

애플리케이션의 경우 웹 사이트나 설치형 프로그램 형태로 개발하는 것이 일반적입니다. 그러나 2024년 11월 20일 기준, 밴드 측에서 제공하는 Open API가 분석을 수행하는 데에 다음과 같은 한계가 존재합니다.

• 게시물의 조회수를 비롯한 주요 지표를 확인하려면 각각의 게시물을 일일이 조회해야 합니다. 따라서, 만약 분석 대상이 되는 밴드에 게시물이 200개가 있고, 게시물당 평균 10개의 댓글이 있다면, 총 408회의 API 호출이 필요합니다.
  • 전체 게시물 목록을 조회하기 위하여 8회의 API 호출이 필요합니다. 1회당 25개의 게시물이 조회됩니다.
  • 각 게시물의 상세 조회를 위하여 200회의 API 호출이 필요합니다.
  • 각 게시물의 댓글 목록 조회를 위하여 200회의 API 호출이 필요합니다.
• Open API 사용 시 사용량 제한이 존재합니다. 이는 사용자 단위뿐 아니라 애플리케이션 단위로도 존재합니다. 이로 인해 사용량이 너무 많아 제한에 걸리는 경우, 일정 시간 동안 애플리케이션을 이용할 수 없게 됩니다.
  • 사용량 제한의 정확한 기준은 공개되어 있지 않습니다. 다만, 사용자가 10명만 되어도 4천 회 이상의 API 호출이 발생합니다. 따라서 애플리케이션 단위 사용량 제한에 걸릴 가능성이 존재합니다.
  • 사용량 제한에 도달하는 경우 24시간 동안 API 호출이 거부됩니다. 즉, 다른 사용자들은 24시간 동안 애플리케이션을 이용할 수 없게 됩니다.

한편 Extension으로 개발하는 경우, 아래에 서술한 바와 같이 밴드 페이지 내에서 별도의 스크립트를 실행할 수 있습니다. 이러면, 밴드에 로그인한 사용자의 권한으로 밴드에서 사용하는 내부 API를 호출할 수 있습니다. 그러면 다음과 같은 장점이 있습니다.

• 내부 API에서는 전체 게시물 목록을 조회할 때 주요 지표를 함께 제공합니다. 따라서, 각 게시물을 상세 조회하지 않아도 됩니다. 위 예시에 따르면, 200회의 API 호출이 절약됩니다.
• 내부 API에도 사용량 제한은 존재하지만, 애플리케이션 단위로 적용되지는 않습니다. 따라서, 사용자가 여러명이더라도 각자의 사용량 제한만 적용됩니다. 예를 들어, 어떤 사용자가 이 Extension을 너무 많이 사용하여 24시간 동안 사용 제한이 걸리더라도, 다른 사용자들은 여전히 이 Extension을 사용할 수 있습니다.

[Quirax]

목표 및 현황

❎️ 작업이 시작되지 않았으며, 당분간 계획 없음 🗑 폐기된 목표 🗓 작업이 시작되지 않았으나, 계획에는 포함됨 🛠 작업이 시작되었음 ✅️ 작업이 완료되었음

---

✅️ 페이지 간 통신   ✅️ 팝업-Content Script 간 통신   ✅️ 팝업-Service Worker 간 통신   ✅️ CS-Inject Script 간 통신 ✅️ 밴드 정보, 게시물 및 댓글 목록 수집   ✅️ Band API에 접근   ✅️ 밴드 정보에 접근   ✅️ 게시물 목록에 접근   ✅️ 댓글 목록에 접근 ✅️ Stat 페이지에서 분석   ✅️ 데이터 전달   ✅️ 분석 및 그래프로 표시 ❎️ 설정 ❎️ DevTools

[Quirax]

한계

• 상기한 바와 같이 밴드 페이지에 스크립트를 주입하는 방식으로 구현되어 있어, 추후 밴드 운영사인 네이버 사에서 이를 차단할 가능성이 있습니다.
• 밴드에 미리 로그인한 뒤, 밴드 페이지가 열려 있는 상태에서만 분석 진행이 가능합니다. 팝업에서 소속된 밴드를 선택할 수 없습니다.
• 로그인한 사용자의 자격으로 밴드 API를 사용하므로, 사용량이 많은 경우 밴드 측에서 어뷰징으로 간주하여 24시간 동안 이용이 제한될 수 있습니다. 개발 과정에서 파악한 바 게시물 개수 기준 약 250개 정도에서는 큰 문제가 없었으나, 이것이 곧 언제나 이용 제한이 발생하지 않는다고 보장하진 않습니다.

[Quirax]

하고 싶은 말

이 크롬 확장이 만들어지는 데에는 아이디어를 제공하고 지속적으로 검증에 참여한 연화의 공로가 있었습니다. 제게는 매우 소중한 동생으로서, 커뮤 운영에 관한 아이디어와 구현 능력, 운영 능력을 고루 갖춘 인재입니다. 캐릭터 디자인이나 일러스트레이션 능력도 갖추고 있습니다. 이 자리를 빌어 존경과 감사를 표합니다. 이 외에도 프로젝트에 직·간접적으로 참여해주신 모든 분들께 감사의 뜻을 전합니다.

필요한 통계의 종류를 비롯하여 기능 제안을 기다리고 있습니다. Issues 탭에서 새 이슈를 만들어주셔서 제안해주시면 감사하겠습니다.

[Quirax]

동작 원리

스크립트 삽입

Extension에서는 스크립트 삽입이 가능합니다. 이를 통해 밴드 페이지 내에서 스크립트를 실행하여, 밴드 API를 호출하기 위한 준비 과정을 진행합니다.

밴드 페이지와 통신

원칙적으로 Extension의 팝업 등 다른 페이지와 밴드 페이지는 직접 통신할 수 없습니다. Extension 내에서는 chrome.runtime.sendMessage API를 이용하여 통신합니다. Extension과 밴드 페이지 간에는 window.postMessage API를 이용하여 통신합니다.

이러한 통신 구조는 modules/messenger.js에 구현되어 있으며, Extension과 밴드 페이지 간의 통신은 content script에 구현되어 있습니다.

전체 실행 과정

사용자가 밴드 페이지에 있지 않은 경우, 팝업에서 관련된 안내 메시지를 표시합니다.

밴드 페이지에서 팝업을 표시하는 경우, 준비 상태의 화면을 표시합니다. 여기서 현재 밴드 분석하기 버튼을 클릭하면, 밴드 내 모든 게시물과 댓글을 수집합니다. 이 때 밴드 페이지와 통신하여 API를 호출합니다. 수집이 완료되면 local extension storage에 저장한 뒤, Stat 페이지로 넘겨줍니다.

Stat 페이지에서는 전달받은 데이터를 local extension storage로부터 가져온 뒤, 사용자가 선택한 통계 종류에 따라 그래프로 표시합니다.

[Quirax]

사용 라이브러리

• Base Framework: Quirax/chrome-extension-boilerplate-react forked from lxieyang/chrome-extension-boilerplate-react
  • node-sass (v8.0.0): https://github.com/Quirax/chrome-extension-boilerplate-react/issues/1 적용
  • cross-env (v7.0.3): Production build를 위해 적용
• 아이콘 폰트: @fortawesome/fontawesome-svg-core (v6.6.0), @fortawesome/free-solid-svg-icons (v6.6.0), @fortawesome/react-fontawesome (v0.2.2)
• 밴드 API 사용을 위한 dependencies: jquery (v3.7.1), moment (v2.30.1), moment-timezone (v0.5.45), underscore (v1.13.6)
• 차트 표시: recharts (v2.13.3)
• 요소 스타일링: styled-components (v6.1.12)

참고자료

• Extension 관련
  • 통신
  • 크롬 익스텐션 컴포넌트끼리 통신하는 방법 - 개발기 by Broccolism
  • 구글 확장프로그램 개발 (2)-스크립트간 통신 by 이명환
  • chrome.storage by Google
  • chrome.alarms by Google
  • chrome.tabs by Google
  • Access window variable from Content Script
  • Using window globals in ManifestV3 service worker background script
  • [해결된 문제] Chrome extension service worker inactive by 개발자의 의자
• styled-components attrs()에 대하여 by Ayaan
• Javascript
  • 날짜
  • [Javascript] YYYY-MM-DD 형태의 날짜 정보를 만들어보자! by 박기영
  • [JavaScript] 날짜 관련 유용 함수 총 정리(feat.String to Date) by .java의 개발일기
  • URL 처리
  • Javascript / URL Query String 가져오기 by Wintering
  • Event when window.location.href changes
  • Generate random string/characters in JavaScript
• https://github.com/recharts/recharts/issues/397

[Quirax]

ChatGPT를 통한 1차 검수 결과 (기준 버전)

작성된 README.md는 전체적으로 잘 구성되어 있으며, 프로젝트의 개요, 동작 원리, 실행 방법, 배경, 한계, 사용된 기술 등을 체계적으로 설명하고 있어 이해하기 쉽습니다. 하지만 몇 가지 개선할 점과 고려사항을 제안할게.

---

1. 추가로 더 설명이 필요한 부분

• 실행 화면

  • [x] 실제 스크린샷을 추가하면 더 직관적으로 이해할 수 있을 듯. "실행 화면" 섹션에 스크린샷이 없으면 추후 README를 읽는 사용자가 테스트 환경을 상상하기 어려울 수 있어.
  • 가능하다면 유튜브 영상이나 GIF로 간단한 데모를 제공하는 것도 추천.

• Releases 설치 시 경고 문구

  • [x] "테스트 버전은 정식 버전에 비해 불안정하거나 치명적인 버그가 있을 수 있습니다."는 명확하지만, 추가로 어떤 점에서 주의해야 하는지 구체적으로 적으면 좋아. 예를 들어 "데이터 손실 가능성" 등.

• "분석 진행 과정"에서의 설명 부족

  • [x] 단계별로 각 과정에 대한 설명은 충분히 제공되었지만, 실행 화면 스크린샷이 비어 있는 부분에 대한 이미지 추가가 필요.
  • [x] 각 단계가 실패했을 경우의 에러 처리에 대해 언급하면 완성도가 올라갈 것 같아.

• 한계

  • [x] "밴드 운영사인 네이버 사에서 이를 차단할 가능성"이 있다는 문구에서 차단될 경우 대체 방안(예: 유지보수 계획이나 커뮤니케이션 방법 등)을 간략히 언급하면 신뢰감을 줄 수 있을 것 같아.

---

2. 없어도 이해에 문제가 없는 군더더기

• "자캐 커뮤니티(커뮤)란?" 섹션

  • [x] 자캐 커뮤니티의 설명이 다소 길어서, 프로젝트의 대상 사용자가 이미 자캐 커뮤니티에 익숙하다면 생략 가능.
  • [x] "러너", "괄진" 등의 설명은 사용자에게 필수적이지 않을 수 있으니 간략화 추천.
  • [x] 제안: 이 섹션을 별도의 문서(ex. docs/background.md)로 분리해 필요에 따라 참고하도록 안내.

• Extension 개발의 동작 원리

  • "Extension으로 개발하는 이유"는 자세한 설명이 좋아 보이지만, 너무 길어서 기술적 배경이 필요한 사용자들에게만 유용할 수 있음.
  • [x] 제안: README 본문에는 요약만 두고, 자세한 동작 원리는 docs/technical-details.md로 옮기는 것도 방법.

• 참고 자료

  • [x] 참고 자료의 링크가 과도하게 많아 보여. 프로젝트 관련 핵심적인 링크 위주로 줄이고, 나머지는 기술 문서에 분리하는 게 깔끔할 듯.

---

3. 오탈자 및 오해 소지가 있는 부분

• 용어 일관성

  • [x] "커뮤"와 "커뮤니티" 용어가 혼용되어 있어. 하나로 통일하면 독자가 더 자연스럽게 읽을 수 있을 것 같아.
  • [x] "Extension" 대신 "확장 프로그램"으로 번역하거나 병기하는 것도 고려. 한국어를 기준으로 작성된 문서라면 맞추는 편이 더 친절해 보일 수 있음.

• 표현의 간결화

  • [x] "이로써 편파를 객관적인 데이터로 효율적으로 확인할 수 있습니다" → "편파를 객관적으로 확인할 수 있습니다"로 간결화 가능.
  • [x] "이는 편파를 탐지하는 일반적인 능률을 향상시키고..." 문장은 두 문장으로 나눠 더 명확히 설명 가능.

• 한계의 '추측' 표현

  • [x] "밴드 운영사인 네이버 사에서 이를 차단할 가능성이 있습니다."라는 표현이 추측으로 들릴 수 있음. 가능성의 근거가 있다면 추가 설명 추천.
  • [x] "개발 과정에서 파악한 바 게시물 개수 기준 약 250개 정도에서는 큰 문제가 없었으나..." 같은 문장은 데이터에 기반한 사실로 들리도록 구체화 필요. 예: "테스트 결과, 게시물 250개 기준으로는 문제가 없었으나...".

---

제안된 개선된 README 구조

1. 간략한 개요

   • "밴드를 위한 자캐 커뮤니티 편파 탐색기란?" 섹션에 주요 기능과 목표를 요약.
   • 자캐 커뮤니티 설명은 링크로 대체 가능.

2. 실행 화면

   • 스크린샷 또는 GIF 추가.

3. 실행 방법

   • 간단한 설치 방법 후 고급 사용자를 위한 링크 제공.

4. 기술 세부 사항

   • Extension 개발 이유와 동작 원리 섹션 요약 후 별도 문서 링크.

5. 한계와 주의 사항

   • 한계와 추후 계획 간단히 명시.

6. 감사의 말

   • 현재 작성된 내용 적절.

---

전체적으로 잘 작성된 문서지만, 구조를 단순화하고 추가 자료를 분리하면 사용자 입장에서 더 간결하고 이해하기 쉬워질 거야. 👍

[Quirax]

ChatGPT를 통한 2차 검수 결과 (기준 버전)

수정된 문서는 다음 기준에 따라 분석할게.

1. 가독성

• 문서가 잘 나뉘어 있어 내용이 쉽게 이해돼.
• 실행 방법은 단계별로 명확히 서술되었고, 스크린샷이 추가되어 직관적이야.
• "문제 해결" 섹션도 유용하며 상황별로 나뉘어 있어 좋아.

2. 명확성

• 주요 기능과 실행 방법이 구체적이고 명확하게 설명되어 있어.
• "Releases에서 설치" 섹션에서 테스트 버전에 대한 경고가 적절히 들어갔어.
• 다만, "Web Store에서 설치"가 준비 중이라고만 되어 있어 추가 정보(예: 예상 출시 일정)가 있으면 더 완벽할 듯.

3. 구조화

• 섹션들이 논리적으로 잘 배치되었어. (실행 화면 → 실행 방법 → 분석 과정 → 문제 해결 등)
• 목표 및 현황과 한계를 따로 정리해 두어 현재 상태를 명확히 전달하고 있어.

4. 효율성

• 불필요한 장황한 설명 없이 간결하게 작성되었어.
• 스크린샷과 텍스트가 적절히 조화돼 이해를 돕고 있어.

개선 제안

• [x] "Web Store 설치"에 예상 일정이나 링크 업데이트 관련 계획을 추가.
• [x] "하고 싶은 말" 섹션을 간략히 정리하거나 프로젝트 관련 감사 내용을 중심으로 수정.

총평

문서는 전반적으로 잘 작성되었고, 사용자가 쉽게 따라할 수 있도록 구성되었어. 추가로 작은 디테일만 보완하면 완벽할 듯!