{"id":31640355,"url":"https://github.com/9bow/kr-glossary","last_synced_at":"2025-10-07T02:22:43.304Z","repository":{"id":317329328,"uuid":"1051948480","full_name":"9bow/kr-glossary","owner":"9bow","description":"WIP","archived":false,"fork":false,"pushed_at":"2025-09-09T21:33:23.000Z","size":529,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-30T08:48:57.260Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/9bow.png","metadata":{"files":{"readme":"README.ADMIN.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-07T04:16:48.000Z","updated_at":"2025-09-09T01:02:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"b9265e3a-dfa2-4b7f-903c-5a1b95727e4c","html_url":"https://github.com/9bow/kr-glossary","commit_stats":null,"previous_names":["9bow/kr-glossary"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/9bow/kr-glossary","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9bow%2Fkr-glossary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9bow%2Fkr-glossary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9bow%2Fkr-glossary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9bow%2Fkr-glossary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/9bow","download_url":"https://codeload.github.com/9bow/kr-glossary/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9bow%2Fkr-glossary/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278708128,"owners_count":26031956,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-07T02:22:38.088Z","updated_at":"2025-10-07T02:22:43.296Z","avatar_url":"https://github.com/9bow.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 관리자 가이드 (Administrator Guide)\n\n\u003cdiv align=\"center\"\u003e\n\n**AI/ML 한국어 용어집 관리자 매뉴얼**\n\n*GitHub 기반 자동화 시스템 가이드*\n\n\u003c/div\u003e\n\n## 목차\n\n- [관리자 역할 개요](#관리자-역할-개요)\n- [권한 및 책임](#권한-및-책임)\n- [GitHub 워크플로우 관리](#github-워크플로우-관리)\n- [Issue 관리 시스템](#issue-관리-시스템)\n- [데이터 품질 관리](#데이터-품질-관리)\n- [자동화 시스템 모니터링](#자동화-시스템-모니터링)\n- [긴급 상황 대응](#긴급-상황-대응)\n- [관리 도구 및 스크립트](#관리-도구-및-스크립트)\n- [FAQ 및 트러블슈팅](#faq-및-트러블슈팅)\n\n## 관리자 역할 개요\n\n### 핵심 책임\n- **품질 관리**: 용어의 정확성 및 일관성 보장\n- **커뮤니티 관리**: 기여자와의 소통 및 가이드 제공\n- **시스템 관리**: 자동화 워크플로우 모니터링 및 유지보수\n- **정책 수립**: 용어 승인 기준 및 가이드라인 정의\n\n### 관리 범위\n- GitHub Issues 검토 및 승인/거절\n- 자동화 워크플로우 상태 모니터링\n- 데이터 무결성 및 품질 확인\n- 커뮤니티 가이드라인 시행\n\n## 권한 및 책임\n\n### 필수 GitHub 권한\n- **Repository Admin**: 저장소 설정 및 브랜치 보호 규칙 관리\n- **Issues Management**: Issue 라벨 관리 및 상태 변경\n- **Actions Management**: GitHub Actions 워크플로우 관리\n- **Pages Management**: GitHub Pages 배포 설정\n\n### 관리자 등급 시스템\n\n| 등급 | 권한 | 책임 |\n|------|------|------|\n| **Lead Admin** | 모든 권한, 새 관리자 임명 | 전체 시스템 관리, 정책 수립 |\n| **Senior Admin** | Issue 승인, 시스템 모니터링 | 용어 검토, 품질 관리 |\n| **Junior Admin** | Issue 검토, 피드백 제공 | 초기 검토, 커뮤니티 지원 |\n\n### 관리자 목록 관리\n\n관리자 정보는 `.github/config/admins.json`에 저장됩니다:\n\n```json\n{\n  \"admins\": [\n    {\n      \"githubUsername\": \"admin1\",\n      \"name\": \"관리자 이름\",\n      \"role\": \"lead\",\n      \"permissions\": [\"all\"],\n      \"email\": \"admin@example.com\",\n      \"expertise\": [\"machine-learning\", \"nlp\"],\n      \"joinDate\": \"2024-01-01\",\n      \"status\": \"active\"\n    }\n  ]\n}\n```\n\n## GitHub 워크플로우 관리\n\n### 주요 워크플로우 파일\n\n#### 1. `.github/workflows/data-management.yml`\n**목적**: Issue 승인 시 자동 데이터 처리\n**트리거**: Issue 라벨 변경 (`approved`, `rejected`)\n\n```yaml\n# 주요 작업\n- Issue 데이터 추출 및 검증\n- 자동 PR 생성 및 병합\n- 데이터 무결성 확인\n```\n\n#### 2. `.github/workflows/issue-validation.yml`\n**목적**: 새 Issue 자동 검증\n**트리거**: Issue 생성/수정\n\n```yaml\n# 검증 항목\n- 필수 필드 완성도\n- 데이터 형식 유효성\n- 중복 검사\n- 자동 라벨링\n```\n\n#### 3. `.github/workflows/deploy.yml`\n**목적**: GitHub Pages 자동 배포\n**트리거**: main 브랜치 푸시\n\n```yaml\n# 배포 과정\n- 빌드 및 테스트\n- 데이터 전처리\n- GitHub Pages 배포\n```\n\n### 워크플로우 모니터링\n\n#### Actions 탭에서 확인할 내용\n1. **성공률**: 각 워크플로우의 성공/실패 비율\n2. **실행 시간**: 평균 실행 시간 및 성능 추세\n3. **오류 패턴**: 자주 발생하는 오류 유형\n4. **리소스 사용량**: GitHub Actions 사용량\n\n#### 모니터링 명령어\n```bash\n# 최근 워크플로우 실행 상태 확인\ngh run list --limit 20\n\n# 특정 워크플로우 로그 확인\ngh run view [RUN_ID] --log\n\n# 워크플로우 수동 실행\ngh workflow run \"Data Management Workflow\"\n```\n\n## Issue 관리 시스템\n\n### Issue 생명 주기\n\n```mermaid\ngraph LR\n    A[새 Issue] --\u003e B{자동 검증}\n    B --\u003e|통과| C[needs-review]\n    B --\u003e|실패| D[invalid]\n    C --\u003e E{관리자 검토}\n    E --\u003e|승인| F[approved]\n    E --\u003e|거절| G[rejected]\n    E --\u003e|수정 필요| H[needs-changes]\n    F --\u003e I[자동 PR 생성]\n    I --\u003e J[배포]\n```\n\n### Issue 라벨 시스템\n\n#### 유형 라벨 (자동 할당)\n- `type:term-addition` - 새 용어 추가\n- `type:term-modification` - 기존 용어 수정\n- `type:contributor-addition` - 기여자 등록\n- `type:organization-addition` - 조직 등록\n- `type:admin-addition` - 관리자 추천\n- `type:verification-org-addition` - 검증 기관 등록\n\n#### 상태 라벨 (관리자 수동 관리)\n- `status:needs-review` - 검토 필요 (기본)\n- `status:approved` - 승인됨 (자동 처리 트리거)\n- `status:rejected` - 거절됨\n- `status:needs-changes` - 수정 필요\n- `status:on-hold` - 보류\n\n#### 우선순위 라벨\n- `priority:high` - 높음\n- `priority:medium` - 중간 (기본)\n- `priority:low` - 낮음\n\n#### 전문 분야 라벨\n- `domain:machine-learning`\n- `domain:deep-learning`\n- `domain:nlp`\n- `domain:computer-vision`\n- `domain:data-science`\n\n### 관리자 검토 가이드\n\n#### 1. 용어 추가/수정 검토\n\n**필수 확인 사항:**\n- ✅ 한글/영어 용어의 정확성\n- ✅ 정의의 명확성 및 정확성\n- ✅ 예시의 적절성\n- ✅ 참고문헌의 신뢰성\n- ✅ 중복 용어 여부\n\n**승인 기준:**\n- 학술적으로 검증된 용어\n- 업계에서 널리 사용되는 용어\n- 명확한 정의와 적절한 예시 제공\n\n**거절 사유:**\n- 부정확하거나 모호한 정의\n- 이미 존재하는 용어\n- 학술적 근거 부족\n- 부적절한 내용\n\n#### 2. 기여자/조직 등록 검토\n\n**확인 사항:**\n- ✅ GitHub 프로필 실존 여부\n- ✅ 전문성 관련 증빙 자료\n- ✅ 연락처 정보 유효성\n- ✅ 이미 등록된 기여자/조직 여부\n\n#### 검토 프로세스\n\n```bash\n# 1. Issue 세부 내용 확인\ngh issue view [ISSUE_NUMBER]\n\n# 2. 기여자 프로필 확인 (용어 관련)\ngh api users/[USERNAME]\n\n# 3. 라벨 추가/변경\ngh issue edit [ISSUE_NUMBER] --add-label \"approved\"\ngh issue edit [ISSUE_NUMBER] --add-label \"status:needs-changes\"\n\n# 4. 댓글로 피드백 제공\ngh issue comment [ISSUE_NUMBER] --body \"승인합니다. 자동 처리됩니다.\"\n```\n\n## 데이터 품질 관리\n\n### 자동 검증 시스템\n\n프로젝트에는 다음과 같은 자동 검증 스크립트가 포함되어 있습니다:\n\n#### `scripts/validate-terms.py`\n```python\n# 용어 데이터 유효성 검증\n- JSON 스키마 검증\n- 필수 필드 존재 여부\n- 데이터 타입 정확성\n```\n\n#### `scripts/check-duplicates.py`\n```python\n# 중복 데이터 검사\n- 동일한 영어/한글 용어\n- 비슷한 용어 탐지 (Levenshtein distance)\n```\n\n#### `scripts/validate-sorting.py`\n```python\n# 정렬 순서 검증\n- 알파벳 순 정렬 확인\n- 데이터 구조 일관성\n```\n\n### 수동 품질 관리\n\n#### 월간 품질 점검 체크리스트\n\n- [ ] 전체 용어 데이터 백업\n- [ ] 중복 용어 전면 검사\n- [ ] 링크된 참고문헌 유효성 확인\n- [ ] 기여자 정보 최신성 검증\n- [ ] 조직 정보 업데이트 상태 확인\n\n#### 품질 지표 모니터링\n\n```bash\n# 총 용어 수 확인\njq length data/terms/terms-a-z.json\n\n# 최근 업데이트된 용어 확인\njq '.[] | select(.metadata.updatedAt \u003e \"2024-01-01\") | .english' data/terms/terms-a-z.json\n\n# 상태별 용어 분포 확인\njq 'group_by(.status) | map({status: .[0].status, count: length})' data/terms/terms-a-z.json\n```\n\n## 자동화 시스템 모니터링\n\n### 핵심 모니터링 지표\n\n#### 1. 워크플로우 성공률\n```bash\n# 최근 50개 워크플로우 실행 성공률 확인\ngh run list --limit 50 --json status,conclusion | jq '[.[] | select(.status == \"completed\")] | group_by(.conclusion) | map({conclusion: .[0].conclusion, count: length})'\n```\n\n#### 2. 처리 시간 모니터링\n```bash\n# 평균 처리 시간 확인\ngh run list --limit 20 --json createdAt,updatedAt | jq '.[] | ((.updatedAt | strptime(\"%Y-%m-%dT%H:%M:%SZ\") | mktime) - (.createdAt | strptime(\"%Y-%m-%dT%H:%M:%SZ\") | mktime)) / 60' | awk '{sum+=$1; count++} END {print \"Average minutes:\", sum/count}'\n```\n\n#### 3. 에러 패턴 분석\n```bash\n# 최근 실패한 워크플로우 로그 확인\ngh run list --status failure --limit 10 --json databaseId | jq -r '.[] | .databaseId' | head -5 | xargs -I {} gh run view {} --log\n```\n\n### 알림 설정\n\n#### GitHub Notifications\n- Repository watching을 \"All Activity\"로 설정\n- 실패한 워크플로우에 대한 이메일 알림 활성화\n\n#### 외부 모니터링 (선택사항)\n```yaml\n# .github/workflows/monitoring.yml\nname: System Health Check\non:\n  schedule:\n    - cron: '0 */6 * * *'  # 6시간마다 실행\n\njobs:\n  health-check:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Check system status\n        run: |\n          # 데이터 파일 존재 및 크기 확인\n          # 최근 활동 상태 확인\n          # 외부 서비스 연결 테스트\n```\n\n## 긴급 상황 대응\n\n### 비상 연락체계\n\n#### 1단계: 자동 복구 시도\n- GitHub Actions 워크플로우 재실행\n- 캐시 클리어 및 재배포\n\n#### 2단계: 수동 개입\n- 문제 있는 데이터 수동 수정\n- 임시 우회 방법 적용\n\n#### 3단계: 시스템 복원\n- 백업에서 데이터 복원\n- 시스템 재시작\n\n### 일반적인 긴급 상황\n\n#### 1. 자동화 워크플로우 실패\n```bash\n# 워크플로우 상태 확인\ngh run list --workflow=\"Data Management Workflow\" --limit 5\n\n# 실패한 워크플로우 재실행\ngh run rerun [RUN_ID]\n\n# 수동으로 Issue 처리\npython .github/scripts/process-term-data.py --issue-data-file issue_data.json --action add\n```\n\n#### 2. 잘못된 데이터 배포\n```bash\n# Git 히스토리에서 이전 버전 복원\ngit log --oneline data/terms/terms-a-z.json\ngit checkout [COMMIT_HASH] -- data/terms/terms-a-z.json\ngit commit -m \"🔥 Revert incorrect data changes\"\ngit push origin main\n```\n\n#### 3. 대량의 스팸 Issues\n```bash\n# 일괄 Issue 닫기 (주의 필요)\ngh issue list --label \"spam\" --json number | jq -r '.[] | .number' | xargs -I {} gh issue close {} --comment \"스팸으로 판단되어 닫습니다.\"\n```\n\n## 관리 도구 및 스크립트\n\n### 필수 CLI 도구\n\n#### GitHub CLI 설정\n```bash\n# GitHub CLI 설치 및 인증\ngh auth login\n\n# 저장소 클론\ngh repo clone 9bow/kr-glossary\ncd kr-glossary\n\n# 기본 설정\ngh alias set issues-pending 'issue list --label \"status:needs-review\"'\ngh alias set approve-issue '!gh issue edit $1 --add-label approved'\n```\n\n#### 관리 스크립트 실행\n```bash\n# Python 환경 설정\npip install -r requirements.txt\n\n# 데이터 검증\npython scripts/validate-terms.py\npython scripts/check-duplicates.py\npython scripts/validate-sorting.py\n\n# 통계 생성\npython scripts/generate-statistics.py\n```\n\n### 관리자 전용 스크립트\n\n#### 1. 대량 Issue 처리 스크립트\n```python\n# scripts/bulk-issue-processing.py\n# 여러 Issue를 한 번에 승인/거절하는 스크립트\n```\n\n#### 2. 데이터 백업 스크립트\n```bash\n# scripts/backup-data.sh\n#!/bin/bash\nBACKUP_DIR=\"backups/$(date +%Y%m%d_%H%M%S)\"\nmkdir -p \"$BACKUP_DIR\"\ncp -r data/ \"$BACKUP_DIR/\"\necho \"백업 완료: $BACKUP_DIR\"\n```\n\n#### 3. 성능 모니터링 스크립트\n```python\n# scripts/performance-monitor.py\n# 시스템 성능 지표 수집 및 보고서 생성\n```\n\n### 정기 유지보수 작업\n\n#### 일간 작업\n- [ ] 새 Issue 검토 (gh issues-pending)\n- [ ] 워크플로우 실패 여부 확인\n- [ ] 커뮤니티 질문 응답\n\n#### 주간 작업\n- [ ] 데이터 품질 검증 실행\n- [ ] 성능 지표 검토\n- [ ] 기여자 통계 업데이트\n\n#### 월간 작업\n- [ ] 전체 시스템 백업\n- [ ] 외부 링크 유효성 검사\n- [ ] 용어 사용 통계 분석\n- [ ] 커뮤니티 성장 지표 리뷰\n\n## FAQ 및 트러블슈팅\n\n### 자주 묻는 질문\n\n#### Q1: Issue가 자동으로 처리되지 않아요\n**A1**: 다음을 확인하세요:\n1. Issue에 올바른 라벨이 있는지 (`approved`)\n2. GitHub Actions가 정상 작동하는지\n3. 데이터 검증이 통과했는지\n\n```bash\n# 워크플로우 로그 확인\ngh run list --workflow=\"Data Management Workflow\" --limit 3\ngh run view [RUN_ID] --log\n```\n\n#### Q2: 중복 용어가 추가되었어요\n**A2**: 중복 검사 스크립트를 실행하고 수동으로 제거:\n```bash\npython scripts/check-duplicates.py\n# 중복 용어를 직접 편집\ngit add data/terms/terms-a-z.json\ngit commit -m \"Remove duplicate terms\"\ngit push origin main\n```\n\n#### Q3: 기여자가 GitHub에서 찾을 수 없어요\n**A3**: GitHub API로 확인:\n```bash\ngh api users/[USERNAME] || echo \"사용자가 존재하지 않습니다\"\n```\n\n### 일반적인 오류 해결\n\n#### 워크플로우 권한 오류\n```yaml\n# .github/workflows/data-management.yml에서 권한 확인\npermissions:\n  contents: write\n  issues: write\n  pull-requests: write\n```\n\n#### JSON 파싱 오류\n```bash\n# JSON 유효성 검사\njq empty data/terms/terms-a-z.json \u0026\u0026 echo \"Valid JSON\" || echo \"Invalid JSON\"\n\n# 문제가 있는 경우 백업에서 복원\ncp data/terms/terms-a-z.json.backup data/terms/terms-a-z.json\n```\n\n#### GitHub Pages 배포 실패\n```bash\n# Pages 설정 확인\ngh repo view --json hasIssuesEnabled,hasWikiEnabled,homepageUrl\n\n# 수동 배포 트리거\ngh workflow run \"Deploy to GitHub Pages\"\n```\n\n## 추가 리소스\n\n### 관련 문서\n- [GitHub Actions 문서](https://docs.github.com/en/actions)\n- [GitHub CLI 매뉴얼](https://cli.github.com/manual/)\n- [JSON Schema 가이드](https://json-schema.org/learn/)\n\n### 외부 도구\n- [GitHub Desktop](https://desktop.github.com/) - GUI Git 클라이언트\n- [VS Code](https://code.visualstudio.com/) - JSON 편집용 에디터\n- [Postman](https://www.postman.com/) - GitHub API 테스트\n\n### 커뮤니티\n- [GitHub Discussions](https://github.com/9bow/kr-glossary/discussions) - 관리자 간 소통\n- [AI/ML 용어집 Discord](링크) - 실시간 채팅\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**긴급 연락처**\n- Lead Admin: [GitHub Username]\n- 기술 문의: [Issues](https://github.com/9bow/kr-glossary/issues)\n- 시스템 상태: [Status Page](링크)\n\n*이 문서는 지속적으로 업데이트됩니다. 최신 버전을 확인해주세요.*\n\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F9bow%2Fkr-glossary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F9bow%2Fkr-glossary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F9bow%2Fkr-glossary/lists"}