8bf34ea346
비개발자/기획자/개발자 누구나 이해하도록 일목요연하게 정리. 길이 분산 위해 분할. - README.md: 3줄 요약 + 워크플로우 다이어그램 + 주요기능 + 빠른시작 + 문서 목차 - docs/architecture.md: 구성요소·처리 파이프라인·재시도/프록시/봇감지/이력 원리 - docs/database.md: 테이블 4종(job/price_history/search_negative/bot_detection) + 코드값 - docs/api.md: 엔드포인트 요청/응답 예시(curl/Postman), 상태·코드 요약 - docs/operations.md: 실행·로그·DB조회·테스트·문제해결·배포유의 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
113 lines
5.4 KiB
Markdown
113 lines
5.4 KiB
Markdown
# LPS — 인터넷 최저가 검색 솔루션
|
|
|
|
> 상품 정보를 넣으면 **네이버·쿠팡을 뒤져 "같은 상품"의 최저가를 찾아** 돌려주고, 그 가격을 **시간에 따라 기록**해 그래프로 볼 수 있는 시스템입니다.
|
|
|
|
---
|
|
|
|
## 🧭 이게 뭔가요? (비개발자용 3줄 요약)
|
|
|
|
1. "맥심 커피 (1박스, 160개입)" 같은 상품 정보를 보내면,
|
|
2. 시스템이 **네이버·쿠팡을 실제로 검색**하고, **AI가 "진짜 같은 상품"만 골라** 최저가를 알려줍니다. (빨대·커버 같은 **엉뚱한 액세서리는 걸러냅니다**)
|
|
3. 같은 상품을 **여러 번 조회하면 가격 변화가 쌓여서**, 네이버/쿠팡/최종 최저가를 **그래프**로 볼 수 있습니다.
|
|
|
|
**왜 유용한가?** 사람이 일일이 검색·비교하지 않아도, 필요한 상품만(조회할 때만) 자동으로 최저가를 찾고 가격 추이를 남깁니다.
|
|
|
|
---
|
|
|
|
## ⚙️ 어떻게 동작하나요? (워크플로우)
|
|
|
|
```
|
|
[1] 검색 요청 [2] 대기줄(큐) [3] 일꾼(워커)가 처리
|
|
상품 정보 전송 ─────▶ 순서대로 쌓임 ─────▶ 네이버 + 쿠팡 동시 검색
|
|
(POST /search) (즉시 접수번호 반환) │
|
|
▼
|
|
[4] 걸러내기 + AI 판정
|
|
가격 이상치 제거 → "같은 상품"만 선별
|
|
│
|
|
▼
|
|
[5] 최저가 확정 + 기록
|
|
네이버/쿠팡/최종 최저가 저장 → 그래프용 이력 적재
|
|
│
|
|
▼
|
|
[6] 완료(결과 조회 가능)
|
|
```
|
|
|
|
**핵심 포인트**
|
|
- **즉시 응답 + 나중 처리**: 요청하면 바로 "접수번호(job_id)"를 주고, 실제 검색은 뒤에서 진행됩니다. (검색은 몇 초~수십 초 걸림)
|
|
- **못 찾으면 검색어를 바꿔 재시도**: "맥심 커피"로 안 나오면 "맥심 모카골드 커피믹스"처럼 **AI가 검색어를 다듬어** 다시 시도하고, 그래도 없으면 "없음"으로 정리합니다. (무한 재시도 안 함)
|
|
- **차단 대응**: 쿠팡이 봇으로 감지하면 **다른 IP로 바꿔** 재시도하고, 감지 이력도 기록합니다.
|
|
|
|
---
|
|
|
|
## ✨ 주요 기능
|
|
|
|
| 기능 | 설명 |
|
|
|------|------|
|
|
| 멀티 소스 검색 | 네이버 쇼핑 API + 쿠팡(봇 차단 우회) 동시 검색·병합 |
|
|
| AI 같은 상품 판정 | "진짜 그 상품"만 선별 (액세서리·다른 규격 제외) |
|
|
| 검색어 자동 정제 | 0건이면 정밀/광역 검색어로 재시도 |
|
|
| 최저가 이력 그래프 | 조회 시점마다 네이버/쿠팡/최종 최저가를 시계열로 기록 |
|
|
| 안정적 큐 처리 | 작업 유실 없이 순서대로, 실패 시 자동 재시도 |
|
|
| 프록시 IP 회전 | 차단 회피용 IP 자동 순환(DECODO) |
|
|
|
|
---
|
|
|
|
## 🚀 빠른 시작
|
|
|
|
```bash
|
|
cd lps
|
|
|
|
# 1) 설정 파일 준비 (DB·API 키 등)
|
|
cp config/config.local.toml.example config/config.local.toml # 값 채우기
|
|
|
|
# 2) API 서버 실행 (요청 접수)
|
|
./run_local_server.sh # → http://localhost:9600/docs
|
|
|
|
# 3) 워커 실행 (실제 검색 수행) — 별도 터미널
|
|
python worker_main.py
|
|
```
|
|
|
|
간단 테스트:
|
|
```bash
|
|
curl -X POST localhost:9600/v1/lps/search -H 'Content-Type: application/json' \
|
|
-d '{"data":[{"product_code":"T1","product_name":"맥심 커피","specification":"1박스, 160개입"}]}'
|
|
```
|
|
|
|
> 자세한 실행/설정은 [운영 가이드](docs/operations.md) 참고.
|
|
|
|
---
|
|
|
|
## 📚 문서
|
|
|
|
| 문서 | 대상 | 내용 |
|
|
|------|------|------|
|
|
| **[아키텍처](docs/architecture.md)** | 개발자/기획자 | 구성요소, 처리 파이프라인, 재시도·프록시·AI 동작 원리 |
|
|
| **[데이터베이스](docs/database.md)** | 개발자/기획자 | 테이블 4종 구조와 코드값 |
|
|
| **[API 사용법](docs/api.md)** | 연동 개발자 | 엔드포인트·요청/응답 예시(Postman/curl) |
|
|
| **[운영 가이드](docs/operations.md)** | 운영자/개발자 | 실행·로그 보기·DB 조회·문제 해결 |
|
|
|
|
---
|
|
|
|
## 📁 폴더 구조
|
|
|
|
```
|
|
lps/
|
|
├── web_main.py # API 서버 진입점 (요청 접수)
|
|
├── worker_main.py # 워커 진입점 (실제 검색 수행)
|
|
├── run_local_server.sh # 로컬 API 실행 스크립트
|
|
├── config/ # 설정(config.local.toml — 포트/DB/API키, 미커밋)
|
|
├── common/ # 공통(enums, DB 세션, 모델, 로거)
|
|
│ └── database/model/models.py # DB 테이블 정의
|
|
├── crud/ # DB 접근 (job_crud, price_history, negative_cache, bot_detection)
|
|
├── services/
|
|
│ ├── search/ # 소스 어댑터 (coupang, naver) + 프록시·필터
|
|
│ ├── pipeline/ # 필터·이상치·최저가 정렬
|
|
│ └── ai/ # AI 유사도 판정·검색어 생성 (OpenAI)
|
|
├── worker/ # 워커 루프·핸들러·알림(NOTIFY)
|
|
├── router/v1/lps/ # API 라우터
|
|
└── tests/ # 테스트
|
|
```
|
|
|
|
## 포트
|
|
backend 9300 / negodata 9400 / agent 9500 과 겹치지 않게 **LPS는 9600**.
|