"""모호한 요청에 대한 구조화된 명확화 질문 생성 유틸리티.

5W1H 차원을 키워드 휴리스틱으로 분석하여 누락된 차원과 제안 질문을 반환한다.
외부 LLM 호출 없이 순수 키워드 기반으로 동작한다.

Usage:
    from utils.clarify import analyze_ambiguity
    report = analyze_ambiguity("뭔가 만들어줘")
    # report.score: 0~10, report.missing_dimensions: list, report.suggested_questions: list
"""

from __future__ import annotations

from dataclasses import dataclass, field

# 각 항목: (차원명, 키워드 목록, 누락 시 제안 질문)
_DIMENSIONS: list[tuple[str, list[str], str]] = [
    (
        "What",
        [
            "구현",
            "작성",
            "만들",
            "개발",
            "분석",
            "설계",
            "수정",
            "추가",
            "제거",
            "삭제",
            "생성",
            "빌드",
            "코드",
            "스크립트",
            "함수",
            "모듈",
            "클래스",
            "API",
            "서비스",
            "기능",
            "리팩터",
            "리팩토링",
            "테스트",
            "문서",
            "파일",
            "보고서",
            "페이지",
            "create",
            "write",
            "build",
            "implement",
            "develop",
            "refactor",
        ],
        "어떤 것을(무엇을) 만들거나 수행해야 하나요? 구체적인 산출물이나 작업 범위를 알려주세요.",
    ),
    (
        "Why",
        [
            "위해",
            "때문에",
            "목적",
            "이유",
            "배경",
            "동기",
            "원인",
            "필요",
            "향상",
            "개선",
            "해결",
            "최적화",
            "효율",
            "성능",
            "품질",
            "용도",
            "활용",
            "사용",
            "보고",
            "제출",
            "for",
            "because",
            "purpose",
            "reason",
            "goal",
            "objective",
        ],
        "왜 이 작업이 필요한가요? 목적이나 배경을 알려주시면 더 적합하게 도와드릴 수 있습니다.",
    ),
    (
        "Where",
        [
            "서버",
            "데이터베이스",
            "DB",
            "파일",
            "클라우드",
            "로컬",
            "환경",
            "프론트엔드",
            "백엔드",
            "인프라",
            "시스템",
            "플랫폼",
            "저장소",
            "레포",
            "리포지토리",
            "디렉터리",
            "폴더",
            "경로",
            "URL",
            "엔드포인트",
            "server",
            "database",
            "cloud",
            "local",
            "frontend",
            "backend",
        ],
        "어디서(어느 환경·시스템·위치에서) 이 작업이 이루어지나요?",
    ),
    (
        "When",
        [
            "오늘",
            "내일",
            "이번 주",
            "다음 주",
            "이번 달",
            "다음 달",
            "월요일",
            "화요일",
            "수요일",
            "목요일",
            "금요일",
            "주말",
            "까지",
            "기한",
            "마감",
            "일정",
            "언제",
            "스프린트",
            "릴리스",
            "today",
            "tomorrow",
            "deadline",
            "sprint",
            "release",
            "by",
        ],
        "언제까지 완료해야 하나요? 기한이나 일정 정보를 알려주세요.",
    ),
    (
        "Who",
        [
            "팀",
            "개발자",
            "사용자",
            "고객",
            "관리자",
            "운영자",
            "담당자",
            "이해관계자",
            "팀장",
            "매니저",
            "클라이언트",
            "파트너",
            "나",
            "우리",
            "저",
            "제가",
            "team",
            "developer",
            "user",
            "admin",
            "manager",
            "client",
        ],
        "누가 사용하거나 관여하나요? 대상 사용자나 이해관계자를 알려주세요.",
    ),
    (
        "How",
        [
            "방식",
            "방법",
            "절차",
            "단계",
            "프레임워크",
            "라이브러리",
            "언어",
            "파이썬",
            "Python",
            "자바",
            "Java",
            "타입스크립트",
            "TypeScript",
            "REST",
            "GraphQL",
            "gRPC",
            "SQL",
            "NoSQL",
            "으로",
            "를 사용",
            "을 사용",
            "기반",
            "통해",
            "how",
            "using",
            "via",
            "with",
            "method",
            "approach",
        ],
        "어떤 방법이나 기술 스택을 사용해야 하나요? 구현 방식에 대한 제약이 있다면 알려주세요.",
    ),
]

_POINTS_PER_DIM: float = 10.0 / len(_DIMENSIONS)


@dataclass
class AmbiguityReport:
    """모호성 분석 결과.

    Attributes:
        score:               모호성 점수 (0 = 명확, 10 = 매우 모호).
        missing_dimensions:  정보가 누락된 5W1H 차원 이름 목록.
        suggested_questions: 각 누락 차원에 대한 명확화 질문 목록.
    """

    score: float
    missing_dimensions: list[str] = field(default_factory=list)
    suggested_questions: list[str] = field(default_factory=list)


def _has_dimension(text: str, keywords: list[str]) -> bool:
    """텍스트에 키워드가 하나라도 포함되면 True."""
    lower = text.lower()
    return any(kw.lower() in lower for kw in keywords)


def analyze_ambiguity(request: str) -> AmbiguityReport:
    """요청 문자열의 모호성을 5W1H 키워드 휴리스틱으로 분석한다.

    Args:
        request: 분석할 요청 텍스트.

    Returns:
        AmbiguityReport — score(0~10), missing_dimensions, suggested_questions.
    """
    missing_dims: list[str] = []
    suggested_qs: list[str] = []

    for dim_name, keywords, question in _DIMENSIONS:
        if not _has_dimension(request, keywords):
            missing_dims.append(dim_name)
            suggested_qs.append(question)

    n = len(missing_dims)
    if n == 0:
        score = 0.0
    elif n == len(_DIMENSIONS):
        score = 10.0
    else:
        score = round(n * _POINTS_PER_DIM, 2)

    return AmbiguityReport(
        score=score,
        missing_dimensions=missing_dims,
        suggested_questions=suggested_qs,
    )