# 황님보고서 기준 정합성 검토

기준 문서는 [황님보고서.md](../../../디자인_지식저장소/황님보고서.md)이다.

## 결론

v3 카드 설계의 방향은 황님보고서의 목적과 대체로 맞다.

황님보고서는 예쁜 리포트보다 데이터 품질, 근거 연결, 정규화,
검색 가능성을 우선한다. v3도 8가지 카테고리와 설계 이유를 카드
구조로 저장하고, 각 필드에 근거와 신뢰도를 붙이는 방향이다.

하지만 현재 v3는 아직 운영 가능한 지식저장소가 아니다.
지금은 구조 검토와 샘플 확인을 위한 공유용 설계안에 가깝다.

## 보고서가 요구하는 저장소

황님보고서는 디자인 지식저장소가 다음 역할을 해야 한다고 본다.

- 원본 링크, 이미지, 텍스트, OCR 결과를 보관한다.
- 8가지 디자인 지식을 구조화한다.
- 각 판단이 어디에서 나왔는지 근거를 연결한다.
- 원문에 명시된 정보와 추론한 정보를 구분한다.
- 신뢰도를 붙여 보고서 에이전트가 약한 추론을 걸러낼 수 있게 한다.
- 비슷한 표현을 같은 의미로 묶는 분류 체계를 적용한다.
- 검색, 비교 분석, 보고서 생성에 다시 쓸 수 있는 형태로 제공한다.

v3 카드 설계는 이 요구 중 일부를 반영했다.
하지만 데이터베이스 저장, 검색 API, 검수 흐름까지는 아직 연결되지 않았다.

## 현재 맞는 부분

v3는 8가지 카테고리와 설계 이유를 카드 안에 넣는다.
그래서 제품 카테고리, 사용자, 사용 맥락, 문제, 경험 가치, 형태 전략,
CMF, 기술/생산 선택을 같은 틀로 비교할 수 있다.

원본 자료는 카드 본문에 섞지 않고 `raw_refs`로 연결한다.
이 방식은 황님보고서가 말한 원본 재현성과 맞다.

원문 정보와 추론 정보는 `grounding`으로 구분한다.
예를 들어 `original_text`, `original_plus_inference`,
`image_observation`, `inference`를 나눠서 저장한다.

근거는 각 필드의 `basis`에 붙인다.
짧은 내부 ID만 남기는 대신, 원문 인용(`quote`),
이미지 관찰(`observation`), 추론 이유(`reasoning`),
원본 위치를 같은 자리에서 볼 수 있게 한다.

검색 대상도 카드 전체가 아니라 필드 단위로 본다.
`statement`, `value`, `values`, `tags`,
`basis.quote`, `basis.observation`, `basis.reasoning`을
검색 가능한 단위로 삼는다.

## 수정한 부분

처음 v3 샘플은 모든 값을 문장형으로 저장했다.
제품 유형, 색상, 소재, 형태 키워드까지 `statement`로 감싸면서
스캔성과 정규화가 떨어졌다.

그래서 필드 타입을 둘로 나눴다.

- 설명이 필요한 필드는 `statement`로 저장한다.
- 분류, 키워드, 색상, 소재처럼 값 자체가 중요한 필드는
  `value` 또는 `values`로 저장한다.

예를 들어 제품 유형은 문장으로 저장하지 않는다.

```yaml
product_type:
  value: 개인용 헤어 스타일링 스테이션
  grounding: original_text
  confidence: Gold
```

반면 문제 정의는 문장으로 저장한다.

```yaml
problem_definition:
  statement: 자기표현을 위해 헤어 스타일링을 일상적으로 시도하고 싶지만,
    기존 스타일링은 도구 숙련도 의존이 커서 캐주얼하게 접근하기 어렵다.
  grounding: original_plus_inference
  confidence: Silver
```

## 신뢰도 해석

황님보고서의 `confidence`는 카드 전체 점수라기보다
추출 결과의 신뢰도에 가깝다.

보고서에는 각 필드에 값, 추론 수준, 신뢰도, 근거 참조를 담는다고 되어 있다.
따라서 Gold, Silver, Bronze는 필드별 근거 등급으로 보는 것이 자연스럽다.

다만 보고서에는 low-confidence record 검수도 필요하다고 되어 있다.
그래서 카드 전체 상태는 별도로 둔다.

- 필드별 `confidence`는 해당 값이나 문장의 근거 강도를 나타낸다.
- 카드별 `quality_summary`는 신뢰도 분포, 누락 필드 수,
  검수 필요 여부를 나타낸다.

이렇게 나누면 카드 전체를 하나의 점수로 뭉개지 않아도 된다.
동시에 검수가 필요한 카드는 `quality_summary.review_status`로 찾을 수 있다.

## 아직 어긋나는 부분

v3 샘플은 아직 `KnowledgeRecord` 저장 구조와 직접 연결되어 있지 않다.
현재는 YAML 파일이며, ingest API에서 데이터베이스에 저장되는 흐름은 아니다.

분류 체계도 아직 충분하지 않다.
`tags`는 붙어 있지만, taxonomy canonical term이나 synonym mapping은
실제로 적용되지 않았다.

근거 연결도 더 촘촘해야 한다.
현재 `basis`는 필드 안에 근거를 넣지만, 이미지 영역, OCR 위치,
원문 문단 위치까지 충분히 세밀하게 가리키지는 않는다.

검색 기능도 아직 샘플 수준이다.
배포판은 구조와 샘플을 보여주는 페이지이지,
보고서 생성 에이전트가 호출할 검색 API가 아니다.

재분석, 수동 수정, taxonomy 변경 이력도 아직 없다.
황님보고서가 말한 revision 구조와 manual patch 흐름은
후속 구현이 필요하다.

low-confidence 검수 흐름도 아직 계산값 수준이다.
Bronze, No data, 누락 필드를 실제 검수 큐로 보내는 화면과 절차는
아직 만들어지지 않았다.

## 다음 구현 과제

먼저 v3 YAML 샘플을 실제 `KnowledgeRecord` 저장 구조와 매핑해야 한다.

그 다음 ingest API에서 URL 입력, 원본 수집, 카드 생성,
데이터베이스 저장까지 이어지게 만들어야 한다.

근거는 텍스트, 이미지, OCR, raw asset 단위로 더 촘촘하게 연결해야 한다.
특히 이미지 기반 판단은 어느 이미지의 어떤 관찰에서 나왔는지 남겨야 한다.

분류 체계는 `tags`와 분리해야 한다.
검색용 자유 태그와 표준화된 taxonomy term은 역할이 다르다.

마지막으로 보고서 생성 에이전트가 받을 검색 응답 구조를 설계해야 한다.
응답에는 사례, 필드 값, 근거, 신뢰도, 원본 확인 경로가 함께 들어가야 한다.