# ChromaDB Collection 명명 규칙 통일

**작성일**: 2025-09-20
**작성자**: Claude
**관련 서비스**: rb8001, skill-rag-file
**이슈**: ChromaDB 컬렉션 명명 규칙 불일치

## 문제 상황
- rb8001과 skill-rag-file이 서로 다른 명명 규칙 사용
- 기존: `rb8001_{user_id}`, `rb8001_{team_id}_documents`
- 일관성 없는 명명으로 관리 어려움

## 해결 방안

### 표준 명명 규칙 정의
```
{service}_{identifier}_{type}
```
- **service**: 서비스명 (rb8001, skill_rag_file 등)
- **identifier**: UUID (user_uuid 또는 team_uuid)
- **type**: 데이터 타입 (memory, documents 등)

### 구현 변경사항

#### 1. rb8001 수정
**파일**: `/home/admin/ivada_project/rb8001/app/memory/manager.py`

변경 전:
```python
self.collection_name = f"{robeing_id}_{user_id}"
```

변경 후:
```python
self.collection_name = f"{robeing_id}_{user_id}_memory"
collection_metadata = {"service": robeing_id, "user_id": user_id, "type": "memory"}
```

#### 2. skill-rag-file 수정
**파일**: `/home/admin/ivada_project/skill-rag-file/app/api/upload.py`
**파일**: `/home/admin/ivada_project/skill-rag-file/app/api/search.py`

변경 전:
```python
collection_name = f"rb8001_{team_id}_documents"
```

변경 후:
```python
collection_name = f"skill_rag_file_{team_id}_documents"
```

#### 3. 마이그레이션 스크립트
**파일**: `/home/admin/ivada_project/rb8001/scripts/migrate_chromadb_collections.py`

주요 기능:
- 기존 컬렉션 백업
- 새 명명 규칙으로 복원
- 메타데이터 추가 (service, type)
- 자동 실행 모드 지원 (`--auto`)

### 테스트 결과

#### rb8001 테스트
```python
# 생성된 컬렉션명
rb8001_test_user_12345_memory

# 메타데이터
{
  "service": "rb8001",
  "user_id": "test_user_12345",
  "type": "memory"
}
```

#### skill-rag-file 테스트
```python
# 생성된 컬렉션명
skill_rag_file_test_team_123_documents

# 메타데이터
{
  "service": "skill_rag_file",
  "type": "documents",
  "team_id": "test_team_123"
}
```

## 배포 절차

1. 코드 수정 및 푸시
2. 서비스 재시작
   ```bash
   # rb8001
   docker compose down && docker compose up -d --build

   # skill-rag-file
   cd /home/admin/ivada_project/skill-rag-file
   docker compose down && docker compose up -d --build
   ```

3. 권한 수정 (필요시)
   ```bash
   sudo chown -R admin:xusers /home/admin/ivada_project/rb8001/chroma_db/
   sudo chmod -R 775 /home/admin/ivada_project/rb8001/chroma_db/
   ```

4. 마이그레이션 실행 (기존 데이터가 있는 경우)
   ```bash
   python3 scripts/migrate_chromadb_collections.py --auto
   ```

## 주의사항
- ChromaDB 버전에 따른 호환성 문제 가능
- 권한 문제 발생 시 chown/chmod 필요
- 텔레메트리 관련 경고는 무시 가능

## 교훈
1. **명명 규칙 표준화의 중요성**: 초기 설계 단계에서 전체 시스템의 명명 규칙을 통일
2. **메타데이터 활용**: 컬렉션 메타데이터로 서비스, 타입 등 추가 정보 저장
3. **마이그레이션 준비**: 스키마 변경 시 항상 마이그레이션 스크립트 준비
4. **권한 관리**: Docker 컨테이너와 호스트 간 파일 권한 일치 필요

## 관련 문서
- [000000_unresolved_items_matrix.md](../plans/000000_unresolved_items_matrix.md)
- [250915_skill-rag-file_초기_구축.md](250915_skill-rag-file_초기_구축.md)