관리 가이드 — 사용자 / 외부 API 클라이언트

4인 팀 — 역할 구분 없음. 로그인한 누구나 admin 액션 가능 (사용자 추가/정지 / client 생성·키 발급·revoke 등). 자기 자신 정지·legacy 사용자 변경만 차단.

사용자 관리 (`/admin/users`)

새 팀원 추가

사이드바 사용자 → "사용자 추가" → 폼:
- email (검증)
- 이름
- 임시 비밀번호 (8자 이상). 본인이 첫 로그인 후 변경하도록 안내.
추가 즉시 활성 (active=true). 본인 로그인 가능.

정지 / 활성화

사용자 row 우측 "정지" / "활성화" 토글 (확인 모달).
정지된 사용자는 로그인 차단 (DB 조회 시 active=false → authorize 실패).
자기 자신 정지 차단 (lockout 회피). legacy 사용자 (id=1) 변경 불가.

비밀번호 변경

현 단계 미지원. 본인이 잊으면 다른 팀원 (admin) 이 계정 정지 후 새 계정 으로 재발급. 향후 /account/password 페이지 추가 예정.

legacy 사용자

id=1 legacy@searchright.local (비활성 + 잠김).
인증 도입 이전 시기의 audit 이력 호환용 — 옛 row 들이 가리키는 placeholder.
로그인 불가 / 변경 불가. 통계상 그대로 두면 됨.

외부 API 클라이언트 (`/admin/clients`)

외부 시스템 (소싱 파이프라인 / CRM 등) 이 SearchRight 검색 API 를 호출할 때 사용. partner 단위 client + 각 client 의 다중 key + per-key scope·rate-limit.

새 client 생성

사이드바 외부 API → "클라이언트 추가" → 폼:
- 이름 (회사명/별칭, 예: "Acme CRM")
- contact email (선택)
추가 후 리스트에 표시. 관리 → 링크로 상세 진입.

Client 상세 — 키 발급 / revoke / 사용량 보기

상세 페이지:

최근 7일 호출 그래프

일별 호출 수 막대. 5xx 에러 수는 hover tooltip. 사용 패턴 / 이슈 빠르게 surface.

새 키 생성

"새 키 생성" → 폼:
- 라벨 (선택, 예: "production-server" / "staging") — 키 식별용.
- scopes (default search:read) — comma-separated. 초기 사용 가능 = search:read. 추후 diagnose:read / correction:write 등 단계적 추가 예정.
- rate_limit_rpm (default 60) — 분당 호출 한도. 이 키만 따로 조정 가능.
"생성" → plaintext 키가 한 번만 표시 (srk_live_xxx...):
- "클립보드 복사" 버튼 → partner 에게 안전한 채널로 전달 (Bitwarden / 1Password 공유 등).
- 절대 사용자가 본 후 닫지 않으면 다시 못 봄 (DB 에는 sha256 hash 만).
"저장했어요 (새로고침)" → 키 리스트로.

분실 시 — 새 키 발급 후 기존 키 revoke. SearchRight 도 평문 다시 못 봄.

키 revoke

키 row 우측 "revoke" → 확인 모달 → 즉시 외부 호출 차단. soft revoke (revoked_at set, 행 영구 보존).

키 상태

🟢 active: 정상 사용 가능.
⚪ revoked: revoke 됨. 401 반환.
⚪ expired: expires_at 지남. 401 반환.

Rate limit 모델

per-key 1분 sliding window — key.rate_limit_rpm 가 한도.
초과 시 429 + Retry-After: 1 헤더.
응답 헤더 X-RateLimit-Remaining 로 남은 토큰 (대략) — partner 가 backoff 로직 짤 수 있음.
키마다 rpm 조정 가능 → trusted partner 는 높이고 미검증 partner 는 낮게.

Usage 로그

모든 /api/v1/* 호출이 api_usage_log 에 INSERT (endpoint / 상태코드 / latency / IP).
per-client 7일 그래프는 상세 페이지에 자동 표시.
per-endpoint·시간단위 fancy 분석은 H-5 (Observability) 마일스톤 예정.

환경변수

production 배포 시 필요한 env (Vercel / Railway / 기타):

키	설명	필수
`DATABASE_URL`	Postgres 연결 문자열	✅
`OPENAI_API_KEY`	LLM (HyDE / parser / enrich / embed)	✅
`COHERE_API_KEY`	rerank-v3.5	✅
`AUTH_SECRET`	NextAuth JWT 서명 (32B random, `openssl rand -hex 32`)	✅
`INITIAL_ADMIN_EMAIL`	첫 배포 1회 부트스트랩 admin 이메일	첫 배포만
`INITIAL_ADMIN_PASSWORD`	첫 배포 1회 부트스트랩 임시 비밀번호	첫 배포만
`SR_EN_SERVICE_API_KEY`	sr-be → sr-en service-to-service alias	service mesh 사용 시
`ENABLE_HYDE`, `ENABLE_RERANK`, `ENABLE_HYBRID`	검색 엔진 토글 (default off, UI 가 per-request override)	선택

제거된 env (M-HARDEN 이전 잔재)

다음은 더 이상 사용 안 함 — .env 에서 정리 권장:

AUTH_USER, AUTH_PASSWORD (H-1 — DB users 로 교체)
EXTERNAL_API_KEYS, EXTERNAL_API_RPS, EXTERNAL_API_BURST (H-2 — DB clients/keys 로 교체)
REVIEW_PASSWORD (검수 페이지 폐기 후 stale, 인증 도입 시 middleware cleanup 됨)

데이터 sync (개발 / 배포)

local 에서 데이터를 교정 (audit row 생성) / enrich (회사·프로필 추가) 한 경우 prod 로 sync 필요:

pnpm db:sync:up           # dry-run (변경 미리보기)
pnpm db:sync:up -- --apply  # 실제 적용

자세한 sync runbook = docs/plans/sync-runbook.md.

언제 sync 가 필요한가 — local enrich-single / 교정 적용 / 사용자·client·키 추가 등 DB 변경이 있는 작업 후. 검색만 했으면 (search_history 누적) sync 불필요 (이력은 local-only OK).