refactor(S15P11A705-96): 공개 설정의 정본을 코드로 옮긴다

[colosair]

요약

설정값을 비밀 / 공개로 가르고, 공개 값은 코드가 정본이 되게 합니다. 공용 계약 개정(docs#27, f7740b0)이 선행이며 이미 머지됐습니다.

비밀   DATABASE_URL · GMS_API_KEY · INTERNAL_SHARED_SECRET       주입 필수
       GMS_BASE_URL — 값은 비밀이 아니나 배포마다 달라 주입받는다
공개   PINLOG_EMBEDDING_* 넷 · JUDGE_MODEL · TOP_K · FLOOR · EXPIRY   코드가 정본

공개 값 중 EMBEDDING 넷만 기본값이 없었습니다. 나머지는 이미 갖고 있었으므로, 새 규칙을 만든 것이 아니라 어긋나 있던 넷을 규칙에 맞춘 것입니다.

Jira

• S15P11A705-96 — [AI] dev 배포용 GMS·모델·bootstrap·관측 계약 확정
• https://ssafy.atlassian.net/browse/S15P11A705-96

왜

값이 배포 설정에만 있으면 교체가 git 이력도 리뷰도 남기지 않습니다. Profile 변경은 기존 임베딩을 전부 조회 대상에서 빼는 결정인데(05 §9.3 검색 필터의 embedding_profile 일치 조건), 그것이 콘솔 편집 한 번으로 가능했습니다. 값 자체는 05 §7.1 표에 이미 공개돼 있어 숨겨진 적도 없습니다.

모델 교체 절차가 이렇게 바뀝니다.

전   Secret 콘솔에서 4개 수정 → 재배포              이력·리뷰 없음
후   config.py 4줄 → PR → 리뷰 → 머지 → 재배포      이력·리뷰 있음

변경 사항

파일	무엇을 · 왜
app/core/config.py	EMBEDDING 넷에 기본값. alias 유지 — 덮어쓰기 경로는 그대로
.env.example	비밀 / 공개 두 절로 나누고 각 절의 규칙 명시
docs/spec/model-profile.md §2.1	"기본값을 넣지 않는다" → "기본값이 정본이다". 원문과 개정 근거를 인용문으로 보존
.github/workflows/seal-ai-secrets.yml	봉인 대상 7종 → 3종
docs/proposals/P45-…	결정 근거·기각한 대안·감수하는 것
tests/test_unit.py	주장 셋을 고정하는 테스트 3개

설계 결정 — 기각한 대안

config/*.yaml 계층 도입. 목적은 같게 달성하지만 설정 소스가 셋(yaml → env → Secret)이 되어, 장애를 볼 때마다 *"이 값이 어디서 왔나"*를 역추적해야 합니다. pydantic-settings를 이미 쓰므로 필드 기본값만으로 같은 이익이 나옵니다.

원 규정 유지. *"기본값이 있으면 배포 설정 누락이 조용한 Profile 불일치가 된다"*가 원 논거인데, 그것은 주입이 필수라는 전제 위에 있습니다. 주입을 덮어쓰기로 낮추면 "누락"이라는 상태 자체가 없어집니다.

테스트 / 검증

• 전체 스위트 69 passed (Testcontainers 포함, exit 0). 기존 66 + 신규 3
• test_public_settings_fall_back_to_code_defaults — 넷을 지우고도 기동
• test_code_defaults_satisfy_profile_consistency — 기본값끼리도 정합
• test_injection_overrides_code_defaults — 덮어쓰기 우선
• 기존 profile 정합·GMS_BASE_URL fail-fast 테스트 전부 유지

리뷰 포인트

1. 두 번째 테스트가 이 PR의 핵심 안전장치입니다. 정합 검사가 주입값에만 걸린다고 오해하면, 기본값이 어긋난 채 배포됐을 때 아무도 주입하지 않은 환경에서만 기동이 죽습니다. 정본을 코드로 옮긴 이상 그 정합도 코드가 책임져야 합니다.
2. 봉인 대상 축소가 Infra 요구와 충돌하지 않습니다. 값이 이미지에 들어 있으므로 주입할 것이 없어집니다. 덮어써야 하면 ConfigMap이면 되고 그 경로에 암호화가 불필요합니다. 등록된 Actions Secret은 지우지 않아도 되며 workflow가 읽지 않을 뿐입니다 — ai#32에 예고했습니다.

절차에 대해

처음에 하위 명세(model-profile.md)만 고치고 공용 계약을 그대로 뒀습니다. CONTRIBUTING.md가 *"공용 계약과 충돌하면 소유 파트와 합의한 뒤 양쪽 문서를 갱신한다"*고 요구하는데, 하위만 고치면 두 문서가 어긋난 채 남습니다. 커밋 전에 발견해 되돌리고 docs#27을 먼저 올렸습니다.

미결 / 후속

• Spring 쪽 Profile 취득 경로 — 05 §7.1이 -135 시점 결정으로 명시적으로 유예했습니다. 소비자가 없는 상태에서 정하면 붙일 때 뒤집힙니다
• 덮어쓰기 상시화 — 배포가 늘 환경변수로 덮어쓴다면 그 값은 공개가 아니라 환경 종속이므로 분류를 다시 봐야 합니다. 이 결정의 전제입니다

🤖 Generated with Claude Code